.\" (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.239 2006/01/03 16:55:18 jmc Exp $
+.\" $OpenBSD: ssh.1,v 1.253 2006/01/30 13:37:49 jmc Exp $
.Dd September 25, 1999
.Dt SSH 1
.Os
It is intended to replace rlogin and rsh,
and provide secure encrypted communications between
two untrusted hosts over an insecure network.
-X11 connections and arbitrary TCP/IP ports
+X11 connections and arbitrary TCP ports
can also be forwarded over the secure channel.
.Pp
.Nm
Only useful on systems with more than one address.
.It Fl C
Requests compression of all data (including stdin, stdout, stderr, and
-data for forwarded X11 and TCP/IP connections).
+data for forwarded X11 and TCP connections).
The compression algorithm is the same used by
.Xr gzip 1 ,
and the
.It Protocol
.It ProxyCommand
.It PubkeyAuthentication
+.It RekeyLimit
.It RemoteForward
.It RhostsRSAAuthentication
.It RSAAuthentication
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.
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.
will also make the session transparent even if a tty is used.
.Pp
The session terminates when the command or shell on the remote
-machine exits and all X11 and TCP/IP connections have been closed.
+machine exits and all X11 and TCP connections have been closed.
.Sh ESCAPE CHARACTERS
When a pseudo-terminal has been requested,
.Nm
Request rekeying of the connection
(only useful for SSH protocol version 2 and if the peer supports it).
.El
-.Sh X11 AND TCP FORWARDING
+.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
If the
.Cm ForwardX11
variable is set to
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
-Forwarding of arbitrary TCP/IP connections over the secure channel can
-be specified either on the command line or in a configuration file.
-One possible application of TCP/IP forwarding is a secure connection to an
-electronic purse; another is going through firewalls.
+.Dl $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key
+.Pp
+If the fingerprint is already known,
+it can be matched and verified,
+and the key can be accepted.
+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 -f /etc/ssh/ssh_host_rsa_key.pub -r host.example.com.
+$ ssh-keygen -f /etc/ssh/ssh_host_dsa_key.pub -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, provided that the SSH server
+running on the gateway to the remote network,
+at 192.168.1.15, allows it:
+.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
+.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 the first
+.Xr tun 4
+device from user
+.Dq jane
+and on the second device 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 tun1" ssh-rsa ... john
+.Ed
+.Pp
+Since a 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:
.Sh FILES
.Bl -tag -width Ds -compact
.It ~/.rhosts
-This file is used in
-.Cm RhostsRSAAuthentication
-and
-.Cm HostbasedAuthentication
-authentication to list the
-host/user pairs that are permitted to log in.
-(Note that this file is
-also used by rlogin and rsh, which makes using this file insecure.)
-Each line of the file contains a host name (in the canonical form
-returned by name servers), and then a user name on that host,
-separated by a space.
+This file is used for host-based authentication (see above).
On some machines this file may need to be
-world-readable if the user's home directory is on a NFS partition,
+world-readable if the user's home directory is on an NFS partition,
because
.Xr sshd 8
reads it as root.
permission for most machines is read/write for the user, and not
accessible by others.
.Pp
-Note that
-.Xr sshd 8
-allows authentication only in combination with client host key
-authentication before permitting log in.
-If the server machine does not have the client's host key in
-.Pa /etc/ssh/ssh_known_hosts ,
-it can be stored in
-.Pa ~/.ssh/known_hosts .
-The easiest way to do this is to
-connect back to the client from the server machine using ssh; this
-will automatically add the host key to
-.Pa ~/.ssh/known_hosts .
-.Pp
.It ~/.shosts
-This file is used exactly the same way as
-.Pa .rhosts .
-The purpose for
-having this file is to be able to use
-.Cm RhostsRSAAuthentication
-and
-.Cm HostbasedAuthentication
-authentication without permitting login with
-.Xr rlogin
-or
-.Xr rsh 1 .
+This file is used in exactly the same way as
+.Pa .rhosts ,
+but allows host-based authentication without permitting login with
+rlogin/rsh.
.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
.Xr sshd 8
manual page.
-In the simplest form the format is the same as the
-.Pa .pub
-identity files.
This file is not highly sensitive, but the recommended
permissions are read/write for the user, and not accessible by others.
.Pp
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
-Records host keys for all hosts the user has logged into that are not
-in
-.Pa /etc/ssh/ssh_known_hosts .
+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.
See
-.Xr sshd 8 .
+.Xr sshd 8
+for further details of the format of this file.
.Pp
.It ~/.ssh/rc
Commands in this file are executed by
.Nm
-when the user logs in just before the user's shell (or command) is
+when the user logs in, just before the user's shell (or command) is
started.
See the
.Xr sshd 8
manual page for more information.
.Pp
.It /etc/hosts.equiv
-This file is used during
-.Cm RhostsRSAAuthentication
-and
-.Cm HostbasedAuthentication
-authentication.
-It contains
-canonical hosts names, one per line (the full format is described in the
-.Xr sshd 8
-manual page).
-If the client host is found in this file, login is
-automatically permitted provided client and server user names are the
-same.
-Additionally, successful client host key authentication is required.
-This file should only be writable by root.
+This file is for host-based authentication (see above).
+It should only be writable by root.
.Pp
.It /etc/shosts.equiv
-This file is processed exactly as
-.Pa /etc/hosts.equiv .
-This file may be useful to permit logins using
-.Nm
-but not using rsh/rlogin.
+This file is used in exactly the same way as
+.Pa hosts.equiv ,
+but allows host-based authentication without permitting login with
+rlogin/rsh.
.Pp
.It Pa /etc/ssh/ssh_config
Systemwide configuration file.
.It /etc/ssh/ssh_host_dsa_key
.It /etc/ssh/ssh_host_rsa_key
These three files contain the private parts of the host keys
-and are used for
-.Cm RhostsRSAAuthentication
-and
-.Cm HostbasedAuthentication .
-If the protocol version 1
-.Cm RhostsRSAAuthentication
-method is used,
+and are used for host-based authentication.
+If protocol version 1 is used,
.Nm
must be setuid root, since the host key is readable only by root.
For protocol version 2,
.Nm
uses
.Xr ssh-keysign 8
-to access the host keys for
-.Cm HostbasedAuthentication .
-This eliminates the requirement that
+to access the host keys,
+eliminating the requirement that
.Nm
-be setuid root when that authentication method is used.
+be setuid root when host-based authentication is used.
By default
.Nm
is not setuid root.
This file should be prepared by the
system administrator to contain the public host keys of all machines in the
organization.
-This file should be world-readable.
-This file contains
-public keys, one per line, in the following format (fields separated
-by spaces): system name, public key and optional comment field.
-When different names are used
-for the same machine, all such names should be listed, separated by
-commas.
-The format is described in the
-.Xr sshd 8
-manual page.
-.Pp
-The canonical system name (as returned by name servers) is used by
+It should be world-readable.
+See
.Xr sshd 8
-to verify the client host when logging in; other names are needed because
-.Nm
-does not convert the user-supplied name to a canonical name before
-checking the key, because someone with access to the name servers
-would then be able to fool host authentication.
+for further details of the format of this file.
.Pp
.It /etc/ssh/sshrc
Commands in this file are executed by
.Nm
-when the user logs in just before the user's shell (or command) is started.
+when the user logs in, just before the user's shell (or command) is started.
See the
.Xr sshd 8
manual page for more information.
.El
.Sh SEE ALSO
-.Xr gzip 1 ,
-.Xr rsh 1 ,
.Xr scp 1 ,
.Xr sftp 1 ,
.Xr ssh-add 1 ,
.Xr ssh-agent 1 ,
.Xr ssh-keygen 1 ,
-.Xr telnet 1 ,
+.Xr ssh-keyscan 1 ,
+.Xr tun 4 ,
.Xr hosts.equiv 5 ,
.Xr ssh_config 5 ,
.Xr ssh-keysign 8 ,
andersk / openssh.git / blobdiff