Debian Codegraph @

upstream/mageia-cauldron/man1/ssh.1

raw
1 .\"
2 .\" Author: Tatu Ylonen <[email protected]>
3 .\" Copyright (c) 1995 Tatu Ylonen <[email protected]>, Espoo, Finland
4 .\" All rights reserved
5 .\"
6 .\" As far as I am concerned, the code I have written for this software
7 .\" can be used freely for any purpose. Any derived versions of this
8 .\" software must be clearly marked as such, and if the derived work is
9 .\" incompatible with the protocol description in the RFC file, it must be
10 .\" called by a name other than "ssh" or "Secure Shell".
11 .\"
12 .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
13 .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
14 .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
15 .\"
16 .\" Redistribution and use in source and binary forms, with or without
17 .\" modification, are permitted provided that the following conditions
18 .\" are met:
19 .\" 1. Redistributions of source code must retain the above copyright
20 .\" notice, this list of conditions and the following disclaimer.
21 .\" 2. Redistributions in binary form must reproduce the above copyright
22 .\" notice, this list of conditions and the following disclaimer in the
23 .\" documentation and/or other materials provided with the distribution.
24 .\"
25 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
26 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
27 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
28 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
29 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
30 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
31 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
32 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
33 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
34 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35 .\"
36 .\" $OpenBSD: ssh.1,v 1.444 2024/12/04 14:37:55 djm Exp $
37 .Dd $Mdocdate: December 4 2024 $
38 .Dt SSH 1
39 .Os
40 .Sh NAME
41 .Nm ssh
42 .Nd OpenSSH remote login client
43 .Sh SYNOPSIS
44 .Nm ssh
45 .Op Fl 46AaCfGgKkMNnqsTtVvXxYy
46 .Op Fl B Ar bind_interface
47 .Op Fl b Ar bind_address
48 .Op Fl c Ar cipher_spec
49 .Op Fl D Oo Ar bind_address : Oc Ns Ar port
50 .Op Fl E Ar log_file
51 .Op Fl e Ar escape_char
52 .Op Fl F Ar configfile
53 .Op Fl I Ar pkcs11
54 .Op Fl i Ar identity_file
55 .Op Fl J Ar destination
56 .Op Fl L Ar address
57 .Op Fl l Ar login_name
58 .Op Fl m Ar mac_spec
59 .Op Fl O Ar ctl_cmd
60 .Op Fl o Ar option
61 .Op Fl P Ar tag
62 .Op Fl p Ar port
63 .Op Fl R Ar address
64 .Op Fl S Ar ctl_path
65 .Op Fl W Ar host : Ns Ar port
66 .Op Fl w Ar local_tun Ns Op : Ns Ar remote_tun
67 .Ar destination
68 .Op Ar command Op Ar argument ...
69 .Nm
70 .Op Fl Q Ar query_option
71 .Sh DESCRIPTION
72 .Nm
73 (SSH client) is a program for logging into a remote machine and for
74 executing commands on a remote machine.
75 It is intended to provide secure encrypted communications between
76 two untrusted hosts over an insecure network.
77 X11 connections, arbitrary TCP ports and
78 .Ux Ns -domain
79 sockets can also be forwarded over the secure channel.
80 .Pp
81 .Nm
82 connects and logs into the specified
83 .Ar destination ,
84 which may be specified as either
85 .Sm off
86 .Oo user @ Oc hostname
87 .Sm on
88 or a URI of the form
89 .Sm off
90 .No ssh:// Oo user @ Oc hostname Op : port .
91 .Sm on
92 The user must prove
93 their identity to the remote machine using one of several methods
94 (see below).
95 .Pp
96 If a
97 .Ar command
98 is specified,
99 it will be executed on the remote host instead of a login shell.
100 A complete command line may be specified as
101 .Ar command ,
102 or it may have additional arguments.
103 If supplied, the arguments will be appended to the command, separated by
104 spaces, before it is sent to the server to be executed.
105 .Pp
106 The options are as follows:
107 .Pp
108 .Bl -tag -width Ds -compact
109 .It Fl 4
110 Forces
111 .Nm
112 to use IPv4 addresses only.
113 .Pp
114 .It Fl 6
115 Forces
116 .Nm
117 to use IPv6 addresses only.
118 .Pp
119 .It Fl A
120 Enables forwarding of connections from an authentication agent such as
121 .Xr ssh-agent 1 .
122 This can also be specified on a per-host basis in a configuration file.
123 .Pp
124 Agent forwarding should be enabled with caution.
125 Users with the ability to bypass file permissions on the remote host
126 (for the agent's
127 .Ux Ns -domain
128 socket) can access the local agent through the forwarded connection.
129 An attacker cannot obtain key material from the agent,
130 however they can perform operations on the keys that enable them to
131 authenticate using the identities loaded into the agent.
132 A safer alternative may be to use a jump host
133 (see
134 .Fl J ) .
135 .Pp
136 .It Fl a
137 Disables forwarding of the authentication agent connection.
138 .Pp
139 .It Fl B Ar bind_interface
140 Bind to the address of
141 .Ar bind_interface
142 before attempting to connect to the destination host.
143 This is only useful on systems with more than one address.
144 .Pp
145 .It Fl b Ar bind_address
146 Use
147 .Ar bind_address
148 on the local machine as the source address
149 of the connection.
150 Only useful on systems with more than one address.
151 .Pp
152 .It Fl C
153 Requests compression of all data (including stdin, stdout, stderr, and
154 data for forwarded X11, TCP and
155 .Ux Ns -domain
156 connections).
157 The compression algorithm is the same used by
158 .Xr gzip 1 .
159 Compression is desirable on modem lines and other
160 slow connections, but will only slow down things on fast networks.
161 The default value can be set on a host-by-host basis in the
162 configuration files; see the
163 .Cm Compression
164 option in
165 .Xr ssh_config 5 .
166 .Pp
167 .It Fl c Ar cipher_spec
168 Selects the cipher specification for encrypting the session.
169 .Ar cipher_spec
170 is a comma-separated list of ciphers
171 listed in order of preference.
172 See the
173 .Cm Ciphers
174 keyword in
175 .Xr ssh_config 5
176 for more information.
177 .Pp
178 .It Fl D Xo
179 .Sm off
180 .Oo Ar bind_address : Oc
181 .Ar port
182 .Sm on
183 .Xc
184 Specifies a local
185 .Dq dynamic
186 application-level port forwarding.
187 This works by allocating a socket to listen to
188 .Ar port
189 on the local side, optionally bound to the specified
190 .Ar bind_address .
191 Whenever a connection is made to this port, the
192 connection is forwarded over the secure channel, and the application
193 protocol is then used to determine where to connect to from the
194 remote machine.
195 Currently the SOCKS4 and SOCKS5 protocols are supported, and
196 .Nm
197 will act as a SOCKS server.
198 Only root can forward privileged ports.
199 Dynamic port forwardings can also be specified in the configuration file.
200 .Pp
201 IPv6 addresses can be specified by enclosing the address in square brackets.
202 Only the superuser can forward privileged ports.
203 By default, the local port is bound in accordance with the
204 .Cm GatewayPorts
205 setting.
206 However, an explicit
207 .Ar bind_address
208 may be used to bind the connection to a specific address.
209 The
210 .Ar bind_address
211 of
212 .Dq localhost
213 indicates that the listening port be bound for local use only, while an
214 empty address or
215 .Sq *
216 indicates that the port should be available from all interfaces.
217 .Pp
218 .It Fl E Ar log_file
219 Append debug logs to
220 .Ar log_file
221 instead of standard error.
222 .Pp
223 .It Fl e Ar escape_char
224 Sets the escape character for sessions with a pty (default:
225 .Ql ~ ) .
226 The escape character is only recognized at the beginning of a line.
227 The escape character followed by a dot
228 .Pq Ql \&.
229 closes the connection;
230 followed by control-Z suspends the connection;
231 and followed by itself sends the escape character once.
232 Setting the character to
233 .Dq none
234 disables any escapes and makes the session fully transparent.
235 .Pp
236 .It Fl F Ar configfile
237 Specifies an alternative per-user configuration file.
238 If a configuration file is given on the command line,
239 the system-wide configuration file
240 .Pq Pa /etc/ssh/ssh_config
241 will be ignored.
242 The default for the per-user configuration file is
243 .Pa ~/.ssh/config .
244 If set to
245 .Dq none ,
246 no configuration files will be read.
247 .Pp
248 .It Fl f
249 Requests
250 .Nm
251 to go to background just before command execution.
252 This is useful if
253 .Nm
254 is going to ask for passwords or passphrases, but the user
255 wants it in the background.
256 This implies
257 .Fl n .
258 The recommended way to start X11 programs at a remote site is with
259 something like
260 .Ic ssh -f host xterm .
261 .Pp
262 If the
263 .Cm ExitOnForwardFailure
264 configuration option is set to
265 .Dq yes ,
266 then a client started with
267 .Fl f
268 will wait for all remote port forwards to be successfully established
269 before placing itself in the background.
270 Refer to the description of
271 .Cm ForkAfterAuthentication
272 in
273 .Xr ssh_config 5
274 for details.
275 .Pp
276 .It Fl G
277 Causes
278 .Nm
279 to print its configuration after evaluating
280 .Cm Host
281 and
282 .Cm Match
283 blocks and exit.
284 .Pp
285 .It Fl g
286 Allows remote hosts to connect to local forwarded ports.
287 If used on a multiplexed connection, then this option must be specified
288 on the master process.
289 .Pp
290 .It Fl I Ar pkcs11
291 Specify the PKCS#11 shared library
292 .Nm
293 should use to communicate with a PKCS#11 token providing keys for user
294 authentication.
295 .Pp
296 .It Fl i Ar identity_file
297 Selects a file from which the identity (private key) for
298 public key authentication is read.
299 You can also specify a public key file to use the corresponding
300 private key that is loaded in
301 .Xr ssh-agent 1
302 when the private key file is not present locally.
303 The default is
304 .Pa ~/.ssh/id_rsa ,
305 .Pa ~/.ssh/id_ecdsa ,
306 .Pa ~/.ssh/id_ecdsa_sk ,
307 .Pa ~/.ssh/id_ed25519
308 and
309 .Pa ~/.ssh/id_ed25519_sk .
310 Identity files may also be specified on
311 a per-host basis in the configuration file.
312 It is possible to have multiple
313 .Fl i
314 options (and multiple identities specified in
315 configuration files).
316 If no certificates have been explicitly specified by the
317 .Cm CertificateFile
318 directive,
319 .Nm
320 will also try to load certificate information from the filename obtained
321 by appending
322 .Pa -cert.pub
323 to identity filenames.
324 .Pp
325 .It Fl J Ar destination
326 Connect to the target host by first making an
327 .Nm
328 connection to the jump host described by
329 .Ar destination
330 and then establishing a TCP forwarding to the ultimate destination from
331 there.
332 Multiple jump hops may be specified separated by comma characters.
333 IPv6 addresses can be specified by enclosing the address in square brackets.
334 This is a shortcut to specify a
335 .Cm ProxyJump
336 configuration directive.
337 Note that configuration directives supplied on the command-line generally
338 apply to the destination host and not any specified jump hosts.
339 Use
340 .Pa ~/.ssh/config
341 to specify configuration for jump hosts.
342 .Pp
343 .It Fl K
344 Enables GSSAPI-based authentication and forwarding (delegation) of GSSAPI
345 credentials to the server.
346 .Pp
347 .It Fl k
348 Disables forwarding (delegation) of GSSAPI credentials to the server.
349 .Pp
350 .It Fl L Xo
351 .Sm off
352 .Oo Ar bind_address : Oc
353 .Ar port : host : hostport
354 .Sm on
355 .Xc
356 .It Fl L Xo
357 .Sm off
358 .Oo Ar bind_address : Oc
359 .Ar port : remote_socket
360 .Sm on
361 .Xc
362 .It Fl L Xo
363 .Sm off
364 .Ar local_socket : host : hostport
365 .Sm on
366 .Xc
367 .It Fl L Xo
368 .Sm off
369 .Ar local_socket : remote_socket
370 .Sm on
371 .Xc
372 Specifies that connections to the given TCP port or Unix socket on the local
373 (client) host are to be forwarded to the given host and port, or Unix socket,
374 on the remote side.
375 This works by allocating a socket to listen to either a TCP
376 .Ar port
377 on the local side, optionally bound to the specified
378 .Ar bind_address ,
379 or to a Unix socket.
380 Whenever a connection is made to the local port or socket, the
381 connection is forwarded over the secure channel, and a connection is
382 made to either
383 .Ar host
384 port
385 .Ar hostport ,
386 or the Unix socket
387 .Ar remote_socket ,
388 from the remote machine.
389 .Pp
390 Port forwardings can also be specified in the configuration file.
391 Only the superuser can forward privileged ports.
392 IPv6 addresses can be specified by enclosing the address in square brackets.
393 .Pp
394 By default, the local port is bound in accordance with the
395 .Cm GatewayPorts
396 setting.
397 However, an explicit
398 .Ar bind_address
399 may be used to bind the connection to a specific address.
400 The
401 .Ar bind_address
402 of
403 .Dq localhost
404 indicates that the listening port be bound for local use only, while an
405 empty address or
406 .Sq *
407 indicates that the port should be available from all interfaces.
408 .Pp
409 .It Fl l Ar login_name
410 Specifies the user to log in as on the remote machine.
411 This also may be specified on a per-host basis in the configuration file.
412 .Pp
413 .It Fl M
414 Places the
415 .Nm
416 client into
417 .Dq master
418 mode for connection sharing.
419 Multiple
420 .Fl M
421 options places
422 .Nm
423 into
424 .Dq master
425 mode but with confirmation required using
426 .Xr ssh-askpass 1
427 before each operation that changes the multiplexing state
428 (e.g. opening a new session).
429 Refer to the description of
430 .Cm ControlMaster
431 in
432 .Xr ssh_config 5
433 for details.
434 .Pp
435 .It Fl m Ar mac_spec
436 A comma-separated list of MAC (message authentication code) algorithms,
437 specified in order of preference.
438 See the
439 .Cm MACs
440 keyword in
441 .Xr ssh_config 5
442 for more information.
443 .Pp
444 .It Fl N
445 Do not execute a remote command.
446 This is useful for just forwarding ports.
447 Refer to the description of
448 .Cm SessionType
449 in
450 .Xr ssh_config 5
451 for details.
452 .Pp
453 .It Fl n
454 Redirects stdin from
455 .Pa /dev/null
456 (actually, prevents reading from stdin).
457 This must be used when
458 .Nm
459 is run in the background.
460 A common trick is to use this to run X11 programs on a remote machine.
461 For example,
462 .Ic ssh -n shadows.cs.hut.fi emacs &
463 will start an emacs on shadows.cs.hut.fi, and the X11
464 connection will be automatically forwarded over an encrypted channel.
465 The
466 .Nm
467 program will be put in the background.
468 (This does not work if
469 .Nm
470 needs to ask for a password or passphrase; see also the
471 .Fl f
472 option.)
473 Refer to the description of
474 .Cm StdinNull
475 in
476 .Xr ssh_config 5
477 for details.
478 .Pp
479 .It Fl O Ar ctl_cmd
480 Control an active connection multiplexing master process.
481 When the
482 .Fl O
483 option is specified, the
484 .Ar ctl_cmd
485 argument is interpreted and passed to the master process.
486 Valid commands are:
487 .Dq check
488 (check that the master process is running),
489 .Dq forward
490 (request forwardings without command execution),
491 .Dq cancel
492 (cancel forwardings),
493 .Dq proxy
494 (connect to a running multiplexing master in proxy mode),
495 .Dq exit
496 (request the master to exit), and
497 .Dq stop
498 (request the master to stop accepting further multiplexing requests).
499 .Pp
500 .It Fl o Ar option
501 Can be used to give options in the format used in the configuration file.
502 This is useful for specifying options for which there is no separate
503 command-line flag.
504 For full details of the options listed below, and their possible values, see
505 .Xr ssh_config 5 .
506 .Pp
507 .Bl -tag -width Ds -offset indent -compact
508 .It AddKeysToAgent
509 .It AddressFamily
510 .It BatchMode
511 .It BindAddress
512 .It BindInterface
513 .It CanonicalDomains
514 .It CanonicalizeFallbackLocal
515 .It CanonicalizeHostname
516 .It CanonicalizeMaxDots
517 .It CanonicalizePermittedCNAMEs
518 .It CASignatureAlgorithms
519 .It CertificateFile
520 .It ChannelTimeout
521 .It CheckHostIP
522 .It Ciphers
523 .It ClearAllForwardings
524 .It Compression
525 .It ConnectTimeout
526 .It ConnectionAttempts
527 .It ControlMaster
528 .It ControlPath
529 .It ControlPersist
530 .It DynamicForward
531 .It EnableSSHKeysign
532 .It EnableEscapeCommandline
533 .It EnableSSHKeysign
534 .It EscapeChar
535 .It ExitOnForwardFailure
536 .It FingerprintHash
537 .It ForkAfterAuthentication
538 .It ForwardAgent
539 .It ForwardX11
540 .It ForwardX11Timeout
541 .It ForwardX11Trusted
542 .It GSSAPIAuthentication
543 .It GSSAPIDelegateCredentials
544 .It GatewayPorts
545 .It GlobalKnownHostsFile
546 .It HashKnownHosts
547 .It Host
548 .It HostKeyAlgorithms
549 .It HostKeyAlias
550 .It HostbasedAcceptedAlgorithms
551 .It HostbasedAuthentication
552 .It Hostname
553 .It IPQoS
554 .It IdentitiesOnly
555 .It IdentityAgent
556 .It IdentityFile
557 .It IgnoreUnknown
558 .It Include
559 .It KbdInteractiveAuthentication
560 .It KbdInteractiveDevices
561 .It KexAlgorithms
562 .It KnownHostsCommand
563 .It LocalCommand
564 .It LocalForward
565 .It LogLevel
566 .It LogVerbose
567 .It MACs
568 .It NoHostAuthenticationForLocalhost
569 .It NumberOfPasswordPrompts
570 .It ObscureKeystrokeTiming
571 .It PKCS11Provider
572 .It PasswordAuthentication
573 .It PermitLocalCommand
574 .It PermitRemoteOpen
575 .It Port
576 .It PreferredAuthentications
577 .It ProxyCommand
578 .It ProxyJump
579 .It ProxyUseFdpass
580 .It PubkeyAcceptedAlgorithms
581 .It PubkeyAuthentication
582 .It RekeyLimit
583 .It RemoteCommand
584 .It RemoteForward
585 .It RequestTTY
586 .It RevokedHostKeys
587 .It SecurityKeyProvider
588 .It RequiredRSASize
589 .It RevokedHostKeys
590 .It SecurityKeyProvider
591 .It SendEnv
592 .It ServerAliveCountMax
593 .It ServerAliveInterval
594 .It SessionType
595 .It SetEnv
596 .It StdinNull
597 .It StreamLocalBindMask
598 .It StreamLocalBindUnlink
599 .It StrictHostKeyChecking
600 .It SyslogFacility
601 .It TCPKeepAlive
602 .It Tag
603 .It Tunnel
604 .It TunnelDevice
605 .It UpdateHostKeys
606 .It User
607 .It UserKnownHostsFile
608 .It VerifyHostKeyDNS
609 .It VisualHostKey
610 .It XAuthLocation
611 .El
612 .Pp
613 .It Fl P Ar tag
614 Specify a tag name that may be used to select configuration in
615 .Xr ssh_config 5 .
616 Refer to the
617 .Cm Tag
618 and
619 .Cm Match
620 keywords in
621 .Xr ssh_config 5
622 for more information.
623 .It Fl p Ar port
624 Port to connect to on the remote host.
625 This can be specified on a
626 per-host basis in the configuration file.
627 .Pp
628 .It Fl Q Ar query_option
629 Queries for the algorithms supported by one of the following features:
630 .Ar cipher
631 (supported symmetric ciphers),
632 .Ar cipher-auth
633 (supported symmetric ciphers that support authenticated encryption),
634 .Ar help
635 (supported query terms for use with the
636 .Fl Q
637 flag),
638 .Ar mac
639 (supported message integrity codes),
640 .Ar kex
641 (key exchange algorithms),
642 .Ar key
643 (key types),
644 .Ar key-ca-sign
645 (valid CA signature algorithms for certificates),
646 .Ar key-cert
647 (certificate key types),
648 .Ar key-plain
649 (non-certificate key types),
650 .Ar key-sig
651 (all key types and signature algorithms),
652 .Ar protocol-version
653 (supported SSH protocol versions), and
654 .Ar sig
655 (supported signature algorithms).
656 Alternatively, any keyword from
657 .Xr ssh_config 5
658 or
659 .Xr sshd_config 5
660 that takes an algorithm list may be used as an alias for the corresponding
661 query_option.
662 .Pp
663 .It Fl q
664 Quiet mode.
665 Causes most warning and diagnostic messages to be suppressed.
666 .Pp
667 .It Fl R Xo
668 .Sm off
669 .Oo Ar bind_address : Oc
670 .Ar port : host : hostport
671 .Sm on
672 .Xc
673 .It Fl R Xo
674 .Sm off
675 .Oo Ar bind_address : Oc
676 .Ar port : local_socket
677 .Sm on
678 .Xc
679 .It Fl R Xo
680 .Sm off
681 .Ar remote_socket : host : hostport
682 .Sm on
683 .Xc
684 .It Fl R Xo
685 .Sm off
686 .Ar remote_socket : local_socket
687 .Sm on
688 .Xc
689 .It Fl R Xo
690 .Sm off
691 .Oo Ar bind_address : Oc
692 .Ar port
693 .Sm on
694 .Xc
695 Specifies that connections to the given TCP port or Unix socket on the remote
696 (server) host are to be forwarded to the local side.
697 .Pp
698 This works by allocating a socket to listen to either a TCP
699 .Ar port
700 or to a Unix socket on the remote side.
701 Whenever a connection is made to this port or Unix socket, the
702 connection is forwarded over the secure channel, and a connection
703 is made from the local machine to either an explicit destination specified by
704 .Ar host
705 port
706 .Ar hostport ,
707 or
708 .Ar local_socket ,
709 or, if no explicit destination was specified,
710 .Nm
711 will act as a SOCKS 4/5 proxy and forward connections to the destinations
712 requested by the remote SOCKS client.
713 .Pp
714 Port forwardings can also be specified in the configuration file.
715 Privileged ports can be forwarded only when
716 logging in as root on the remote machine.
717 IPv6 addresses can be specified by enclosing the address in square brackets.
718 .Pp
719 By default, TCP listening sockets on the server will be bound to the loopback
720 interface only.
721 This may be overridden by specifying a
722 .Ar bind_address .
723 An empty
724 .Ar bind_address ,
725 or the address
726 .Ql * ,
727 indicates that the remote socket should listen on all interfaces.
728 Specifying a remote
729 .Ar bind_address
730 will only succeed if the server's
731 .Cm GatewayPorts
732 option is enabled (see
733 .Xr sshd_config 5 ) .
734 .Pp
735 If the
736 .Ar port
737 argument is
738 .Ql 0 ,
739 the listen port will be dynamically allocated on the server and reported
740 to the client at run time.
741 When used together with
742 .Ic -O forward ,
743 the allocated port will be printed to the standard output.
744 .Pp
745 .It Fl S Ar ctl_path
746 Specifies the location of a control socket for connection sharing,
747 or the string
748 .Dq none
749 to disable connection sharing.
750 Refer to the description of
751 .Cm ControlPath
752 and
753 .Cm ControlMaster
754 in
755 .Xr ssh_config 5
756 for details.
757 .Pp
758 .It Fl s
759 May be used to request invocation of a subsystem on the remote system.
760 Subsystems facilitate the use of SSH
761 as a secure transport for other applications (e.g.\&
762 .Xr sftp 1 ) .
763 The subsystem is specified as the remote command.
764 Refer to the description of
765 .Cm SessionType
766 in
767 .Xr ssh_config 5
768 for details.
769 .Pp
770 .It Fl T
771 Disable pseudo-terminal allocation.
772 .Pp
773 .It Fl t
774 Force pseudo-terminal allocation.
775 This can be used to execute arbitrary
776 screen-based programs on a remote machine, which can be very useful,
777 e.g. when implementing menu services.
778 Multiple
779 .Fl t
780 options force tty allocation, even if
781 .Nm
782 has no local tty.
783 .Pp
784 .It Fl V
785 Display the version number and exit.
786 .Pp
787 .It Fl v
788 Verbose mode.
789 Causes
790 .Nm
791 to print debugging messages about its progress.
792 This is helpful in
793 debugging connection, authentication, and configuration problems.
794 Multiple
795 .Fl v
796 options increase the verbosity.
797 The maximum is 3.
798 .Pp
799 .It Fl W Ar host : Ns Ar port
800 Requests that standard input and output on the client be forwarded to
801 .Ar host
802 on
803 .Ar port
804 over the secure channel.
805 Implies
806 .Fl N ,
807 .Fl T ,
808 .Cm ExitOnForwardFailure
809 and
810 .Cm ClearAllForwardings ,
811 though these can be overridden in the configuration file or using
812 .Fl o
813 command line options.
814 .Pp
815 .It Fl w Xo
816 .Ar local_tun Ns Op : Ns Ar remote_tun
817 .Xc
818 Requests
819 tunnel
820 device forwarding with the specified
821 .Xr tun 4
822 devices between the client
823 .Pq Ar local_tun
824 and the server
825 .Pq Ar remote_tun .
826 .Pp
827 The devices may be specified by numerical ID or the keyword
828 .Dq any ,
829 which uses the next available tunnel device.
830 If
831 .Ar remote_tun
832 is not specified, it defaults to
833 .Dq any .
834 See also the
835 .Cm Tunnel
836 and
837 .Cm TunnelDevice
838 directives in
839 .Xr ssh_config 5 .
840 .Pp
841 If the
842 .Cm Tunnel
843 directive is unset, it will be set to the default tunnel mode, which is
844 .Dq point-to-point .
845 If a different
846 .Cm Tunnel
847 forwarding mode it desired, then it should be specified before
848 .Fl w .
849 .Pp
850 .It Fl X
851 Enables X11 forwarding.
852 This can also be specified on a per-host basis in a configuration file.
853 .Pp
854 X11 forwarding should be enabled with caution.
855 Users with the ability to bypass file permissions on the remote host
856 (for the user's X authorization database)
857 can access the local X11 display through the forwarded connection.
858 An attacker may then be able to perform activities such as keystroke monitoring.
859 .Pp
860 For this reason, X11 forwarding is subjected to X11 SECURITY extension
861 restrictions by default.
862 Refer to the
863 .Nm
864 .Fl Y
865 option and the
866 .Cm ForwardX11Trusted
867 directive in
868 .Xr ssh_config 5
869 for more information.
870 .Pp
871 .It Fl x
872 Disables X11 forwarding.
873 .Pp
874 .It Fl Y
875 Enables trusted X11 forwarding.
876 Trusted X11 forwardings are not subjected to the X11 SECURITY extension
877 controls.
878 .Pp
879 .It Fl y
880 Send log information using the
881 .Xr syslog 3
882 system module.
883 By default this information is sent to stderr.
884 .El
885 .Pp
886 .Nm
887 may additionally obtain configuration data from
888 a per-user configuration file and a system-wide configuration file.
889 The file format and configuration options are described in
890 .Xr ssh_config 5 .
891 .Sh AUTHENTICATION
892 The OpenSSH SSH client supports SSH protocol 2.
893 .Pp
894 The methods available for authentication are:
895 GSSAPI-based authentication,
896 host-based authentication,
897 public key authentication,
898 keyboard-interactive authentication,
899 and password authentication.
900 Authentication methods are tried in the order specified above,
901 though
902 .Cm PreferredAuthentications
903 can be used to change the default order.
904 .Pp
905 Host-based authentication works as follows:
906 If the machine the user logs in from is listed in
907 .Pa /etc/hosts.equiv
908 or
909 .Pa /etc/ssh/shosts.equiv
910 on the remote machine, the user is non-root and the user names are
911 the same on both sides, or if the files
912 .Pa ~/.rhosts
913 or
914 .Pa ~/.shosts
915 exist in the user's home directory on the
916 remote machine and contain a line containing the name of the client
917 machine and the name of the user on that machine, the user is
918 considered for login.
919 Additionally, the server
920 .Em must
921 be able to verify the client's
922 host key (see the description of
923 .Pa /etc/ssh/ssh_known_hosts
924 and
925 .Pa ~/.ssh/known_hosts ,
926 below)
927 for login to be permitted.
928 This authentication method closes security holes due to IP
929 spoofing, DNS spoofing, and routing spoofing.
930 [Note to the administrator:
931 .Pa /etc/hosts.equiv ,
932 .Pa ~/.rhosts ,
933 and the rlogin/rsh protocol in general, are inherently insecure and should be
934 disabled if security is desired.]
935 .Pp
936 Public key authentication works as follows:
937 The scheme is based on public-key cryptography,
938 using cryptosystems
939 where encryption and decryption are done using separate keys,
940 and it is unfeasible to derive the decryption key from the encryption key.
941 The idea is that each user creates a public/private
942 key pair for authentication purposes.
943 The server knows the public key, and only the user knows the private key.
944 .Nm
945 implements public key authentication protocol automatically,
946 using one of the ECDSA, Ed25519 or RSA algorithms.
947 .Pp
948 The file
949 .Pa ~/.ssh/authorized_keys
950 lists the public keys that are permitted for logging in.
951 When the user logs in, the
952 .Nm
953 program tells the server which key pair it would like to use for
954 authentication.
955 The client proves that it has access to the private key
956 and the server checks that the corresponding public key
957 is authorized to accept the account.
958 .Pp
959 The server may inform the client of errors that prevented public key
960 authentication from succeeding after authentication completes using a
961 different method.
962 These may be viewed by increasing the
963 .Cm LogLevel
964 to
965 .Cm DEBUG
966 or higher (e.g. by using the
967 .Fl v
968 flag).
969 .Pp
970 The user creates their key pair by running
971 .Xr ssh-keygen 1 .
972 This stores the private key in
973 .Pa ~/.ssh/id_ecdsa
974 (ECDSA),
975 .Pa ~/.ssh/id_ecdsa_sk
976 (authenticator-hosted ECDSA),
977 .Pa ~/.ssh/id_ed25519
978 (Ed25519),
979 .Pa ~/.ssh/id_ed25519_sk
980 (authenticator-hosted Ed25519),
981 or
982 .Pa ~/.ssh/id_rsa
983 (RSA)
984 and stores the public key in
985 .Pa ~/.ssh/id_ecdsa.pub
986 (ECDSA),
987 .Pa ~/.ssh/id_ecdsa_sk.pub
988 (authenticator-hosted ECDSA),
989 .Pa ~/.ssh/id_ed25519.pub
990 (Ed25519),
991 .Pa ~/.ssh/id_ed25519_sk.pub
992 (authenticator-hosted Ed25519),
993 or
994 .Pa ~/.ssh/id_rsa.pub
995 (RSA)
996 in the user's home directory.
997 The user should then copy the public key
998 to
999 .Pa ~/.ssh/authorized_keys
1000 in their home directory on the remote machine.
1001 The
1002 .Pa authorized_keys
1003 file corresponds to the conventional
1004 .Pa ~/.rhosts
1005 file, and has one key
1006 per line, though the lines can be very long.
1007 After this, the user can log in without giving the password.
1008 .Pp
1009 A variation on public key authentication
1010 is available in the form of certificate authentication:
1011 instead of a set of public/private keys,
1012 signed certificates are used.
1013 This has the advantage that a single trusted certification authority
1014 can be used in place of many public/private keys.
1015 See the CERTIFICATES section of
1016 .Xr ssh-keygen 1
1017 for more information.
1018 .Pp
1019 The most convenient way to use public key or certificate authentication
1020 may be with an authentication agent.
1021 See
1022 .Xr ssh-agent 1
1023 and (optionally) the
1024 .Cm AddKeysToAgent
1025 directive in
1026 .Xr ssh_config 5
1027 for more information.
1028 .Pp
1029 Keyboard-interactive authentication works as follows:
1030 The server sends an arbitrary
1031 .Qq challenge
1032 text and prompts for a response, possibly multiple times.
1033 Examples of keyboard-interactive authentication include
1034 .Bx
1035 Authentication (see
1036 .Xr login.conf 5 )
1037 and PAM (some
1038 .Pf non- Ox
1039 systems).
1040 .Pp
1041 Finally, if other authentication methods fail,
1042 .Nm
1043 prompts the user for a password.
1044 The password is sent to the remote
1045 host for checking; however, since all communications are encrypted,
1046 the password cannot be seen by someone listening on the network.
1047 .Pp
1048 .Nm
1049 automatically maintains and checks a database containing
1050 identification for all hosts it has ever been used with.
1051 Host keys are stored in
1052 .Pa ~/.ssh/known_hosts
1053 in the user's home directory.
1054 Additionally, the file
1055 .Pa /etc/ssh/ssh_known_hosts
1056 is automatically checked for known hosts.
1057 Any new hosts are automatically added to the user's file.
1058 If a host's identification ever changes,
1059 .Nm
1060 warns about this and disables password authentication to prevent
1061 server spoofing or man-in-the-middle attacks,
1062 which could otherwise be used to circumvent the encryption.
1063 The
1064 .Cm StrictHostKeyChecking
1065 option can be used to control logins to machines whose
1066 host key is not known or has changed.
1067 .Pp
1068 When the user's identity has been accepted by the server, the server
1069 either executes the given command in a non-interactive session or,
1070 if no command has been specified, logs into the machine and gives
1071 the user a normal shell as an interactive session.
1072 All communication with
1073 the remote command or shell will be automatically encrypted.
1074 .Pp
1075 If an interactive session is requested,
1076 .Nm
1077 by default will only request a pseudo-terminal (pty) for interactive
1078 sessions when the client has one.
1079 The flags
1080 .Fl T
1081 and
1082 .Fl t
1083 can be used to override this behaviour.
1084 .Pp
1085 If a pseudo-terminal has been allocated, the
1086 user may use the escape characters noted below.
1087 .Pp
1088 If no pseudo-terminal has been allocated,
1089 the session is transparent and can be used to reliably transfer binary data.
1090 On most systems, setting the escape character to
1091 .Dq none
1092 will also make the session transparent even if a tty is used.
1093 .Pp
1094 The session terminates when the command or shell on the remote
1095 machine exits and all X11 and TCP connections have been closed.
1096 .Sh ESCAPE CHARACTERS
1097 When a pseudo-terminal has been requested,
1098 .Nm
1099 supports a number of functions through the use of an escape character.
1100 .Pp
1101 A single tilde character can be sent as
1102 .Ic ~~
1103 or by following the tilde by a character other than those described below.
1104 The escape character must always follow a newline to be interpreted as
1105 special.
1106 The escape character can be changed in configuration files using the
1107 .Cm EscapeChar
1108 configuration directive or on the command line by the
1109 .Fl e
1110 option.
1111 .Pp
1112 The supported escapes (assuming the default
1113 .Ql ~ )
1114 are:
1115 .Bl -tag -width Ds
1116 .It Cm ~.
1117 Disconnect.
1118 .It Cm ~^Z
1119 Background
1120 .Nm .
1121 .It Cm ~#
1122 List forwarded connections.
1123 .It Cm ~&
1124 Background
1125 .Nm
1126 at logout when waiting for forwarded connection / X11 sessions to terminate.
1127 .It Cm ~?
1128 Display a list of escape characters.
1129 .It Cm ~B
1130 Send a BREAK to the remote system
1131 (only useful if the peer supports it).
1132 .It Cm ~C
1133 Open command line.
1134 Currently this allows the addition of port forwardings using the
1135 .Fl L ,
1136 .Fl R
1137 and
1138 .Fl D
1139 options (see above).
1140 It also allows the cancellation of existing port-forwardings
1141 with
1142 .Sm off
1143 .Fl KL Oo Ar bind_address : Oc Ar port
1144 .Sm on
1145 for local,
1146 .Sm off
1147 .Fl KR Oo Ar bind_address : Oc Ar port
1148 .Sm on
1149 for remote and
1150 .Sm off
1151 .Fl KD Oo Ar bind_address : Oc Ar port
1152 .Sm on
1153 for dynamic port-forwardings.
1154 .Ic !\& Ns Ar command
1155 allows the user to execute a local command if the
1156 .Ic PermitLocalCommand
1157 option is enabled in
1158 .Xr ssh_config 5 .
1159 Basic help is available, using the
1160 .Fl h
1161 option.
1162 .It Cm ~R
1163 Request rekeying of the connection
1164 (only useful if the peer supports it).
1165 .It Cm ~V
1166 Decrease the verbosity
1167 .Pq Ic LogLevel
1168 when errors are being written to stderr.
1169 .It Cm ~v
1170 Increase the verbosity
1171 .Pq Ic LogLevel
1172 when errors are being written to stderr.
1173 .El
1174 .Sh TCP FORWARDING
1175 Forwarding of arbitrary TCP connections over a secure channel
1176 can be specified either on the command line or in a configuration file.
1177 One possible application of TCP forwarding is a secure connection to a
1178 mail server; another is going through firewalls.
1179 .Pp
1180 In the example below, we look at encrypting communication for an IRC client,
1181 even though the IRC server it connects to does not directly
1182 support encrypted communication.
1183 This works as follows:
1184 the user connects to the remote host using
1185 .Nm ,
1186 specifying the ports to be used to forward the connection.
1187 After that it is possible to start the program locally,
1188 and
1189 .Nm
1190 will encrypt and forward the connection to the remote server.
1191 .Pp
1192 The following example tunnels an IRC session from the client
1193 to an IRC server at
1194 .Dq server.example.com ,
1195 joining channel
1196 .Dq #users ,
1197 nickname
1198 .Dq pinky ,
1199 using the standard IRC port, 6667:
1200 .Bd -literal -offset 4n
1201 $ ssh -f -L 6667:localhost:6667 server.example.com sleep 10
1202 $ irc -c '#users' pinky IRC/127.0.0.1
1203 .Ed
1204 .Pp
1205 The
1206 .Fl f
1207 option backgrounds
1208 .Nm
1209 and the remote command
1210 .Dq sleep 10
1211 is specified to allow an amount of time
1212 (10 seconds, in the example)
1213 to start the program which is going to use the tunnel.
1214 If no connections are made within the time specified,
1215 .Nm
1216 will exit.
1217 .Sh X11 FORWARDING
1218 If the
1219 .Cm ForwardX11
1220 variable is set to
1221 .Dq yes
1222 (or see the description of the
1223 .Fl X ,
1224 .Fl x ,
1225 and
1226 .Fl Y
1227 options above)
1228 and the user is using X11 (the
1229 .Ev DISPLAY
1230 environment variable is set), the connection to the X11 display is
1231 automatically forwarded to the remote side in such a way that any X11
1232 programs started from the shell (or command) will go through the
1233 encrypted channel, and the connection to the real X server will be made
1234 from the local machine.
1235 The user should not manually set
1236 .Ev DISPLAY .
1237 Forwarding of X11 connections can be
1238 configured on the command line or in configuration files.
1239 .Pp
1240 The
1241 .Ev DISPLAY
1242 value set by
1243 .Nm
1244 will point to the server machine, but with a display number greater than zero.
1245 This is normal, and happens because
1246 .Nm
1247 creates a
1248 .Dq proxy
1249 X server on the server machine for forwarding the
1250 connections over the encrypted channel.
1251 .Pp
1252 .Nm
1253 will also automatically set up Xauthority data on the server machine.
1254 For this purpose, it will generate a random authorization cookie,
1255 store it in Xauthority on the server, and verify that any forwarded
1256 connections carry this cookie and replace it by the real cookie when
1257 the connection is opened.
1258 The real authentication cookie is never
1259 sent to the server machine (and no cookies are sent in the plain).
1260 .Pp
1261 If the
1262 .Cm ForwardAgent
1263 variable is set to
1264 .Dq yes
1265 (or see the description of the
1266 .Fl A
1267 and
1268 .Fl a
1269 options above) and
1270 the user is using an authentication agent, the connection to the agent
1271 is automatically forwarded to the remote side.
1272 .Sh VERIFYING HOST KEYS
1273 When connecting to a server for the first time,
1274 a fingerprint of the server's public key is presented to the user
1275 (unless the option
1276 .Cm StrictHostKeyChecking
1277 has been disabled).
1278 Fingerprints can be determined using
1279 .Xr ssh-keygen 1 :
1280 .Pp
1281 .Dl $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key
1282 .Pp
1283 If the fingerprint is already known, it can be matched
1284 and the key can be accepted or rejected.
1285 If only legacy (MD5) fingerprints for the server are available, the
1286 .Xr ssh-keygen 1
1287 .Fl E
1288 option may be used to downgrade the fingerprint algorithm to match.
1289 .Pp
1290 Because of the difficulty of comparing host keys
1291 just by looking at fingerprint strings,
1292 there is also support to compare host keys visually,
1293 using
1294 .Em random art .
1295 By setting the
1296 .Cm VisualHostKey
1297 option to
1298 .Dq yes ,
1299 a small ASCII graphic gets displayed on every login to a server, no matter
1300 if the session itself is interactive or not.
1301 By learning the pattern a known server produces, a user can easily
1302 find out that the host key has changed when a completely different pattern
1303 is displayed.
1304 Because these patterns are not unambiguous however, a pattern that looks
1305 similar to the pattern remembered only gives a good probability that the
1306 host key is the same, not guaranteed proof.
1307 .Pp
1308 To get a listing of the fingerprints along with their random art for
1309 all known hosts, the following command line can be used:
1310 .Pp
1311 .Dl $ ssh-keygen -lv -f ~/.ssh/known_hosts
1312 .Pp
1313 If the fingerprint is unknown,
1314 an alternative method of verification is available:
1315 SSH fingerprints verified by DNS.
1316 An additional resource record (RR),
1317 SSHFP,
1318 is added to a zonefile
1319 and the connecting client is able to match the fingerprint
1320 with that of the key presented.
1321 .Pp
1322 In this example, we are connecting a client to a server,
1323 .Dq host.example.com .
1324 The SSHFP resource records should first be added to the zonefile for
1325 host.example.com:
1326 .Bd -literal -offset indent
1327 $ ssh-keygen -r host.example.com.
1328 .Ed
1329 .Pp
1330 The output lines will have to be added to the zonefile.
1331 To check that the zone is answering fingerprint queries:
1332 .Pp
1333 .Dl $ dig -t SSHFP host.example.com
1334 .Pp
1335 Finally the client connects:
1336 .Bd -literal -offset indent
1337 $ ssh -o "VerifyHostKeyDNS ask" host.example.com
1338 [...]
1339 Matching host key fingerprint found in DNS.
1340 Are you sure you want to continue connecting (yes/no)?
1341 .Ed
1342 .Pp
1343 See the
1344 .Cm VerifyHostKeyDNS
1345 option in
1346 .Xr ssh_config 5
1347 for more information.
1348 .Sh SSH-BASED VIRTUAL PRIVATE NETWORKS
1349 .Nm
1350 contains support for Virtual Private Network (VPN) tunnelling
1351 using the
1352 .Xr tun 4
1353 network pseudo-device,
1354 allowing two networks to be joined securely.
1355 The
1356 .Xr sshd_config 5
1357 configuration option
1358 .Cm PermitTunnel
1359 controls whether the server supports this,
1360 and at what level (layer 2 or 3 traffic).
1361 .Pp
1362 The following example would connect client network 10.0.50.0/24
1363 with remote network 10.0.99.0/24 using a point-to-point connection
1364 from 10.1.1.1 to 10.1.1.2,
1365 provided that the SSH server running on the gateway to the remote network,
1366 at 192.168.1.15, allows it.
1367 .Pp
1368 On the client:
1369 .Bd -literal -offset indent
1370 # ssh -f -w 0:1 192.168.1.15 true
1371 # ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252
1372 # route add 10.0.99.0/24 10.1.1.2
1373 .Ed
1374 .Pp
1375 On the server:
1376 .Bd -literal -offset indent
1377 # ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252
1378 # route add 10.0.50.0/24 10.1.1.1
1379 .Ed
1380 .Pp
1381 Client access may be more finely tuned via the
1382 .Pa /root/.ssh/authorized_keys
1383 file (see below) and the
1384 .Cm PermitRootLogin
1385 server option.
1386 The following entry would permit connections on
1387 .Xr tun 4
1388 device 1 from user
1389 .Dq jane
1390 and on tun device 2 from user
1391 .Dq john ,
1392 if
1393 .Cm PermitRootLogin
1394 is set to
1395 .Dq forced-commands-only :
1396 .Bd -literal -offset 2n
1397 tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane
1398 tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john
1399 .Ed
1400 .Pp
1401 Since an SSH-based setup entails a fair amount of overhead,
1402 it may be more suited to temporary setups,
1403 such as for wireless VPNs.
1404 More permanent VPNs are better provided by tools such as
1405 .Xr ipsecctl 8
1406 and
1407 .Xr isakmpd 8 .
1408 .Sh ENVIRONMENT
1409 .Nm
1410 will normally set the following environment variables:
1411 .Bl -tag -width "SSH_ORIGINAL_COMMAND"
1412 .It Ev DISPLAY
1413 The
1414 .Ev DISPLAY
1415 variable indicates the location of the X11 server.
1416 It is automatically set by
1417 .Nm
1418 to point to a value of the form
1419 .Dq hostname:n ,
1420 where
1421 .Dq hostname
1422 indicates the host where the shell runs, and
1423 .Sq n
1424 is an integer \*(Ge 1.
1425 .Nm
1426 uses this special value to forward X11 connections over the secure
1427 channel.
1428 The user should normally not set
1429 .Ev DISPLAY
1430 explicitly, as that
1431 will render the X11 connection insecure (and will require the user to
1432 manually copy any required authorization cookies).
1433 .It Ev HOME
1434 Set to the path of the user's home directory.
1435 .It Ev LOGNAME
1436 Synonym for
1437 .Ev USER ;
1438 set for compatibility with systems that use this variable.
1439 .It Ev MAIL
1440 Set to the path of the user's mailbox.
1441 .It Ev PATH
1442 Set to the default
1443 .Ev PATH ,
1444 as specified when compiling
1445 .Nm .
1446 .It Ev SSH_ASKPASS
1447 If
1448 .Nm
1449 needs a passphrase, it will read the passphrase from the current
1450 terminal if it was run from a terminal.
1451 If
1452 .Nm
1453 does not have a terminal associated with it but
1454 .Ev DISPLAY
1455 and
1456 .Ev SSH_ASKPASS
1457 are set, it will execute the program specified by
1458 .Ev SSH_ASKPASS
1459 and open an X11 window to read the passphrase.
1460 This is particularly useful when calling
1461 .Nm
1462 from a
1463 .Pa .xsession
1464 or related script.
1465 (Note that on some machines it
1466 may be necessary to redirect the input from
1467 .Pa /dev/null
1468 to make this work.)
1469 .It Ev SSH_ASKPASS_REQUIRE
1470 Allows further control over the use of an askpass program.
1471 If this variable is set to
1472 .Dq never
1473 then
1474 .Nm
1475 will never attempt to use one.
1476 If it is set to
1477 .Dq prefer ,
1478 then
1479 .Nm
1480 will prefer to use the askpass program instead of the TTY when requesting
1481 passwords.
1482 Finally, if the variable is set to
1483 .Dq force ,
1484 then the askpass program will be used for all passphrase input regardless
1485 of whether
1486 .Ev DISPLAY
1487 is set.
1488 .It Ev SSH_AUTH_SOCK
1489 Identifies the path of a
1490 .Ux Ns -domain
1491 socket used to communicate with the agent.
1492 .It Ev SSH_CONNECTION
1493 Identifies the client and server ends of the connection.
1494 The variable contains
1495 four space-separated values: client IP address, client port number,
1496 server IP address, and server port number.
1497 .It Ev SSH_ORIGINAL_COMMAND
1498 This variable contains the original command line if a forced command
1499 is executed.
1500 It can be used to extract the original arguments.
1501 .It Ev SSH_TTY
1502 This is set to the name of the tty (path to the device) associated
1503 with the current shell or command.
1504 If the current session has no tty,
1505 this variable is not set.
1506 .It Ev SSH_TUNNEL
1507 Optionally set by
1508 .Xr sshd 8
1509 to contain the interface names assigned if tunnel forwarding was
1510 requested by the client.
1511 .It Ev SSH_USER_AUTH
1512 Optionally set by
1513 .Xr sshd 8 ,
1514 this variable may contain a pathname to a file that lists the authentication
1515 methods successfully used when the session was established, including any
1516 public keys that were used.
1517 .It Ev TZ
1518 This variable is set to indicate the present time zone if it
1519 was set when the daemon was started (i.e. the daemon passes the value
1520 on to new connections).
1521 .It Ev USER
1522 Set to the name of the user logging in.
1523 .El
1524 .Pp
1525 Additionally,
1526 .Nm
1527 reads
1528 .Pa ~/.ssh/environment ,
1529 and adds lines of the format
1530 .Dq VARNAME=value
1531 to the environment if the file exists and users are allowed to
1532 change their environment.
1533 For more information, see the
1534 .Cm PermitUserEnvironment
1535 option in
1536 .Xr sshd_config 5 .
1537 .Sh FILES
1538 .Bl -tag -width Ds -compact
1539 .It Pa ~/.rhosts
1540 This file is used for host-based authentication (see above).
1541 On some machines this file may need to be
1542 world-readable if the user's home directory is on an NFS partition,
1543 because
1544 .Xr sshd 8
1545 reads it as root.
1546 Additionally, this file must be owned by the user,
1547 and must not have write permissions for anyone else.
1548 The recommended
1549 permission for most machines is read/write for the user, and not
1550 accessible by others.
1551 .Pp
1552 .It Pa ~/.shosts
1553 This file is used in exactly the same way as
1554 .Pa .rhosts ,
1555 but allows host-based authentication without permitting login with
1556 rlogin/rsh.
1557 .Pp
1558 .It Pa ~/.ssh/
1559 This directory is the default location for all user-specific configuration
1560 and authentication information.
1561 There is no general requirement to keep the entire contents of this directory
1562 secret, but the recommended permissions are read/write/execute for the user,
1563 and not accessible by others.
1564 .Pp
1565 .It Pa ~/.ssh/authorized_keys
1566 Lists the public keys (ECDSA, Ed25519, RSA)
1567 that can be used for logging in as this user.
1568 The format of this file is described in the
1569 .Xr sshd 8
1570 manual page.
1571 This file is not highly sensitive, but the recommended
1572 permissions are read/write for the user, and not accessible by others.
1573 .Pp
1574 .It Pa ~/.ssh/config
1575 This is the per-user configuration file.
1576 The file format and configuration options are described in
1577 .Xr ssh_config 5 .
1578 Because of the potential for abuse, this file must have strict permissions:
1579 read/write for the user, and not writable by others.
1580 .Pp
1581 .It Pa ~/.ssh/environment
1582 Contains additional definitions for environment variables; see
1583 .Sx ENVIRONMENT ,
1584 above.
1585 .Pp
1586 .It Pa ~/.ssh/id_ecdsa
1587 .It Pa ~/.ssh/id_ecdsa_sk
1588 .It Pa ~/.ssh/id_ed25519
1589 .It Pa ~/.ssh/id_ed25519_sk
1590 .It Pa ~/.ssh/id_rsa
1591 Contains the private key for authentication.
1592 These files
1593 contain sensitive data and should be readable by the user but not
1594 accessible by others (read/write/execute).
1595 .Nm
1596 will simply ignore a private key file if it is accessible by others.
1597 It is possible to specify a passphrase when
1598 generating the key which will be used to encrypt the
1599 sensitive part of this file using AES-128.
1600 .Pp
1601 .It Pa ~/.ssh/id_ecdsa.pub
1602 .It Pa ~/.ssh/id_ecdsa_sk.pub
1603 .It Pa ~/.ssh/id_ed25519.pub
1604 .It Pa ~/.ssh/id_ed25519_sk.pub
1605 .It Pa ~/.ssh/id_rsa.pub
1606 Contains the public key for authentication.
1607 These files are not
1608 sensitive and can (but need not) be readable by anyone.
1609 .Pp
1610 .It Pa ~/.ssh/known_hosts
1611 Contains a list of host keys for all hosts the user has logged into
1612 that are not already in the systemwide list of known host keys.
1613 See
1614 .Xr sshd 8
1615 for further details of the format of this file.
1616 .Pp
1617 .It Pa ~/.ssh/rc
1618 Commands in this file are executed by
1619 .Nm
1620 when the user logs in, just before the user's shell (or command) is
1621 started.
1622 See the
1623 .Xr sshd 8
1624 manual page for more information.
1625 .Pp
1626 .It Pa /etc/hosts.equiv
1627 This file is for host-based authentication (see above).
1628 It should only be writable by root.
1629 .Pp
1630 .It Pa /etc/ssh/shosts.equiv
1631 This file is used in exactly the same way as
1632 .Pa hosts.equiv ,
1633 but allows host-based authentication without permitting login with
1634 rlogin/rsh.
1635 .Pp
1636 .It Pa /etc/ssh/ssh_config
1637 Systemwide configuration file.
1638 The file format and configuration options are described in
1639 .Xr ssh_config 5 .
1640 .Pp
1641 .It Pa /etc/ssh/ssh_host_ecdsa_key
1642 .It Pa /etc/ssh/ssh_host_ed25519_key
1643 .It Pa /etc/ssh/ssh_host_rsa_key
1644 These files contain the private parts of the host keys
1645 and are used for host-based authentication.
1646 .Pp
1647 .It Pa /etc/ssh/ssh_known_hosts
1648 Systemwide list of known host keys.
1649 This file should be prepared by the
1650 system administrator to contain the public host keys of all machines in the
1651 organization.
1652 It should be world-readable.
1653 See
1654 .Xr sshd 8
1655 for further details of the format of this file.
1656 .Pp
1657 .It Pa /etc/ssh/sshrc
1658 Commands in this file are executed by
1659 .Nm
1660 when the user logs in, just before the user's shell (or command) is started.
1661 See the
1662 .Xr sshd 8
1663 manual page for more information.
1664 .El
1665 .Sh EXIT STATUS
1666 .Nm
1667 exits with the exit status of the remote command or with 255
1668 if an error occurred.
1669 .Sh SEE ALSO
1670 .Xr scp 1 ,
1671 .Xr sftp 1 ,
1672 .Xr ssh-add 1 ,
1673 .Xr ssh-agent 1 ,
1674 .Xr ssh-keygen 1 ,
1675 .Xr ssh-keyscan 1 ,
1676 .Xr tun 4 ,
1677 .Xr ssh_config 5 ,
1678 .Xr ssh-keysign 8 ,
1679 .Xr sshd 8
1680 .Sh STANDARDS
1681 .Rs
1682 .%A S. Lehtinen
1683 .%A C. Lonvick
1684 .%D January 2006
1685 .%R RFC 4250
1686 .%T The Secure Shell (SSH) Protocol Assigned Numbers
1687 .Re
1688 .Pp
1689 .Rs
1690 .%A T. Ylonen
1691 .%A C. Lonvick
1692 .%D January 2006
1693 .%R RFC 4251
1694 .%T The Secure Shell (SSH) Protocol Architecture
1695 .Re
1696 .Pp
1697 .Rs
1698 .%A T. Ylonen
1699 .%A C. Lonvick
1700 .%D January 2006
1701 .%R RFC 4252
1702 .%T The Secure Shell (SSH) Authentication Protocol
1703 .Re
1704 .Pp
1705 .Rs
1706 .%A T. Ylonen
1707 .%A C. Lonvick
1708 .%D January 2006
1709 .%R RFC 4253
1710 .%T The Secure Shell (SSH) Transport Layer Protocol
1711 .Re
1712 .Pp
1713 .Rs
1714 .%A T. Ylonen
1715 .%A C. Lonvick
1716 .%D January 2006
1717 .%R RFC 4254
1718 .%T The Secure Shell (SSH) Connection Protocol
1719 .Re
1720 .Pp
1721 .Rs
1722 .%A J. Schlyter
1723 .%A W. Griffin
1724 .%D January 2006
1725 .%R RFC 4255
1726 .%T Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints
1727 .Re
1728 .Pp
1729 .Rs
1730 .%A F. Cusack
1731 .%A M. Forssen
1732 .%D January 2006
1733 .%R RFC 4256
1734 .%T Generic Message Exchange Authentication for the Secure Shell Protocol (SSH)
1735 .Re
1736 .Pp
1737 .Rs
1738 .%A J. Galbraith
1739 .%A P. Remaker
1740 .%D January 2006
1741 .%R RFC 4335
1742 .%T The Secure Shell (SSH) Session Channel Break Extension
1743 .Re
1744 .Pp
1745 .Rs
1746 .%A M. Bellare
1747 .%A T. Kohno
1748 .%A C. Namprempre
1749 .%D January 2006
1750 .%R RFC 4344
1751 .%T The Secure Shell (SSH) Transport Layer Encryption Modes
1752 .Re
1753 .Pp
1754 .Rs
1755 .%A B. Harris
1756 .%D January 2006
1757 .%R RFC 4345
1758 .%T Improved Arcfour Modes for the Secure Shell (SSH) Transport Layer Protocol
1759 .Re
1760 .Pp
1761 .Rs
1762 .%A M. Friedl
1763 .%A N. Provos
1764 .%A W. Simpson
1765 .%D March 2006
1766 .%R RFC 4419
1767 .%T Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol
1768 .Re
1769 .Pp
1770 .Rs
1771 .%A J. Galbraith
1772 .%A R. Thayer
1773 .%D November 2006
1774 .%R RFC 4716
1775 .%T The Secure Shell (SSH) Public Key File Format
1776 .Re
1777 .Pp
1778 .Rs
1779 .%A D. Stebila
1780 .%A J. Green
1781 .%D December 2009
1782 .%R RFC 5656
1783 .%T Elliptic Curve Algorithm Integration in the Secure Shell Transport Layer
1784 .Re
1785 .Pp
1786 .Rs
1787 .%A A. Perrig
1788 .%A D. Song
1789 .%D 1999
1790 .%O International Workshop on Cryptographic Techniques and E-Commerce (CrypTEC '99)
1791 .%T Hash Visualization: a New Technique to improve Real-World Security
1792 .Re
1793 .Sh AUTHORS
1794 OpenSSH is a derivative of the original and free
1795 ssh 1.2.12 release by Tatu Ylonen.
1796 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1797 Theo de Raadt and Dug Song
1798 removed many bugs, re-added newer features and
1799 created OpenSSH.
1800 Markus Friedl contributed the support for SSH
1801 protocol versions 1.5 and 2.0.