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