.\" (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.243 2006/01/04 19:50:09 jmc Exp $
+.\" $OpenBSD: ssh.1,v 1.249 2006/01/15 17:37:05 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
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.
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.
-.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.
.Sh ENVIRONMENT
.Nm
will normally set the following environment variables:
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
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
.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.