X-Git-Url: http://andersk.mit.edu/gitweb/openssh.git/blobdiff_plain/db175906e383bf590551ef4c9b469dd8ec1864dc..4f983ff501d9432d5f1dfbcc320da9abaac97fcd:/ssh.1 diff --git a/ssh.1 b/ssh.1 index 3fe142dc..71a46f95 100644 --- a/ssh.1 +++ b/ssh.1 @@ -34,8 +34,8 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $OpenBSD: ssh.1,v 1.251 2006/01/20 00:14:55 dtucker Exp $ -.Dd September 25, 1999 +.\" $OpenBSD: ssh.1,v 1.282 2009/02/12 03:44:25 djm Exp $ +.Dd $Mdocdate$ .Dt SSH 1 .Os .Sh NAME @@ -43,7 +43,7 @@ .Nd OpenSSH SSH client (remote login program) .Sh SYNOPSIS .Nm ssh -.Op Fl 1246AaCfgkMNnqsTtVvXxY +.Op Fl 1246AaCfgKkMNnqsTtVvXxYy .Op Fl b Ar bind_address .Op Fl c Ar cipher_spec .Oo Fl D\ \& @@ -78,7 +78,8 @@ .Oc .Op Fl S Ar ctl_path .Bk -words -.Op Fl w Ar tunnel : Ns Ar tunnel +.Oo Fl w Ar local_tun Ns +.Op : Ns Ar remote_tun Oc .Oo Ar user Ns @ Oc Ns Ar hostname .Op Ar command .Ek @@ -289,6 +290,15 @@ This implies The recommended way to start X11 programs at a remote site is with something like .Ic ssh -f host xterm . +.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. .It Fl g Allows remote hosts to connect to local forwarded ports. .It Fl I Ar smartcard_device @@ -314,6 +324,9 @@ It is possible to have multiple .Fl i options (and multiple identities specified in configuration files). +.It Fl K +Enables GSSAPI-based authentication and forwarding (delegation) of GSSAPI +credentials to the server. .It Fl k Disables forwarding (delegation) of GSSAPI credentials to the server. .It Fl L Xo @@ -448,6 +461,7 @@ For full details of the options listed below, and their possible values, see .It ControlPath .It DynamicForward .It EscapeChar +.It ExitOnForwardFailure .It ForwardAgent .It ForwardX11 .It ForwardX11Trusted @@ -493,6 +507,7 @@ For full details of the options listed below, and their possible values, see .It User .It UserKnownHostsFile .It VerifyHostKeyDNS +.It VisualHostKey .It XAuthLocation .El .It Fl p Ar port @@ -501,7 +516,7 @@ This can be specified on a per-host basis in the configuration file. .It Fl q Quiet mode. -Causes all warning and diagnostic messages to be suppressed. +Causes most warning and diagnostic messages to be suppressed. .It Fl R Xo .Sm off .Oo Ar bind_address : Oc @@ -535,7 +550,7 @@ using an alternative syntax: .Pp By default, the listening socket on the server will be bound to the loopback interface only. -This may be overriden by specifying a +This may be overridden by specifying a .Ar bind_address . An empty .Ar bind_address , @@ -548,6 +563,13 @@ will only succeed if the server's .Cm GatewayPorts option is enabled (see .Xr sshd_config 5 ) . +.Pp +If the +.Ar port +argument is +.Ql 0 , +the listen port will be dynamically allocated on the server and reported +to the client at run time. .It Fl S Ar ctl_path Specifies the location of a control socket for connection sharing. Refer to the description of @@ -569,7 +591,7 @@ Disable pseudo-tty allocation. Force pseudo-tty allocation. This can be used to execute arbitrary screen-based programs on a remote machine, which can be very useful, -e.g., when implementing menu services. +e.g. when implementing menu services. Multiple .Fl t options force tty allocation, even if @@ -588,24 +610,35 @@ Multiple .Fl v options increase the verbosity. The maximum is 3. -.It Fl w Ar tunnel : Ns Ar tunnel -Requests a +.It Fl w Xo +.Ar local_tun Ns Op : Ns Ar remote_tun +.Xc +Requests +tunnel +device forwarding with the specified .Xr tun 4 -device on the client -(first -.Ar tunnel -arg) -and server -(second -.Ar tunnel -arg). +devices between the client +.Pq Ar local_tun +and the server +.Pq Ar remote_tun . +.Pp The devices may be specified by numerical ID or the keyword .Dq any , which uses the next available tunnel device. +If +.Ar remote_tun +is not specified, it defaults to +.Dq any . See also the .Cm Tunnel -directive in +and +.Cm TunnelDevice +directives in .Xr ssh_config 5 . +If the +.Cm Tunnel +directive is unset, it is set to the default tunnel mode, which is +.Dq point-to-point . .It Fl X Enables X11 forwarding. This can also be specified on a per-host basis in a configuration file. @@ -632,6 +665,11 @@ Disables X11 forwarding. Enables trusted X11 forwarding. Trusted X11 forwardings are not subjected to the X11 SECURITY extension controls. +.It Fl y +Send log information using the +.Xr syslog 3 +system module. +By default this information is sent to stderr. .El .Pp .Nm @@ -661,11 +699,12 @@ Both protocols support similar authentication methods, but protocol 2 is preferred since it provides additional mechanisms for confidentiality (the traffic is encrypted using AES, 3DES, Blowfish, CAST128, or Arcfour) -and integrity (hmac-md5, hmac-sha1, hmac-ripemd160). +and integrity (hmac-md5, hmac-sha1, umac-64, hmac-ripemd160). Protocol 1 lacks a strong mechanism for ensuring the integrity of the connection. .Pp The methods available for authentication are: +GSSAPI-based authentication, host-based authentication, public key authentication, challenge-response authentication, @@ -810,15 +849,6 @@ The option can be used to control logins to machines whose host key is not known or has changed. .Pp -.Nm -can be configured to verify host identification using fingerprint resource -records (SSHFP) published in DNS. -The -.Cm VerifyHostKeyDNS -option can be used to control how DNS lookups are performed. -SSHFP resource records can be generated using -.Xr ssh-keygen 1 . -.Pp When the user's identity has been accepted by the server, the server either executes the given command, or logs into the machine and gives the user a normal shell on the remote machine. @@ -875,13 +905,16 @@ Send a BREAK to the remote system .It Cm ~C Open command line. Currently this allows the addition of port forwardings using the -.Fl L -and +.Fl L , .Fl R +and +.Fl D options (see above). It also allows the cancellation of existing remote port-forwardings using -.Fl KR Ar hostport . +.Sm off +.Fl KR Oo Ar bind_address : Oc Ar port . +.Sm on .Ic !\& Ns Ar command allows the user to execute a local command if the .Ic PermitLocalCommand @@ -1006,6 +1039,77 @@ and options above) and the user is using an authentication agent, the connection to the agent is automatically forwarded to the remote side. +.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 +If the fingerprint is already known, it can be matched +and the key can be accepted or rejected. +Because of the difficulty of comparing host keys +just by looking at hex strings, +there is also support to compare host keys visually, +using +.Em random art . +By setting the +.Cm VisualHostKey +option to +.Dq yes , +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 +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 +$ ssh-keygen -r host.example.com. +.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. .Sh SSH-BASED VIRTUAL PRIVATE NETWORKS .Nm contains support for Virtual Private Network (VPN) tunnelling @@ -1021,12 +1125,22 @@ 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 -with remote network 10.0.99.0/24, provided that the SSH server -running on the gateway to the remote network, -at 192.168.1.15, allows it: +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: .Bd -literal -offset indent # ssh -f -w 0:1 192.168.1.15 true -# ifconfig tun0 10.0.50.1 10.0.99.1 netmask 255.255.255.252 +# 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 .Ed .Pp Client access may be more finely tuned via the @@ -1034,11 +1148,11 @@ Client access may be more finely tuned via the file (see below) and the .Cm PermitRootLogin server option. -The following entry would permit connections on the first +The following entry would permit connections on .Xr tun 4 -device from user +device 1 from user .Dq jane -and on the second device from user +and on tun device 2 from user .Dq john , if .Cm PermitRootLogin @@ -1046,10 +1160,10 @@ is set to .Dq forced-commands-only : .Bd -literal -offset 2n tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane -tunnel="2",command="sh /etc/netstart tun1" ssh-rsa ... john +tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john .Ed .Pp -Since a SSH-based setup entails a fair amount of overhead, +Since an SSH-based setup entails a fair amount of overhead, it may be more suited to temporary setups, such as for wireless VPNs. More permanent VPNs are better provided by tools such as @@ -1137,7 +1251,7 @@ If the current session has no tty, this variable is not set. .It Ev TZ This variable is set to indicate the present time zone if it -was set when the daemon was started (i.e., the daemon passes the value +was set when the daemon was started (i.e. the daemon passes the value on to new connections). .It Ev USER Set to the name of the user logging in. @@ -1176,6 +1290,13 @@ This file is used in exactly the same way as but allows host-based authentication without permitting login with rlogin/rsh. .Pp +.It ~/.ssh/ +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 .It ~/.ssh/authorized_keys Lists the public keys (RSA/DSA) that can be used for logging in as this user. The format of this file is described in the @@ -1215,9 +1336,6 @@ sensitive part of this file using 3DES. Contains the public key for authentication. These files are not sensitive and can (but need not) be readable by anyone. -They are -never used automatically and are not necessary: they are only provided for -the convenience of the user. .Pp .It ~/.ssh/known_hosts Contains a list of host keys for all hosts the user has logged into @@ -1301,15 +1419,71 @@ manual page for more information. .Xr ssh-keysign 8 , .Xr sshd 8 .Rs -.%A T. Ylonen -.%A T. Kivinen -.%A M. Saarinen -.%A T. Rinne -.%A S. Lehtinen -.%T "SSH Protocol Architecture" -.%N draft-ietf-secsh-architecture-12.txt -.%D January 2002 -.%O work in progress material +.%R RFC 4250 +.%T "The Secure Shell (SSH) Protocol Assigned Numbers" +.%D 2006 +.Re +.Rs +.%R RFC 4251 +.%T "The Secure Shell (SSH) Protocol Architecture" +.%D 2006 +.Re +.Rs +.%R RFC 4252 +.%T "The Secure Shell (SSH) Authentication Protocol" +.%D 2006 +.Re +.Rs +.%R RFC 4253 +.%T "The Secure Shell (SSH) Transport Layer Protocol" +.%D 2006 +.Re +.Rs +.%R RFC 4254 +.%T "The Secure Shell (SSH) Connection Protocol" +.%D 2006 +.Re +.Rs +.%R RFC 4255 +.%T "Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints" +.%D 2006 +.Re +.Rs +.%R RFC 4256 +.%T "Generic Message Exchange Authentication for the Secure Shell Protocol (SSH)" +.%D 2006 +.Re +.Rs +.%R RFC 4335 +.%T "The Secure Shell (SSH) Session Channel Break Extension" +.%D 2006 +.Re +.Rs +.%R RFC 4344 +.%T "The Secure Shell (SSH) Transport Layer Encryption Modes" +.%D 2006 +.Re +.Rs +.%R RFC 4345 +.%T "Improved Arcfour Modes for the Secure Shell (SSH) Transport Layer Protocol" +.%D 2006 +.Re +.Rs +.%R RFC 4419 +.%T "Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol" +.%D 2006 +.Re +.Rs +.%R RFC 4716 +.%T "The Secure Shell (SSH) Public Key File Format" +.%D 2006 +.Re +.Rs +.%T "Hash Visualization: a New Technique to improve Real-World Security" +.%A A. Perrig +.%A D. Song +.%D 1999 +.%O "International Workshop on Cryptographic Techniques and E-Commerce (CrypTEC '99)" .Re .Sh AUTHORS OpenSSH is a derivative of the original and free