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