This is my ssh implementation, moussh. This file is a usage document; for a compilation document, see INSTALL. This file is in the public domain. (In jurisdictions where it is not possible for a copyright holder to deliberately release a work into the public domain, the statements in the various files that they are public domain should be interpreted as the closest approximation available, probably something like "you have a perpetual, unlimited, sublicenseable license to use and/or modify this work in any way you see fit".) Command-line: [options] [args] The program can run in multiple modes of operation (for example, as a client, or as a key generator). The operation modes, together with short codes used to refer to them in descriptions below, are: Client c Runs as a client to connect to a server. This is the commonest mode. Server s Runs as a server, accepting connections from clients. Keygen kg Generates new keys. Setpass sp Changes the passphrase on (the secret portion of) a public/private key file pair. Setcomm sc Changes the comment on a public/private key file pair. Agent ag Runs as an authentication agent. Add a+ Adds a key to an existing authentication agent. Delete a-1 Deletes a key from an existing authentication agent. List a? Lists the keys held by an authentication agent. Delete-all a-* Deletes all keys from an authentication agent. Export exp Exports a key from moussh's format to the standard public-key file format. Import imp Imports a key to moussh's format from the standard public-key file format. Options are marked with a set of short codes in { }, indicating what operation modes the option is useful in, exceot for options that set the operation mode, which are marked with the pseudo-mode "op" and an equal sign with the mode they set (eg, -server is marked {op=s}). Most options are actually accepted in all modes but are ignored except by the modes they are designed for use with. {all} is used for options that apply to all, or almost all, of the modes. -import {op=imp} Read a series of standard public-key file blobs on stdin; write the same key in the format moussh uses on stdout. The Comment: header is converted to the key comment; other headers are ignored. -export {op=exp} Read a series of keys in moussh's format on stdin; write the same keys as standard public-key file blobs on stdout. The key comment is converted to a Comment: header. No Subject: header is generated, unless -user is given (or equivalent), in which case that supplies the Subject: header value. -host HOST {c} Specify host unambiguously. (The first non-option argument in client mode is treated as if it had -host before it, so the -host flag is needed only when the argument begins, or might begin, with a dash.) If the command's name (the basename of argv[0]) is neither "ssh" nor "moussh", it is taken as a host name, as if it appeared on the command line before any other arguments. -nohost {c} Clear any host that may be set. This is most useful when the command's name is not one of the recognized names, to regain the argument-list semantics that are present when it is, but it can be used to discard a host set either with -host or without any flag at all. It is not an error if no host is set. -port PORT {c,s} In client mode, specify the port number to connect to. In this mode, if multiple -port options are given, each is tried in order until one succeeds (or the list is exhausted). In server mode, specify a port number to listen on. In this mode, the argument may actually be ADDR/PORT, which listens on just a particular address (the default is to listen on all available addresses for all supported protocols); multiple -port options specify multiple ports (and possibly associated addresses) to listen for connections on. The ADDR portion, when a slash is given, may be a numeric address or a hostname; if a hostname is given, all of its addresses are listened on. If no -port options at all are given, a default equivalent to specifying just one, with argument "22", is supplied. -share-server PATH {c} Specify shared-client server mode. See below for more on shared-client modes. -share-client PATH {c} Specify shared-client client mode. See below for more on shared-client modes. -auto-share SHAREPATH LOCKPATH {c} Specify auto shared-client mode. See below for more on shared-client modes. -auto-share-timeout SECONDS {c} Specify a sharing server timeout for auto shared-client mode. See below for more on shared-client modes. -nothing {c} Specify that no shell or command is to be executed on the remote machine. This is intended for use when all you want is to set up a connection and (eg) forwarding, without actually doing anything on the server host immediately. This is not what you want if you want to do an auto-share run to get a sharing server started if it's not already but don't want to do anything but start the server; for that, see -just-die. -just-die {c} Specify that no shell or command is to be executed on the remote machine; at that point, exit, rather than requesting a shell, a command execution, or (with -nothing) hanging. This is intended for use with -auto-share, to just start the sharing server and get it to authenticate, but not do anything further. -kex ALGS {c,s} -hk ALGS {c,s} -enc ALGS {c,s} -mac ALGS {c,s} -comp ALGS {c,s} -ua ALGS {c,s} Specify key-exchange (-kex), host-key (-hk), encryption (-enc), MAC (-mac), compression (-comp), or user authentication (-ua) algorithms. There is a list of supported algorithms for each of these, which can be obtained by passing a single ? as argument. There is a default list of algorithms, which for most of these is all supported algorithms in some default order; the list of algorithms starts with this default list and is modified by the options, applied in the order they appear on the command line. The ALGS argument can be: - The word DEFAULT, all caps: discards the current list and resets the current list to the default list. - The word CLEAR, all caps: discards the current list and leave it empty. - A comma-separated list of algorithms: discards the current list and replaces it with the list given. The first-listed algorithm is in the most-preferred spot. - A + followed by a comma-separated list of algorithms: the algorithms listed are moved to the head of the list (the most preferred positions), adding them to the list if necessary. The first-listed algorithm ends up in the most-preferred spot. - +- followed by a comma-separated list of algorithms: the algorithms listed are moved to the tail of the list (the least preferred positions), adding them to the list if necessary. The first-listed algorithm ends up most preferred of the affected algorithms (which collectively end up in the least-preferred spots). - A - followed by a comma-separated list of algorithms: the algorithms listed are removed from the list entirely. An unrecognized algorithm name is an error, but a recognized algorithm that is not currently in the list is not. The resulting list is the list offered during algorithm negotiation, for all but -ua; for -ua, the resulting list is the list of algorithms offered (for server mode) or attempted (for client mode). -enc-c2s {c,s} -enc-s2c {c,s} -mac-c2s {c,s} -mac-s2c {c,s} -comp-c2s {c,s} -comp-s2c {c,s} Just like -enc, -mac, and -comp except they apply to only the client->server (c2s) or server->client (s2c) direction, whereas the unsuffixed forms apply to both directions. -lang-c2s {c,s} -lang-s2c {c,s} Specify the languages list to be sent to the peer for the client->server (c2s) or server->client (s2c) direction. By default, these lists are empty. -lang {c,s} Specifies both -lang-c2s and -lang-s2c with just one option. -l USER {c,exp} -user USER {c,exp} -remuser USER {c,exp} In client mode, specify the remote user to (try to) authenticate as, defaulting to "$USER"; in export mode, specify the contents of the generated Subject: header, with the default being to omit the header. -sshdir DIR {all} Specify the directory to look for administrative files (such as identities) in. The default is "$HOME/.moussh" in most modes, but in server mode when started by root, a fixed compiled-in path is used; at this writing, that path is /local/etc/moussh. This directory, whether defaulted or not, is referred to as SSHDIR elsewhere. -config PATH {all} Specify where to find the config file. Normally this is found in a default location (SSHDIR/config at this writing); this option allows you to specify where it is. -noconfig {all} Specify that no config file is to be read. -hkdb PATH {c} Specify the file containing the database of known host keys. Default is "SSHDIR/known-hosts". -nohk ACTION {c} Specifies what to do if no host key is on record for the server. The default in this case is to prompt the user for what to do. The ACTION can be the string "prompt", which restores the default behaviour of prompting the user, or one of the actions the user can specify when prompted: "yes" to accept the host key for this connection but not save it; "no" to reject the host key (and thus abort the connection); or "save" to accept the host key and save it for future use. (Compare with -badhk.) Note that careless use of this option can compromise security by accepting bogus host keys and thereby leaving the connection open to man-in-the-middle attacks. -badhk ACTION {c} Specifies what to do if a host key is on record for the server but the recorded host key doesn't match the host key received from the server. The default in this case is to prompt the user for what to do. The ACTION can be the string "prompt", which restores the default behaviour of prompting the user, or one of the actions the user can specify when prompted: "yes" to accept the host key for this connection but not do anything to the saved-keys file; "no" to reject the host key (and thus abort the connection); "replace" to accept the host key and replace all saved keys for this host and algorithm with the new one; "replall" to accept the host key and replace all saved keys for this host; or "add" to accept the host key and add it to the list of keys for this host, without deleting anything. (Compare with -nohk.) ("host" actually means "host-key database lookup key", which can be set arbitrarily from the config file and defaults to host-name/port-number (eg, "bigbox/22"). Note that use of actions other than "no" is dangerous from a security standpoint, as that leaves the connection vulnerable to man-in-the-middle attacks. "replace" and "replall" in particular should never be used unless you are certain the real host key for the server you are trying to connect to has been changed. The actions which modify the known-hosts database are dangerous in a non-cryptographic way as well: if two concurrent runs try to modify the same known-hosts database at the same time, it is possible to corrupt the database. -randfile PATH {c,s,kg} Specifies where to find the randomness pool file. Default is "SSHDIR/random-pool". -authkeydir PATH {c} Specifies a directory to look for public-key files in. This directory is called AUTHKEYDIR below. Default is SSHDIR. -authkey PATH {c} Specifies the name of a file to look in for a public-key identity. If the argument contains a slash, it is used directly as a pathname; otherwise, it is looked for in AUTHKEYDIR. This option may be given multiple times to name multiple files. If no -authkey options are given at all, the default is to look for the default file name for each algorithm supported (each algorithm has a default name). -noagent {c} Disables use of the authentication agent for public-key authentication. -hostkeydir PATH {s} Specifies the directory where host key files are kept. Default is a fixed compiled-in path; at this writing, that path is /local/etc/moussh/hostkeys. -setpass {op=sp} -setpassphrase {op=sp} Specifies set-passphrase mode. -setcomm {op=sc} -setcomment {op=sc} Specifies set-comment mode. -keyfile msut be given. -keygen {op=kg} Specifies key-generation mode. -keytype must be given. -keytype TYPE {kg} Specifies the type of key to generate. Use a TYPE string of just a single ? to get a list. -keysize BITS {kg} Specifies the size of the key to generate, in bits. There may be minimum sizes; specifying ridiculously small sizes may produce an error or may use some default size. -keyfile PATH {kg} Specifies the base name of the key file pair to write the generated key into. If not specified, a default depending on key type is used. -keyfile-pub PATH {kg} -keyfile-priv PATH {kg} Specifies the name of the public (-keyfile-pub) or private (-keyfile-priv) portion of the key file pair to write the generated key into. You should need this only in very unusual circumstances. -passphrase PHRASE {c,kg,sp,a+} Specifies a passphrase to use when trying to read public-key files (client, setpass, or add) or when writing public-key files (keygen). This option destroys the command-line string as soon as possible, but it is still vulnerable to snooping with programs such as ps(1) briefly; the possible security exposure should be weighed carefully before using it. -comment COMMENT {kg,sc} Specifies the comment to set on a public key, either when it is being generated or when the comment is being changed. When generating a key, this defaults to $USER@`hostname`, or (unknown)@`hostname` if $USER is not set; when changing an existing key's comment, the default is to read the new comment interactively. -e ESCCHAR {c} -esc ESCCHAR {c} Specifies the escape character to use in client mode. This is used only when talking to a tty locally. If the argument is the string "none", there is no escape character, and the connection is transparent. Otherwise, the character specified allows various special operations when it is typed immediately following a newline. If the argument is a single-character string, that character is the escape character; if it is ^ followed by a single character, the escape character is the corresponding control character; if it is a single character with one or more c- and/or m- prefixes, it is the corresponding control and/or meta character; and if it is "0x" or "0X" followed by two hexadecimal digits, it is that octet. Anything else is an error. -agent {op=ag} -add {op=a+} -list {op=a?} -delete {op=a-1} -delete-all {op=a-*} Specifies agent, add, list, delete, or delete-all mode. -long {a?} Specifies a long listing. Normally only the comment is printed from each key. With -long, the public key data blob is printed as well. -server {op=s} Specifies server mode. -oneconn {s} Specifies that only one connection is to be handled, and that the server is not to fork to handle the connection. (This greatly eases debugging in many cases.) -V arg {all} Turns on verbosity. The argument consists of one or more keywords, separated with commas, optionally with an equal sign and a destination to send verbose output to appended; optionally, there may be multiple such, separated from one another with whitespace (note that whitespace will usually need quoting to protect it from the shell, though you can simply use multiple -V options to get the same effect). Using an arg consisting of just a single ? will give you a brief help message, including a list of recognized keywords. The list changes too rapidly to keep it up to date here. -v Identical in effect to "-V default". -L [LHOST/]LPORT/RHOST/RPORT {c} -R [RHOST/]RPORT/LHOST/LPORT {c} Specifies TCP connection forwarding. The local process (if -L) or server (if -R) is instructed to listen for connections on the first port number, with a wildcard address if the first hostname is not specified, or on only that hostname if it is given; such connections are forwarded through to the other end of the connection, which then connects to the second host on the second port. (The first port, and host if given, are where the listening takes place; the second host/port pair are where the connection is forwarded to. -L listens on the client and forwards to the server; -R listens on the server and forwards to the client.) -fwd WHAT {c,s} -nofwd WHAT {c,s} Specifies that the thing identified by WHAT is to be forwarded (-fwd) or not forwarded (-nofwd). For the client, this controls whether forwarding is requested (assuming it's not disabled for some other reason); for the server, whether forwarding will be supported if the client asks for it. Use a WHAT string of just a single ? for a list of recognized WHAT values. -n {c} Specifies that the client is to ignore its input. (This actually works by redirecting input from /dev/null.) -f {c} Specifies that the client is to fork and background itself as soon as it has completed startup and established all command-line forwarding. (When the client backgrounds itself, it also redirects its standard output and error to /dev/null.) -neverauth {s} Specifies that authentication is never to succeed, no matter what authentication information may be presented. Exactly what effects this has depends on what authentication method the client tries. This option is intended for interop testing of layers below the authentication layer (such as new crypto algorithms), but it may find other uses such as honeypots. -nointer {all} Specifies that no user interaction is to take place. Prompting for things such as key passphrases, authentication passwords, actions such as described for "-nohk prompt", is disabled. Some presumably-sensible default is chosen for cases where no information is provided through other mechanisms (the -nohk option is an example of such a mechanism). -cmd {all} -- {all} Either flag indicates that all further arguments form a command to execute on the remote host. If there are no further arguments, an interactive login will be done. The first non-flag argument not claimed by a flag is taken as if -host had been given before it. If another non-flag argument is found, it and all further arguments are taken as a command to execute, as if -cmd had been given before it. (This admittedly may not be the Right Thing when operating in a mode that doesn't use -host, such as share-client mode: "moussh -share-client foo date" does a rendezvous at "foo" and then runs an interactive login, not the "date" command, because the "date" is taken as "-host date" and there is then no command, leading to the interactive login. Since -share-client will normally not be used - -auto-share is preferable in most circumstances - and there are no other modes which ignore -host but do remote work, and since sharing will normally be turned on through the config file rather than the command line, I do not consider this a big problem.) Shared-client and shared-server modes allow one client<->server connection to handle multiple concurrent sessions. In this mode, one run with -share-server is done, which just sets up the connection and establishes a rendezvous socket at the path named as an argument (and also acts as a normal client, as controlled by its other arguments); then, a later client run can specify -share-client. -share-client takes a similar pathname argument and uses it to talk to the share server. Because of protocol design botches, shared-client mode is incompatible with standard agent, X11, or TCP connection forwarding. This implementation supports non-botched variants of these forwardings which work fine in shared-client mode, but which will not interoperate with a peer which knows only the standardized variants; when talking with a server that does not support these `fixed' requests, forwarding will not work at all for shared-client sessions. There also is auto-share mode. In this case, two paths must be provided. The first is used as for -share-client and -share-server; a rendezvous socket is created there. The second must name a file; it is used as a lock file to resolve races that can otherwise cause trouble. (The same lock file can serve for many rendezvous points; also, its contents are irrelevant - moussh does not do anything with the contents.) Normally, the sharing server process lasts forever, holding the server connection open. -auto-share-timeout can be given to specify an idle timeout for it; the argument is in seconds, and if that long passes without there being any sharing clients, the sharing server will exit. (A timeout of zero directs the sharing server to exit as soon as it has no clients; any value less than zero means no timeout.) There are some issues surrounding forwarding - agent forwarding, X11 forwarding, and TCP connection forwarding. The standard requests for these are somewhat broken, in that they do not work correctly in the presence of multiple sessions. This implementation supports fixed versions of these requests which permit correct operation even in the presence of multiple sessions. For agent forwarding, if the `fixed' request is refused, a standard request is made; this permits agent forwarding to mostly work, but does open up a minor potential attack, in that if some but not all session channels have requested agent forwarding, the client has no way of telling whether an incoming forwarded agent connection corresponds to a session for which agent forwarding has been requested or one for which it has not. (This is only a minor attack because if the server is malicious it could just as easily pretend the agent request corresponds to a channel for which forwarding has been requested.) For X11 forwarding, the situation is even worse; there is no fallback to the standard request - only the `fixed' request works. For TCP connection forwarding, there is a fallback mechanism similar to the one for agent forwarding (and with similar caveats). There is a client command-line that has nothing to do with the command line as typed to start the program. This is entered by typing % after the escape character, as indicated in the help output that results from typing a ? after the escape character. This command line allows controlling a number of interesting aspects of the client's operation; experimentation is encouraged - there is internal help for most of the commands available. The protocol uses strings at a number of points (such as usernames) for which the spec demands UTF-8 encoding. However, we don't have character strings; we have octet strings. Despite much discussion on the list, I never got any clear direction what the correct thing to do in such circumstances is. We can't recode to UTF-8, since we don't know what characters the octets correspond to. (Various people have made plausible arguments that they do correspond to characters in human minds, but as few machines are equipped with the mind-reading peripheral necessary to get at that information, this is little help even for those who find the arguments convincing.) Most of the discussion seemed to be unhelpful comments along the lines of "but you should be using character strings rather than octet strings for usernames, because it does what naïve users expect in more circumstances" - arguably good advice for OS designers, but no help whatever for implementors who have to deal with existing OSes. moussh treats such things as opaque octet sequences. Thus, moussh will not, strictly, be conformant to the spec unless you always use UTF-8 for such strings (including such places as the passwd database). Note that sticking to ASCII satisfies this, so most systems, at least in English-using areas, probably conform already. /~\ The ASCII der Mouse \ / Ribbon Campaign X Against HTML mouse@rodents.montreal.qc.ca / \ Email! 7D C8 61 52 5D E7 2D 39 4E F1 31 3E E8 B3 27 4B