1MOSH(1) General Commands Manual MOSH(1)
2
6 mosh - mobile shell with roaming and intelligent local echo
7
9 mosh [options] [--] [user@]host [command...]
10
12 mosh (mobile shell) is a remote terminal application that supports in‐
13 termittent connectivity, allows roaming, and provides speculative local
14 echo and line editing of user keystrokes.
15 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 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 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 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 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 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 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-re‐
58 lated environment variables, which come from the system default config‐
59 uration (sometimes /etc/default/locale) or from having been passed over
60 the SSH connection. But if these variables don't call for the use of
61 UTF-8, mosh-server will apply the locale-related environment variables
62 from the client and try again.
63
66 Options named --experimental-* are subject to change or removal in fu‐
67 ture versions of Mosh; their design or function is not yet final.
68 command
71 Command to run on remote host. By default, mosh executes a login
72 shell.
73 --client=PATH
76 path to client helper on local machine (default: "mosh-client")
77 --server=COMMAND
80 command to run server helper on remote machine (default: "mosh-
81 server")
82 The server helper is unprivileged and can be installed in the
84 user's home directory.
85 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 --ssh=COMMAND
93 OpenSSH command to remotely execute mosh-server on remote ma‐
94 chine (default: "ssh")
95 An alternate ssh port can be specified with, e.g., --ssh="ssh -p
97 2222".
98 --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 --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 The MOSH_PREDICTION_DISPLAY environment variable controls this
111 setting permanently and can adopt the same three values.
112 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 -a Synonym for --predict=always
120 -n Synonym for --predict=never
123 --predict-overwrite
126 When prediction is enabled, do not insert speculative local echo
127 before existing text, but overwrite it instead.
128 The MOSH_PREDICTION_OVERWRITE environment variable also enables
130 this if its value is 'yes'.
131 -o Synonym for --predict-overwrite
134 --family=inet
137 Only use IPv4 for the SSH connection and Mosh session.
138 --family=inet6
141 Only use IPv6 for the SSH connection and Mosh session. This and
142 the following modes require Perl's IO::Socket::IP or
143 IO::Socket::INET6 modules.
144 --family=auto
147 Autodetect IPv4 or IPv6 for hosts that only have addresses in a
148 single family. Hosts with both IPv4 and IPv6 addresses will
149 raise an error, and require re-invocation of mosh with another
150 --family option.
151 --family=all
154 Choose an address from all available IPv4 or IPv6 address, even
155 for dual-stack hosts. This is the most convenient option, but
156 requires dual-stack connectivity, and Mosh 1.2.5 or later on the
157 server, when roaming with dual-stack servers.
158 --family=prefer-inet
161 Similar to --family=all, but attempt connects to the IPv4 ad‐
162 dresses first. This is the default.
163 --family=prefer-inet6
166 Similar to --family=all, but attempt connects to the IPv6 ad‐
167 dresses first.
168 -4 Synonym for --family=inet
171 -6 Synonym for --family=inet6
174 -p PORT[:PORT2], --port=PORT[:PORT2]
177 Use a particular server-side UDP port or port range, for exam‐
178 ple, if this is the only port that is forwarded through a fire‐
179 wall to the server. With -p 0, the server will let the operating
180 system pick an available UDP port. Otherwise, mosh will choose a
181 port between 60000 and 61000. Please note that this option does
182 not affect the server-side port used by SSH.
183 --bind-server={ssh|any|IP}
186 Control the IP address that the mosh-server binds to.
187 The default is `ssh', in which case the server will reply from
189 the IP address that the SSH connection came from (as found in
190 the SSH_CONNECTION environment variable). This is useful for
191 multihomed servers.
192 With --bind-server=any, the server will reply on the default in‐
194 terface and will not bind to a particular IP address. This can
195 be useful if the connection is made through sslh or another tool
196 that makes the SSH connection appear to come from localhost.
197 With --bind-server=IP, the server will attempt to bind to the
199 specified IP address.
200 --no-init
203 Do not send the smcup initialization string and rmcup deinitial‐
204 ization string to the client's terminal. On many terminals this
205 disables alternate screen mode.
206 --local
209 Invoke mosh-server locally, without using ssh. This option re‐
210 quires the host argument to be a local, numeric IPv4/IPv6 ad‐
211 dress. This option is useful for testing.
212 --experimental-remote-ip={proxy|local|remote}
215 Select the method used to discover the IP address that the mosh-
216 client connects to.
217 The default is proxy, which uses SSH's --ssh-proxy-command op‐
219 tion to generate and report the exact address that ssh uses to
220 connect to the remote host. This option is generally the most
221 compatible with hosts and other options configured in ssh con‐
222 figuration files. However, this may not work for some configu‐
223 rations, or for environments where a ssh bastion host forwards
224 to a remote machine. It only works with OpenSSH.
225 With remote, the server's SSH_CONNECTION environment variable
227 will be used. This is useful for environments where ssh for‐
228 warding is used, or the --ssh-proxy-command option is used for
229 other purposes.
230 With local, Mosh resolves the hostname given on its command
232 line, and uses that address for both ssh and Mosh connections.
233 This option ignores any configuration in ssh_config for the same
234 hostname.
235
238 The default escape character used by Mosh is ASCII RS (decimal 30).
239 This is typically typed as Ctrl-^ or Ctrl-Shift-6, on US English key‐
240 boards. Users of non-English keyboards may find it difficult or impos‐
241 sible to type the default escape character, and may need to change the
242 escape character. See the description of MOSH_ESCAPE_KEY, below. In
243 this description, the configured escape character is represented as
244 Esc.
245 There are two slightly different modes for escape sequences, depending
247 whether the escape character is printable or not.
248 If the escape character is a printable character, it must be prefixed
250 with a newline, similar to OpenSSH. To send the escape character it‐
251 self, type it twice. If the escape character is set to ~, mosh will
252 behave much like OpenSSH.
253 If the escape character is a non-printable control character, no prefix
255 is used and the escape character is recognized at any time. To send
256 the escape character itself, type the escape character, then its corre‐
257 sponding ASCII character (for Ctrl-^ you would type ^, for Ctrl-B you
258 would type B).
259 The escape sequence to shut down the connection is Esc .. The sequence
261 Esc Ctrl-Z suspends the client. Any other sequence passes both charac‐
262 ters through to the server.
263
266 These variables are not actually interpreted by mosh(1) itself, but are
267 passed through to mosh-server(1). They are described here for ease of
268 use.
269 MOSH_ESCAPE_KEY
272 When set, this configures the escape character used for local
273 commands. The escape character may be set to any ASCII charac‐
274 ter in the range 1-127. The variable must be set with a single
275 literal ASCII character. Control characters are set with the
276 actual ASCII control character, not with a printable representa‐
277 tion such as "^B".
278 MOSH_PREDICTION_DISPLAY
281 Controls local echo as described above. The command-line flag
282 overrides this variable.
283 MOSH_TITLE_NOPREFIX
286 When set, inhibits prepending "[mosh]" to window title.
287
290 mosh-client(1), mosh-server(1).
291 Project home page: https://mosh.org
293
296 mosh was written by Keith Winstein <mosh-devel@mit.edu>.
297
299 Please report bugs to mosh-devel@mit.edu. Users may also subscribe to
300 the mosh-users@mit.edu mailing list, at
301 http://mailman.mit.edu/mailman/listinfo/mosh-users
302 April 2013 MOSH(1)