 |
Index for
Section 1 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
ssh2(1)
NAME
ssh2, ssh - Secure Shell client remote login and command execution
application
SYNOPSIS
ssh2 [-l login_name] hostname [command]
ssh2 [-l login_name] [-n] [+a] [-a] [+x] [+X] [-x] [-i file] [-F file] [-t]
[-v] [-d debug_level] [-V] [-q] [-f [o]] [-e char] [-c cipher] [-m MAC] [-p
port] [-S] [-L [protocol/]port:host:hostport] [-L socks/port] [-R
[protocol/]port:host:hostport] [-g] [+g] [+C] [-C] [-E provider] [-I
initstring] [-4] [-6] [-1 [ti]] [-o option] [-h] [login_name@] hostname
[port#] [command]
OPTIONS
-l login_name
Specifies the user for login to the remote system.
-n Redirects input from /dev/null (i.e., do not read stdin). This option
also can be specified in the configuration file.
+a Enables authentication agent forwarding (default).
-a Disables authentication agent forwarding.
+x Enables X11 connection forwarding (default). If the X11 SECURITY
extension is compiled, you treat the client applications as untrusted.
See the TrustX11Applications section in ssh2_config(4) for additional
details.
+X Similar to +x, but the client applications are treated as trusted.
-x Disables X11 connection forwarding.
-i file
Specifies the identity file for public key authentication. This option
also can be specified in the configuration file.
-F file
Specifies an alternative client configuration file. The default client
configuration file is the /etc/ssh2/ssh2_config file. Each user can
also have their own ssh2_config file in their $HOME/.ssh2 directory,
where $HOME is the name of the user's account. The
/etc/ssh2/ssh2_config file is read first, then the user's copy. The
last obtained value for a keyword is used.
-t For tty allocation. For example, allocate a tty even if a command is
given. This option also can be specified in the /etc/ssh2/ssh2_config
configuration file.
-v Enables verbose mode. Displays verbose debugging messages. Equal to the
-d 2 option. This option also can be specified in the
/etc/ssh2/ssh2_config configuration file.
-d debug_level
Prints extensive debug information to stderr. The debug_level argument
is a number from 0 to 99, where 99 specifies that all debug information
should be displayed, or it is a comma-separated list of assignments.
This should be the first argument on the command line.
-V Displays the version string.
-q Disables warning messages. This option also can be specified in the
/etc/ssh2/ssh2_config configuration file.
-f [o]
Forks into the background after authentication waiting indefinitely for
connections. It must be killed for it to stop listening. This option
implies -S and -n. The o argument specifies one-shot mode, which means
that once all channels are closed, the ssh2 command exits. This option
also can be specified in the /etc/ssh2/ssh2_config configuration file.
-e char
Sets the escape character. The default escape character is the tilde
(~). Use none to disable the escape character. This option also can be
specified in the /etc/ssh2/ssh2_config configuration file.
-c cipher
Specifies the encryption algorithm to use. See the Ciphers keyword in
the /etc/ssh2/sshd2_config file and in the /etc/ssh2/ssh2_config file
for more information. Multiple -c options are allowed; a single -c
option can specify only one cipher. Allowed values are aes, blowfish,
twofish, cast, arcfour, 3des, and des.
-m MAC
Specifies the Message Authentication Code (MAC) algorithm. See the MACs
keyword in the /etc/ssh2/sshd2_config file and in the
/etc/ssh2/ssh2_config file for more information. Multiple -m options
are allowed; a single -m option can have only one MAC.
-p port #
Specifies the port to connect to on the remote system. This option also
can be specified in the /etc/ssh2/ssh2_config file.
-S Disables requests for a session channel. This can be used with port-
forwarding requests, if a session channel (and tty) is not needed, or
the server does not give one.
-L [protocol/]port:host:hostport
Fowards the given port on the local (client) system to the specified
host and port on the remote system. This allocates a socket to listen
to port on the local system. Whenever a connection is made to this
port, the connection is forwarded over the secure channel, and a
connection is made to the host:hostport argument from the remote
system. Only root can forward privileged ports. The argument protocol
enables the protocol-specific forwarding. The protocols implemented are
tcp (default, no special processing) and ftp. Temporary forwardings
are created for ftp data channels, effectively securing the whole ftp
session. This option can also be specified in the /etc/ssh2/ssh2_config
file.
With socks, the Secure Shell client will act as a SOCKS server for
other applications, creating forwards as requested by the SOCKS
transaction. Secure Shell supports both SOCKS4 and SOCKS5, so you can
configure it to use your socks forward by setting an approriate value
for the SocksServer configuration option. See ssh2_config(4). If the
local host is given, forwarding listens only to the interface that is
bound to the address of the given host. If it is omitted, all
interfaces are listening.
-L socks/port
Same as above.
-R [protocol/]port:host:hostport
Forwards the given port on the remote (server) system to the specified
host and port on the local system. This allocates a socket to listen
to port on the remote system. Whenever a connection is made to this
port, the connection is forwarded over the secure channel, and a
connection is made to the host:hostport argument from the local system.
Only root can forward privileged ports on the remote system. The
argument protocol enables the protocol-specific forwarding. The
protocols implemented are tcp (default, no special processing) and ftp.
Temporary forwardings are created for ftp data channels, effectively
securing the whole ftp session. This option also can be specified in
the /etc/ssh2/ssh2_config file.
-g Allows gateway ports (i.e., remote hosts can connect to locally
forwarded ports).
+g Denies gateway ports.
+C Enables compression.
-C Disables compression. (default)
-E provider
Uses an external key provider for user authentication. This feature is
only available when external key support is included in the software.
See ssh-externalkeys(4) for more information.
-I initstring
Uses an initialization string to access an external key provider for
user authentication. This feature is onlyavailable when external key
support is included in the software. See ssh-externalkeys(4) for more
information.
-4 Uses IPv4 to connect.
-6 Uses IPv6 to connect.
-1 [ti]
Falls back to the SSH1 protocol. An additional argument is mandatory.
The i argument signifies internal emulation, and the t argument
indicates traditional mechanism.
-o option
Specifies an option in the format used in the /etc/ssh2/ssh2_config
file. This is useful for specifying an option for which there is no
command-line option. Comment lines are not accepted with this option.
Where aplication, use the egrep regex format.
-h Displays help on ssh2 command options.
DESCRIPTION
The ssh2 command creates a secure connection between a Secure Shell client
and server for remote log in and command execution. The ssh2 command is
intended as a secure replacement for the rlogin and rsh commands. A secure
connection provides client and server authentication, user authentication,
data encryption, data integrity, and nonrepudiation. X11 connections and
arbitrary TCP/IP ports also can be forwarded over these secure channels.
A Secure Shell client and server use public host keys to authenticate each
other. When a client connects to a server for the first time, the user is
prompted to accept a copy of the server's public host key. If the user
accepts the key, a copy of the server's public host key is copied to the
user's hostkeys directory on the client. The client uses this public host
key to authenticate the server on subsequent connects. A Secure Shell
server authenticates a user by using password authentication, host-based
authentication, or public key authentication.
Private and public key pairs can be created with ssh-keygen2. See ssh-
agent2 for information on how to use public-key authentication in
conjunction with an authentication agent. If other authentication methods
fail, the ssh2 command will prompt for a password. The filenames of
private keys that are used in authentication are stored in
$HOME/.ssh2/identification. When the user tries to authenticate himself,
the server checks $HOME/.ssh2/authorization for filenames of matching
public keys and sends a challenge to the user. The user is authenticated
by signing the challenge using the private key.
After the user's identity has been proven, the Secure Shell server executes
the given command or logs the user into the system and gives the user a
normal shell on the remote system. All communication with the remote
command or shell will be encrypted automatically and checked for integrity.
If no pseudo-tty was allocated, the session is transparent and can be used
to reliably transfer binary data. The session terminates when the command
or shell on the remote system exits and all X11 and TCP/IP connections have
been closed. The exit status of the remote program is returned as the exit
status of ssh2.
If the user is using X11 (the DISPLAY environment variable is set), the
connection to the X11 display is automatically forwarded to the remote side
in such a way that any X11 programs started from the shell (or command)
will go through the encrypted channel, and the connection to the real X
server will be made from the local machine. The user should not manually
set DISPLAY. Forwarding of X11 connections can be configured on the
command line or in configuration files. The DISPLAY value set by the ssh2
command will point to the server machine, but with a display number greater
than zero. This is normal, and happens because ssh2 creates a proxy X
server on the server machine for forwarding the connections over the
encrypted channel.
The ssh2 command will also automatically set up the Xauthority data on the
server machine. It will generate a random authentication cookie, store it
in the Xauthority data on the server, and verify that any forwarded
connections carry this cookie and replace it with the real cookie when the
connection is opened. The real authentication cookie is never sent to the
server.
If the user is using an authentication agent, the connection to the agent
is automatically forwarded to the remote side unless disabled on the
command line or in a configuration file. Forwarding of arbitrary
TCP/IP connections over the secure channel can be specified either on the
command line or in a configuration file. TCP/IP forwarding can be used for
secure connections to electronic purses or for going through firewalls.
Ssh2 automatically maintains and checks a database containing the public
host keys. When logging in on a host for the first time, the host's public
key is stored in the .ssh2/hostkey_PORTNUMBER_HOSTNAME.pub file in the
user's home directory. If a host's identification changes, ssh2 issues a
warning and disables the password authentication in order to prevent man-
in-the- middle attacks which could otherwise be used to circumvent the
encryption or steal passwords.
Secure Shell has built-in support for SOCKS versions 4 and 5 for traversing
firewalls. (See the Environment Variables section.) However, the SOCKS5
support does not include support for the SOCKS authentication methods.
See Security Administration for more information about Secure Shell clients
and servers and Secure Shell authentication.
NOTES
The ssh2 command obtains configuration data from the following sources (in
this order):
1. /etc/ssh2/ssh2_config (system's global configuration file )
2. $HOME/.ssh2/ssh2_config (user's configuration file)
3. command-line options
For each parameter, the last obtained value will be effective.
Escape Sequences
The ssh2 command supports the escape sequences that. For any escape
sequences to take effect, you must enter a newline character (press the
Enter key), then enter the characters. For example, a newline, a tilde (~),
and the appropriate character for a task. Following are the escape
sequences:
~. Terminates the connection.
~Ctrl/Z
Suspends the session. Simultaneously press the Ctrl key and the Z key.
~~ Sends the escape character.
~# Lists forwarded connections.
~- Disables the escape character.
~? Displays escape sequences.
~r Initiates rekeying manually.
~s Displays statistics about the connection, including server and client
version, compression, packets in, packets out, compression, key
exchange algorithms, public key algorithms, and symmetric ciphers.
~V Displays the client version number to stderr (useful for
troubleshooting).
EXIT STATUS
On normal execution, the ssh2 command exits with the status of the command
run. On successful runs this is normally zero. If ssh2 encounters an
error, you usually see the reason in an error message. Some common exit
values for ssh2 include the following:
128 + signal number
Returned if ssh2 encounters a fatal signal. For example, 143 would
be returned for SIGTERM (signal number 15).
64 + disconnect code
Returned on disconnect, clean or otherwise.
Following are some disconnect codes:
1 host not allowed to connect
2 protocol error
3 key exchange failed
4 key exchange failed
5 mac error
6 compression error
7 service not available
8 protocol version not supported
9 host key not verifiable
10 connection lost
11 by application
12 too many connections
13 auth cancelled by user
14 no more auth methods available
15 illegal user name
For example, 74 would mean "Connection lost."
255 Returned on a call for ssh_fatal().
254 Usually means that ssh2 failed to exec(3) something (generic
catch-all in the libraries for failures to fork(2) or exec(3)).
1 Generic error.
2 Connecting to remote host failed.
ENVIRONMENT VARIABLES
The ssh2 command will set the following environment variables.
Additionally, the ssh2 command reads the /etc/environment file and the
$HOME/.ssh2/environment file and adds lines of the format VARNAME=value to
the environment.
DISPLAY
Indicates the location of the X11 server. It is automatically set to
point to a value of the form hostname:n, where hostname is the host
where the shell runs, and n is an integer >= 1. The ssh2 command uses
this special value to forward X11 connections over the secure channel.
The user should normally not set the DISPLAY environment variable, as
that will render the X11 connection insecure (and will require the user
to manually copy any required authorization cookies).
HOME
Points to the user's home directory.
LOGNAME
Synonym for USER; sets for compatibility with systems using this
variable.
MAIL
Points to the user's mailbox.
PATH
Sets the default PATH, as specified when compiling the ssh2 command or,
on some systems, /etc/environment or /etc/default/login.
SSH_SOCKS_SERVER
If SOCKS is used, it is configured with this variable. The format of
the variable is:
socks://username@socks_server:port/network/netmask,network/netmask...
For example, setting the environment variable SSH_SOCKS_SERVER to
socks://mylogin@socks.ssh.com:1080/203.123.0.0/16,198.74.23.0/24 uses
host socks.ssh.com port 1080 as the SOCKS server if a connection is
attempted outside of networks 203.123.0.0 (16 bit domain) and
198.74.23.0 (8 bit domain) which are connected directly.
A default value for the SSH_SOCKS_SERVER variable can be specified at
compile time by specifying --with-socks-server=VALUE on the configure
command line when compiling the ssh2 command. The default value can be
cancelled by setting SSH_SOCKS_SERVER to an empty string and overridden
by setting SSH_SOCKS_SERVER to a new value. If the SSH_SOCKS_SERVER
variable is set, it should contain a local loopback network
(127.0.0.0/8) as the network that is connected directly.
SSH2_AUTH_SOCK
Indicates the path of a unix-domain socket used to communicate with the
authentication agent (or its local representative).
SSH2_CLIENT
Identifies the client of the connection. The variable contains the
following space-separated values: client ip-address, client port
number, host ip-address, and server port number.
SSH2_ORIGINAL_COMMAND
The original command given to the ssh2 command if a forced command is
run. For example, it can be used to fetch arguments from the other
system. This does not have to be a real command; it can be the name of
a file, device, parameters or anything else.
SSH2_TTY
Set to the name of the tty (path to the device) associated with the
current shell or command. If the current session has no tty, this
variable is not set.
TZ Sets to the present time zone if it was set when the daemon was
started. The daemon passes the value to new connections.
USER
Sets to the name of the user logging in.
FILES
/etc/ssh2/ssh2_config
Specifies Secure Shell client configuration information.
/etc/ssh2/sshd2_config
Specifies Secure Shell server configuration information.
$HOME/.ssh2/random_seed
Seeds the random number generator. This file is created the first time
the program is run and it is updated automatically. The user should
never need to modify this file. This file contains sensitive data and
its permissions should be set to "read/write" for the user and "not
accessible" for others.
$HOME/.ssh2/ssh2_config
Contains per-user configuration information. The format of this file
is described above. This file is used by the Secure Shell client.
This file does not usually contain any sensitive information, but the
recommended permissions are "read/write" for the user, and "not
accessible" for others.
$HOME/.ssh2/identification
Contains information on how the user will be authenticated when
contacting a specific host. The identification file has the same
general syntax as the configuration files. The following keywords can
be used:
IdKey Precedes the file name of a private key in the $HOME/.ssh2
directory used for identification when contacting a host. If
there is more than one IdKey, they are tried in the order that
they appear in the identification file.
PgpSecretKeyFile
Precedes the file name of the user's OpenPGP private keyring in
the $HOME/.ssh2 directory. The OpenPGP keys listed after this
line are expected to be found from this file. The keys
identified with IdPgpKey*-keywords are used like ones
identified with IdKey-keyword.
IdPgpKeyName
Preceds the OpenPGP key name of the key in the PgpSecretKeyFile
file.
IdPgpKeyFingerprint
Precedes the OpenPGP key fingerprint of the key in the
PgpSecretKeyFile file.
IdPgpKeyId
Precedes the OpenPGP key ID of the key in the PgpSecretKeyFile
file.
$HOME/.ssh2/authorization
Contains information on how the server will verify the identity of an
user. The authorization file has the same general syntax as the
configuration files. The following keywords can be used:
Key Precedes the file name of a public key in the $HOME/.ssh2
directory used for identification when contacting the host.
More than one key is acceptable for login.
PgpPublicKeyFile
Precedes the file name of the user's OpenPGP public keyring in
the $HOME/.ssh2directory. OpenPGP keys listed after this line
are expected to be found from this file. Keys identified with
PgpKey*-keywords are used like ones identified with Key-
keyword.
PgpKeyName
Precedes the OpenPGP key name.
PgpKeyFingerprint
Precedes the OpenPGP key fingerprint.
PgpKeyId
Precedes the OpenPGP key ID.
Options This keyword, if used, must follow the Key or PgpKey* keyword.
The various options are specified as a comma-separated list.
(See the Public Key Options section for more details.)
Command This keyword is deprecated. Use Options instead.
$HOME/.ssh2/hostkeys/key_xxxx_yyyy.pub
These files are the public keys of the hosts to which you connect. They
are updated automatically, unless you set the StrictHostKeyChecking
parameter to yes in the ssh2_config file. If a host's key changes, you
should put the key here only if you are sure that the new key is valid
(i.e., there was no man-in-the-middle attack). The xxxx is the port on
the server, where the sshd2 deamon runs, and the yyyy is the host
(specified on the command line).
/etc/ssh2/hostkeys/key_xxxx_yyyy.pub
If a host key is not found from the user's $HOME/.ssh2/hostkeys
directory, this is the next location to be checked. These files must be
updated manually; no files are put here automatically.
$HOME/.rhosts
Contains a list of remote users who are not required to supply a
password when they use Secure Shell host-based authentication with the
ssh2 command. The same file is used by rlogind and rshd.
The sshd2 differs from rlogind and rshd in that it requires public
host-key authentication from the Secure Shell server running on this
host in addition to validating the host name retrieved from domain name
servers. The file must be writable only by the user; it should not be
accessible to others. It is also possible to use netgroups in the file.
Either host or user name may be of the form +@groupname to specify all
hosts or all users in the group.
$HOME/.shosts
The same as $HOME/.rhosts. However, this file is not used by rlogin and
rsh, so using it permits access using ssh2 only.
/etc/hosts.equiv
Contains the names of remote hosts and users that are equivalent to the
local host or user. An equivalent host or user is allowed to use the
ssh2 command with Secure Shell host-based authentication without
supplying a password. Additionally, the syntax +@group can be used to
specify netgroups. Negated entries start with a minus (-) sign. This
file must be writable only by root; it should also be world-readable.
Warning: You should not inlcude user names in hosts.equiv. The named
users could log in as anybody, including bin, daemon, adm, and other
accounts that own critical binaries and directories. The only valid
use for user names should be in negative entries. This warning also
applies to rsh and rlogin.
/etc/shosts.equiv
The same as /etc/hosts.equiv. However, this file is not used by
rlogin and rshd, so using it permits access using ssh2 only.
$HOME/.ssh2/knownhosts/xxxxyyyy.pub
Contains the public host keys of hosts that users need to log in to
when using host based authentication.
The xxxx is the fully qualified domain name (FQDN) and yyyy is the
public key algorithm. Public key algorithms are ssh-dss and ssh-rsa.
For example, if the FQDN for a host is server1.foo.fi and it has a key
algorithm of ssh-dss, the host key would be server1.foo.fi.ssh-dss.pub
in the knownhosts directory.
A user must add the host name to a $HOME/.shosts file or an
$HOME/.rhosts file.
/etc/ssh2/knownhosts/xxxxyyyy.pub
Same as the $HOME/.ssh2/knownhosts/xxxxyyyy.pub file, but system-wide.
This file is overridden if the user puts a file with the same name in
the $HOME/.ssh2/knownhosts directory.
PUBLIC KEY OPTIONS
The following options are specified as a comma-separated list:
allow-from and deny-from
In addition to public-key authentication, the canonical name of the
remote host must match the given patterns. These parameters follow
the logic of {Allow,Deny}Hosts, described in detail in
sshd2_config(4). You specify one pattern per keyword. Multiple
keywords can be used.
command="command"
Specifies a forced command that will be executed on the server side
instead of anything else when the user is authenticated. The
command supplied by the user is put in the environment variable
SSH2_ORIGINAL_COMMAND. The command is run on a pty if the
connection requests a pty; otherwise it is run without a tty.
Quotes may be used in the command if escaped with backslashes. This
option might be useful for restricting certain public keys to
perform just a specific operation. An example might be a key that
permits remote backups but nothing else. Notice that the client
may specify TCP/IP and/or X11 forwarding, unless they are
explicitly prohibited (see no-port-forwarding).
environment="NAME=value"
Specifies that the string is to be added to the environment when
logging in using this key. Environment variables set this way
override other default environment values. Multiple options of
this type are permitted.
idle-timeout=time
Sets idle timeout limit to time in seconds (s or nothing after
number), in minutes (m), in hours (h), in days (d), or in weeks
(w). If the connection has been idle (all channels) this long, the
connection is closed.
no-port-forwarding
Forbids TCP/IP forwarding when this key is used for authentication.
Any port forward requests by the client will return an error. This
is useful in combination with the command option.
no-x11-forwarding
Forbids X11 forwarding when this key is used for authentication.
Any X11 forward requests by the client will return an error.
no-agent-forwarding
Forbids authentication agent forwarding when this key is used for
authentication.
no-pty Prevents tty allocation (a request to allocate a pty will fail).
LEGAL NOTICES
SSH is a registered trademark of SSH Communication Security Ltd.
SEE ALSO
Commands: rlogin(1), rsh(1), scp2(1), sftp(1), ssh-add2(1), ssh-agent2(1),
ssh-keygen2(1), telnet(1), sshd2(8)
Files: hosts.equiv(4), rhosts(4), shosts(4), ssh2_config(4),
sshd2_config(4)
Guides: Security Administration
|
Index for
Section 1 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|