-SSH(1) OpenBSD Reference Manual SSH(1)
+SSH(1) BSD General Commands Manual SSH(1)
NAME
ssh - OpenSSH SSH client (remote login program)
SYNOPSIS
- ssh [-1246AaCfgkMNnqsTtVvXxY] [-b bind_address] [-c cipher_spec]
- [-D [bind_address:]port] [-e escape_char] [-F configfile]
- [-i identity_file] [-L [bind_address:]port:host:hostport]
- [-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option] [-p port]
- [-R [bind_address:]port:host:hostport] [-S ctl_path]
+ ssh [-1246AaCfgkMNnqsTtVvXxY] [-b bind_address] [-c cipher_spec] [-D
+ [bind_address:]port] [-e escape_char] [-F configfile]
+ [-i identity_file] [-L [bind_address:]port:host:hostport]
+ [-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option] [-p port] [-R
+ [bind_address:]port:host:hostport] [-S ctl_path]
[-w local_tun[:remote_tun]] [user@]hostname [command]
DESCRIPTION
ssh (SSH client) is a program for logging into a remote machine and for
executing commands on a remote machine. It is intended to replace rlogin
- and rsh, and provide secure encrypted communications between two untrust-
- ed hosts over an insecure network. X11 connections and arbitrary TCP
- ports can also be forwarded over the secure channel.
+ and rsh, and provide secure encrypted communications between two
+ untrusted hosts over an insecure network. X11 connections and arbitrary
+ TCP ports can also be forwarded over the secure channel.
ssh connects and logs into the specified hostname (with optional user
name). The user must prove his/her identity to the remote machine using
- one of several methods depending on the protocol version used (see be-
- low).
+ one of several methods depending on the protocol version used (see
+ below).
If command is specified, it is executed on the remote host instead of a
login shell.
-b bind_address
Use bind_address on the local machine as the source address of
- the connection. Only useful on systems with more than one ad-
- dress.
+ the connection. Only useful on systems with more than one
+ address.
-C Requests compression of all data (including stdin, stdout,
stderr, and data for forwarded X11 and TCP connections). The
the secure channel, and the application protocol is then used to
determine where to connect to from the remote machine. Currently
the SOCKS4 and SOCKS5 protocols are supported, and ssh will act
- as a SOCKS server. Only root can forward privileged ports. Dy-
- namic port forwardings can also be specified in the configuration
- file.
+ as a SOCKS server. Only root can forward privileged ports.
+ Dynamic port forwardings can also be specified in the configura-
+ tion file.
IPv6 addresses can be specified with an alternative syntax:
[bind_address/]port or by enclosing the address in square brack-
- ets. Only the superuser can forward privileged ports. By de-
- fault, the local port is bound in accordance with the
+ ets. Only the superuser can forward privileged ports. By
+ default, the local port is bound in accordance with the
GatewayPorts setting. However, an explicit bind_address may be
used to bind the connection to a specific address. The
bind_address of ``localhost'' indicates that the listening port
- be bound for local use only, while an empty address or `*' indi-
+ be bound for local use only, while an empty address or '*' indi-
cates that the port should be available from all interfaces.
-e escape_char
- Sets the escape character for sessions with a pty (default: `~').
+ Sets the escape character for sessions with a pty (default: '~').
The escape character is only recognized at the beginning of a
- line. The escape character followed by a dot (`.') closes the
+ line. The escape character followed by a dot ('.') closes the
connection; followed by control-Z suspends the connection; and
followed by itself sends the escape character once. Setting the
character to ``none'' disables any escapes and makes the session
default for the per-user configuration file is ~/.ssh/config.
-f Requests ssh to go to background just before command execution.
- This is useful if ssh is going to ask for passwords or passphras-
- es, but the user wants it in the background. This implies -n.
- The recommended way to start X11 programs at a remote site is
- with something like ssh -f host xterm.
+ This is useful if ssh is going to ask for passwords or
+ passphrases, but the user wants it in the background. This
+ implies -n. The recommended way to start X11 programs at a
+ remote site is with something like ssh -f host xterm.
-g Allows remote hosts to connect to local forwarded ports.
-I smartcard_device
Specify the device ssh should use to communicate with a smartcard
used for storing the user's private RSA key. This option is only
- available if support for smartcard devices is compiled in (de-
- fault is no support).
+ available if support for smartcard devices is compiled in
+ (default is no support).
-i identity_file
Selects a file from which the identity (private key) for RSA or
the secure channel, and a connection is made to host port
hostport from the remote machine. Port forwardings can also be
specified in the configuration file. IPv6 addresses can be spec-
- ified with an alternative syntax: [bind_address/]port/host/host-
- port or by enclosing the address in square brackets. Only the
- superuser can forward privileged ports. By default, the local
- port is bound in accordance with the GatewayPorts setting. How-
- ever, an explicit bind_address may be used to bind the connection
- to a specific address. The bind_address of ``localhost'' indi-
- cates that the listening port be bound for local use only, while
- an empty address or `*' indicates that the port should be avail-
- able from all interfaces.
+ ified with an alternative syntax:
+ [bind_address/]port/host/hostport or by enclosing the address in
+ square brackets. Only the superuser can forward privileged
+ ports. By default, the local port is bound in accordance with
+ the GatewayPorts setting. However, an explicit bind_address may
+ be used to bind the connection to a specific address. The
+ bind_address of ``localhost'' indicates that the listening port
+ be bound for local use only, while an empty address or '*' indi-
+ cates that the port should be available from all interfaces.
-l login_name
Specifies the user to log in as on the remote machine. This also
-M Places the ssh client into ``master'' mode for connection shar-
ing. Multiple -M options places ssh into ``master'' mode with
- confirmation required before slave connections are accepted. Re-
- fer to the description of ControlMaster in ssh_config(5) for de-
- tails.
+ confirmation required before slave connections are accepted.
+ Refer to the description of ControlMaster in ssh_config(5) for
+ details.
-m mac_spec
Additionally, for protocol version 2 a comma-separated list of
-n Redirects stdin from /dev/null (actually, prevents reading from
stdin). This must be used when ssh is run in the background. A
- common trick is to use this to run X11 programs on a remote ma-
- chine. For example, ssh -n shadows.cs.hut.fi emacs & will start
- an emacs on shadows.cs.hut.fi, and the X11 connection will be au-
- tomatically forwarded over an encrypted channel. The ssh program
- will be put in the background. (This does not work if ssh needs
- to ask for a password or passphrase; see also the -f option.)
+ common trick is to use this to run X11 programs on a remote
+ machine. For example, ssh -n shadows.cs.hut.fi emacs & will
+ start an emacs on shadows.cs.hut.fi, and the X11 connection will
+ be automatically forwarded over an encrypted channel. The ssh
+ program will be put in the background. (This does not work if
+ ssh needs to ask for a password or passphrase; see also the -f
+ option.)
-O ctl_cmd
Control an active connection multiplexing master process. When
-o option
Can be used to give options in the format used in the configura-
tion file. This is useful for specifying options for which there
- is no separate command-line flag. For full details of the op-
- tions listed below, and their possible values, see ssh_config(5).
+ is no separate command-line flag. For full details of the
+ options listed below, and their possible values, see
+ ssh_config(5).
AddressFamily
BatchMode
By default, the listening socket on the server will be bound to
the loopback interface only. This may be overriden by specifying
- a bind_address. An empty bind_address, or the address `*', indi-
+ a bind_address. An empty bind_address, or the address '*', indi-
cates that the remote socket should listen on all interfaces.
- Specifying a remote bind_address will only succeed if the serv-
- er's GatewayPorts option is enabled (see sshd_config(5)).
+ Specifying a remote bind_address will only succeed if the
+ server's GatewayPorts option is enabled (see sshd_config(5)).
-S ctl_path
Specifies the location of a control socket for connection shar-
in ssh_config(5) for details.
-s May be used to request invocation of a subsystem on the remote
- system. Subsystems are a feature of the SSH2 protocol which fa-
- cilitate the use of SSH as a secure transport for other applica-
- tions (eg. sftp(1)). The subsystem is specified as the remote
+ system. Subsystems are a feature of the SSH2 protocol which
+ facilitate the use of SSH as a secure transport for other appli-
+ cations (eg. sftp(1)). The subsystem is specified as the remote
command.
-T Disable pseudo-tty allocation.
the verbosity. The maximum is 3.
-w local_tun[:remote_tun]
- Requests tunnel device forwarding with the specified tun(4) de-
- vices between the client (local_tun) and the server (remote_tun).
+ Requests tunnel device forwarding with the specified tun(4)
+ devices between the client (local_tun) and the server
+ (remote_tun).
The devices may be specified by numerical ID or the keyword
``any'', which uses the next available tunnel device. If
through the forwarded connection. An attacker may then be able
to perform activities such as keystroke monitoring.
- For this reason, X11 forwarding is subjected to X11 SECURITY ex-
- tension restrictions by default. Please refer to the ssh -Y op-
- tion and the ForwardX11Trusted directive in ssh_config(5) for
+ For this reason, X11 forwarding is subjected to X11 SECURITY
+ extension restrictions by default. Please refer to the ssh -Y
+ option and the ForwardX11Trusted directive in ssh_config(5) for
more information.
-x Disables X11 forwarding.
strong mechanism for ensuring the integrity of the connection.
The methods available for authentication are: GSSAPI-based authentica-
- tion, host-based authentication, public key authentication, challenge-re-
- sponse authentication, and password authentication. Authentication meth-
- ods are tried in the order specified above, though protocol 2 has a con-
- figuration option to change the default order: PreferredAuthentications.
+ tion, host-based authentication, public key authentication, challenge-
+ response authentication, and password authentication. Authentication
+ methods are tried in the order specified above, though protocol 2 has a
+ configuration option to change the default order:
+ PreferredAuthentications.
Host-based authentication works as follows: If the machine the user logs
in from is listed in /etc/hosts.equiv or /etc/shosts.equiv on the remote
the name of the user on that machine, the user is considered for login.
Additionally, the server must be able to verify the client's host key
(see the description of /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts,
- below) for login to be permitted. This authentication method closes se-
- curity holes due to IP spoofing, DNS spoofing, and routing spoofing.
+ below) for login to be permitted. This authentication method closes
+ security holes due to IP spoofing, DNS spoofing, and routing spoofing.
[Note to the administrator: /etc/hosts.equiv, ~/.rhosts, and the
rlogin/rsh protocol in general, are inherently insecure and should be
disabled if security is desired.]
the private key in ~/.ssh/identity (protocol 1), ~/.ssh/id_dsa (protocol
2 DSA), or ~/.ssh/id_rsa (protocol 2 RSA) and stores the public key in
~/.ssh/identity.pub (protocol 1), ~/.ssh/id_dsa.pub (protocol 2 DSA), or
- ~/.ssh/id_rsa.pub (protocol 2 RSA) in the user's home directory. The us-
- er should then copy the public key to ~/.ssh/authorized_keys in his/her
+ ~/.ssh/id_rsa.pub (protocol 2 RSA) in the user's home directory. The
+ user should then copy the public key to ~/.ssh/authorized_keys in his/her
home directory on the remote machine. The authorized_keys file corre-
sponds to the conventional ~/.rhosts file, and has one key per line,
though the lines can be very long. After this, the user can log in with-
authentication agent. See ssh-agent(1) for more information.
Challenge-response authentication works as follows: The server sends an
- arbitrary "challenge" text, and prompts for a response. Protocol 2 al-
- lows multiple challenges and responses; protocol 1 is restricted to just
- one challenge/response. Examples of challenge-response authentication
- include BSD Authentication (see login.conf(5)) and PAM (some non-OpenBSD
- systems).
+ arbitrary "challenge" text, and prompts for a response. Protocol 2
+ allows multiple challenges and responses; protocol 1 is restricted to
+ just one challenge/response. Examples of challenge-response authentica-
+ tion include BSD Authentication (see login.conf(5)) and PAM (some non-
+ OpenBSD systems).
Finally, if other authentication methods fail, ssh prompts the user for a
password. The password is sent to the remote host for checking; however,
~/.ssh/known_hosts in the user's home directory. Additionally, the file
/etc/ssh/ssh_known_hosts is automatically checked for known hosts. Any
new hosts are automatically added to the user's file. If a host's iden-
- tification ever changes, ssh warns about this and disables password au-
- thentication to prevent server spoofing or man-in-the-middle attacks,
+ tification ever changes, ssh warns about this and disables password
+ authentication to prevent server spoofing or man-in-the-middle attacks,
which could otherwise be used to circumvent the encryption. The
StrictHostKeyChecking option can be used to control logins to machines
whose host key is not known or has changed.
- When the user's identity has been accepted by the server, the server ei-
- ther executes the given command, or logs into the machine and gives the
+ 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. All communication with the
remote command or shell will be automatically encrypted.
ter can be changed in configuration files using the EscapeChar configura-
tion directive or on the command line by the -e option.
- The supported escapes (assuming the default `~') are:
+ The supported escapes (assuming the default '~') are:
~. Disconnect.
version 2 and if the peer supports it).
~C Open command line. Currently this allows the addition of port
- forwardings using the -L and -R options (see above). It also al-
- lows the cancellation of existing remote port-forwardings using
+ forwardings using the -L and -R options (see above). It also
+ allows the cancellation of existing remote port-forwardings using
-KR[bind_address:]port. !command allows the user to execute a
local command if the PermitLocalCommand option is enabled in
ssh_config(5). Basic help is available, using the -h option.
If the ForwardAgent variable is set to ``yes'' (or see the description of
the -A and -a options above) and the user is using an authentication
- agent, the connection to the agent is automatically forwarded to the re-
- mote side.
+ agent, the connection to the agent is automatically forwarded to the
+ remote side.
VERIFYING HOST KEYS
When connecting to a server for the first time, a fingerprint of the
SSH-BASED VIRTUAL PRIVATE NETWORKS
ssh contains support for Virtual Private Network (VPN) tunnelling using
- the tun(4) network pseudo-device, allowing two networks to be joined se-
- curely. The sshd_config(5) configuration option PermitTunnel controls
+ the tun(4) network pseudo-device, allowing two networks to be joined
+ securely. The sshd_config(5) configuration option PermitTunnel controls
whether the server supports this, and at what level (layer 2 or 3 traf-
fic).
- The following example would connect client network 10.0.50.0/24 with re-
- mote network 10.0.99.0/24, provided that the SSH server running on the
+ 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:
# ssh -f -w 0:1 192.168.1.15 true
X11 server. It is automatically set by ssh to
point to a value of the form ``hostname:n'', where
``hostname'' indicates the host where the shell
- runs, and `n' is an integer >= 1. ssh uses this
+ runs, and 'n' is an integer >= 1. ssh uses this
special value to forward X11 connections over the
secure channel. The user should normally not set
DISPLAY explicitly, as that will render the X11
communicate with the agent.
SSH_CONNECTION Identifies the client and server ends of the con-
- nection. The variable contains four space-separat-
- ed values: client IP address, client port number,
- server IP address, and server port number.
+ nection. The variable contains four space-sepa-
+ rated values: client IP address, client port num-
+ ber, server IP address, and server port number.
SSH_ORIGINAL_COMMAND This variable contains the original command line if
a forced command is executed. It can be used to
extract the original arguments.
- SSH_TTY This is set to the name of the tty (path to the de-
- vice) associated with the current shell or command.
- If the current session has no tty, this variable is
- not set.
+ SSH_TTY This is set to the name of the tty (path to the
+ device) associated with the current shell or com-
+ mand. If the current session has no tty, this
+ variable is not set.
TZ This variable is set to indicate the present time
zone if it was set when the daemon was started
USER Set to the name of the user logging in.
Additionally, ssh reads ~/.ssh/environment, and adds lines of the format
- ``VARNAME=value'' to the environment if the file exists and users are al-
- lowed to change their environment. For more information, see the
+ ``VARNAME=value'' to the environment if the file exists and users are
+ allowed to change their environment. For more information, see the
PermitUserEnvironment option in sshd_config(5).
FILES
~/.rhosts
This file is used for host-based authentication (see above). On
- some machines this file may need to be world-readable if the us-
- er's home directory is on an NFS partition, because sshd(8) reads
- it as root. Additionally, this file must be owned by the user,
- and must not have write permissions for anyone else. The recom-
- mended permission for most machines is read/write for the user,
- and not accessible by others.
+ some machines this file may need to be world-readable if the
+ user's home directory is on an NFS partition, because sshd(8)
+ reads it as root. Additionally, this file must be owned by the
+ user, and must not have write permissions for anyone else. The
+ recommended permission for most machines is read/write for the
+ user, and not accessible by others.
~/.shosts
This file is used in exactly the same way as .rhosts, but allows
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
sshd(8) manual page. This file is not highly sensitive, but the
- recommended permissions are read/write for the user, and not ac-
- cessible by others.
+ recommended permissions are read/write for the user, and not
+ accessible by others.
~/.ssh/config
This is the per-user configuration file. The file format and
should only be writable by root.
/etc/shosts.equiv
- This file is used in exactly the same way as hosts.equiv, but al-
- lows host-based authentication without permitting login with
+ This file is used in exactly the same way as hosts.equiv, but
+ allows host-based authentication without permitting login with
rlogin/rsh.
/etc/ssh/ssh_config
/etc/ssh/ssh_host_rsa_key
These three files contain the private parts of the host keys and
are used for host-based authentication. If protocol version 1 is
- used, ssh must be setuid root, since the host key is readable on-
- ly by root. For protocol version 2, ssh uses ssh-keysign(8) to
- access the host keys, eliminating the requirement that ssh be se-
- tuid root when host-based authentication is used. By default ssh
- is not setuid root.
+ used, ssh must be setuid root, since the host key is readable
+ only by root. For protocol version 2, ssh uses ssh-keysign(8) to
+ access the host keys, eliminating the requirement that ssh be
+ setuid root when host-based authentication is used. By default
+ ssh is not setuid root.
/etc/ssh/ssh_known_hosts
Systemwide list of known host keys. This file should be prepared
AUTHORS
OpenSSH is a derivative of the original and free ssh 1.2.12 release by
Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
- de Raadt and Dug Song removed many bugs, re-added newer features and
- created OpenSSH. Markus Friedl contributed the support for SSH protocol
+ de Raadt and Dug Song removed many bugs, re-added newer features and cre-
+ ated OpenSSH. Markus Friedl contributed the support for SSH protocol
versions 1.5 and 2.0.
-OpenBSD 4.0 September 25, 1999 13
+BSD September 25, 1999 BSD