src/usr.bin/ssh/ssh.1 - diff

Return to ssh.1 CVS log

Up to [local] / src / usr.bin / ssh

Diff for /src/usr.bin/ssh/ssh.1 between version 1.64.2.4 and 1.64.2.5

version 1.64.2.4, 2001/05/07 21:09:36

version 1.64.2.5, 2001/09/27 00:15:42

Line 44

.Sh SYNOPSIS

.Nm ssh

.Op Fl l Ar login_name

.Op Ar hostname | user@hostname

.Ar hostname | user@hostname

.Op Ar command

.Pp

.Nm ssh

.Op Fl afgknqstvxACNPTX1246

.Op Fl b Ar bind_address

.Op Fl c Ar cipher_spec

.Op Fl e Ar escape_char

.Op Fl i Ar identity_file

Line 56

Line 57

.Op Fl m Ar mac_spec

.Op Fl o Ar option

.Op Fl p Ar port

.Op Fl F Ar configfile

.Oo Fl L Xo

.Sm off

.Ar port :

Line 72

Line 74

.Sm on

.Xc

.Oc

.Op Ar hostname | user@hostname

.Op Fl D Ar port

.Ar hostname | user@hostname

.Op Ar command

.Sh DESCRIPTION

.Nm

Line 208

Line 211

different authentication methods are available.

Using the default values for

.Cm PreferredAuthentications ,

the client will try to authenticate first using the public key method;

the client will try to authenticate first using the hostbased method;

if this method fails password authentication is attempted,

if this method fails public key authentication is attempted,

and finally if this method fails keyboard-interactive authentication

and finally if this method fails keyboard-interactive and

is attempted.

password authentication are tried.

If this method fails password authentication is

tried.

.Pp

The public key method is similar to RSA authentication described

in the previous section and allows the RSA or DSA algorithm to be used:

Line 223

Line 224

.Pa $HOME/.ssh/id_rsa ,

to sign the session identifier and sends the result to the server.

The server checks whether the matching public key is listed in

.Pa $HOME/.ssh/authorized_keys2

.Pa $HOME/.ssh/authorized_keys

and grants access if both the key is found and the signature is correct.

The session identifier is derived from a shared Diffie-Hellman value

and is only known to the client and the server.

Line 268

Line 269

.Ss Escape Characters

.Pp

When a pseudo terminal has been requested, ssh supports a number of functions

through the use of an escape character.

.Pp

A single tilde character can be sent as

.Ic ~~

(or by following the tilde by a character other than those described above).

or by following the tilde by a character other than those described below.

The escape character must always follow a newline to be interpreted as

special.

The escape character can be changed in configuration files using the

.Cm EscapeChar

configuration directive or on the command line by the

.Fl e

option.

.Pp

Line 303

Line 304

.Pp

.Ss X11 and TCP forwarding

.Pp

If the user is using X11 (the

If the

.Cm ForwardX11

variable is set to

.Dq yes

(or, see the description of the

.Fl X

and

.Fl x

options described later)

and the user is using X11 (the

.Ev 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

Line 339

Line 349

.Pp

If the user is using an authentication agent, the connection to the agent

is automatically forwarded to the remote side unless disabled on

command line or in a configuration file.

the command line or in a configuration file.

.Pp

Forwarding of arbitrary TCP/IP connections over the secure channel can

be specified either on command line or in a configuration file.

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.

.Pp

Line 351

Line 361

.Nm

automatically maintains and checks a database containing

identifications for all hosts it has ever been used with.

RSA host keys are stored in

Host keys are stored in

.Pa $HOME/.ssh/known_hosts

and

host keys used in the protocol version 2 are stored in

.Pa $HOME/.ssh/known_hosts2

in the user's home directory.

Additionally, the files

Additionally, the file

.Pa /etc/ssh_known_hosts

and

is automatically checked for known hosts.

.Pa /etc/ssh_known_hosts2

are automatically checked for known hosts.

Any new hosts are automatically added to the user's file.

If a host's identification

ever changes,

Line 383

Line 388

.It Fl A

Enables forwarding of the authentication agent connection.

This can also be specified on a per-host basis in a configuration file.

.It Fl c Ar blowfish|3des

.It Fl b Ar bind_address

Specify the interface to transmit from on machines with multiple

interfaces or aliased addresses.

.It Fl c Ar blowfish|3des|des

Selects the cipher to use for encrypting the session.

.Ar 3des

is used by default.

It is believed to be secure.

.Ar 3des

(triple-des) is an encrypt-decrypt-encrypt triple with three different keys.

It is presumably more secure than the

.Ar des

cipher which is no longer fully supported in

.Nm ssh .

.Ar blowfish

is a fast block cipher, it appears very secure and is much faster than

.Ar 3des .

.Ar des

is only supported in the

.Nm

client for interoperability with legacy protocol 1 implementations

that do not support the

.Ar 3des

cipher. Its use is strongly discouraged due to cryptographic

weaknesses.

.It Fl c Ar cipher_spec

Additionally, for protocol version 2 a comma-separated list of ciphers can

be specified in order of preference.

Line 442

Line 454

.Fl i

options (and multiple identities specified in

configuration files).

.It Fl I Ar smartcard_device

Specifies which smartcard device to use. The argument is

the device

.Nm

should use to communicate with a smartcard used for storing the user's

private RSA key.

.It Fl k

Disables forwarding of Kerberos tickets and AFS tokens.

This may also be specified on a per-host basis in the configuration file.

Line 477

Line 495

option.)

.It Fl N

Do not execute a remote command.

This is useful if you just want to forward ports

This is useful for just forwarding ports

(protocol version 2 only).

.It Fl o Ar option

Can be used to give options in the format used in the config file.

Can be used to give options in the format used in the configuration file.

This is useful for specifying options for which there is no separate

command-line flag.

The option has the same format as a line in the configuration file.

.It Fl p Ar port

Port to connect to on the remote host.

This can be specified on a

per-host basis in the configuration file.

.It Fl P

Use a non-privileged port for outgoing connections.

This can be used if your firewall does

This can be used if a firewall does

not permit connections from privileged ports.

Note that this option turns off

.Cm RhostsAuthentication

Line 502

Line 519

Causes all warning and diagnostic messages to be suppressed.

Only fatal errors are displayed.

.It Fl s

May be used to request invocation of a subsystem on the remote system. Subsystems are a feature of the SSH2 protocol which facilitate the use

of SSH as a secure transport for other application (eg. sftp). The

of SSH as a secure transport for other applications (eg. sftp). The

subsystem is specified as the remote command.

.It Fl t

Force pseudo-tty allocation.

Line 547

Line 564

slow connections, but will only slow down things on fast networks.

The default value can be set on a host-by-host basis in the

configuration files; see the

.Cm Compress

.Cm Compression

option below.

.It Fl F Ar configfile

Specifies an alternative per-user configuration file.

If a configuration file is given on the command line,

the system-wide configuration file

.Pq Pa /etc/ssh_config

will be ignored.

The default for the per-user configuration file is

.Pa $HOME/.ssh/config .

.It Fl L Ar port:host:hostport

Specifies that the given port on the local (client) host is to be

forwarded to the given host and port on the remote side.

Line 582

Line 607

logging in as root on the remote machine.

IPv6 addresses can be specified with an alternative syntax:

.Ar port/host/hostport

.It Fl D Ar port

Specifies a local

.Dq dynamic

application-level port forwarding.

This works by allocating a socket to listen to

.Ar port

on the local side, and whenever a connection is made to this port, the

connection is forwarded over the secure channel, and the application

protocol is then used to determine where to connect to from the

remote machine. Currently the SOCKS4 protocol is supported, and

.Nm

will act as a SOCKS4 server.

Only root can forward privileged ports.

Dynamic port forwardings can also be specified in the configuration file.

.It Fl 1

Forces

.Nm

Line 601

Line 640

.El

.Sh CONFIGURATION FILES

.Nm

obtains configuration data from the following sources (in this order):

obtains configuration data from the following sources in

the following order:

command line options, user's configuration file

.Pq Pa $HOME/.ssh/config ,

and system-wide configuration file

Line 626

Line 666

.Pp

Otherwise a line is of the format

.Dq keyword arguments .

Configuration options may be separated by whitespace or

optional whitespace and exactly one

.Ql = ;

the latter format is useful to avoid the need to quote whitespace

when specifying configuration options using the

.Nm ssh ,

.Nm scp

and

.Nm sftp

.Fl o

option.

.Pp

The possible

keywords and their meanings are as follows (note that the

keywords and their meanings are as follows (note that

configuration files are case-sensitive):

keywords are case-insensitive and arguments are case-sensitive):

.Bl -tag -width Ds

.It Cm Host

Restricts the following declarations (up to the next

Line 659

Line 711

If set to

.Dq yes ,

passphrase/password querying will be disabled.

This option is useful in scripts and other batch jobs where you have no

This option is useful in scripts and other batch jobs where no user

user to supply the password.

is present to supply the password.

The argument must be

.Dq yes

.Dq no .

The default is

.Dq no .

.It Cm BindAddress

Specify the interface to transmit from on machines with multiple

interfaces or aliased addresses.

Note that this option does not work if

.Cm UsePrivilegedPort

is set to

.Dq yes .

.It Cm CheckHostIP

If this flag is set to

.Dq yes ,

Line 683

Line 742

Specifies the cipher to use for encrypting the session

in protocol version 1.

Currently,

.Dq blowfish

.Dq blowfish ,

.Dq 3des ,

and

.Dq 3des

.Dq des

are supported.

.Ar des

is only supported in the

.Nm

client for interoperability with legacy protocol 1 implementations

that do not support the

.Ar 3des

cipher. Its use is strongly discouraged due to cryptographic

weaknesses.

The default is

.Dq 3des .

.It Cm Ciphers

Line 699

Line 767

``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour,

aes192-cbc,aes256-cbc''

.Ed

.It Cm ClearAllForwardings

Specifies that all local, remote and dynamic port forwardings

specified in the configuration files or on the command line be

cleared. This option is primarily useful when used from the

.Nm

command line to clear port forwardings set in

configuration files, and is automatically set by

.Xr scp 1

and

.Xr sftp 1 .

The argument must be

.Dq yes

.Dq no .

The default is

.Dq no .

.It Cm Compression

Specifies whether to use compression.

The argument must be

Line 719

Line 803

back to rsh or exiting.

The argument must be an integer.

This may be useful in scripts if the connection sometimes fails.

The default is 4.

The default is 1.

.It Cm DynamicForward

Specifies that a TCP/IP port on the local machine be forwarded

over the secure channel, and the application

protocol is then used to determine where to connect to from the

remote machine. The argument must be a port number.

Currently the SOCKS4 protocol is supported, and

.Nm

will act as a SOCKS4 server.

Multiple forwardings may be specified, and

additional forwardings can be given on the command line. Only

the superuser can forward privileged ports.

.It Cm EscapeChar

Sets the escape character (default:

.Ql ~ ) .

Line 770

Line 865

.It Cm GatewayPorts

Specifies whether remote hosts are allowed to connect to local

forwarded ports.

By default,

.Nm

binds local port forwardings to the loopback addresss. This

prevents other remote hosts from connecting to forwarded ports.

.Cm GatewayPorts

can be used to specify that

.Nm

should bind local port forwardings to the wildcard address,

thus allowing remote hosts to connect to forwarded ports.

The argument must be

.Dq yes

Line 777

Line 881

The default is

.Dq no .

.It Cm GlobalKnownHostsFile

Specifies a file to use for the protocol version 1 global

Specifies a file to use for the global

host key database instead of

.Pa /etc/ssh_known_hosts .

.It Cm GlobalKnownHostsFile2

Specifies a file to use for the protocol version 2 global

host key database instead of

.Pa /etc/ssh_known_hosts2 .

.It Cm HostbasedAuthentication

Specifies whether to try rhosts based authentication with public key

authentication.

Line 792

Line 892

.Dq no .

The default is

.Dq yes .

.Dq no .

This option applies to protocol version 2 only and

is similar to

.Cm RhostsRSAAuthentication .

.It Cm HostKeyAlgorithms

Specfies the protocol version 2 host key algorithms

Specifies the protocol version 2 host key algorithms

that the client wants to use in order of preference.

The default for this option is:

.Dq ssh-rsa,ssh-dss

Line 806

Line 906

real host name when looking up or saving the host key

in the host key database files.

This option is useful for tunneling ssh connections

or if you have multiple servers running on a single host.

or for multiple servers running on a single host.

.It Cm HostName

Specifies the real host name to log into.

This can be used to specify nicknames or abbreviations for hosts.

Line 859

Line 959

.Dq no .

.It Cm LocalForward

Specifies that a TCP/IP port on the local machine be forwarded over

the secure channel to given host:port from the remote machine.

the secure channel to the specified host and port from the remote machine.

The first argument must be a port number, and the second must be

host:port.

.Ar host:port .

IPv6 addresses can be specified with an alternative syntax:

.Ar host/port .

Multiple forwardings may be specified, and additional

forwardings can be given on the command line.

Only the superuser can forward privileged ports.

Line 872

Line 974

QUIET, FATAL, ERROR, INFO, VERBOSE and DEBUG.

The default is INFO.

.It Cm MACs

Specifies the MAC (message authentication code) algorithms

in order of preference.

The MAC algorithm is used in protocol version 2

for data integrity protection.

Multiple algorithms must be comma-separated.

The default is

.Pp

.Dq hmac-md5,hmac-sha1,hmac-ripemd160,hmac-sha1-96,hmac-md5-96 .

.Bd -literal

``hmac-md5,hmac-sha1,hmac-ripemd160,hmac-ripemd160@openssh.com,

hmac-sha1-96,hmac-md5-96''

.Ed

.It Cm NumberOfPasswordPrompts

Specifies the number of password prompts before giving up.

The argument to this keyword must be an integer.

Line 899

Line 997

Specifies the port number to connect on the remote host.

Default is 22.

.It Cm PreferredAuthentications

Specifies the order in which the client should try protocol 2

authentication methods. This allows a client to prefer one method (e.g.

.Cm keyboard-interactive )

over another method (e.g.

.Cm password )

The default for this option is:

.Dq publickey, password, keyboard-interactive

.Dq hostbased,publickey,keyboard-interactive,password

.It Cm Protocol

Specifies the protocol versions

.Nm

Line 957

Line 1055

This option applies to protocol version 2 only.

.It Cm RemoteForward

Specifies that a TCP/IP port on the remote machine be forwarded over

the secure channel to given host:port from the local machine.

the secure channel to the specified host and port from the local machine.

The first argument must be a port number, and the second must be

host:port.

.Ar host:port .

IPv6 addresses can be specified with an alternative syntax:

.Ar host/port .

Multiple forwardings may be specified, and additional

forwardings can be given on the command line.

Only the superuser can forward privileged ports.

Line 972

Line 1072

authentication time on slow connections when rhosts authentication is

not used.

Most servers do not permit RhostsAuthentication because it

is not secure (see

.Cm RhostsRSAAuthentication ).

.Cm RhostsRSAAuthentication ) .

The argument to this keyword must be

.Dq yes

Line 1005

Line 1105

Note that this option applies to protocol version 1 only.

.It Cm ChallengeResponseAuthentication

Specifies whether to use challenge response authentication.

Currently there is only support for

.Xr skey 1

authentication.

The argument to this keyword must be

.Dq yes

.Dq no .

The default is

.Dq no .

.Dq yes .

.It Cm SmartcardDevice

Specifies which smartcard device to use. The argument to this keyword is

the device

.Nm

should use to communicate with a smartcard used for storing the user's

private RSA key. By default, no device is specified and smartcard support

is not activated.

.It Cm StrictHostKeyChecking

If this flag is set to

.Dq yes ,

.Nm

will never automatically add host keys to the

.Pa $HOME/.ssh/known_hosts

and

file, and refuses to connect to hosts whose host key has changed.

.Pa $HOME/.ssh/known_hosts2

This provides maximum protection against trojan horse attacks,

files, and refuses to connect to hosts whose host key has changed.

however, can be annoying when the

This provides maximum protection against trojan horse attacks.

However, it can be somewhat annoying if you don't have good

.Pa /etc/ssh_known_hosts

and

file is poorly maintained, or connections to new hosts are

.Pa /etc/ssh_known_hosts2

frequently made.

files installed and frequently

connect to new hosts.

This option forces the user to manually

add all new hosts.

If this flag is set to

Line 1061

Line 1161

.Dq no .

The default is

.Dq no .

Note that you need to set this option to

Note that this option must be set to

.Dq yes

if you want to use

.Cm RhostsAuthentication

and

.Cm RhostsRSAAuthentication

with older servers.

authentications are needed with older servers.

.It Cm User

Specifies the user to log in as.

This can be useful if you have a different user name on different machines.

This can be useful when a different user name is used on different machines.

This saves the trouble of

having to remember to give the user name on the command line.

.It Cm UserKnownHostsFile

Specifies a file to use for the protocol version 1 user

Specifies a file to use for the user

host key database instead of

.Pa $HOME/.ssh/known_hosts .

.It Cm UserKnownHostsFile2

Specifies a file to use for the protocol version 2 user

host key database instead of

.Pa $HOME/.ssh/known_hosts2 .

.It Cm UseRsh

Specifies that rlogin/rsh should be used for this host.

It is possible that the host does not at all support the

Line 1133

Line 1229

.Ev USER ;

set for compatibility with systems that use this variable.

.It Ev MAIL

Set to point the user's mailbox.

Set to the path of the user's mailbox.

.It Ev PATH

Set to the default

.Ev PATH ,

as specified when compiling

.Nm ssh .

.It Ev SSH_ASKPASS

.Nm

needs a passphrase, it will read the passphrase from the current

terminal if it was run from a terminal.

.Nm

does not have a terminal associated with it but

.Ev DISPLAY

and

.Ev SSH_ASKPASS

are set, it will execute the program specified by

.Ev SSH_ASKPASS

and open an X11 window to read the passphrase.

This is particularly useful when calling

.Nm

from a

.Pa .Xsession

or related script.

(Note that on some machines it

may be necessary to redirect the input from

.Pa /dev/null

to make this work.)

.It Ev SSH_AUTH_SOCK

indicates the path of a unix-domain socket used to communicate with the

Identifies the path of a unix-domain socket used to communicate with the

agent.

.It Ev SSH_CLIENT

Identifies the client end of the connection.

Line 1173

Line 1292

to the environment.

.Sh FILES

.Bl -tag -width Ds

.It Pa $HOME/.ssh/known_hosts, $HOME/.ssh/known_hosts2

.It Pa $HOME/.ssh/known_hosts

Records host keys for all hosts the user has logged into (that are not

Records host keys for all hosts the user has logged into that are not

.Pa /etc/ssh_known_hosts

.Pa /etc/ssh_known_hosts .

for protocol version 1 or

.Pa /etc/ssh_known_hosts2

for protocol version 2).

See

.Xr sshd 8 .

.It Pa $HOME/.ssh/identity, $HOME/.ssh/id_dsa, $HOME/.ssh/id_rsa

Line 1202

Line 1318

file should be added to

.Pa $HOME/.ssh/authorized_keys

on all machines

where you wish to log in using protocol version 1 RSA authentication.

where the user wishes to log in using protocol version 1 RSA authentication.

The contents of the

.Pa $HOME/.ssh/id_dsa.pub

and

.Pa $HOME/.ssh/id_rsa.pub

file should be added to

.Pa $HOME/.ssh/authorized_keys2

.Pa $HOME/.ssh/authorized_keys

on all machines

where you wish to log in using protocol version 2 DSA/RSA authentication.

where the user wishes to log in using protocol version 2 DSA/RSA authentication.

These files are not

sensitive and can (but need not) be readable by anyone.

These files are

Line 1226

Line 1342

but the recommended permissions are read/write for the user, and not

accessible by others.

.It Pa $HOME/.ssh/authorized_keys

Lists the RSA keys that can be used for logging in as this user.

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 .pub

identity files (that is, each line contains the number of bits in

identity files.

modulus, public exponent, modulus, and comment fields, separated by

spaces).

This file is not highly sensitive, but the recommended

permissions are read/write for the user, and not accessible by others.

.It Pa $HOME/.ssh/authorized_keys2

.It Pa /etc/ssh_known_hosts

Lists the public keys (RSA/DSA) that can be used for logging in as this user.

This file is not highly sensitive, but the recommended

permissions are read/write for the user, and not accessible by others.

.It Pa /etc/ssh_known_hosts, /etc/ssh_known_hosts2

Systemwide list of known host keys.

.Pa /etc/ssh_known_hosts

This file should be prepared by the

contains RSA and

.Pa /etc/ssh_known_hosts2

contains RSA or DSA keys for protocol version 2.

These files 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, number of bits in modulus, public exponent,

by spaces): system name, public key and optional comment field.

modulus, and optional comment field.

When different names are used

for the same machine, all such names should be listed, separated by

commas.

Line 1299

Line 1404

.Xr sshd 8

will be installed so that it requires successful RSA host

authentication before permitting \s+2.\s0rhosts authentication.

If your server machine does not have the client's host key in

If the server machine does not have the client's host key in

.Pa /etc/ssh_known_hosts ,

you can store it in

it can be stored in

.Pa $HOME/.ssh/known_hosts .

The easiest way to do this is to

connect back to the client from the server machine using ssh; this

Line 1383

Line 1488

.%A T. Rinne

.%A S. Lehtinen

.%T "SSH Protocol Architecture"

.%N draft-ietf-secsh-architecture-07.txt

.%N draft-ietf-secsh-architecture-09.txt

.%D January 2001

.%D July 2001

.%O work in progress material

.Re