X-Git-Url: http://andersk.mit.edu/gitweb/openssh.git/blobdiff_plain/5d4e571cbecc4af613398e31aba146fae2381012..4f983ff501d9432d5f1dfbcc320da9abaac97fcd:/ssh.1?ds=sidebyside diff --git a/ssh.1 b/ssh.1 index b430ff82..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.247 2006/01/12 18:48:48 jmc 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 @@ -477,6 +491,7 @@ For full details of the options listed below, and their possible values, see .It Protocol .It ProxyCommand .It PubkeyAuthentication +.It RekeyLimit .It RemoteForward .It RhostsRSAAuthentication .It RSAAuthentication @@ -492,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 @@ -500,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 @@ -534,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 , @@ -547,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 @@ -568,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 @@ -587,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. @@ -631,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 @@ -643,7 +682,7 @@ The file format and configuration options are described in exits with the exit status of the remote command or with 255 if an error occurred. .Sh AUTHENTICATION -The OpenSSH SSH client supports OpenSSH protocols 1 and 2. +The OpenSSH SSH client supports SSH protocols 1 and 2. Protocol 2 is the default, with .Nm falling back to protocol 1 if it detects protocol 2 is unsupported. @@ -660,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, @@ -809,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. @@ -874,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 @@ -950,9 +984,6 @@ to start the service which is to be tunnelled. If no connections are made within the time specified, .Nm will exit. -Once opened, -a SSH connection will remain active -until all actively forwarded connections have closed. .Sh X11 FORWARDING If the .Cm ForwardX11 @@ -1008,6 +1039,137 @@ 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 +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 +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.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 +.Pa /root/.ssh/authorized_keys +file (see below) and the +.Cm PermitRootLogin +server option. +The following entry would permit connections on +.Xr tun 4 +device 1 from user +.Dq jane +and on tun device 2 from user +.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 +tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john +.Ed +.Pp +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 +.Xr ipsecctl 8 +and +.Xr isakmpd 8 . .Sh ENVIRONMENT .Nm will normally set the following environment variables: @@ -1089,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. @@ -1128,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 @@ -1167,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 @@ -1247,20 +1413,77 @@ manual page for more information. .Xr ssh-agent 1 , .Xr ssh-keygen 1 , .Xr ssh-keyscan 1 , +.Xr tun 4 , .Xr hosts.equiv 5 , .Xr ssh_config 5 , .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