.\" (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 $
+.\" $OpenBSD: ssh.1,v 1.266 2006/12/11 21:25:46 markus Exp $
.Dd September 25, 1999
.Dt SSH 1
.Os
.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
.It ControlPath
.It DynamicForward
.It EscapeChar
+.It ExitOnForwardFailure
.It ForwardAgent
.It ForwardX11
.It ForwardX11Trusted
.It Protocol
.It ProxyCommand
.It PubkeyAuthentication
+.It RekeyLimit
.It RemoteForward
.It RhostsRSAAuthentication
.It RSAAuthentication
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
.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.
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.
integrity of the connection.
.Pp
The methods available for authentication are:
+GSSAPI-based authentication,
host-based authentication,
public key authentication,
challenge-response authentication,
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.
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
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
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 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 -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:
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.
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
.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
.Sh AUTHORS
OpenSSH is a derivative of the original and free
andersk / openssh.git / blobdiff