1MOSH(1)                     General Commands Manual                    MOSH(1)
2
3
4

NAME

6       mosh - mobile shell with roaming and intelligent local echo
7

SYNOPSIS

9       mosh [options] [--] [user@]host [command...]
10

DESCRIPTION

12       mosh  (mobile  shell)  is  a  remote terminal application that supports
13       intermittent connectivity, allows  roaming,  and  provides  speculative
14       local echo and line editing of user keystrokes.
15
16       Compared with ssh, mosh is more robust — its connections stay up across
17       sleeps and changes in the client's IP address —  and  more  responsive,
18       because the protocol is tolerant of packet loss and the client can echo
19       most keystrokes immediately, without waiting for a network round-trip.
20
21       mosh uses ssh to establish a connection to the remote host and  authen‐
22       ticate  with existing means (e.g., public-key authentication or a pass‐
23       word). mosh executes the unprivileged mosh-server helper program on the
24       server,  then  closes  the  SSH  connection and starts the mosh-client,
25       which establishes a long-lived datagram connection over UDP.
26
27       To improve responsiveness, mosh runs a predictive model of the server's
28       behavior  in  the  background,  trying to guess the effect of each key‐
29       stroke  on  the  screen.  It  makes  predictions  for  normal   typing,
30       backspace,  and  the  left- and right-arrow keys. When it is confident,
31       mosh displays the predictions without waiting for the server. The  pre‐
32       dictive  model  must  prove itself anew on each row of the terminal and
33       after each control character, so mosh avoids echoing passwords or  non-
34       echoing editor commands.
35
36       By default, mosh shows its predictions only on high-latency connections
37       and to smooth out network glitches. (On longer-latency links, the  pre‐
38       dicted  cells are underlined until confirmed by the server.) Occasional
39       echo mistakes are corrected within a  network  round-trip  and  do  not
40       cause lasting effect.
41
42       mosh  does not support X forwarding or the non-interactive uses of SSH,
43       including port forwarding or sshfs. mosh works through typical  client-
44       side  network  address  translators  but  requires  UDP to pass between
45       client and server. By default, mosh uses the ports  between  60000  and
46       61000, but allows the user to request a particular UDP port instead.
47
48       Currently,  mosh has limited support for IPv6, dual-stack networks, and
49       servers with multiple addresses.  At session start, it  will  select  a
50       single  IPv4  or  IPv6 server address to connect to for the lifetime of
51       the session.
52
53       mosh will do its best to arrange a UTF-8 character set  locale  on  the
54       client  and  server.  The  client  must have locale-related environment
55       variables that specify UTF-8. mosh will pass these client variables  to
56       the  mosh-server  on  its command line, but in most cases they will not
57       need to be used. mosh-server first attempts  to  use  its  own  locale-
58       related  environment variables, which come from the system default con‐
59       figuration (sometimes /etc/default/locale) or from having  been  passed
60       over  the SSH connection. But if these variables don't call for the use
61       of UTF-8, mosh-server will apply the locale-related  environment  vari‐
62       ables from the client and try again.
63
64

OPTIONS

66       Options  named   --experimental-*  are  subject to change or removal in
67       future versions of Mosh; their design or function is not yet final.
68
69
70       command
71              Command to run on remote host. By default, mosh executes a login
72              shell.
73
74
75       --client=PATH
76              path to client helper on local machine (default: "mosh-client")
77
78
79       --server=COMMAND
80              command  to run server helper on remote machine (default: "mosh-
81              server")
82
83              The server helper is unprivileged and can be  installed  in  the
84              user's home directory.
85
86              This  option  can  be  used to set environment variables for the
87              server by using the env(1) command to  wrap  the  actual  server
88              command.   See  mosh-server(1)  for  available environment vari‐
89              ables.
90
91
92       --ssh=COMMAND
93              OpenSSH  command  to  remotely  execute  mosh-server  on  remote
94              machine (default: "ssh")
95
96              An alternate ssh port can be specified with, e.g., --ssh="ssh -p
97              2222".
98
99
100       --ssh-pty
101              --no-ssh-pty Enable or disable ssh's use of a pty when  connect‐
102              ing to a remote host.  The default is enabled.
103
104
105       --predict=WHEN
106              Controls  use of speculative local echo. WHEN defaults to `adap‐
107              tive' (show predictions on slower links and to smooth  out  net‐
108              work glitches) and can also be `always` or `never'.
109
110              The  MOSH_PREDICTION_DISPLAY  environment variable controls this
111              setting permanently and can adopt the same three values.
112
113              Even on `always', mosh will only show  predictions  when  it  is
114              confident.  This  generally  means  a previous prediction on the
115              same row of the terminal has been confirmed by the server, with‐
116              out any intervening control character keystrokes.
117
118
119       -a     Synonym for --predict=always
120
121
122       -n     Synonym for --predict=never
123
124
125       --family=inet
126              Only use IPv4 for the SSH connection and Mosh session.
127
128
129       --family=inet6
130              Only use IPv6 for the SSH connection and Mosh session.  This and
131              the   following   modes   require   Perl's   IO::Socket::IP   or
132              IO::Socket::INET6 modules.
133
134
135       --family=auto
136              Autodetect  IPv4 or IPv6 for hosts that only have addresses in a
137              single family.  Hosts with both IPv4  and  IPv6  addresses  will
138              raise  an  error, and require re-invocation of mosh with another
139              --family option.
140
141
142       --family=all
143              Choose an address from all available IPv4 or IPv6 address,  even
144              for  dual-stack  hosts.  This is the most convenient option, but
145              requires dual-stack connectivity, and Mosh 1.2.5 or later on the
146              server, when roaming with dual-stack servers.
147
148
149       --family=prefer-inet
150              Similar  to  --family=all,  but  attempt  connects  to  the IPv4
151              addresses first.  This is the default.
152
153
154       --family=prefer-inet6
155              Similar to  --family=all,  but  attempt  connects  to  the  IPv6
156              addresses first.
157
158
159       -4     Synonym for --family=inet
160
161
162       -6     Synonym for --family=inet6
163
164
165       -p PORT[:PORT2], --port=PORT[:PORT2]
166              Use  a  particular server-side UDP port or port range, for exam‐
167              ple, if this is the only port that is forwarded through a  fire‐
168              wall to the server. With -p 0, the server will let the operating
169              system pick an available UDP port. Otherwise, mosh will choose a
170              port  between 60000 and 61000. Please note that this option does
171              not affect the server-side port used by SSH.
172
173
174       --bind-server={ssh|any|IP}
175              Control the IP address that the mosh-server binds to.
176
177              The default is `ssh', in which case the server will  reply  from
178              the  IP  address  that the SSH connection came from (as found in
179              the SSH_CONNECTION environment variable).  This  is  useful  for
180              multihomed servers.
181
182              With  --bind-server=any,  the  server  will reply on the default
183              interface and will not bind to a particular IP address. This can
184              be useful if the connection is made through sslh or another tool
185              that makes the SSH connection appear to come from localhost.
186
187              With --bind-server=IP, the server will attempt to  bind  to  the
188              specified IP address.
189
190
191       --no-init
192              Do not send the smcup initialization string and rmcup deinitial‐
193              ization string to the client's terminal. On many terminals  this
194              disables alternate screen mode.
195
196
197       --local
198              Invoke  mosh-server  locally,  without  using  ssh.  This option
199              requires the host argument to  be  a  local,  numeric  IPv4/IPv6
200              address.  This option is useful for testing.
201
202
203       --experimental-remote-ip={proxy|local|remote}
204              Select the method used to discover the IP address that the mosh-
205              client connects to.
206
207              The default  is  proxy,  which  uses  SSH's  --ssh-proxy-command
208              option to generate and report the exact address that ssh uses to
209              connect to the remote host.  This option is generally  the  most
210              compatible  with  hosts and other options configured in ssh con‐
211              figuration files.  However, this may not work for some  configu‐
212              rations,  or  for environments where a ssh bastion host forwards
213              to a remote machine.  It only works with OpenSSH.
214
215              With remote, the server's  SSH_CONNECTION  environment  variable
216              will  be  used.   This is useful for environments where ssh for‐
217              warding is used, or the --ssh-proxy-command option is  used  for
218              other purposes.
219
220              With  local,  Mosh  resolves  the  hostname given on its command
221              line, and uses that address for both ssh and  Mosh  connections.
222              This option ignores any configuration in ssh_config for the same
223              hostname.
224
225

ESCAPE SEQUENCES

227       The default escape character used by Mosh is  ASCII  RS  (decimal  30).
228       This  is  typically typed as Ctrl-^ or Ctrl-Shift-6, on US English key‐
229       boards.  Users of non-English keyboards may find it difficult or impos‐
230       sible  to type the default escape character, and may need to change the
231       escape character.  See the description of MOSH_ESCAPE_KEY,  below.   In
232       this  description,  the  configured  escape character is represented as
233       Esc.
234
235       There are two slightly different modes for escape sequences,  depending
236       whether the escape character is printable or not.
237
238       If  the  escape character is a printable character, it must be prefixed
239       with a newline, similar to  OpenSSH.   To  send  the  escape  character
240       itself,  type it twice.  If the escape character is set to ~, mosh will
241       behave much like OpenSSH.
242
243       If the escape character is a non-printable control character, no prefix
244       is  used  and  the escape character is recognized at any time.  To send
245       the escape character itself, type the escape character, then its corre‐
246       sponding  ASCII  character (for Ctrl-^ you would type ^, for Ctrl-B you
247       would type B).
248
249       The escape sequence to shut down the connection is Esc .. The  sequence
250       Esc Ctrl-Z suspends the client.  Any other sequence passes both charac‐
251       ters through to the server.
252
253

ENVIRONMENT VARIABLES

255       These variables are not actually interpreted by mosh(1) itself, but are
256       passed  through to mosh-server(1).  They are described here for ease of
257       use.
258
259
260       MOSH_ESCAPE_KEY
261              When set, this configures the escape character  used  for  local
262              commands.   The escape character may be set to any ASCII charac‐
263              ter in the range 1-127.  The variable must be set with a  single
264              literal  ASCII  character.   Control characters are set with the
265              actual ASCII control character, not with a printable representa‐
266              tion such as "^B".
267
268
269       MOSH_PREDICTION_DISPLAY
270              Controls  local  echo as described above.  The command-line flag
271              overrides this variable.
272
273
274       MOSH_TITLE_NOPREFIX
275              When set, inhibits prepending "[mosh]" to window title.
276
277

SEE ALSO

279       mosh-client(1), mosh-server(1).
280
281       Project home page: https://mosh.org
282
283

AUTHOR

285       mosh was written by Keith Winstein <mosh-devel@mit.edu>.
286

BUGS

288       Please report bugs to mosh-devel@mit.edu. Users may also  subscribe  to
289       the mosh-users@mit.edu mailing list, at
290       http://mailman.mit.edu/mailman/listinfo/mosh-users
291
292
293
294
295                                  April 2013                           MOSH(1)
Impressum