path: root/man/mosh.1

.\"                                      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 <n>    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.

Currently, \fBmosh\fP has limited support for IPv6, dual-stack
networks, and servers with multiple addresses.  At session start, it
will select a single IPv4 or IPv6 server address to connect to for the
lifetime of the session.

\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
Options named \fB \-\-experimental-*\fP are subject to change or
removal in future versions of Mosh; their design or function is not
yet final.

.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.

This option can be used to set environment variables for the server by
using the
.BR env (1)
command to wrap the actual server command.  See
.BR mosh-server (1)
for available environment variables.

.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 \-\-ssh-pty\fP
.B \-\-no-ssh-pty\fP
Enable or disable ssh's use of a pty when connecting to a remote host.
The default is enabled.

.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 \-\-predict\-overwrite\fP
When prediction is enabled, do not insert speculative local echo
before existing text, but overwrite it instead.

The MOSH_PREDICTION_OVERWRITE environment variable also enables this
if its value is 'yes'.

.TP
.B \-o
Synonym for \-\-predict\-overwrite

.TP
.B \-\-family=inet
Only use IPv4 for the SSH connection and Mosh session.

.TP
.B \-\-family=inet6
Only use IPv6 for the SSH connection and Mosh session.  This and the
following modes require Perl's IO::Socket::IP or IO::Socket::INET6
modules.

.TP
.B \-\-family=auto
Autodetect IPv4 or IPv6 for hosts that only have addresses
in a single family.  Hosts with both IPv4 and IPv6 addresses will
raise an error, and require re-invocation of \fBmosh\fP with another
\fB\-\-family\fP option.

.TP
.B \-\-family=all
Choose an address from all available IPv4 or IPv6 address, even for
dual-stack hosts.  This is the most convenient option, but requires
dual-stack connectivity, and Mosh 1.2.5 or later on the server, when
roaming with dual-stack servers.

.TP
.B \-\-family=prefer-inet
Similar to \fB\-\-family=all\fP, but attempt connects to the IPv4
addresses first.  This is the default.

.TP
.B \-\-family=prefer-inet6
Similar to \fB\-\-family=all\fP, but attempt connects to the IPv6
addresses first.

.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. With \fB\-p 0\fP, the server will let the operating system pick an
available UDP port. Otherwise, \fBmosh\fP will choose a port between 60000 and
61000. Please note that this option does not affect the server-side
port used by SSH.

.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.

.TP
.B \-\-local
Invoke \fBmosh-server\fP locally, without using \fBssh\fP.  This
option requires the \fBhost\fP argument to be a local, numeric
IPv4/IPv6 address.  This option is useful for testing.

.TP
.B \-\-experimental\-remote\-ip={proxy|local|remote}
Select the method used to discover the IP address that the
\fBmosh-client\fP connects to.

The default is \fBproxy\fP, which uses SSH's
.B \-\-ssh\-proxy\-command
option to generate and report the exact address that \fBssh\fP uses to
connect to the remote host.  This option is generally the most
compatible with hosts and other options configured in \fBssh\fP
configuration files.  However, this may not work for some
configurations, or for environments where a \fBssh\fP bastion host
forwards to a remote machine.  It only works with \fBOpenSSH\fP.

With \fBremote\fP, the server's
.B SSH_CONNECTION
environment variable will be used.  This is useful for environments
where \fBssh\fP forwarding is used, or the
.B \-\-ssh\-proxy\-command
option is used for other purposes.

With \fBlocal\fP, Mosh resolves the hostname given on its command
line, and uses that address for both \fBssh\fP and Mosh connections.
This option ignores any configuration in
.B ssh_config
for the same hostname.

.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 https://mosh.org

.br
.SH AUTHOR
mosh was written by Keith Winstein <mosh-devel@mit.edu>.
.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
.