.\" Hey, EMACS: -*- nroff -*- .\" First parameter, NAME, should be all caps .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection .\" other parameters are allowed: see man(7), man(1) .TH MOSH 1 "April 2013" .\" Please adjust this date whenever revising the manpage. .\" .\" Some roff macros, for reference: .\" .nh disable hyphenation .\" .hy enable hyphenation .\" .ad l left justify .\" .ad b justify to both left and right margins .\" .nf disable filling .\" .fi enable filling .\" .br insert line break .\" .sp insert n+1 empty lines .\" for manpage-specific macros, see man(7) .SH NAME mosh \- mobile shell with roaming and intelligent local echo .SH SYNOPSIS .B mosh .RI [ options ] [--] [user@]host [command...] .br .SH DESCRIPTION \fBmosh\fP (mobile shell) is a remote terminal application that supports intermittent connectivity, allows roaming, and provides speculative local echo and line editing of user keystrokes. Compared with \fBssh\fP, \fBmosh\fP is more robust \(em its connections stay up across sleeps and changes in the client's IP address \(em and more responsive, because the protocol is tolerant of packet loss and the client can echo most keystrokes immediately, without waiting for a network round-trip. \fBmosh\fP uses \fBssh\fP to establish a connection to the remote host and authenticate with existing means (e.g., public-key authentication or a password). \fBmosh\fP executes the unprivileged \fBmosh-server\fP helper program on the server, then closes the SSH connection and starts the \fBmosh-client\fP, which establishes a long-lived datagram connection over UDP. To improve responsiveness, \fBmosh\fP runs a predictive model of the server's behavior in the background, trying to guess the effect of each keystroke on the screen. It makes predictions for normal typing, backspace, and the left- and right-arrow keys. When it is confident, \fBmosh\fP displays the predictions without waiting for the server. The predictive model must prove itself anew on each row of the terminal and after each control character, so \fBmosh\fP avoids echoing passwords or non-echoing editor commands. By default, \fBmosh\fP shows its predictions only on high-latency connections and to smooth out network glitches. (On longer-latency links, the predicted cells are underlined until confirmed by the server.) Occasional echo mistakes are corrected within a network round-trip and do not cause lasting effect. \fBmosh\fP does not support X forwarding or the non-interactive uses of SSH, including port forwarding or sshfs. \fBmosh\fP works through typical client-side network address translators but requires UDP to pass between client and server. By default, \fBmosh\fP uses the ports between 60000 and 61000, but allows the user to request a particular UDP port instead. \fBmosh\fP will do its best to arrange a UTF-8 character set locale on the client and server. The client must have locale-related environment variables that specify UTF-8. \fBmosh\fP will pass these client variables to the \fBmosh-server\fP on its command line, but in most cases they will not need to be used. \fBmosh-server\fP first attempts to use its own locale-related environment variables, which come from the system default configuration (sometimes /etc/default/locale) or from having been passed over the SSH connection. But if these variables don't call for the use of UTF-8, \fBmosh-server\fP will apply the locale-related environment variables from the client and try again. .SH OPTIONS .TP .B \fIcommand\fP Command to run on remote host. By default, \fBmosh\fP executes a login shell. .TP .B \-\-client=\fIPATH\fP path to client helper on local machine (default: "mosh-client") .TP .B \-\-server=\fICOMMAND\fP command to run server helper on remote machine (default: "mosh-server") The server helper is unprivileged and can be installed in the user's home directory. .TP .B \-\-ssh=\fICOMMAND\fP OpenSSH command to remotely execute mosh-server on remote machine (default: "ssh") An alternate ssh port can be specified with, \fIe.g.\fP, \-\-ssh="ssh \-p 2222". .TP .B \-\-predict=\fIWHEN\fP Controls use of speculative local echo. WHEN defaults to `adaptive' (show predictions on slower links and to smooth out network glitches) and can also be `always` or `never'. The MOSH_PREDICTION_DISPLAY environment variable controls this setting permanently and can adopt the same three values. Even on `always', \fBmosh\fP will only show predictions when it is confident. This generally means a previous prediction on the same row of the terminal has been confirmed by the server, without any intervening control character keystrokes. .TP .B \-a Synonym for \-\-predict=always .TP .B \-n Synonym for \-\-predict=never .TP .B --family=\fIFAMILY\fP Force the use of a particular address family, which defaults to `inet' (IPv4), and can also be `inet6' (IPv6; requires IO::Socket::IP or IO::Socket::INET6). .TP .B -4 Synonym for \-\-family=inet .TP .B -6 Synonym for \-\-family=inet6 .TP .B \-p \fIPORT\fP[:\fIPORT2\fP], \-\-port=\fIPORT\fP[:\fIPORT2\fP] Use a particular server-side UDP port or port range, for example, if this is the only port that is forwarded through a firewall to the server. Otherwise, \fBmosh\fP will choose a port between 60000 and 61000. .TP .B \-\-bind\-server={ssh|any|\fIIP\fP} Control the IP address that the \fBmosh-server\fP binds to. The default is `ssh', in which case the server will reply from the IP address that the SSH connection came from (as found in the \fBSSH_CONNECTION\fP environment variable). This is useful for multihomed servers. With \-\-bind\-server=any, the server will reply on the default interface and will not bind to a particular IP address. This can be useful if the connection is made through \fBsslh\fP or another tool that makes the SSH connection appear to come from localhost. With \-\-bind\-server=\fIIP\fP, the server will attempt to bind to the specified IP address. .TP .B \-\-no\-init Do not send the \fBsmcup\fP initialization string and \fBrmcup\fP deinitialization string to the client's terminal. On many terminals this disables alternate screen mode. .SH ESCAPE SEQUENCES The default escape character used by Mosh is ASCII RS (decimal 30). This is typically typed as \fBCtrl-^\fP or \fBCtrl-Shift-6\fP, on US English keyboards. Users of non-English keyboards may find it difficult or impossible to type the default escape character, and may need to change the escape character. See the description of MOSH_ESCAPE_KEY, below. In this description, the configured escape character is represented as \fBEsc\fP. There are two slightly different modes for escape sequences, depending whether the escape character is printable or not. If the escape character is a printable character, it must be prefixed with a newline, similar to \fBOpenSSH\fP. To send the escape character itself, type it twice. If the escape character is set to \fB~\fP, \fBmosh\fP will behave much like \fBOpenSSH\fP. If the escape character is a non-printable control character, no prefix is used and the escape character is recognized at any time. To send the escape character itself, type the escape character, then its corresponding ASCII character (for \fBCtrl-^\fP you would type \fB^\fP, for \fBCtrl-B\fP you would type \fBB\fP). The escape sequence to shut down the connection is \fBEsc .\fP. The sequence \fBEsc Ctrl-Z\fP suspends the client. Any other sequence passes both characters through to the server. .SH ENVIRONMENT VARIABLES These variables are not actually interpreted by .BR mosh (1) itself, but are passed through to .BR mosh-server (1). They are described here for ease of use. .TP .B MOSH_ESCAPE_KEY When set, this configures the escape character used for local commands. The escape character may be set to any ASCII character in the range 1-127. The variable must be set with a single literal ASCII character. Control characters are set with the actual ASCII control character, not with a printable representation such as "^B". .TP .B MOSH_PREDICTION_DISPLAY Controls local echo as described above. The command-line flag overrides this variable. .TP .B MOSH_TITLE_NOPREFIX When set, inhibits prepending "[mosh]" to window title. .SH SEE ALSO .BR mosh-client (1), .BR mosh-server (1). Project home page: .I http://mosh.mit.edu .br .SH AUTHOR mosh was written by Keith Winstein . .SH BUGS Please report bugs to \fImosh-devel@mit.edu\fP. Users may also subscribe to the .nh .I mosh-users@mit.edu .hy mailing list, at .br .nh .I http://mailman.mit.edu/mailman/listinfo/mosh-users .hy .