Debian Codegraph @

upstream/debian-unstable/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.447 2025/12/22 01:17:31 djm Exp $
37 .Dd $Mdocdate: December 22 2025 $
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 conninfo
490 (report information about the master connection),
491 .Dq channels
492 (report information about open channels),
493 .Dq forward
494 (request forwardings without command execution),
495 .Dq cancel
496 (cancel forwardings),
497 .Dq proxy
498 (connect to a running multiplexing master in proxy mode),
499 .Dq exit
500 (request the master to exit), and
501 .Dq stop
502 (request the master to stop accepting further multiplexing requests).
503 .Pp
504 .It Fl o Ar option
505 Can be used to give options in the format used in the configuration file.
506 This is useful for specifying options for which there is no separate
507 command-line flag.
508 For full details of the options listed below, and their possible values, see
509 .Xr ssh_config 5 .
510 .Pp
511 .Bl -tag -width Ds -offset indent -compact
512 .It AddKeysToAgent
513 .It AddressFamily
514 .It BatchMode
515 .It BindAddress
516 .It BindInterface
517 .It CASignatureAlgorithms
518 .It CanonicalDomains
519 .It CanonicalizeFallbackLocal
520 .It CanonicalizeHostname
521 .It CanonicalizeMaxDots
522 .It CanonicalizePermittedCNAMEs
523 .It CertificateFile
524 .It ChannelTimeout
525 .It CheckHostIP
526 .It Ciphers
527 .It ClearAllForwardings
528 .It Compression
529 .It ConnectTimeout
530 .It ConnectionAttempts
531 .It ControlMaster
532 .It ControlPath
533 .It ControlPersist
534 .It DynamicForward
535 .It EnableEscapeCommandline
536 .It EnableSSHKeysign
537 .It EscapeChar
538 .It ExitOnForwardFailure
539 .It FingerprintHash
540 .It ForkAfterAuthentication
541 .It ForwardAgent
542 .It ForwardX11
543 .It ForwardX11Timeout
544 .It ForwardX11Trusted
545 .It GSSAPIAuthentication
546 .It GSSAPIKeyExchange
547 .It GSSAPIClientIdentity
548 .It GSSAPIDelegateCredentials
549 .It GSSAPIKexAlgorithms
550 .It GSSAPIRenewalForcesRekey
551 .It GSSAPIServerIdentity
552 .It GSSAPITrustDns
553 .It GatewayPorts
554 .It GlobalKnownHostsFile
555 .It HashKnownHosts
556 .It Host
557 .It HostKeyAlgorithms
558 .It HostKeyAlias
559 .It HostbasedAcceptedAlgorithms
560 .It HostbasedAuthentication
561 .It Hostname
562 .It IPQoS
563 .It IdentitiesOnly
564 .It IdentityAgent
565 .It IdentityFile
566 .It IgnoreUnknown
567 .It Include
568 .It KbdInteractiveAuthentication
569 .It KbdInteractiveDevices
570 .It KexAlgorithms
571 .It KnownHostsCommand
572 .It LocalCommand
573 .It LocalForward
574 .It LogLevel
575 .It LogVerbose
576 .It MACs
577 .It NoHostAuthenticationForLocalhost
578 .It NumberOfPasswordPrompts
579 .It ObscureKeystrokeTiming
580 .It PKCS11Provider
581 .It PasswordAuthentication
582 .It PermitLocalCommand
583 .It PermitRemoteOpen
584 .It Port
585 .It PreferredAuthentications
586 .It ProxyCommand
587 .It ProxyJump
588 .It ProxyUseFdpass
589 .It PubkeyAcceptedAlgorithms
590 .It PubkeyAuthentication
591 .It RekeyLimit
592 .It RemoteCommand
593 .It RemoteForward
594 .It RequestTTY
595 .It RequiredRSASize
596 .It RevokedHostKeys
597 .It SecurityKeyProvider
598 .It SendEnv
599 .It ServerAliveCountMax
600 .It ServerAliveInterval
601 .It SessionType
602 .It SetEnv
603 .It StdinNull
604 .It StreamLocalBindMask
605 .It StreamLocalBindUnlink
606 .It StrictHostKeyChecking
607 .It SyslogFacility
608 .It TCPKeepAlive
609 .It Tag
610 .It Tunnel
611 .It TunnelDevice
612 .It UpdateHostKeys
613 .It User
614 .It UserKnownHostsFile
615 .It VerifyHostKeyDNS
616 .It VisualHostKey
617 .It XAuthLocation
618 .El
619 .Pp
620 .It Fl P Ar tag
621 Specify a tag name that may be used to select configuration in
622 .Xr ssh_config 5 .
623 Refer to the
624 .Cm Tag
625 and
626 .Cm Match
627 keywords in
628 .Xr ssh_config 5
629 for more information.
630 .It Fl p Ar port
631 Port to connect to on the remote host.
632 This can be specified on a
633 per-host basis in the configuration file.
634 .Pp
635 .It Fl Q Ar query_option
636 Queries for the algorithms supported by one of the following features:
637 .Ar cipher
638 (supported symmetric ciphers),
639 .Ar cipher-auth
640 (supported symmetric ciphers that support authenticated encryption),
641 .Ar help
642 (supported query terms for use with the
643 .Fl Q
644 flag),
645 .Ar mac
646 (supported message integrity codes),
647 .Ar kex
648 (key exchange algorithms),
649 .Ar kex-gss
650 (GSSAPI key exchange algorithms),
651 .Ar key
652 (key types),
653 .Ar key-ca-sign
654 (valid CA signature algorithms for certificates),
655 .Ar key-cert
656 (certificate key types),
657 .Ar key-plain
658 (non-certificate key types),
659 .Ar key-sig
660 (all key types and signature algorithms),
661 .Ar protocol-version
662 (supported SSH protocol versions), and
663 .Ar sig
664 (supported signature algorithms).
665 Alternatively, any keyword from
666 .Xr ssh_config 5
667 or
668 .Xr sshd_config 5
669 that takes an algorithm list may be used as an alias for the corresponding
670 query_option.
671 .Pp
672 .It Fl q
673 Quiet mode.
674 Causes most warning and diagnostic messages to be suppressed.
675 .Pp
676 .It Fl R Xo
677 .Sm off
678 .Oo Ar bind_address : Oc
679 .Ar port : host : hostport
680 .Sm on
681 .Xc
682 .It Fl R Xo
683 .Sm off
684 .Oo Ar bind_address : Oc
685 .Ar port : local_socket
686 .Sm on
687 .Xc
688 .It Fl R Xo
689 .Sm off
690 .Ar remote_socket : host : hostport
691 .Sm on
692 .Xc
693 .It Fl R Xo
694 .Sm off
695 .Ar remote_socket : local_socket
696 .Sm on
697 .Xc
698 .It Fl R Xo
699 .Sm off
700 .Oo Ar bind_address : Oc
701 .Ar port
702 .Sm on
703 .Xc
704 Specifies that connections to the given TCP port or Unix socket on the remote
705 (server) host are to be forwarded to the local side.
706 .Pp
707 This works by allocating a socket to listen to either a TCP
708 .Ar port
709 or to a Unix socket on the remote side.
710 Whenever a connection is made to this port or Unix socket, the
711 connection is forwarded over the secure channel, and a connection
712 is made from the local machine to either an explicit destination specified by
713 .Ar host
714 port
715 .Ar hostport ,
716 or
717 .Ar local_socket ,
718 or, if no explicit destination was specified,
719 .Nm
720 will act as a SOCKS 4/5 proxy and forward connections to the destinations
721 requested by the remote SOCKS client.
722 .Pp
723 Port forwardings can also be specified in the configuration file.
724 Privileged ports can be forwarded only when
725 logging in as root on the remote machine.
726 IPv6 addresses can be specified by enclosing the address in square brackets.
727 .Pp
728 By default, TCP listening sockets on the server will be bound to the loopback
729 interface only.
730 This may be overridden by specifying a
731 .Ar bind_address .
732 An empty
733 .Ar bind_address ,
734 or the address
735 .Ql * ,
736 indicates that the remote socket should listen on all interfaces.
737 Specifying a remote
738 .Ar bind_address
739 will only succeed if the server's
740 .Cm GatewayPorts
741 option is enabled (see
742 .Xr sshd_config 5 ) .
743 .Pp
744 If the
745 .Ar port
746 argument is
747 .Ql 0 ,
748 the listen port will be dynamically allocated on the server and reported
749 to the client at run time.
750 When used together with
751 .Ic -O forward ,
752 the allocated port will be printed to the standard output.
753 .Pp
754 .It Fl S Ar ctl_path
755 Specifies the location of a control socket for connection sharing,
756 or the string
757 .Dq none
758 to disable connection sharing.
759 Refer to the description of
760 .Cm ControlPath
761 and
762 .Cm ControlMaster
763 in
764 .Xr ssh_config 5
765 for details.
766 .Pp
767 .It Fl s
768 May be used to request invocation of a subsystem on the remote system.
769 Subsystems facilitate the use of SSH
770 as a secure transport for other applications (e.g.\&
771 .Xr sftp 1 ) .
772 The subsystem is specified as the remote command.
773 Refer to the description of
774 .Cm SessionType
775 in
776 .Xr ssh_config 5
777 for details.
778 .Pp
779 .It Fl T
780 Disable pseudo-terminal allocation.
781 .Pp
782 .It Fl t
783 Force pseudo-terminal allocation.
784 This can be used to execute arbitrary
785 screen-based programs on a remote machine, which can be very useful,
786 e.g. when implementing menu services.
787 Multiple
788 .Fl t
789 options force tty allocation, even if
790 .Nm
791 has no local tty.
792 .Pp
793 .It Fl V
794 Display the version number and exit.
795 .Pp
796 .It Fl v
797 Verbose mode.
798 Causes
799 .Nm
800 to print debugging messages about its progress.
801 This is helpful in
802 debugging connection, authentication, and configuration problems.
803 Multiple
804 .Fl v
805 options increase the verbosity.
806 The maximum is 3.
807 .Pp
808 .It Fl W Ar host : Ns Ar port
809 Requests that standard input and output on the client be forwarded to
810 .Ar host
811 on
812 .Ar port
813 over the secure channel.
814 Implies
815 .Fl N ,
816 .Fl T ,
817 .Cm ExitOnForwardFailure
818 and
819 .Cm ClearAllForwardings ,
820 though these can be overridden in the configuration file or using
821 .Fl o
822 command line options.
823 .Pp
824 .It Fl w Xo
825 .Ar local_tun Ns Op : Ns Ar remote_tun
826 .Xc
827 Requests
828 tunnel
829 device forwarding with the specified
830 .Xr tun 4
831 devices between the client
832 .Pq Ar local_tun
833 and the server
834 .Pq Ar remote_tun .
835 .Pp
836 The devices may be specified by numerical ID or the keyword
837 .Dq any ,
838 which uses the next available tunnel device.
839 If
840 .Ar remote_tun
841 is not specified, it defaults to
842 .Dq any .
843 See also the
844 .Cm Tunnel
845 and
846 .Cm TunnelDevice
847 directives in
848 .Xr ssh_config 5 .
849 .Pp
850 If the
851 .Cm Tunnel
852 directive is unset, it will be set to the default tunnel mode, which is
853 .Dq point-to-point .
854 If a different
855 .Cm Tunnel
856 forwarding mode it desired, then it should be specified before
857 .Fl w .
858 .Pp
859 .It Fl X
860 Enables X11 forwarding.
861 This can also be specified on a per-host basis in a configuration file.
862 .Pp
863 X11 forwarding should be enabled with caution.
864 Users with the ability to bypass file permissions on the remote host
865 (for the user's X authorization database)
866 can access the local X11 display through the forwarded connection.
867 An attacker may then be able to perform activities such as keystroke monitoring.
868 .Pp
869 For this reason, X11 forwarding is subjected to X11 SECURITY extension
870 restrictions by default.
871 Refer to the
872 .Nm
873 .Fl Y
874 option and the
875 .Cm ForwardX11Trusted
876 directive in
877 .Xr ssh_config 5
878 for more information.
879 .Pp
880 (Debian-specific: X11 forwarding is not subjected to X11 SECURITY extension
881 restrictions by default, because too many programs currently crash in this
882 mode.
883 Set the
884 .Cm ForwardX11Trusted
885 option to
886 .Dq no
887 to restore the upstream behaviour.
888 This may change in future depending on client-side improvements.)
889 .Pp
890 .It Fl x
891 Disables X11 forwarding.
892 .Pp
893 .It Fl Y
894 Enables trusted X11 forwarding.
895 Trusted X11 forwardings are not subjected to the X11 SECURITY extension
896 controls.
897 .Pp
898 (Debian-specific: In the default configuration, this option is equivalent to
899 .Fl X ,
900 since
901 .Cm ForwardX11Trusted
902 defaults to
903 .Dq yes
904 as described above.
905 Set the
906 .Cm ForwardX11Trusted
907 option to
908 .Dq no
909 to restore the upstream behaviour.
910 This may change in future depending on client-side improvements.)
911 .Pp
912 .It Fl y
913 Send log information using the
914 .Xr syslog 3
915 system module.
916 By default this information is sent to stderr.
917 .El
918 .Pp
919 .Nm
920 may additionally obtain configuration data from
921 a per-user configuration file and a system-wide configuration file.
922 The file format and configuration options are described in
923 .Xr ssh_config 5 .
924 .Sh AUTHENTICATION
925 The OpenSSH SSH client supports SSH protocol 2.
926 .Pp
927 The methods available for authentication are:
928 GSSAPI-based authentication,
929 host-based authentication,
930 public key authentication,
931 keyboard-interactive authentication,
932 and password authentication.
933 Authentication methods are tried in the order specified above,
934 though
935 .Cm PreferredAuthentications
936 can be used to change the default order.
937 .Pp
938 Host-based authentication works as follows:
939 If the machine the user logs in from is listed in
940 .Pa /etc/hosts.equiv
941 or
942 .Pa /etc/ssh/shosts.equiv
943 on the remote machine, the user is non-root and the user names are
944 the same on both sides, or if the files
945 .Pa ~/.rhosts
946 or
947 .Pa ~/.shosts
948 exist in the user's home directory on the
949 remote machine and contain a line containing the name of the client
950 machine and the name of the user on that machine, the user is
951 considered for login.
952 Additionally, the server
953 .Em must
954 be able to verify the client's
955 host key (see the description of
956 .Pa /etc/ssh/ssh_known_hosts
957 and
958 .Pa ~/.ssh/known_hosts ,
959 below)
960 for login to be permitted.
961 This authentication method closes security holes due to IP
962 spoofing, DNS spoofing, and routing spoofing.
963 [Note to the administrator:
964 .Pa /etc/hosts.equiv ,
965 .Pa ~/.rhosts ,
966 and the rlogin/rsh protocol in general, are inherently insecure and should be
967 disabled if security is desired.]
968 .Pp
969 Public key authentication works as follows:
970 The scheme is based on public-key cryptography,
971 using cryptosystems
972 where encryption and decryption are done using separate keys,
973 and it is unfeasible to derive the decryption key from the encryption key.
974 The idea is that each user creates a public/private
975 key pair for authentication purposes.
976 The server knows the public key, and only the user knows the private key.
977 .Nm
978 implements public key authentication protocol automatically,
979 using one of the ECDSA, Ed25519 or RSA algorithms.
980 .Pp
981 The file
982 .Pa ~/.ssh/authorized_keys
983 lists the public keys that are permitted for logging in.
984 When the user logs in, the
985 .Nm
986 program tells the server which key pair it would like to use for
987 authentication.
988 The client proves that it has access to the private key
989 and the server checks that the corresponding public key
990 is authorized to accept the account.
991 .Pp
992 The server may inform the client of errors that prevented public key
993 authentication from succeeding after authentication completes using a
994 different method.
995 These may be viewed by increasing the
996 .Cm LogLevel
997 to
998 .Cm DEBUG
999 or higher (e.g. by using the
1000 .Fl v
1001 flag).
1002 .Pp
1003 The user creates their key pair by running
1004 .Xr ssh-keygen 1 .
1005 This stores the private key in
1006 .Pa ~/.ssh/id_ecdsa
1007 (ECDSA),
1008 .Pa ~/.ssh/id_ecdsa_sk
1009 (authenticator-hosted ECDSA),
1010 .Pa ~/.ssh/id_ed25519
1011 (Ed25519),
1012 .Pa ~/.ssh/id_ed25519_sk
1013 (authenticator-hosted Ed25519),
1014 or
1015 .Pa ~/.ssh/id_rsa
1016 (RSA)
1017 and stores the public key in
1018 .Pa ~/.ssh/id_ecdsa.pub
1019 (ECDSA),
1020 .Pa ~/.ssh/id_ecdsa_sk.pub
1021 (authenticator-hosted ECDSA),
1022 .Pa ~/.ssh/id_ed25519.pub
1023 (Ed25519),
1024 .Pa ~/.ssh/id_ed25519_sk.pub
1025 (authenticator-hosted Ed25519),
1026 or
1027 .Pa ~/.ssh/id_rsa.pub
1028 (RSA)
1029 in the user's home directory.
1030 The user should then copy the public key
1031 to
1032 .Pa ~/.ssh/authorized_keys
1033 in their home directory on the remote machine.
1034 The
1035 .Pa authorized_keys
1036 file corresponds to the conventional
1037 .Pa ~/.rhosts
1038 file, and has one key
1039 per line, though the lines can be very long.
1040 After this, the user can log in without giving the password.
1041 .Pp
1042 A variation on public key authentication
1043 is available in the form of certificate authentication:
1044 instead of a set of public/private keys,
1045 signed certificates are used.
1046 This has the advantage that a single trusted certification authority
1047 can be used in place of many public/private keys.
1048 See the CERTIFICATES section of
1049 .Xr ssh-keygen 1
1050 for more information.
1051 .Pp
1052 The most convenient way to use public key or certificate authentication
1053 may be with an authentication agent.
1054 See
1055 .Xr ssh-agent 1
1056 and (optionally) the
1057 .Cm AddKeysToAgent
1058 directive in
1059 .Xr ssh_config 5
1060 for more information.
1061 .Pp
1062 Keyboard-interactive authentication works as follows:
1063 The server sends an arbitrary
1064 .Qq challenge
1065 text and prompts for a response, possibly multiple times.
1066 Examples of keyboard-interactive authentication include
1067 .Bx
1068 Authentication (see
1069 .Xr login.conf 5 )
1070 and PAM (some
1071 .Pf non- Ox
1072 systems).
1073 .Pp
1074 Finally, if other authentication methods fail,
1075 .Nm
1076 prompts the user for a password.
1077 The password is sent to the remote
1078 host for checking; however, since all communications are encrypted,
1079 the password cannot be seen by someone listening on the network.
1080 .Pp
1081 .Nm
1082 automatically maintains and checks a database containing
1083 identification for all hosts it has ever been used with.
1084 Host keys are stored in
1085 .Pa ~/.ssh/known_hosts
1086 in the user's home directory.
1087 Additionally, the file
1088 .Pa /etc/ssh/ssh_known_hosts
1089 is automatically checked for known hosts.
1090 Any new hosts are automatically added to the user's file.
1091 If a host's identification ever changes,
1092 .Nm
1093 warns about this and disables password authentication to prevent
1094 server spoofing or man-in-the-middle attacks,
1095 which could otherwise be used to circumvent the encryption.
1096 The
1097 .Cm StrictHostKeyChecking
1098 option can be used to control logins to machines whose
1099 host key is not known or has changed.
1100 .Pp
1101 When the user's identity has been accepted by the server, the server
1102 either executes the given command in a non-interactive session or,
1103 if no command has been specified, logs into the machine and gives
1104 the user a normal shell as an interactive session.
1105 All communication with
1106 the remote command or shell will be automatically encrypted.
1107 .Pp
1108 If an interactive session is requested,
1109 .Nm
1110 by default will only request a pseudo-terminal (pty) for interactive
1111 sessions when the client has one.
1112 The flags
1113 .Fl T
1114 and
1115 .Fl t
1116 can be used to override this behaviour.
1117 .Pp
1118 If a pseudo-terminal has been allocated, the
1119 user may use the escape characters noted below.
1120 .Pp
1121 If no pseudo-terminal has been allocated,
1122 the session is transparent and can be used to reliably transfer binary data.
1123 On most systems, setting the escape character to
1124 .Dq none
1125 will also make the session transparent even if a tty is used.
1126 .Pp
1127 The session terminates when the command or shell on the remote
1128 machine exits and all X11 and TCP connections have been closed.
1129 .Sh ESCAPE CHARACTERS
1130 When a pseudo-terminal has been requested,
1131 .Nm
1132 supports a number of functions through the use of an escape character.
1133 .Pp
1134 A single tilde character can be sent as
1135 .Ic ~~
1136 or by following the tilde by a character other than those described below.
1137 The escape character must always follow a newline to be interpreted as
1138 special.
1139 The escape character can be changed in configuration files using the
1140 .Cm EscapeChar
1141 configuration directive or on the command line by the
1142 .Fl e
1143 option.
1144 .Pp
1145 The supported escapes (assuming the default
1146 .Ql ~ )
1147 are:
1148 .Bl -tag -width Ds
1149 .It Cm ~.
1150 Disconnect.
1151 .It Cm ~^Z
1152 Background
1153 .Nm .
1154 .It Cm ~#
1155 List forwarded connections.
1156 .It Cm ~&
1157 Background
1158 .Nm
1159 at logout when waiting for forwarded connection / X11 sessions to terminate.
1160 .It Cm ~?
1161 Display a list of escape characters.
1162 .It Cm ~B
1163 Send a BREAK to the remote system
1164 (only useful if the peer supports it).
1165 .It Cm ~C
1166 Open command line.
1167 Currently this allows the addition of port forwardings using the
1168 .Fl L ,
1169 .Fl R
1170 and
1171 .Fl D
1172 options (see above).
1173 It also allows the cancellation of existing port-forwardings
1174 with
1175 .Sm off
1176 .Fl KL Oo Ar bind_address : Oc Ar port
1177 .Sm on
1178 for local,
1179 .Sm off
1180 .Fl KR Oo Ar bind_address : Oc Ar port
1181 .Sm on
1182 for remote and
1183 .Sm off
1184 .Fl KD Oo Ar bind_address : Oc Ar port
1185 .Sm on
1186 for dynamic port-forwardings.
1187 .Ic !\& Ns Ar command
1188 allows the user to execute a local command if the
1189 .Ic PermitLocalCommand
1190 option is enabled in
1191 .Xr ssh_config 5 .
1192 Basic help is available, using the
1193 .Fl h
1194 option.
1195 .It Cm ~I
1196 Show information about the current SSH connection.
1197 .It Cm ~R
1198 Request rekeying of the connection
1199 (only useful if the peer supports it).
1200 .It Cm ~V
1201 Decrease the verbosity
1202 .Pq Ic LogLevel
1203 when errors are being written to stderr.
1204 .It Cm ~v
1205 Increase the verbosity
1206 .Pq Ic LogLevel
1207 when errors are being written to stderr.
1208 .El
1209 .Sh TCP FORWARDING
1210 Forwarding of arbitrary TCP connections over a secure channel
1211 can be specified either on the command line or in a configuration file.
1212 One possible application of TCP forwarding is a secure connection to a
1213 mail server; another is going through firewalls.
1214 .Pp
1215 In the example below, we look at encrypting communication for an IRC client,
1216 even though the IRC server it connects to does not directly
1217 support encrypted communication.
1218 This works as follows:
1219 the user connects to the remote host using
1220 .Nm ,
1221 specifying the ports to be used to forward the connection.
1222 After that it is possible to start the program locally,
1223 and
1224 .Nm
1225 will encrypt and forward the connection to the remote server.
1226 .Pp
1227 The following example tunnels an IRC session from the client
1228 to an IRC server at
1229 .Dq server.example.com ,
1230 joining channel
1231 .Dq #users ,
1232 nickname
1233 .Dq pinky ,
1234 using the standard IRC port, 6667:
1235 .Bd -literal -offset 4n
1236 $ ssh -f -L 6667:localhost:6667 server.example.com sleep 10
1237 $ irc -c '#users' pinky IRC/127.0.0.1
1238 .Ed
1239 .Pp
1240 The
1241 .Fl f
1242 option backgrounds
1243 .Nm
1244 and the remote command
1245 .Dq sleep 10
1246 is specified to allow an amount of time
1247 (10 seconds, in the example)
1248 to start the program which is going to use the tunnel.
1249 If no connections are made within the time specified,
1250 .Nm
1251 will exit.
1252 .Sh X11 FORWARDING
1253 If the
1254 .Cm ForwardX11
1255 variable is set to
1256 .Dq yes
1257 (or see the description of the
1258 .Fl X ,
1259 .Fl x ,
1260 and
1261 .Fl Y
1262 options above)
1263 and the user is using X11 (the
1264 .Ev DISPLAY
1265 environment variable is set), the connection to the X11 display is
1266 automatically forwarded to the remote side in such a way that any X11
1267 programs started from the shell (or command) will go through the
1268 encrypted channel, and the connection to the real X server will be made
1269 from the local machine.
1270 The user should not manually set
1271 .Ev DISPLAY .
1272 Forwarding of X11 connections can be
1273 configured on the command line or in configuration files.
1274 .Pp
1275 The
1276 .Ev DISPLAY
1277 value set by
1278 .Nm
1279 will point to the server machine, but with a display number greater than zero.
1280 This is normal, and happens because
1281 .Nm
1282 creates a
1283 .Dq proxy
1284 X server on the server machine for forwarding the
1285 connections over the encrypted channel.
1286 .Pp
1287 .Nm
1288 will also automatically set up Xauthority data on the server machine.
1289 For this purpose, it will generate a random authorization cookie,
1290 store it in Xauthority on the server, and verify that any forwarded
1291 connections carry this cookie and replace it by the real cookie when
1292 the connection is opened.
1293 The real authentication cookie is never
1294 sent to the server machine (and no cookies are sent in the plain).
1295 .Pp
1296 If the
1297 .Cm ForwardAgent
1298 variable is set to
1299 .Dq yes
1300 (or see the description of the
1301 .Fl A
1302 and
1303 .Fl a
1304 options above) and
1305 the user is using an authentication agent, the connection to the agent
1306 is automatically forwarded to the remote side.
1307 .Sh VERIFYING HOST KEYS
1308 When connecting to a server for the first time,
1309 a fingerprint of the server's public key is presented to the user
1310 (unless the option
1311 .Cm StrictHostKeyChecking
1312 has been disabled).
1313 Fingerprints can be determined using
1314 .Xr ssh-keygen 1 :
1315 .Pp
1316 .Dl $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key
1317 .Pp
1318 If the fingerprint is already known, it can be matched
1319 and the key can be accepted or rejected.
1320 If only legacy (MD5) fingerprints for the server are available, the
1321 .Xr ssh-keygen 1
1322 .Fl E
1323 option may be used to downgrade the fingerprint algorithm to match.
1324 .Pp
1325 Because of the difficulty of comparing host keys
1326 just by looking at fingerprint strings,
1327 there is also support to compare host keys visually,
1328 using
1329 .Em random art .
1330 By setting the
1331 .Cm VisualHostKey
1332 option to
1333 .Dq yes ,
1334 a small ASCII graphic gets displayed on every login to a server, no matter
1335 if the session itself is interactive or not.
1336 By learning the pattern a known server produces, a user can easily
1337 find out that the host key has changed when a completely different pattern
1338 is displayed.
1339 Because these patterns are not unambiguous however, a pattern that looks
1340 similar to the pattern remembered only gives a good probability that the
1341 host key is the same, not guaranteed proof.
1342 .Pp
1343 To get a listing of the fingerprints along with their random art for
1344 all known hosts, the following command line can be used:
1345 .Pp
1346 .Dl $ ssh-keygen -lv -f ~/.ssh/known_hosts
1347 .Pp
1348 If the fingerprint is unknown,
1349 an alternative method of verification is available:
1350 SSH fingerprints verified by DNS.
1351 An additional resource record (RR),
1352 SSHFP,
1353 is added to a zonefile
1354 and the connecting client is able to match the fingerprint
1355 with that of the key presented.
1356 .Pp
1357 In this example, we are connecting a client to a server,
1358 .Dq host.example.com .
1359 The SSHFP resource records should first be added to the zonefile for
1360 host.example.com:
1361 .Bd -literal -offset indent
1362 $ ssh-keygen -r host.example.com.
1363 .Ed
1364 .Pp
1365 The output lines will have to be added to the zonefile.
1366 To check that the zone is answering fingerprint queries:
1367 .Pp
1368 .Dl $ dig -t SSHFP host.example.com
1369 .Pp
1370 Finally the client connects:
1371 .Bd -literal -offset indent
1372 $ ssh -o "VerifyHostKeyDNS ask" host.example.com
1373 [...]
1374 Matching host key fingerprint found in DNS.
1375 Are you sure you want to continue connecting (yes/no)?
1376 .Ed
1377 .Pp
1378 See the
1379 .Cm VerifyHostKeyDNS
1380 option in
1381 .Xr ssh_config 5
1382 for more information.
1383 .Sh SSH-BASED VIRTUAL PRIVATE NETWORKS
1384 .Nm
1385 contains support for Virtual Private Network (VPN) tunnelling
1386 using the
1387 .Xr tun 4
1388 network pseudo-device,
1389 allowing two networks to be joined securely.
1390 The
1391 .Xr sshd_config 5
1392 configuration option
1393 .Cm PermitTunnel
1394 controls whether the server supports this,
1395 and at what level (layer 2 or 3 traffic).
1396 .Pp
1397 The following example would connect client network 10.0.50.0/24
1398 with remote network 10.0.99.0/24 using a point-to-point connection
1399 from 10.1.1.1 to 10.1.1.2,
1400 provided that the SSH server running on the gateway to the remote network,
1401 at 192.168.1.15, allows it.
1402 .Pp
1403 On the client:
1404 .Bd -literal -offset indent
1405 # ssh -f -w 0:1 192.168.1.15 true
1406 # ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252
1407 # route add 10.0.99.0/24 10.1.1.2
1408 .Ed
1409 .Pp
1410 On the server:
1411 .Bd -literal -offset indent
1412 # ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252
1413 # route add 10.0.50.0/24 10.1.1.1
1414 .Ed
1415 .Pp
1416 Client access may be more finely tuned via the
1417 .Pa /root/.ssh/authorized_keys
1418 file (see below) and the
1419 .Cm PermitRootLogin
1420 server option.
1421 The following entry would permit connections on
1422 .Xr tun 4
1423 device 1 from user
1424 .Dq jane
1425 and on tun device 2 from user
1426 .Dq john ,
1427 if
1428 .Cm PermitRootLogin
1429 is set to
1430 .Dq forced-commands-only :
1431 .Bd -literal -offset 2n
1432 tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane
1433 tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john
1434 .Ed
1435 .Pp
1436 Since an SSH-based setup entails a fair amount of overhead,
1437 it may be more suited to temporary setups,
1438 such as for wireless VPNs.
1439 More permanent VPNs are better provided by tools such as
1440 .Xr ipsecctl 8
1441 and
1442 .Xr isakmpd 8 .
1443 .Sh ENVIRONMENT
1444 .Nm
1445 will normally set the following environment variables:
1446 .Bl -tag -width "SSH_ORIGINAL_COMMAND"
1447 .It Ev DISPLAY
1448 The
1449 .Ev DISPLAY
1450 variable indicates the location of the X11 server.
1451 It is automatically set by
1452 .Nm
1453 to point to a value of the form
1454 .Dq hostname:n ,
1455 where
1456 .Dq hostname
1457 indicates the host where the shell runs, and
1458 .Sq n
1459 is an integer \*(Ge 1.
1460 .Nm
1461 uses this special value to forward X11 connections over the secure
1462 channel.
1463 The user should normally not set
1464 .Ev DISPLAY
1465 explicitly, as that
1466 will render the X11 connection insecure (and will require the user to
1467 manually copy any required authorization cookies).
1468 .It Ev HOME
1469 Set to the path of the user's home directory.
1470 .It Ev LOGNAME
1471 Synonym for
1472 .Ev USER ;
1473 set for compatibility with systems that use this variable.
1474 .It Ev MAIL
1475 Set to the path of the user's mailbox.
1476 .It Ev PATH
1477 Set to the default
1478 .Ev PATH ,
1479 as specified when compiling
1480 .Nm .
1481 .It Ev SSH_ASKPASS
1482 If
1483 .Nm
1484 needs a passphrase, it will read the passphrase from the current
1485 terminal if it was run from a terminal.
1486 If
1487 .Nm
1488 does not have a terminal associated with it but
1489 .Ev DISPLAY
1490 and
1491 .Ev SSH_ASKPASS
1492 are set, it will execute the program specified by
1493 .Ev SSH_ASKPASS
1494 and open an X11 window to read the passphrase.
1495 This is particularly useful when calling
1496 .Nm
1497 from a
1498 .Pa .xsession
1499 or related script.
1500 (Note that on some machines it
1501 may be necessary to redirect the input from
1502 .Pa /dev/null
1503 to make this work.)
1504 .It Ev SSH_ASKPASS_REQUIRE
1505 Allows further control over the use of an askpass program.
1506 If this variable is set to
1507 .Dq never
1508 then
1509 .Nm
1510 will never attempt to use one.
1511 If it is set to
1512 .Dq prefer ,
1513 then
1514 .Nm
1515 will prefer to use the askpass program instead of the TTY when requesting
1516 passwords.
1517 Finally, if the variable is set to
1518 .Dq force ,
1519 then the askpass program will be used for all passphrase input regardless
1520 of whether
1521 .Ev DISPLAY
1522 is set.
1523 .It Ev SSH_AUTH_SOCK
1524 Identifies the path of a
1525 .Ux Ns -domain
1526 socket used to communicate with the agent.
1527 .It Ev SSH_CONNECTION
1528 Identifies the client and server ends of the connection.
1529 The variable contains
1530 four space-separated values: client IP address, client port number,
1531 server IP address, and server port number.
1532 .It Ev SSH_ORIGINAL_COMMAND
1533 This variable contains the original command line if a forced command
1534 is executed.
1535 It can be used to extract the original arguments.
1536 .It Ev SSH_TTY
1537 This is set to the name of the tty (path to the device) associated
1538 with the current shell or command.
1539 If the current session has no tty,
1540 this variable is not set.
1541 .It Ev SSH_TUNNEL
1542 Optionally set by
1543 .Xr sshd 8
1544 to contain the interface names assigned if tunnel forwarding was
1545 requested by the client.
1546 .It Ev SSH_USER_AUTH
1547 Optionally set by
1548 .Xr sshd 8 ,
1549 this variable may contain a pathname to a file that lists the authentication
1550 methods successfully used when the session was established, including any
1551 public keys that were used.
1552 .It Ev TZ
1553 This variable is set to indicate the present time zone if it
1554 was set when the daemon was started (i.e. the daemon passes the value
1555 on to new connections).
1556 .It Ev USER
1557 Set to the name of the user logging in.
1558 .El
1559 .Pp
1560 Additionally,
1561 .Nm
1562 reads
1563 .Pa ~/.ssh/environment ,
1564 and adds lines of the format
1565 .Dq VARNAME=value
1566 to the environment if the file exists and users are allowed to
1567 change their environment.
1568 For more information, see the
1569 .Cm PermitUserEnvironment
1570 option in
1571 .Xr sshd_config 5 .
1572 .Sh FILES
1573 .Bl -tag -width Ds -compact
1574 .It Pa ~/.rhosts
1575 This file is used for host-based authentication (see above).
1576 On some machines this file may need to be
1577 world-readable if the user's home directory is on an NFS partition,
1578 because
1579 .Xr sshd 8
1580 reads it as root.
1581 Additionally, this file must be owned by the user,
1582 and must not have write permissions for anyone else.
1583 The recommended
1584 permission for most machines is read/write for the user, and not
1585 accessible by others.
1586 .Pp
1587 .It Pa ~/.shosts
1588 This file is used in exactly the same way as
1589 .Pa .rhosts ,
1590 but allows host-based authentication without permitting login with
1591 rlogin/rsh.
1592 .Pp
1593 .It Pa ~/.ssh/
1594 This directory is the default location for all user-specific configuration
1595 and authentication information.
1596 There is no general requirement to keep the entire contents of this directory
1597 secret, but the recommended permissions are read/write/execute for the user,
1598 and not accessible by others.
1599 .Pp
1600 .It Pa ~/.ssh/authorized_keys
1601 Lists the public keys (ECDSA, Ed25519, RSA)
1602 that can be used for logging in as this user.
1603 The format of this file is described in the
1604 .Xr sshd 8
1605 manual page.
1606 This file is not highly sensitive, but the recommended
1607 permissions are read/write for the user, and not accessible by others.
1608 .Pp
1609 .It Pa ~/.ssh/config
1610 This is the per-user configuration file.
1611 The file format and configuration options are described in
1612 .Xr ssh_config 5 .
1613 Because of the potential for abuse, this file must have strict permissions:
1614 read/write for the user, and not writable by others.
1615 It may be group-writable provided that the group in question contains only
1616 the user.
1617 .Pp
1618 .It Pa ~/.ssh/environment
1619 Contains additional definitions for environment variables; see
1620 .Sx ENVIRONMENT ,
1621 above.
1622 .Pp
1623 .It Pa ~/.ssh/id_ecdsa
1624 .It Pa ~/.ssh/id_ecdsa_sk
1625 .It Pa ~/.ssh/id_ed25519
1626 .It Pa ~/.ssh/id_ed25519_sk
1627 .It Pa ~/.ssh/id_rsa
1628 Contains the private key for authentication.
1629 These files
1630 contain sensitive data and should be readable by the user but not
1631 accessible by others (read/write/execute).
1632 .Nm
1633 will simply ignore a private key file if it is accessible by others.
1634 It is possible to specify a passphrase when
1635 generating the key which will be used to encrypt the
1636 sensitive part of this file using AES-128.
1637 .Pp
1638 .It Pa ~/.ssh/id_ecdsa.pub
1639 .It Pa ~/.ssh/id_ecdsa_sk.pub
1640 .It Pa ~/.ssh/id_ed25519.pub
1641 .It Pa ~/.ssh/id_ed25519_sk.pub
1642 .It Pa ~/.ssh/id_rsa.pub
1643 Contains the public key for authentication.
1644 These files are not
1645 sensitive and can (but need not) be readable by anyone.
1646 .Pp
1647 .It Pa ~/.ssh/known_hosts
1648 Contains a list of host keys for all hosts the user has logged into
1649 that are not already in the systemwide list of known host keys.
1650 See
1651 .Xr sshd 8
1652 for further details of the format of this file.
1653 .Pp
1654 .It Pa ~/.ssh/rc
1655 Commands in this file are executed by
1656 .Nm
1657 when the user logs in, just before the user's shell (or command) is
1658 started.
1659 See the
1660 .Xr sshd 8
1661 manual page for more information.
1662 .Pp
1663 .It Pa /etc/hosts.equiv
1664 This file is for host-based authentication (see above).
1665 It should only be writable by root.
1666 .Pp
1667 .It Pa /etc/ssh/shosts.equiv
1668 This file is used in exactly the same way as
1669 .Pa hosts.equiv ,
1670 but allows host-based authentication without permitting login with
1671 rlogin/rsh.
1672 .Pp
1673 .It Pa /etc/ssh/ssh_config
1674 Systemwide configuration file.
1675 The file format and configuration options are described in
1676 .Xr ssh_config 5 .
1677 .Pp
1678 .It Pa /etc/ssh/ssh_host_ecdsa_key
1679 .It Pa /etc/ssh/ssh_host_ed25519_key
1680 .It Pa /etc/ssh/ssh_host_rsa_key
1681 These files contain the private parts of the host keys
1682 and are used for host-based authentication.
1683 .Pp
1684 .It Pa /etc/ssh/ssh_known_hosts
1685 Systemwide list of known host keys.
1686 This file should be prepared by the
1687 system administrator to contain the public host keys of all machines in the
1688 organization.
1689 It should be world-readable.
1690 See
1691 .Xr sshd 8
1692 for further details of the format of this file.
1693 .Pp
1694 .It Pa /etc/ssh/sshrc
1695 Commands in this file are executed by
1696 .Nm
1697 when the user logs in, just before the user's shell (or command) is started.
1698 See the
1699 .Xr sshd 8
1700 manual page for more information.
1701 .El
1702 .Sh EXIT STATUS
1703 .Nm
1704 exits with the exit status of the remote command or with 255
1705 if an error occurred.
1706 .Sh SEE ALSO
1707 .Xr scp 1 ,
1708 .Xr sftp 1 ,
1709 .Xr ssh-add 1 ,
1710 .Xr ssh-agent 1 ,
1711 .Xr ssh-argv0 1 ,
1712 .Xr ssh-keygen 1 ,
1713 .Xr ssh-keyscan 1 ,
1714 .Xr tun 4 ,
1715 .Xr ssh_config 5 ,
1716 .Xr ssh-keysign 8 ,
1717 .Xr sshd 8
1718 .Sh STANDARDS
1719 .Rs
1720 .%A S. Lehtinen
1721 .%A C. Lonvick
1722 .%D January 2006
1723 .%R RFC 4250
1724 .%T The Secure Shell (SSH) Protocol Assigned Numbers
1725 .Re
1726 .Pp
1727 .Rs
1728 .%A T. Ylonen
1729 .%A C. Lonvick
1730 .%D January 2006
1731 .%R RFC 4251
1732 .%T The Secure Shell (SSH) Protocol Architecture
1733 .Re
1734 .Pp
1735 .Rs
1736 .%A T. Ylonen
1737 .%A C. Lonvick
1738 .%D January 2006
1739 .%R RFC 4252
1740 .%T The Secure Shell (SSH) Authentication Protocol
1741 .Re
1742 .Pp
1743 .Rs
1744 .%A T. Ylonen
1745 .%A C. Lonvick
1746 .%D January 2006
1747 .%R RFC 4253
1748 .%T The Secure Shell (SSH) Transport Layer Protocol
1749 .Re
1750 .Pp
1751 .Rs
1752 .%A T. Ylonen
1753 .%A C. Lonvick
1754 .%D January 2006
1755 .%R RFC 4254
1756 .%T The Secure Shell (SSH) Connection Protocol
1757 .Re
1758 .Pp
1759 .Rs
1760 .%A J. Schlyter
1761 .%A W. Griffin
1762 .%D January 2006
1763 .%R RFC 4255
1764 .%T Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints
1765 .Re
1766 .Pp
1767 .Rs
1768 .%A F. Cusack
1769 .%A M. Forssen
1770 .%D January 2006
1771 .%R RFC 4256
1772 .%T Generic Message Exchange Authentication for the Secure Shell Protocol (SSH)
1773 .Re
1774 .Pp
1775 .Rs
1776 .%A J. Galbraith
1777 .%A P. Remaker
1778 .%D January 2006
1779 .%R RFC 4335
1780 .%T The Secure Shell (SSH) Session Channel Break Extension
1781 .Re
1782 .Pp
1783 .Rs
1784 .%A M. Bellare
1785 .%A T. Kohno
1786 .%A C. Namprempre
1787 .%D January 2006
1788 .%R RFC 4344
1789 .%T The Secure Shell (SSH) Transport Layer Encryption Modes
1790 .Re
1791 .Pp
1792 .Rs
1793 .%A B. Harris
1794 .%D January 2006
1795 .%R RFC 4345
1796 .%T Improved Arcfour Modes for the Secure Shell (SSH) Transport Layer Protocol
1797 .Re
1798 .Pp
1799 .Rs
1800 .%A M. Friedl
1801 .%A N. Provos
1802 .%A W. Simpson
1803 .%D March 2006
1804 .%R RFC 4419
1805 .%T Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol
1806 .Re
1807 .Pp
1808 .Rs
1809 .%A J. Galbraith
1810 .%A R. Thayer
1811 .%D November 2006
1812 .%R RFC 4716
1813 .%T The Secure Shell (SSH) Public Key File Format
1814 .Re
1815 .Pp
1816 .Rs
1817 .%A D. Stebila
1818 .%A J. Green
1819 .%D December 2009
1820 .%R RFC 5656
1821 .%T Elliptic Curve Algorithm Integration in the Secure Shell Transport Layer
1822 .Re
1823 .Pp
1824 .Rs
1825 .%A A. Perrig
1826 .%A D. Song
1827 .%D 1999
1828 .%O International Workshop on Cryptographic Techniques and E-Commerce (CrypTEC '99)
1829 .%T Hash Visualization: a New Technique to improve Real-World Security
1830 .Re
1831 .Sh AUTHORS
1832 OpenSSH is a derivative of the original and free
1833 ssh 1.2.12 release by Tatu Ylonen.
1834 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1835 Theo de Raadt and Dug Song
1836 removed many bugs, re-added newer features and
1837 created OpenSSH.
1838 Markus Friedl contributed the support for SSH
1839 protocol versions 1.5 and 2.0.