This is my ssh implementation, moussh. This file is a usage document; for a compilation document, see INSTALL. This file is likely to be somewhat out-of-date; the manpage (see moussh.1) is updated more frequently. 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. Fingerprint kfp Prints key fingerprints. Share-kill shk Share-stop shs Share-drop shd Manipulate connection-sharing servers. Int-agent ia Interactive access to the authentication agent. Known-hosts kh Manipulates the known-hosts database. 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 each key in the format moussh uses on stdout. The Comment: header is converted to the key comment; other headers are ignored. -ia {op=ia} Runs as an interactive front-end to the authentication agent. This works only for runs that would have agent acecss if they were client-mode runs, of course. -export {op=exp} Read a series of keys in moussh's format on stdin; write each key as a standard public-key file blob 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. -kfp {op=kfp} -fingerprint {op=kfp} Reads public-key blobs in moussh's format on stdin; for each one, writes a fingerprint, such as is printed with host-key prompts, to stdout. -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. -keepalive-net {c,s} -kan {c,s} Turns on network-layer keepalives. See setsockopt()'s SO_KEEPALIVE option. -keepalive-ssh {c,s} -kas {c,s} Turns on ssh-layer keepalives. These require AF_TIMER support to work. -share-server PATH {c} Specify shared-client server 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. -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. -no-share {c} Disables sharing, cancelling any earlier options that would normally have turned it on. See below for more on shared-client modes. -share-kill {op=shk} -share-stop {op=shs} -share-drop {op=shd} Manipulate an existing shared-client sharing server. See below for more on shared-client modes. -share-path {c} Specify the rendezvous path for shared-client sharing. 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. -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 they leave 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. moussh attempts to lock the file to guard against this, but it is difficult to do so perfectly, especially in the presence of remote filesystems such as NFS. -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). -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. -noagent {c} Disables use of the authentication agent for public-key authentication. -setpass {op=sp} -setpassphrase {op=sp} Specifies set-passphrase mode. -setcomm {op=sc} -setcomment {op=sc} Specifies set-comment mode. -keyfile must also be given. -keygen {op=kg} Specifies key-generation mode. -keytype must be given. -keyvalues {kg} Prints out full details about generated keys, including complete values for the numbers involved. This data is at least as sensitive as the private portion of the resulting key and should be protected accordingly if it is saved or displayed anywhere. -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-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 these only in very unusual circumstances. -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. -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. -server {op=s} Specifies server mode. -constraint CONSTRAINT {a+} Adds constraints to keys when adding them to the agent. This allows you to specify, for example, that a key may not be used through forwarding, or may not be used more than twice. CONSTRAINT can be: time=TIME TIME is a time value like "3d12h" or "15m"; the supported units are "w" (weeks), "d" (days), "h" (hours), "m" (minutes), and "s" (seconds). After this long, the agent will remove the key from use. use=N Maximum number of uses for this key; after the Nth public-key operation using this key, the agent will remove it from use. fwd=N Maximum forwarding depth; the key cannot be used or deleted by clients behind more than N forwarding hops. (It can still be listed by any client.) confirm=STR If STR is "no", this key does not require confirmation of use; if anything else, it does. Confirmation of use requires using the interactive agent interface; see -ia. Multiple constraints may be given, either by passing a comma-separted list to -constraint or by specifying multiple -constraint options. -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.) -long {a?} Asks for a long listing. When listing agent keys, normally, only the comment is printed from each key. With -long, the public key data blob is printed as well. This also suppresses the usual message if the agent has no keys, producing no output instead in that case. -tty {c} -no-tty {c} Causes moussh to request (-tty) or not request (-no-tty) a pseudo-tty from the server. By default, a pseudo-tty is requested for interactive logins but not when running remote commands. -v {all} Identical in effect to "-V default". -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. The exact argument syntax changes too rapidly to keep it up to date here. -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.) -syslog {all} -nosyslog {all} Causes printed error messages to go (-syslog) or not go (-nosyslog) to syslog as well as being printed. The default is -syslog in server mode and -nosyslog in other modes. -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.) -LL [LHOST/]LPORT/RHOST/RPORT {c} -RR [RHOST/]RPORT/LHOST/LPORT {c} These are just like -L and -R except that, if the forwarding cannot be established, moussh refuses to start. (With -L and -R, a failure to establish the forwarding does not prevent startup.) -fwd WHAT {c} -fwdonce WHAT {c} -nofwd WHAT {c} Specifies that the thing identified by WHAT is to be forwarded (-fwd), not forwarded (-nofwd), or forwarded for one connection but not more (-fwdonce). Use a WHAT string of just a single ? for a list of recognized WHAT values. -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. -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. -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). -fork-pause N {all} Whenever moussh forks, the child will wait for N seconds before continuing. (This is designed to aid debugging, not to be useful in normal operation.) -no-private N {c} moussh implements various private protocols and options. This prevents moussh from offering them to the server. This should never be necessary, but some servers misbehave in various ways when the client offers things they don't understand. -kh OP {op=kh} Performs various operations on the known-hosts database. See the manpage for full documentation. -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; for example, "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 and TCP connection forwarding, and to some extent with standard X11 forwarding. moussh 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, agent and TCP forwarding will not work at all for shared-client sessions, and X11 forwarding will fall back to the kludge described below. 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, there is a workaround; the MIT-MAGIC-COOKIE cookie can be used to disambiguate, so standard X11 forwarding should work thorugh shared-client sharing. (It may not seem like it, though, as at least one popular ssh server does not implement standard X11 forwarding, doing only its own private form of X11 forwarding.) For TCP connection forwarding, there is a fallback mechanism similar to the one for agent forwarding (and with similar caveats). There are three operation modes for manipulating a connection-sharing server directly: -share-kill, -share-stop, and -share-drop. They all contact a sharing server the same way as if moussh were operating in client mode, but they never start a new one if they can't contact an existing one. -share-kill causes the sharing server to die immediately; this causes existing sharing clients to see their connections break ungracefully. -share-stop causes it to continue to serve existing clients but to shut down as far as accepting new clients goes. -share-drop causes it to drop all existing clients but to continue accepting new clients (which are then served as normal). (-share-drop may seem useless, and most of the time it is, but I've occasionally found uses for it.) Sharing servers can be configured to ignore kill, stop, and/or drop requests. 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 Mouse \ / Ribbon Campaign X Against HTML mouse@rodents-montreal.org / \ Email! 7D C8 61 52 5D E7 2D 39 4E F1 31 3E E8 B3 27 4B