crypto/openssh/ssh.1

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