src/usr.bin/ssh/ssh_config.5 - diff

Return to ssh_config.5 CVS log

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

Diff for /src/usr.bin/ssh/ssh_config.5 between version 1.61.2.2 and 1.62

version 1.61.2.2, 2006/10/06 03:19:33

version 1.62, 2005/09/19 11:37:34

Line 47

.It Pa /etc/ssh/ssh_config

.El

.Sh DESCRIPTION

.Xr ssh 1

.Nm ssh

obtains configuration data from the following sources in

the following order:

.Pp

.Bl -enum -offset indent -compact

.It

command-line options

Line 79

Line 78

Empty lines and lines starting with

.Ql #

are comments.

.Pp

Otherwise a line is of the format

.Dq keyword arguments .

Configuration options may be separated by whitespace or

Line 87

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

when specifying configuration options using the

.Nm ssh ,

.Nm scp ,

.Nm scp

and

.Nm sftp

.Fl o

option.

Arguments may optionally be enclosed in double quotes

.Pq \&"

in order to represent arguments containing spaces.

.Pp

The possible

keywords and their meanings are as follows (note that

Line 105

Line 102

.Cm Host

keyword) to be only for those hosts that match one of the patterns

given after the keyword.

.Ql \&*

and

.Ql \&?

can be used as wildcards in the

patterns.

A single

.Ql *

.Ql \&*

as a pattern can be used to provide global

defaults for all hosts.

The host is the

.Ar hostname

argument given on the command line (i.e. the name is not converted to

argument given on the command line (i.e., the name is not converted to

a canonicalized host name before matching).

.Pp

See

.Sx PATTERNS

for more information on patterns.

.It Cm AddressFamily

Specifies which address family to use when connecting.

Valid arguments are

.Dq any ,

.Dq inet

(use IPv4 only), or

(use IPv4 only) or

.Dq inet6

(use IPv6 only).

.It Cm BatchMode

Line 146

Line 144

is set to

.Dq yes .

.It Cm ChallengeResponseAuthentication

Specifies whether to use challenge-response authentication.

Specifies whether to use challenge response authentication.

The argument to this keyword must be

.Dq yes

Line 156

Line 154

.It Cm CheckHostIP

If this flag is set to

.Dq yes ,

.Xr ssh 1

ssh will additionally check the host IP address in the

will additionally check the host IP address in the

.Pa known_hosts

file.

This allows ssh to detect if a host key changed due to DNS spoofing.

Line 177

Line 174

are supported.

.Ar des

is only supported in the

.Xr ssh 1

.Nm ssh

client for interoperability with legacy protocol 1 implementations

that do not support the

.Ar 3des

Line 203

Line 200

.Dq blowfish-cbc ,

and

.Dq cast128-cbc .

The default is:

The default is

.Bd -literal -offset 3n

.Bd -literal

aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour128,

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

arcfour256,arcfour,aes192-cbc,aes256-cbc,aes128-ctr,

aes192-ctr,aes256-ctr

aes192-ctr,aes256-ctr''

.Ed

.It Cm ClearAllForwardings

Specifies that all local, remote, and dynamic port forwardings

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

.Xr ssh 1

.Nm ssh

command line to clear port forwardings set in

configuration files, and is automatically set by

.Xr scp 1

Line 247

Line 244

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

The default is 1.

.It Cm ConnectTimeout

Specifies the timeout (in seconds) used when connecting to the

Specifies the timeout (in seconds) used when connecting to the ssh

SSH server, instead of using the default system TCP timeout.

server, instead of using the default system TCP timeout.

This value is used only when the target is down or really unreachable,

not when it refuses the connection.

.It Cm ControlMaster

Enables the sharing of multiple sessions over a single network connection.

When set to

.Dq yes ,

.Dq yes

.Xr ssh 1

.Nm ssh

will listen for connections on a control socket specified using the

.Cm ControlPath

argument.

Line 266

Line 263

set to

.Dq no

(the default).

These sessions will try to reuse the master instance's network connection

These sessions will reuse the master instance's network connection rather

rather than initiating new ones, but will fall back to connecting normally

than initiating new ones.

if the control socket does not exist, or is not listening.

.Pp

Setting this to

.Dq ask

will cause ssh

will cause

.Nm ssh

to listen for control connections, but require confirmation using the

.Ev SSH_ASKPASS

program before they are accepted (see

Line 280

Line 276

for details).

If the

.Cm ControlPath

cannot be opened,

can not be opened,

ssh will continue without connecting to a master instance.

.Nm ssh

will continue without connecting to a master instance.

.Pp

X11 and

.Xr ssh-agent 1

forwarding is supported over these multiplexed connections, however the

display and agent forwarded will be the one belonging to the master

display and agent fowarded will be the one belonging to the master

connection i.e. it is not possible to forward multiple displays or agents.

.Pp

Two additional options allow for opportunistic multiplexing: try to use a

Line 307

Line 304

.Dq none

to disable connection sharing.

In the path,

.Ql %l

will be substituted by the local host name,

.Ql %h

will be substituted by the target host name,

.Ql %p

the port, and

the port and

.Ql %r

by the remote login username.

It is recommended that any

.Cm ControlPath

used for opportunistic connection sharing include

at least %h, %p, and %r.

all three of these escape sequences.

This ensures that shared connections are uniquely identified.

.It Cm DynamicForward

Specifies that a TCP port on the local machine be forwarded

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.

Line 349

Line 344

indicates that the port should be available from all interfaces.

.Pp

Currently the SOCKS4 and SOCKS5 protocols are supported, and

.Xr ssh 1

.Nm ssh

will act as a SOCKS server.

Multiple forwardings may be specified, and

additional forwardings can be given on the command line.

Line 385

Line 380

to disable the escape

character entirely (making the connection transparent for binary

data).

.It Cm ExitOnForwardFailure

Specifies whether

.Xr ssh 1

should terminate the connection if it cannot set up all requested

dynamic, local, and remote port forwardings.

The argument must be

.Dq yes

.Dq no .

The default is

.Dq no .

.It Cm ForwardAgent

Specifies whether the connection to the authentication agent (if any)

will be forwarded to the remote machine.

Line 435

Line 419

option is also enabled.

.It Cm ForwardX11Trusted

If this option is set to

.Dq yes ,

.Dq yes

remote X11 clients will have full access to the original X11 display.

then remote X11 clients will have full access to the original X11 display.

.Pp

If this option is set to

.Dq no ,

.Dq no

remote X11 clients will be considered untrusted and prevented

then remote X11 clients will be considered untrusted and prevented

from stealing or tampering with data belonging to trusted X11

clients.

Furthermore, the

Line 457

Line 441

Specifies whether remote hosts are allowed to connect to local

forwarded ports.

By default,

.Xr ssh 1

.Nm ssh

binds local port forwardings to the loopback address.

This prevents other remote hosts from connecting to forwarded ports.

.Cm GatewayPorts

can be used to specify that ssh

can be used to specify that

.Nm ssh

should bind local port forwardings to the wildcard address,

thus allowing remote hosts to connect to forwarded ports.

The argument must be

Line 486

Line 471

Note that this option applies to protocol version 2 only.

.It Cm HashKnownHosts

Indicates that

.Xr ssh 1

.Nm ssh

should hash host names and addresses when they are added to

.Pa ~/.ssh/known_hosts .

These hashed names may be used normally by

.Xr ssh 1

.Nm ssh

and

.Xr sshd 8 ,

.Nm sshd ,

but they do not reveal identifying information should the file's contents

be disclosed.

The default is

.Dq no .

Note that existing names and addresses in known hosts files

Note that hashing of names and addresses will not be retrospectively applied

will not be converted automatically,

to existing known hosts files, but these may be manually hashed using

but may be manually hashed using

.Xr ssh-keygen 1 .

.It Cm HostbasedAuthentication

Specifies whether to try rhosts based authentication with public key

Line 522

Line 506

Specifies an alias that should be used instead of the

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

This option is useful for tunneling ssh connections

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.

The default is the name given on the command line.

Default is the name given on the command line.

Numeric IP addresses are also permitted (both on the command line and in

.Cm HostName

specifications).

.It Cm IdentitiesOnly

Specifies that

.Xr ssh 1

should only use the authentication identity files configured in the

.Nm

files,

even if

.Xr ssh-agent 1

offers more identities.

The argument to this keyword must be

.Dq yes

.Dq no .

This option is intended for situations where ssh-agent

offers many different identities.

The default is

.Dq no .

.It Cm IdentityFile

Specifies a file from which the user's RSA or DSA authentication identity

is read.

Line 560

Line 527

for protocol version 2.

Additionally, any identities represented by the authentication agent

will be used for authentication.

.Pp

The file name may use the tilde

syntax to refer to a user's home directory or one of the following

syntax to refer to a user's home directory.

escape characters:

.Ql %d

(local user's home directory),

.Ql %u

(local user name),

.Ql %l

(local host name),

.Ql %h

(remote host name) or

.Ql %r

(remote user name).

.Pp

It is possible to have

multiple identity files specified in configuration files; all these

identities will be tried in sequence.

.It Cm IdentitiesOnly

Specifies that

.Nm ssh

should only use the authentication identity files configured in the

.Nm

files,

even if the

.Nm ssh-agent

offers more identities.

The argument to this keyword must be

.Dq yes

.Dq no .

This option is intented for situations where

.Nm ssh-agent

offers many different identities.

The default is

.Dq no .

.It Cm KbdInteractiveDevices

Specifies the list of methods to use in keyboard-interactive authentication.

Multiple method names must be comma-separated.

The default is to use the server specified list.

The methods available vary depending on what the server supports.

For an OpenSSH server,

it may be zero or more of:

.Dq bsdauth ,

.Dq pam ,

and

.Dq skey .

.It Cm LocalCommand

Specifies a command to execute on the local machine after successfully

connecting to the server.

The command string extends to the end of the line, and is executed with

.Pa /bin/sh .

This directive is ignored unless

.Cm PermitLocalCommand

has been enabled.

.It Cm LocalForward

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

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

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

The first argument must be

.Sm off

Line 630

Line 587

indicates that the port should be available from all interfaces.

.It Cm LogLevel

Gives the verbosity level that is used when logging messages from

.Xr ssh 1 .

.Nm ssh .

The possible values are:

QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3.

QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2 and DEBUG3.

The default is INFO.

DEBUG and DEBUG1 are equivalent.

DEBUG2 and DEBUG3 each specify higher levels of verbose output.

Line 642

Line 599

The MAC algorithm is used in protocol version 2

for data integrity protection.

Multiple algorithms must be comma-separated.

The default is:

The default is

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

.It Cm NoHostAuthenticationForLocalhost

This option can be used if the home directory is shared across machines.

Line 657

Line 614

.It Cm NumberOfPasswordPrompts

Specifies the number of password prompts before giving up.

The argument to this keyword must be an integer.

The default is 3.

Default is 3.

.It Cm PasswordAuthentication

Specifies whether to use password authentication.

The argument to this keyword must be

Line 666

Line 623

.Dq no .

The default is

.Dq yes .

.It Cm PermitLocalCommand

Allow local command execution via the

.Ic LocalCommand

option or using the

.Ic !\& Ns Ar command

escape sequence in

.Xr ssh 1 .

The argument must be

.Dq yes

.Dq no .

The default is

.Dq no .

.It Cm Port

Specifies the port number to connect on the remote host.

The default is 22.

Default is 22.

.It Cm PreferredAuthentications

Specifies the order in which the client should try protocol 2

authentication methods.

Line 690

Line 634

over another method (e.g.\&

.Cm password )

The default for this option is:

.Do gssapi-with-mic ,

.Dq hostbased,publickey,keyboard-interactive,password .

hostbased,

publickey,

keyboard-interactive,

password

.Dc .

.It Cm Protocol

Specifies the protocol versions

.Xr ssh 1

.Nm ssh

should support in order of preference.

The possible values are

.Sq 1

.Dq 1

and

.Sq 2 .

.Dq 2 .

Multiple versions must be comma-separated.

The default is

.Dq 2,1 .

This means that ssh

This means that

.Nm ssh

tries version 2 and falls back to version 1

if version 2 is not available.

.It Cm ProxyCommand

Line 755

Line 695

The default is

.Dq yes .

This option applies to protocol version 2 only.

.It Cm RekeyLimit

Specifies the maximum amount of data that may be transmitted before the

session key is renegotiated.

The argument is the number of bytes, with an optional suffix of

.Sq K ,

.Sq M ,

.Sq G

to indicate Kilobytes, Megabytes, or Gigabytes, respectively.

The default is between

.Sq 1G

and

.Sq 4G ,

depending on the cipher.

This option applies to protocol version 2 only.

.It Cm RemoteForward

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

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

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

The first argument must be

.Sm off

Line 813

Line 738

The default is

.Dq no .

This option applies to protocol version 1 only and requires

.Xr ssh 1

.Nm ssh

to be setuid root.

.It Cm RSAAuthentication

Specifies whether to try RSA authentication.

Line 831

Line 756

Specifies what variables from the local

.Xr environ 7

should be sent to the server.

Note that environment passing is only supported for protocol 2.

Note that environment passing is only supported for protocol 2, the

The server must also support it, and the server must be configured to

server must also support it, and the server must be configured to

accept these environment variables.

Refer to

.Cm AcceptEnv

.Xr sshd_config 5

for how to configure the server.

Variables are specified by name, which may contain wildcard characters.

Variables are specified by name, which may contain the wildcard characters

.Ql \&*

and

.Ql \&? .

Multiple environment variables may be separated by whitespace or spread

across multiple

.Cm SendEnv

directives.

The default is not to send any environment variables.

.Pp

.It Cm ServerAliveInterval

See

Sets a timeout interval in seconds after which if no data has been received

.Sx PATTERNS

from the server,

for more information on patterns.

.Nm ssh

will send a message through the encrypted

channel to request a response from the server.

The default

is 0, indicating that these messages will not be sent to the server.

This option applies to protocol version 2 only.

.It Cm ServerAliveCountMax

Sets the number of server alive messages (see below) which may be

Sets the number of server alive messages (see above) which may be

sent without

.Xr ssh 1

.Nm ssh

receiving any messages back from the server.

If this threshold is reached while server alive messages are being sent,

ssh will disconnect from the server, terminating the session.

.Nm ssh

will disconnect from the server, terminating the session.

It is important to note that the use of server alive messages is very

different from

.Cm TCPKeepAlive

Line 871

Line 805

The default value is 3.

If, for example,

.Cm ServerAliveInterval

(see below) is set to 15 and

(above) is set to 15, and

.Cm ServerAliveCountMax

is left at the default, if the server becomes unresponsive,

is left at the default, if the server becomes unresponsive ssh

ssh will disconnect after approximately 45 seconds.

will disconnect after approximately 45 seconds.

This option applies to protocol version 2 only.

.It Cm ServerAliveInterval

Sets a timeout interval in seconds after which if no data has been received

from the server,

.Xr ssh 1

will send a message through the encrypted

channel to request a response from the server.

The default

is 0, indicating that these messages will not be sent to the server.

This option applies to protocol version 2 only.

.It Cm SmartcardDevice

Specifies which smartcard device to use.

The argument to this keyword is the device

.Xr ssh 1

.Nm ssh

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 ,

.Xr ssh 1

.Nm ssh

will never automatically add host keys to the

.Pa ~/.ssh/known_hosts

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

This provides maximum protection against trojan horse attacks,

though it can be annoying when the

however, can be annoying when the

.Pa /etc/ssh/ssh_known_hosts

file is poorly maintained or when connections to new hosts are

file is poorly maintained, or connections to new hosts are

frequently made.

This option forces the user to manually

add all new hosts.

If this flag is set to

.Dq no ,

ssh will automatically add new host keys to the

.Nm ssh

will automatically add new host keys to the

user known hosts files.

If this flag is set to

.Dq ask ,

new host keys

will be added to the user known host files only after the user

has confirmed that is what they really want to do, and

ssh will refuse to connect to hosts whose host key has changed.

.Nm ssh

will refuse to connect to hosts whose host key has changed.

The host keys of

known hosts will be verified automatically in all cases.

The argument must be

.Dq yes ,

.Dq no ,

.Dq no

.Dq ask .

The default is

Line 942

Line 868

.Pp

To disable TCP keepalive messages, the value should be set to

.Dq no .

.It Cm Tunnel

Request

.Xr tun 4

device forwarding between the client and the server.

The argument must be

.Dq yes ,

.Dq point-to-point

(layer 3),

.Dq ethernet

(layer 2),

.Dq no .

Specifying

.Dq yes

requests the default tunnel mode, which is

.Dq point-to-point .

The default is

.Dq no .

.It Cm TunnelDevice

Specifies the

.Xr tun 4

devices to open on the client

.Pq Ar local_tun

and the server

.Pq Ar remote_tun .

.Pp

The argument must be

.Sm off

.Ar local_tun Op : Ar remote_tun .

.Sm on

The devices may be specified by numerical ID or the keyword

.Dq any ,

which uses the next available tunnel device.

.Ar remote_tun

is not specified, it defaults to

.Dq any .

The default is

.Dq any:any .

.It Cm UsePrivilegedPort

Specifies whether to use a privileged port for outgoing connections.

The argument must be

Line 990

Line 877

The default is

.Dq no .

If set to

.Dq yes ,

.Dq yes

.Xr ssh 1

.Nm ssh

must be setuid root.

Note that this option must be set to

.Dq yes

Line 1024

Line 911

option.

The argument must be

.Dq yes ,

.Dq no ,

.Dq no

.Dq ask .

The default is

.Dq no .

Note that this option applies to protocol version 2 only.

.Pp