39.Dd September 25, 1999
40.Dt SSH_CONFIG 5
41.Os
42.Sh NAME
43.Nm ssh_config
44.Nd OpenSSH SSH client configuration files
45.Sh SYNOPSIS
46.Bl -tag -width Ds -compact
47.It Pa ~/.ssh/config
48.It Pa /etc/ssh/ssh_config
49.El
50.Sh DESCRIPTION
51.Xr ssh 1
52obtains configuration data from the following sources in
53the following order:
54.Pp
55.Bl -enum -offset indent -compact
56.It
57command-line options
58.It
59user's configuration file
60.Pq Pa ~/.ssh/config
61.It
62system-wide configuration file
63.Pq Pa /etc/ssh/ssh_config
64.El
65.Pp
66For each parameter, the first obtained value
67will be used.
68The configuration files contain sections separated by
69.Dq Host
70specifications, and that section is only applied for hosts that
71match one of the patterns given in the specification.
72The matched host name is the one given on the command line.
73.Pp
74Since the first obtained value for each parameter is used, more
75host-specific declarations should be given near the beginning of the
76file, and general defaults at the end.
77.Pp
78The configuration file has the following format:
79.Pp
80Empty lines and lines starting with
81.Ql #
82are comments.
83Otherwise a line is of the format
84.Dq keyword arguments .
85Configuration options may be separated by whitespace or
86optional whitespace and exactly one
87.Ql = ;
88the latter format is useful to avoid the need to quote whitespace
89when specifying configuration options using the
90.Nm ssh ,
91.Nm scp ,
92and
93.Nm sftp
94.Fl o
95option.
96Arguments may optionally be enclosed in double quotes
97.Pq \&"
98in order to represent arguments containing spaces.
99.Pp
100The possible
101keywords and their meanings are as follows (note that
102keywords are case-insensitive and arguments are case-sensitive):
103.Bl -tag -width Ds
104.It Cm Host
105Restricts the following declarations (up to the next
106.Cm Host
107keyword) to be only for those hosts that match one of the patterns
108given after the keyword.
109A single
110.Ql *
111as a pattern can be used to provide global
112defaults for all hosts.
113The host is the
114.Ar hostname
115argument given on the command line (i.e. the name is not converted to
116a canonicalized host name before matching).
117.Pp
118See
119.Sx PATTERNS
120for more information on patterns.
121.It Cm AddressFamily
122Specifies which address family to use when connecting.
123Valid arguments are
124.Dq any ,
125.Dq inet
126(use IPv4 only), or
127.Dq inet6
128(use IPv6 only).
129.It Cm BatchMode
130If set to
131.Dq yes ,
132passphrase/password querying will be disabled.
133This option is useful in scripts and other batch jobs where no user
134is present to supply the password.
135The argument must be
136.Dq yes
137or
138.Dq no .
139The default is
140.Dq no .
141.It Cm BindAddress
142Use the specified address on the local machine as the source address of
143the connection.
144Only useful on systems with more than one address.
145Note that this option does not work if
146.Cm UsePrivilegedPort
147is set to
148.Dq yes .
149.It Cm ChallengeResponseAuthentication
150Specifies whether to use challenge-response authentication.
151The argument to this keyword must be
152.Dq yes
153or
154.Dq no .
155The default is
156.Dq yes .
157.It Cm CheckHostIP
158If this flag is set to
159.Dq yes ,
160.Xr ssh 1
161will additionally check the host IP address in the
162.Pa known_hosts
163file.
164This allows ssh to detect if a host key changed due to DNS spoofing.
165If the option is set to
166.Dq no ,
167the check will not be executed.
168The default is
169.Dq no .
170.It Cm Cipher
171Specifies the cipher to use for encrypting the session
172in protocol version 1.
173Currently,
174.Dq blowfish ,
175.Dq 3des ,
176and
177.Dq des
178are supported.
179.Ar des
180is only supported in the
181.Xr ssh 1
182client for interoperability with legacy protocol 1 implementations
183that do not support the
184.Ar 3des
185cipher.
186Its use is strongly discouraged due to cryptographic weaknesses.
187The default is
188.Dq 3des .
189.It Cm Ciphers
190Specifies the ciphers allowed for protocol version 2
191in order of preference.
192Multiple ciphers must be comma-separated.
193The supported ciphers are
194.Dq 3des-cbc ,
195.Dq aes128-cbc ,
196.Dq aes192-cbc ,
197.Dq aes256-cbc ,
198.Dq aes128-ctr ,
199.Dq aes192-ctr ,
200.Dq aes256-ctr ,
201.Dq arcfour128 ,
202.Dq arcfour256 ,
203.Dq arcfour ,
204.Dq blowfish-cbc ,
205and
206.Dq cast128-cbc .
207The default is:
208.Bd -literal -offset 3n
209aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour128,
210arcfour256,arcfour,aes192-cbc,aes256-cbc,aes128-ctr,
211aes192-ctr,aes256-ctr
212.Ed
213.It Cm ClearAllForwardings
214Specifies that all local, remote, and dynamic port forwardings
215specified in the configuration files or on the command line be
216cleared.
217This option is primarily useful when used from the
218.Xr ssh 1
219command line to clear port forwardings set in
220configuration files, and is automatically set by
221.Xr scp 1
222and
223.Xr sftp 1 .
224The argument must be
225.Dq yes
226or
227.Dq no .
228The default is
229.Dq no .
230.It Cm Compression
231Specifies whether to use compression.
232The argument must be
233.Dq yes
234or
235.Dq no .
236The default is
237.Dq no .
238.It Cm CompressionLevel
239Specifies the compression level to use if compression is enabled.
240The argument must be an integer from 1 (fast) to 9 (slow, best).
241The default level is 6, which is good for most applications.
242The meaning of the values is the same as in
243.Xr gzip 1 .
244Note that this option applies to protocol version 1 only.
245.It Cm ConnectionAttempts
246Specifies the number of tries (one per second) to make before exiting.
247The argument must be an integer.
248This may be useful in scripts if the connection sometimes fails.
249The default is 1.
250.It Cm ConnectTimeout
251Specifies the timeout (in seconds) used when connecting to the
252SSH server, instead of using the default system TCP timeout.
253This value is used only when the target is down or really unreachable,
254not when it refuses the connection.
255.It Cm ControlMaster
256Enables the sharing of multiple sessions over a single network connection.
257When set to
258.Dq yes ,
259.Xr ssh 1
260will listen for connections on a control socket specified using the
261.Cm ControlPath
262argument.
263Additional sessions can connect to this socket using the same
264.Cm ControlPath
265with
266.Cm ControlMaster
267set to
268.Dq no
269(the default).
270These sessions will try to reuse the master instance's network connection
271rather than initiating new ones, but will fall back to connecting normally
272if the control socket does not exist, or is not listening.
273.Pp
274Setting this to
275.Dq ask
276will cause ssh
277to listen for control connections, but require confirmation using the
278.Ev SSH_ASKPASS
279program before they are accepted (see
280.Xr ssh-add 1
281for details).
282If the
283.Cm ControlPath
284cannot be opened,
285ssh will continue without connecting to a master instance.
286.Pp
287X11 and
288.Xr ssh-agent 1
289forwarding is supported over these multiplexed connections, however the
290display and agent forwarded will be the one belonging to the master
291connection i.e. it is not possible to forward multiple displays or agents.
292.Pp
293Two additional options allow for opportunistic multiplexing: try to use a
294master connection but fall back to creating a new one if one does not already
295exist.
296These options are:
297.Dq auto
298and
299.Dq autoask .
300The latter requires confirmation like the
301.Dq ask
302option.
303.It Cm ControlPath
304Specify the path to the control socket used for connection sharing as described
305in the
306.Cm ControlMaster
307section above or the string
308.Dq none
309to disable connection sharing.
310In the path,
311.Ql %l
312will be substituted by the local host name,
313.Ql %h
314will be substituted by the target host name,
315.Ql %p
316the port, and
317.Ql %r
318by the remote login username.
319It is recommended that any
320.Cm ControlPath
321used for opportunistic connection sharing include
322at least %h, %p, and %r.
323This ensures that shared connections are uniquely identified.
324.It Cm DynamicForward
325Specifies that a TCP port on the local machine be forwarded
326over the secure channel, and the application
327protocol is then used to determine where to connect to from the
328remote machine.
329.Pp
330The argument must be
331.Sm off
332.Oo Ar bind_address : Oc Ar port .
333.Sm on
334IPv6 addresses can be specified by enclosing addresses in square brackets or
335by using an alternative syntax:
336.Oo Ar bind_address Ns / Oc Ns Ar port .
337By default, the local port is bound in accordance with the
338.Cm GatewayPorts
339setting.
340However, an explicit
341.Ar bind_address
342may be used to bind the connection to a specific address.
343The
344.Ar bind_address
345of
346.Dq localhost
347indicates that the listening port be bound for local use only, while an
348empty address or
349.Sq *
350indicates that the port should be available from all interfaces.
351.Pp
352Currently the SOCKS4 and SOCKS5 protocols are supported, and
353.Xr ssh 1
354will act as a SOCKS server.
355Multiple forwardings may be specified, and
356additional forwardings can be given on the command line.
357Only the superuser can forward privileged ports.
358.It Cm EnableSSHKeysign
359Setting this option to
360.Dq yes
361in the global client configuration file
362.Pa /etc/ssh/ssh_config
363enables the use of the helper program
364.Xr ssh-keysign 8
365during
366.Cm HostbasedAuthentication .
367The argument must be
368.Dq yes
369or
370.Dq no .
371The default is
372.Dq no .
373This option should be placed in the non-hostspecific section.
374See
375.Xr ssh-keysign 8
376for more information.
377.It Cm EscapeChar
378Sets the escape character (default:
379.Ql ~ ) .
380The escape character can also
381be set on the command line.
382The argument should be a single character,
383.Ql ^
384followed by a letter, or
385.Dq none
386to disable the escape
387character entirely (making the connection transparent for binary
388data).
389.It Cm ExitOnForwardFailure
390Specifies whether
391.Xr ssh 1
392should terminate the connection if it cannot set up all requested
393dynamic, local, and remote port forwardings.
394The argument must be
395.Dq yes
396or
397.Dq no .
398The default is
399.Dq no .
400.It Cm ForwardAgent
401Specifies whether the connection to the authentication agent (if any)
402will be forwarded to the remote machine.
403The argument must be
404.Dq yes
405or
406.Dq no .
407The default is
408.Dq no .
409.Pp
410Agent forwarding should be enabled with caution.
411Users with the ability to bypass file permissions on the remote host
412(for the agent's Unix-domain socket)
413can access the local agent through the forwarded connection.
414An attacker cannot obtain key material from the agent,
415however they can perform operations on the keys that enable them to
416authenticate using the identities loaded into the agent.
417.It Cm ForwardX11
418Specifies whether X11 connections will be automatically redirected
419over the secure channel and
420.Ev DISPLAY
421set.
422The argument must be
423.Dq yes
424or
425.Dq no .
426The default is
427.Dq no .
428.Pp
429X11 forwarding should be enabled with caution.
430Users with the ability to bypass file permissions on the remote host
431(for the user's X11 authorization database)
432can access the local X11 display through the forwarded connection.
433An attacker may then be able to perform activities such as keystroke monitoring
434if the
435.Cm ForwardX11Trusted
436option is also enabled.
437.It Cm ForwardX11Trusted
438If this option is set to
439.Dq yes ,
440remote X11 clients will have full access to the original X11 display.
441.Pp
442If this option is set to
443.Dq no ,
444remote X11 clients will be considered untrusted and prevented
445from stealing or tampering with data belonging to trusted X11
446clients.
447Furthermore, the
448.Xr xauth 1
449token used for the session will be set to expire after 20 minutes.
450Remote clients will be refused access after this time.
451.Pp
452The default is
453.Dq no .
454.Pp
455See the X11 SECURITY extension specification for full details on
456the restrictions imposed on untrusted clients.
457.It Cm GatewayPorts
458Specifies whether remote hosts are allowed to connect to local
459forwarded ports.
460By default,
461.Xr ssh 1
462binds local port forwardings to the loopback address.
463This prevents other remote hosts from connecting to forwarded ports.
464.Cm GatewayPorts
465can be used to specify that ssh
466should bind local port forwardings to the wildcard address,
467thus allowing remote hosts to connect to forwarded ports.
468The argument must be
469.Dq yes
470or
471.Dq no .
472The default is
473.Dq no .
474.It Cm GlobalKnownHostsFile
475Specifies a file to use for the global
476host key database instead of
477.Pa /etc/ssh/ssh_known_hosts .
478.It Cm GSSAPIAuthentication
479Specifies whether user authentication based on GSSAPI is allowed.
480The default is
481.Dq no .
482Note that this option applies to protocol version 2 only.
483.It Cm GSSAPIDelegateCredentials
484Forward (delegate) credentials to the server.
485The default is
486.Dq no .
487Note that this option applies to protocol version 2 only.
488.It Cm HashKnownHosts
489Indicates that
490.Xr ssh 1
491should hash host names and addresses when they are added to
492.Pa ~/.ssh/known_hosts .
493These hashed names may be used normally by
494.Xr ssh 1
495and
496.Xr sshd 8 ,
497but they do not reveal identifying information should the file's contents
498be disclosed.
499The default is
500.Dq no .
501Note that existing names and addresses in known hosts files
502will not be converted automatically,
503but may be manually hashed using
504.Xr ssh-keygen 1 .
505.It Cm HostbasedAuthentication
506Specifies whether to try rhosts based authentication with public key
507authentication.
508The argument must be
509.Dq yes
510or
511.Dq no .
512The default is
513.Dq no .
514This option applies to protocol version 2 only and
515is similar to
516.Cm RhostsRSAAuthentication .
517.It Cm HostKeyAlgorithms
518Specifies the protocol version 2 host key algorithms
519that the client wants to use in order of preference.
520The default for this option is:
521.Dq ssh-rsa,ssh-dss .
522.It Cm HostKeyAlias
523Specifies an alias that should be used instead of the
524real host name when looking up or saving the host key
525in the host key database files.
526This option is useful for tunneling SSH connections
527or for multiple servers running on a single host.
528.It Cm HostName
529Specifies the real host name to log into.
530This can be used to specify nicknames or abbreviations for hosts.
531The default is the name given on the command line.
532Numeric IP addresses are also permitted (both on the command line and in
533.Cm HostName
534specifications).
535.It Cm IdentitiesOnly
536Specifies that
537.Xr ssh 1
538should only use the authentication identity files configured in the
539.Nm
540files,
541even if
542.Xr ssh-agent 1
543offers more identities.
544The argument to this keyword must be
545.Dq yes
546or
547.Dq no .
548This option is intended for situations where ssh-agent
549offers many different identities.
550The default is
551.Dq no .
552.It Cm IdentityFile
553Specifies a file from which the user's RSA or DSA authentication identity
554is read.
555The default is
556.Pa ~/.ssh/identity
557for protocol version 1, and
558.Pa ~/.ssh/id_rsa
559and
560.Pa ~/.ssh/id_dsa
561for protocol version 2.
562Additionally, any identities represented by the authentication agent
563will be used for authentication.
564.Pp
565The file name may use the tilde
566syntax to refer to a user's home directory or one of the following
567escape characters:
568.Ql %d
569(local user's home directory),
570.Ql %u
571(local user name),
572.Ql %l
573(local host name),
574.Ql %h
575(remote host name) or
576.Ql %r
577(remote user name).
578.Pp
579It is possible to have
580multiple identity files specified in configuration files; all these
581identities will be tried in sequence.
582.It Cm KbdInteractiveDevices
583Specifies the list of methods to use in keyboard-interactive authentication.
584Multiple method names must be comma-separated.
585The default is to use the server specified list.
586The methods available vary depending on what the server supports.
587For an OpenSSH server,
588it may be zero or more of:
589.Dq bsdauth ,
590.Dq pam ,
591and
592.Dq skey .
593.It Cm LocalCommand
594Specifies a command to execute on the local machine after successfully
595connecting to the server.
596The command string extends to the end of the line, and is executed with
597.Pa /bin/sh .
598This directive is ignored unless
599.Cm PermitLocalCommand
600has been enabled.
601.It Cm LocalForward
602Specifies that a TCP port on the local machine be forwarded over
603the secure channel to the specified host and port from the remote machine.
604The first argument must be
605.Sm off
606.Oo Ar bind_address : Oc Ar port
607.Sm on
608and the second argument must be
609.Ar host : Ns Ar hostport .
610IPv6 addresses can be specified by enclosing addresses in square brackets or
611by using an alternative syntax:
612.Oo Ar bind_address Ns / Oc Ns Ar port
613and
614.Ar host Ns / Ns Ar hostport .
615Multiple forwardings may be specified, and additional forwardings can be
616given on the command line.
617Only the superuser can forward privileged ports.
618By default, the local port is bound in accordance with the
619.Cm GatewayPorts
620setting.
621However, an explicit
622.Ar bind_address
623may be used to bind the connection to a specific address.
624The
625.Ar bind_address
626of
627.Dq localhost
628indicates that the listening port be bound for local use only, while an
629empty address or
630.Sq *
631indicates that the port should be available from all interfaces.
632.It Cm LogLevel
633Gives the verbosity level that is used when logging messages from
634.Xr ssh 1 .
635The possible values are:
636QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3.
637The default is INFO.
638DEBUG and DEBUG1 are equivalent.
639DEBUG2 and DEBUG3 each specify higher levels of verbose output.
640.It Cm MACs
641Specifies the MAC (message authentication code) algorithms
642in order of preference.
643The MAC algorithm is used in protocol version 2
644for data integrity protection.
645Multiple algorithms must be comma-separated.
646The default is:
647.Dq hmac-md5,hmac-sha1,hmac-ripemd160,hmac-sha1-96,hmac-md5-96 .
648.It Cm NoHostAuthenticationForLocalhost
649This option can be used if the home directory is shared across machines.
650In this case localhost will refer to a different machine on each of
651the machines and the user will get many warnings about changed host keys.
652However, this option disables host authentication for localhost.
653The argument to this keyword must be
654.Dq yes
655or
656.Dq no .
657The default is to check the host key for localhost.
658.It Cm NumberOfPasswordPrompts
659Specifies the number of password prompts before giving up.
660The argument to this keyword must be an integer.
661The default is 3.
662.It Cm PasswordAuthentication
663Specifies whether to use password authentication.
664The argument to this keyword must be
665.Dq yes
666or
667.Dq no .
668The default is
669.Dq yes .
670.It Cm PermitLocalCommand
671Allow local command execution via the
672.Ic LocalCommand
673option or using the
674.Ic !\& Ns Ar command
675escape sequence in
676.Xr ssh 1 .
677The argument must be
678.Dq yes
679or
680.Dq no .
681The default is
682.Dq no .
683.It Cm Port
684Specifies the port number to connect on the remote host.
685The default is 22.
686.It Cm PreferredAuthentications
687Specifies the order in which the client should try protocol 2
688authentication methods.
689This allows a client to prefer one method (e.g.\&
690.Cm keyboard-interactive )
691over another method (e.g.\&
692.Cm password )
693The default for this option is:
694.Do gssapi-with-mic ,
695hostbased,
696publickey,
697keyboard-interactive,
698password
699.Dc .
700.It Cm Protocol
701Specifies the protocol versions
702.Xr ssh 1
703should support in order of preference.
704The possible values are
705.Sq 1
706and
707.Sq 2 .
708Multiple versions must be comma-separated.
709The default is
710.Dq 2,1 .
711This means that ssh
712tries version 2 and falls back to version 1
713if version 2 is not available.
714.It Cm ProxyCommand
715Specifies the command to use to connect to the server.
716The command
717string extends to the end of the line, and is executed with
718.Pa /bin/sh .
719In the command string,
720.Ql %h
721will be substituted by the host name to
722connect and
723.Ql %p
724by the port.
725The command can be basically anything,
726and should read from its standard input and write to its standard output.
727It should eventually connect an
728.Xr sshd 8
729server running on some machine, or execute
730.Ic sshd -i
731somewhere.
732Host key management will be done using the
733HostName of the host being connected (defaulting to the name typed by
734the user).
735Setting the command to
736.Dq none
737disables this option entirely.
738Note that
739.Cm CheckHostIP
740is not available for connects with a proxy command.
741.Pp
742This directive is useful in conjunction with
743.Xr nc 1
744and its proxy support.
745For example, the following directive would connect via an HTTP proxy at
746192.0.2.0:
747.Bd -literal -offset 3n
748ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
749.Ed
750.It Cm PubkeyAuthentication
751Specifies whether to try public key authentication.
752The argument to this keyword must be
753.Dq yes
754or
755.Dq no .
756The default is
757.Dq yes .
758This option applies to protocol version 2 only.
759.It Cm RekeyLimit
760Specifies the maximum amount of data that may be transmitted before the
761session key is renegotiated.
762The argument is the number of bytes, with an optional suffix of
763.Sq K ,
764.Sq M ,
765or
766.Sq G
767to indicate Kilobytes, Megabytes, or Gigabytes, respectively.
768The default is between
769.Sq 1G
770and
771.Sq 4G ,
772depending on the cipher.
773This option applies to protocol version 2 only.
774.It Cm RemoteForward
775Specifies that a TCP port on the remote machine be forwarded over
776the secure channel to the specified host and port from the local machine.
777The first argument must be
778.Sm off
779.Oo Ar bind_address : Oc Ar port
780.Sm on
781and the second argument must be
782.Ar host : Ns Ar hostport .
783IPv6 addresses can be specified by enclosing addresses in square brackets
784or by using an alternative syntax:
785.Oo Ar bind_address Ns / Oc Ns Ar port
786and
787.Ar host Ns / Ns Ar hostport .
788Multiple forwardings may be specified, and additional
789forwardings can be given on the command line.
790Only the superuser can forward privileged ports.
791.Pp
792If the
793.Ar bind_address
794is not specified, the default is to only bind to loopback addresses.
795If the
796.Ar bind_address
797is
798.Ql *
799or an empty string, then the forwarding is requested to listen on all
800interfaces.
801Specifying a remote
802.Ar bind_address
803will only succeed if the server's
804.Cm GatewayPorts
805option is enabled (see
806.Xr sshd_config 5 ) .
807.It Cm RhostsRSAAuthentication
808Specifies whether to try rhosts based authentication with RSA host
809authentication.
810The argument must be
811.Dq yes
812or
813.Dq no .
814The default is
815.Dq no .
816This option applies to protocol version 1 only and requires
817.Xr ssh 1
818to be setuid root.
819.It Cm RSAAuthentication
820Specifies whether to try RSA authentication.
821The argument to this keyword must be
822.Dq yes
823or
824.Dq no .
825RSA authentication will only be
826attempted if the identity file exists, or an authentication agent is
827running.
828The default is
829.Dq yes .
830Note that this option applies to protocol version 1 only.
831.It Cm SendEnv
832Specifies what variables from the local
833.Xr environ 7
834should be sent to the server.
835Note that environment passing is only supported for protocol 2.
836The server must also support it, and the server must be configured to
837accept these environment variables.
838Refer to
839.Cm AcceptEnv
840in
841.Xr sshd_config 5
842for how to configure the server.
843Variables are specified by name, which may contain wildcard characters.
844Multiple environment variables may be separated by whitespace or spread
845across multiple
846.Cm SendEnv
847directives.
848The default is not to send any environment variables.
849.Pp
850See
851.Sx PATTERNS
852for more information on patterns.
853.It Cm ServerAliveCountMax
854Sets the number of server alive messages (see below) which may be
855sent without
856.Xr ssh 1
857receiving any messages back from the server.
858If this threshold is reached while server alive messages are being sent,
859ssh will disconnect from the server, terminating the session.
860It is important to note that the use of server alive messages is very
861different from
862.Cm TCPKeepAlive
863(below).
864The server alive messages are sent through the encrypted channel
865and therefore will not be spoofable.
866The TCP keepalive option enabled by
867.Cm TCPKeepAlive
868is spoofable.
869The server alive mechanism is valuable when the client or
870server depend on knowing when a connection has become inactive.
871.Pp
872The default value is 3.
873If, for example,
874.Cm ServerAliveInterval
875(see below) is set to 15 and
876.Cm ServerAliveCountMax
877is left at the default, if the server becomes unresponsive,
878ssh will disconnect after approximately 45 seconds.
879This option applies to protocol version 2 only.
880.It Cm ServerAliveInterval
881Sets a timeout interval in seconds after which if no data has been received
882from the server,
883.Xr ssh 1
884will send a message through the encrypted
885channel to request a response from the server.
886The default
887is 0, indicating that these messages will not be sent to the server.
888This option applies to protocol version 2 only.
889.It Cm SmartcardDevice
890Specifies which smartcard device to use.
891The argument to this keyword is the device
892.Xr ssh 1
893should use to communicate with a smartcard used for storing the user's
894private RSA key.
895By default, no device is specified and smartcard support is not activated.
896.It Cm StrictHostKeyChecking
897If this flag is set to
898.Dq yes ,
899.Xr ssh 1
900will never automatically add host keys to the
901.Pa ~/.ssh/known_hosts
902file, and refuses to connect to hosts whose host key has changed.
903This provides maximum protection against trojan horse attacks,
904though it can be annoying when the
905.Pa /etc/ssh/ssh_known_hosts
906file is poorly maintained or when connections to new hosts are
907frequently made.
908This option forces the user to manually
909add all new hosts.
910If this flag is set to
911.Dq no ,
912ssh will automatically add new host keys to the
913user known hosts files.
914If this flag is set to
915.Dq ask ,
916new host keys
917will be added to the user known host files only after the user
918has confirmed that is what they really want to do, and
919ssh will refuse to connect to hosts whose host key has changed.
920The host keys of
921known hosts will be verified automatically in all cases.
922The argument must be
923.Dq yes ,
924.Dq no ,
925or
926.Dq ask .
927The default is
928.Dq ask .
929.It Cm TCPKeepAlive
930Specifies whether the system should send TCP keepalive messages to the
931other side.
932If they are sent, death of the connection or crash of one
933of the machines will be properly noticed.
934However, this means that
935connections will die if the route is down temporarily, and some people
936find it annoying.
937.Pp
938The default is
939.Dq yes
940(to send TCP keepalive messages), and the client will notice
941if the network goes down or the remote host dies.
942This is important in scripts, and many users want it too.
943.Pp
944To disable TCP keepalive messages, the value should be set to
945.Dq no .
946.It Cm Tunnel
947Request
948.Xr tun 4
949device forwarding between the client and the server.
950The argument must be
951.Dq yes ,
952.Dq point-to-point
953(layer 3),
954.Dq ethernet
955(layer 2),
956or
957.Dq no .
958Specifying
959.Dq yes
960requests the default tunnel mode, which is
961.Dq point-to-point .
962The default is
963.Dq no .
964.It Cm TunnelDevice
965Specifies the
966.Xr tun 4
967devices to open on the client
968.Pq Ar local_tun
969and the server
970.Pq Ar remote_tun .
971.Pp
972The argument must be
973.Sm off
974.Ar local_tun Op : Ar remote_tun .
975.Sm on
976The devices may be specified by numerical ID or the keyword
977.Dq any ,
978which uses the next available tunnel device.
979If
980.Ar remote_tun
981is not specified, it defaults to
982.Dq any .
983The default is
984.Dq any:any .
985.It Cm UsePrivilegedPort
986Specifies whether to use a privileged port for outgoing connections.
987The argument must be
988.Dq yes
989or
990.Dq no .
991The default is
992.Dq no .
993If set to
994.Dq yes ,
995.Xr ssh 1
996must be setuid root.
997Note that this option must be set to
998.Dq yes
999for
1000.Cm RhostsRSAAuthentication
1001with older servers.
1002.It Cm User
1003Specifies the user to log in as.
1004This can be useful when a different user name is used on different machines.
1005This saves the trouble of
1006having to remember to give the user name on the command line.
1007.It Cm UserKnownHostsFile
1008Specifies a file to use for the user
1009host key database instead of
1010.Pa ~/.ssh/known_hosts .
1011.It Cm VerifyHostKeyDNS
1012Specifies whether to verify the remote key using DNS and SSHFP resource
1013records.
1014If this option is set to
1015.Dq yes ,
1016the client will implicitly trust keys that match a secure fingerprint
1017from DNS.
1018Insecure fingerprints will be handled as if this option was set to
1019.Dq ask .
1020If this option is set to
1021.Dq ask ,
1022information on fingerprint match will be displayed, but the user will still
1023need to confirm new host keys according to the
1024.Cm StrictHostKeyChecking
1025option.
1026The argument must be
1027.Dq yes ,
1028.Dq no ,
1029or
1030.Dq ask .
1031The default is
1032.Dq no .
1033Note that this option applies to protocol version 2 only.
1034.Pp
1035See also
1036.Sx VERIFYING HOST KEYS
1037in
1038.Xr ssh 1 .
1039.It Cm VersionAddendum
1040Specifies a string to append to the regular version string to identify
1041OS- or site-specific modifications.
1042The default is
1043.Dq FreeBSD-20061110 .
1044.It Cm XAuthLocation
1045Specifies the full pathname of the
1046.Xr xauth 1
1047program.
1048The default is
| 39.Dd September 25, 1999
40.Dt SSH_CONFIG 5
41.Os
42.Sh NAME
43.Nm ssh_config
44.Nd OpenSSH SSH client configuration files
45.Sh SYNOPSIS
46.Bl -tag -width Ds -compact
47.It Pa ~/.ssh/config
48.It Pa /etc/ssh/ssh_config
49.El
50.Sh DESCRIPTION
51.Xr ssh 1
52obtains configuration data from the following sources in
53the following order:
54.Pp
55.Bl -enum -offset indent -compact
56.It
57command-line options
58.It
59user's configuration file
60.Pq Pa ~/.ssh/config
61.It
62system-wide configuration file
63.Pq Pa /etc/ssh/ssh_config
64.El
65.Pp
66For each parameter, the first obtained value
67will be used.
68The configuration files contain sections separated by
69.Dq Host
70specifications, and that section is only applied for hosts that
71match one of the patterns given in the specification.
72The matched host name is the one given on the command line.
73.Pp
74Since the first obtained value for each parameter is used, more
75host-specific declarations should be given near the beginning of the
76file, and general defaults at the end.
77.Pp
78The configuration file has the following format:
79.Pp
80Empty lines and lines starting with
81.Ql #
82are comments.
83Otherwise a line is of the format
84.Dq keyword arguments .
85Configuration options may be separated by whitespace or
86optional whitespace and exactly one
87.Ql = ;
88the latter format is useful to avoid the need to quote whitespace
89when specifying configuration options using the
90.Nm ssh ,
91.Nm scp ,
92and
93.Nm sftp
94.Fl o
95option.
96Arguments may optionally be enclosed in double quotes
97.Pq \&"
98in order to represent arguments containing spaces.
99.Pp
100The possible
101keywords and their meanings are as follows (note that
102keywords are case-insensitive and arguments are case-sensitive):
103.Bl -tag -width Ds
104.It Cm Host
105Restricts the following declarations (up to the next
106.Cm Host
107keyword) to be only for those hosts that match one of the patterns
108given after the keyword.
109A single
110.Ql *
111as a pattern can be used to provide global
112defaults for all hosts.
113The host is the
114.Ar hostname
115argument given on the command line (i.e. the name is not converted to
116a canonicalized host name before matching).
117.Pp
118See
119.Sx PATTERNS
120for more information on patterns.
121.It Cm AddressFamily
122Specifies which address family to use when connecting.
123Valid arguments are
124.Dq any ,
125.Dq inet
126(use IPv4 only), or
127.Dq inet6
128(use IPv6 only).
129.It Cm BatchMode
130If set to
131.Dq yes ,
132passphrase/password querying will be disabled.
133This option is useful in scripts and other batch jobs where no user
134is present to supply the password.
135The argument must be
136.Dq yes
137or
138.Dq no .
139The default is
140.Dq no .
141.It Cm BindAddress
142Use the specified address on the local machine as the source address of
143the connection.
144Only useful on systems with more than one address.
145Note that this option does not work if
146.Cm UsePrivilegedPort
147is set to
148.Dq yes .
149.It Cm ChallengeResponseAuthentication
150Specifies whether to use challenge-response authentication.
151The argument to this keyword must be
152.Dq yes
153or
154.Dq no .
155The default is
156.Dq yes .
157.It Cm CheckHostIP
158If this flag is set to
159.Dq yes ,
160.Xr ssh 1
161will additionally check the host IP address in the
162.Pa known_hosts
163file.
164This allows ssh to detect if a host key changed due to DNS spoofing.
165If the option is set to
166.Dq no ,
167the check will not be executed.
168The default is
169.Dq no .
170.It Cm Cipher
171Specifies the cipher to use for encrypting the session
172in protocol version 1.
173Currently,
174.Dq blowfish ,
175.Dq 3des ,
176and
177.Dq des
178are supported.
179.Ar des
180is only supported in the
181.Xr ssh 1
182client for interoperability with legacy protocol 1 implementations
183that do not support the
184.Ar 3des
185cipher.
186Its use is strongly discouraged due to cryptographic weaknesses.
187The default is
188.Dq 3des .
189.It Cm Ciphers
190Specifies the ciphers allowed for protocol version 2
191in order of preference.
192Multiple ciphers must be comma-separated.
193The supported ciphers are
194.Dq 3des-cbc ,
195.Dq aes128-cbc ,
196.Dq aes192-cbc ,
197.Dq aes256-cbc ,
198.Dq aes128-ctr ,
199.Dq aes192-ctr ,
200.Dq aes256-ctr ,
201.Dq arcfour128 ,
202.Dq arcfour256 ,
203.Dq arcfour ,
204.Dq blowfish-cbc ,
205and
206.Dq cast128-cbc .
207The default is:
208.Bd -literal -offset 3n
209aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour128,
210arcfour256,arcfour,aes192-cbc,aes256-cbc,aes128-ctr,
211aes192-ctr,aes256-ctr
212.Ed
213.It Cm ClearAllForwardings
214Specifies that all local, remote, and dynamic port forwardings
215specified in the configuration files or on the command line be
216cleared.
217This option is primarily useful when used from the
218.Xr ssh 1
219command line to clear port forwardings set in
220configuration files, and is automatically set by
221.Xr scp 1
222and
223.Xr sftp 1 .
224The argument must be
225.Dq yes
226or
227.Dq no .
228The default is
229.Dq no .
230.It Cm Compression
231Specifies whether to use compression.
232The argument must be
233.Dq yes
234or
235.Dq no .
236The default is
237.Dq no .
238.It Cm CompressionLevel
239Specifies the compression level to use if compression is enabled.
240The argument must be an integer from 1 (fast) to 9 (slow, best).
241The default level is 6, which is good for most applications.
242The meaning of the values is the same as in
243.Xr gzip 1 .
244Note that this option applies to protocol version 1 only.
245.It Cm ConnectionAttempts
246Specifies the number of tries (one per second) to make before exiting.
247The argument must be an integer.
248This may be useful in scripts if the connection sometimes fails.
249The default is 1.
250.It Cm ConnectTimeout
251Specifies the timeout (in seconds) used when connecting to the
252SSH server, instead of using the default system TCP timeout.
253This value is used only when the target is down or really unreachable,
254not when it refuses the connection.
255.It Cm ControlMaster
256Enables the sharing of multiple sessions over a single network connection.
257When set to
258.Dq yes ,
259.Xr ssh 1
260will listen for connections on a control socket specified using the
261.Cm ControlPath
262argument.
263Additional sessions can connect to this socket using the same
264.Cm ControlPath
265with
266.Cm ControlMaster
267set to
268.Dq no
269(the default).
270These sessions will try to reuse the master instance's network connection
271rather than initiating new ones, but will fall back to connecting normally
272if the control socket does not exist, or is not listening.
273.Pp
274Setting this to
275.Dq ask
276will cause ssh
277to listen for control connections, but require confirmation using the
278.Ev SSH_ASKPASS
279program before they are accepted (see
280.Xr ssh-add 1
281for details).
282If the
283.Cm ControlPath
284cannot be opened,
285ssh will continue without connecting to a master instance.
286.Pp
287X11 and
288.Xr ssh-agent 1
289forwarding is supported over these multiplexed connections, however the
290display and agent forwarded will be the one belonging to the master
291connection i.e. it is not possible to forward multiple displays or agents.
292.Pp
293Two additional options allow for opportunistic multiplexing: try to use a
294master connection but fall back to creating a new one if one does not already
295exist.
296These options are:
297.Dq auto
298and
299.Dq autoask .
300The latter requires confirmation like the
301.Dq ask
302option.
303.It Cm ControlPath
304Specify the path to the control socket used for connection sharing as described
305in the
306.Cm ControlMaster
307section above or the string
308.Dq none
309to disable connection sharing.
310In the path,
311.Ql %l
312will be substituted by the local host name,
313.Ql %h
314will be substituted by the target host name,
315.Ql %p
316the port, and
317.Ql %r
318by the remote login username.
319It is recommended that any
320.Cm ControlPath
321used for opportunistic connection sharing include
322at least %h, %p, and %r.
323This ensures that shared connections are uniquely identified.
324.It Cm DynamicForward
325Specifies that a TCP port on the local machine be forwarded
326over the secure channel, and the application
327protocol is then used to determine where to connect to from the
328remote machine.
329.Pp
330The argument must be
331.Sm off
332.Oo Ar bind_address : Oc Ar port .
333.Sm on
334IPv6 addresses can be specified by enclosing addresses in square brackets or
335by using an alternative syntax:
336.Oo Ar bind_address Ns / Oc Ns Ar port .
337By default, the local port is bound in accordance with the
338.Cm GatewayPorts
339setting.
340However, an explicit
341.Ar bind_address
342may be used to bind the connection to a specific address.
343The
344.Ar bind_address
345of
346.Dq localhost
347indicates that the listening port be bound for local use only, while an
348empty address or
349.Sq *
350indicates that the port should be available from all interfaces.
351.Pp
352Currently the SOCKS4 and SOCKS5 protocols are supported, and
353.Xr ssh 1
354will act as a SOCKS server.
355Multiple forwardings may be specified, and
356additional forwardings can be given on the command line.
357Only the superuser can forward privileged ports.
358.It Cm EnableSSHKeysign
359Setting this option to
360.Dq yes
361in the global client configuration file
362.Pa /etc/ssh/ssh_config
363enables the use of the helper program
364.Xr ssh-keysign 8
365during
366.Cm HostbasedAuthentication .
367The argument must be
368.Dq yes
369or
370.Dq no .
371The default is
372.Dq no .
373This option should be placed in the non-hostspecific section.
374See
375.Xr ssh-keysign 8
376for more information.
377.It Cm EscapeChar
378Sets the escape character (default:
379.Ql ~ ) .
380The escape character can also
381be set on the command line.
382The argument should be a single character,
383.Ql ^
384followed by a letter, or
385.Dq none
386to disable the escape
387character entirely (making the connection transparent for binary
388data).
389.It Cm ExitOnForwardFailure
390Specifies whether
391.Xr ssh 1
392should terminate the connection if it cannot set up all requested
393dynamic, local, and remote port forwardings.
394The argument must be
395.Dq yes
396or
397.Dq no .
398The default is
399.Dq no .
400.It Cm ForwardAgent
401Specifies whether the connection to the authentication agent (if any)
402will be forwarded to the remote machine.
403The argument must be
404.Dq yes
405or
406.Dq no .
407The default is
408.Dq no .
409.Pp
410Agent forwarding should be enabled with caution.
411Users with the ability to bypass file permissions on the remote host
412(for the agent's Unix-domain socket)
413can access the local agent through the forwarded connection.
414An attacker cannot obtain key material from the agent,
415however they can perform operations on the keys that enable them to
416authenticate using the identities loaded into the agent.
417.It Cm ForwardX11
418Specifies whether X11 connections will be automatically redirected
419over the secure channel and
420.Ev DISPLAY
421set.
422The argument must be
423.Dq yes
424or
425.Dq no .
426The default is
427.Dq no .
428.Pp
429X11 forwarding should be enabled with caution.
430Users with the ability to bypass file permissions on the remote host
431(for the user's X11 authorization database)
432can access the local X11 display through the forwarded connection.
433An attacker may then be able to perform activities such as keystroke monitoring
434if the
435.Cm ForwardX11Trusted
436option is also enabled.
437.It Cm ForwardX11Trusted
438If this option is set to
439.Dq yes ,
440remote X11 clients will have full access to the original X11 display.
441.Pp
442If this option is set to
443.Dq no ,
444remote X11 clients will be considered untrusted and prevented
445from stealing or tampering with data belonging to trusted X11
446clients.
447Furthermore, the
448.Xr xauth 1
449token used for the session will be set to expire after 20 minutes.
450Remote clients will be refused access after this time.
451.Pp
452The default is
453.Dq no .
454.Pp
455See the X11 SECURITY extension specification for full details on
456the restrictions imposed on untrusted clients.
457.It Cm GatewayPorts
458Specifies whether remote hosts are allowed to connect to local
459forwarded ports.
460By default,
461.Xr ssh 1
462binds local port forwardings to the loopback address.
463This prevents other remote hosts from connecting to forwarded ports.
464.Cm GatewayPorts
465can be used to specify that ssh
466should bind local port forwardings to the wildcard address,
467thus allowing remote hosts to connect to forwarded ports.
468The argument must be
469.Dq yes
470or
471.Dq no .
472The default is
473.Dq no .
474.It Cm GlobalKnownHostsFile
475Specifies a file to use for the global
476host key database instead of
477.Pa /etc/ssh/ssh_known_hosts .
478.It Cm GSSAPIAuthentication
479Specifies whether user authentication based on GSSAPI is allowed.
480The default is
481.Dq no .
482Note that this option applies to protocol version 2 only.
483.It Cm GSSAPIDelegateCredentials
484Forward (delegate) credentials to the server.
485The default is
486.Dq no .
487Note that this option applies to protocol version 2 only.
488.It Cm HashKnownHosts
489Indicates that
490.Xr ssh 1
491should hash host names and addresses when they are added to
492.Pa ~/.ssh/known_hosts .
493These hashed names may be used normally by
494.Xr ssh 1
495and
496.Xr sshd 8 ,
497but they do not reveal identifying information should the file's contents
498be disclosed.
499The default is
500.Dq no .
501Note that existing names and addresses in known hosts files
502will not be converted automatically,
503but may be manually hashed using
504.Xr ssh-keygen 1 .
505.It Cm HostbasedAuthentication
506Specifies whether to try rhosts based authentication with public key
507authentication.
508The argument must be
509.Dq yes
510or
511.Dq no .
512The default is
513.Dq no .
514This option applies to protocol version 2 only and
515is similar to
516.Cm RhostsRSAAuthentication .
517.It Cm HostKeyAlgorithms
518Specifies the protocol version 2 host key algorithms
519that the client wants to use in order of preference.
520The default for this option is:
521.Dq ssh-rsa,ssh-dss .
522.It Cm HostKeyAlias
523Specifies an alias that should be used instead of the
524real host name when looking up or saving the host key
525in the host key database files.
526This option is useful for tunneling SSH connections
527or for multiple servers running on a single host.
528.It Cm HostName
529Specifies the real host name to log into.
530This can be used to specify nicknames or abbreviations for hosts.
531The default is the name given on the command line.
532Numeric IP addresses are also permitted (both on the command line and in
533.Cm HostName
534specifications).
535.It Cm IdentitiesOnly
536Specifies that
537.Xr ssh 1
538should only use the authentication identity files configured in the
539.Nm
540files,
541even if
542.Xr ssh-agent 1
543offers more identities.
544The argument to this keyword must be
545.Dq yes
546or
547.Dq no .
548This option is intended for situations where ssh-agent
549offers many different identities.
550The default is
551.Dq no .
552.It Cm IdentityFile
553Specifies a file from which the user's RSA or DSA authentication identity
554is read.
555The default is
556.Pa ~/.ssh/identity
557for protocol version 1, and
558.Pa ~/.ssh/id_rsa
559and
560.Pa ~/.ssh/id_dsa
561for protocol version 2.
562Additionally, any identities represented by the authentication agent
563will be used for authentication.
564.Pp
565The file name may use the tilde
566syntax to refer to a user's home directory or one of the following
567escape characters:
568.Ql %d
569(local user's home directory),
570.Ql %u
571(local user name),
572.Ql %l
573(local host name),
574.Ql %h
575(remote host name) or
576.Ql %r
577(remote user name).
578.Pp
579It is possible to have
580multiple identity files specified in configuration files; all these
581identities will be tried in sequence.
582.It Cm KbdInteractiveDevices
583Specifies the list of methods to use in keyboard-interactive authentication.
584Multiple method names must be comma-separated.
585The default is to use the server specified list.
586The methods available vary depending on what the server supports.
587For an OpenSSH server,
588it may be zero or more of:
589.Dq bsdauth ,
590.Dq pam ,
591and
592.Dq skey .
593.It Cm LocalCommand
594Specifies a command to execute on the local machine after successfully
595connecting to the server.
596The command string extends to the end of the line, and is executed with
597.Pa /bin/sh .
598This directive is ignored unless
599.Cm PermitLocalCommand
600has been enabled.
601.It Cm LocalForward
602Specifies that a TCP port on the local machine be forwarded over
603the secure channel to the specified host and port from the remote machine.
604The first argument must be
605.Sm off
606.Oo Ar bind_address : Oc Ar port
607.Sm on
608and the second argument must be
609.Ar host : Ns Ar hostport .
610IPv6 addresses can be specified by enclosing addresses in square brackets or
611by using an alternative syntax:
612.Oo Ar bind_address Ns / Oc Ns Ar port
613and
614.Ar host Ns / Ns Ar hostport .
615Multiple forwardings may be specified, and additional forwardings can be
616given on the command line.
617Only the superuser can forward privileged ports.
618By default, the local port is bound in accordance with the
619.Cm GatewayPorts
620setting.
621However, an explicit
622.Ar bind_address
623may be used to bind the connection to a specific address.
624The
625.Ar bind_address
626of
627.Dq localhost
628indicates that the listening port be bound for local use only, while an
629empty address or
630.Sq *
631indicates that the port should be available from all interfaces.
632.It Cm LogLevel
633Gives the verbosity level that is used when logging messages from
634.Xr ssh 1 .
635The possible values are:
636QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3.
637The default is INFO.
638DEBUG and DEBUG1 are equivalent.
639DEBUG2 and DEBUG3 each specify higher levels of verbose output.
640.It Cm MACs
641Specifies the MAC (message authentication code) algorithms
642in order of preference.
643The MAC algorithm is used in protocol version 2
644for data integrity protection.
645Multiple algorithms must be comma-separated.
646The default is:
647.Dq hmac-md5,hmac-sha1,hmac-ripemd160,hmac-sha1-96,hmac-md5-96 .
648.It Cm NoHostAuthenticationForLocalhost
649This option can be used if the home directory is shared across machines.
650In this case localhost will refer to a different machine on each of
651the machines and the user will get many warnings about changed host keys.
652However, this option disables host authentication for localhost.
653The argument to this keyword must be
654.Dq yes
655or
656.Dq no .
657The default is to check the host key for localhost.
658.It Cm NumberOfPasswordPrompts
659Specifies the number of password prompts before giving up.
660The argument to this keyword must be an integer.
661The default is 3.
662.It Cm PasswordAuthentication
663Specifies whether to use password authentication.
664The argument to this keyword must be
665.Dq yes
666or
667.Dq no .
668The default is
669.Dq yes .
670.It Cm PermitLocalCommand
671Allow local command execution via the
672.Ic LocalCommand
673option or using the
674.Ic !\& Ns Ar command
675escape sequence in
676.Xr ssh 1 .
677The argument must be
678.Dq yes
679or
680.Dq no .
681The default is
682.Dq no .
683.It Cm Port
684Specifies the port number to connect on the remote host.
685The default is 22.
686.It Cm PreferredAuthentications
687Specifies the order in which the client should try protocol 2
688authentication methods.
689This allows a client to prefer one method (e.g.\&
690.Cm keyboard-interactive )
691over another method (e.g.\&
692.Cm password )
693The default for this option is:
694.Do gssapi-with-mic ,
695hostbased,
696publickey,
697keyboard-interactive,
698password
699.Dc .
700.It Cm Protocol
701Specifies the protocol versions
702.Xr ssh 1
703should support in order of preference.
704The possible values are
705.Sq 1
706and
707.Sq 2 .
708Multiple versions must be comma-separated.
709The default is
710.Dq 2,1 .
711This means that ssh
712tries version 2 and falls back to version 1
713if version 2 is not available.
714.It Cm ProxyCommand
715Specifies the command to use to connect to the server.
716The command
717string extends to the end of the line, and is executed with
718.Pa /bin/sh .
719In the command string,
720.Ql %h
721will be substituted by the host name to
722connect and
723.Ql %p
724by the port.
725The command can be basically anything,
726and should read from its standard input and write to its standard output.
727It should eventually connect an
728.Xr sshd 8
729server running on some machine, or execute
730.Ic sshd -i
731somewhere.
732Host key management will be done using the
733HostName of the host being connected (defaulting to the name typed by
734the user).
735Setting the command to
736.Dq none
737disables this option entirely.
738Note that
739.Cm CheckHostIP
740is not available for connects with a proxy command.
741.Pp
742This directive is useful in conjunction with
743.Xr nc 1
744and its proxy support.
745For example, the following directive would connect via an HTTP proxy at
746192.0.2.0:
747.Bd -literal -offset 3n
748ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
749.Ed
750.It Cm PubkeyAuthentication
751Specifies whether to try public key authentication.
752The argument to this keyword must be
753.Dq yes
754or
755.Dq no .
756The default is
757.Dq yes .
758This option applies to protocol version 2 only.
759.It Cm RekeyLimit
760Specifies the maximum amount of data that may be transmitted before the
761session key is renegotiated.
762The argument is the number of bytes, with an optional suffix of
763.Sq K ,
764.Sq M ,
765or
766.Sq G
767to indicate Kilobytes, Megabytes, or Gigabytes, respectively.
768The default is between
769.Sq 1G
770and
771.Sq 4G ,
772depending on the cipher.
773This option applies to protocol version 2 only.
774.It Cm RemoteForward
775Specifies that a TCP port on the remote machine be forwarded over
776the secure channel to the specified host and port from the local machine.
777The first argument must be
778.Sm off
779.Oo Ar bind_address : Oc Ar port
780.Sm on
781and the second argument must be
782.Ar host : Ns Ar hostport .
783IPv6 addresses can be specified by enclosing addresses in square brackets
784or by using an alternative syntax:
785.Oo Ar bind_address Ns / Oc Ns Ar port
786and
787.Ar host Ns / Ns Ar hostport .
788Multiple forwardings may be specified, and additional
789forwardings can be given on the command line.
790Only the superuser can forward privileged ports.
791.Pp
792If the
793.Ar bind_address
794is not specified, the default is to only bind to loopback addresses.
795If the
796.Ar bind_address
797is
798.Ql *
799or an empty string, then the forwarding is requested to listen on all
800interfaces.
801Specifying a remote
802.Ar bind_address
803will only succeed if the server's
804.Cm GatewayPorts
805option is enabled (see
806.Xr sshd_config 5 ) .
807.It Cm RhostsRSAAuthentication
808Specifies whether to try rhosts based authentication with RSA host
809authentication.
810The argument must be
811.Dq yes
812or
813.Dq no .
814The default is
815.Dq no .
816This option applies to protocol version 1 only and requires
817.Xr ssh 1
818to be setuid root.
819.It Cm RSAAuthentication
820Specifies whether to try RSA authentication.
821The argument to this keyword must be
822.Dq yes
823or
824.Dq no .
825RSA authentication will only be
826attempted if the identity file exists, or an authentication agent is
827running.
828The default is
829.Dq yes .
830Note that this option applies to protocol version 1 only.
831.It Cm SendEnv
832Specifies what variables from the local
833.Xr environ 7
834should be sent to the server.
835Note that environment passing is only supported for protocol 2.
836The server must also support it, and the server must be configured to
837accept these environment variables.
838Refer to
839.Cm AcceptEnv
840in
841.Xr sshd_config 5
842for how to configure the server.
843Variables are specified by name, which may contain wildcard characters.
844Multiple environment variables may be separated by whitespace or spread
845across multiple
846.Cm SendEnv
847directives.
848The default is not to send any environment variables.
849.Pp
850See
851.Sx PATTERNS
852for more information on patterns.
853.It Cm ServerAliveCountMax
854Sets the number of server alive messages (see below) which may be
855sent without
856.Xr ssh 1
857receiving any messages back from the server.
858If this threshold is reached while server alive messages are being sent,
859ssh will disconnect from the server, terminating the session.
860It is important to note that the use of server alive messages is very
861different from
862.Cm TCPKeepAlive
863(below).
864The server alive messages are sent through the encrypted channel
865and therefore will not be spoofable.
866The TCP keepalive option enabled by
867.Cm TCPKeepAlive
868is spoofable.
869The server alive mechanism is valuable when the client or
870server depend on knowing when a connection has become inactive.
871.Pp
872The default value is 3.
873If, for example,
874.Cm ServerAliveInterval
875(see below) is set to 15 and
876.Cm ServerAliveCountMax
877is left at the default, if the server becomes unresponsive,
878ssh will disconnect after approximately 45 seconds.
879This option applies to protocol version 2 only.
880.It Cm ServerAliveInterval
881Sets a timeout interval in seconds after which if no data has been received
882from the server,
883.Xr ssh 1
884will send a message through the encrypted
885channel to request a response from the server.
886The default
887is 0, indicating that these messages will not be sent to the server.
888This option applies to protocol version 2 only.
889.It Cm SmartcardDevice
890Specifies which smartcard device to use.
891The argument to this keyword is the device
892.Xr ssh 1
893should use to communicate with a smartcard used for storing the user's
894private RSA key.
895By default, no device is specified and smartcard support is not activated.
896.It Cm StrictHostKeyChecking
897If this flag is set to
898.Dq yes ,
899.Xr ssh 1
900will never automatically add host keys to the
901.Pa ~/.ssh/known_hosts
902file, and refuses to connect to hosts whose host key has changed.
903This provides maximum protection against trojan horse attacks,
904though it can be annoying when the
905.Pa /etc/ssh/ssh_known_hosts
906file is poorly maintained or when connections to new hosts are
907frequently made.
908This option forces the user to manually
909add all new hosts.
910If this flag is set to
911.Dq no ,
912ssh will automatically add new host keys to the
913user known hosts files.
914If this flag is set to
915.Dq ask ,
916new host keys
917will be added to the user known host files only after the user
918has confirmed that is what they really want to do, and
919ssh will refuse to connect to hosts whose host key has changed.
920The host keys of
921known hosts will be verified automatically in all cases.
922The argument must be
923.Dq yes ,
924.Dq no ,
925or
926.Dq ask .
927The default is
928.Dq ask .
929.It Cm TCPKeepAlive
930Specifies whether the system should send TCP keepalive messages to the
931other side.
932If they are sent, death of the connection or crash of one
933of the machines will be properly noticed.
934However, this means that
935connections will die if the route is down temporarily, and some people
936find it annoying.
937.Pp
938The default is
939.Dq yes
940(to send TCP keepalive messages), and the client will notice
941if the network goes down or the remote host dies.
942This is important in scripts, and many users want it too.
943.Pp
944To disable TCP keepalive messages, the value should be set to
945.Dq no .
946.It Cm Tunnel
947Request
948.Xr tun 4
949device forwarding between the client and the server.
950The argument must be
951.Dq yes ,
952.Dq point-to-point
953(layer 3),
954.Dq ethernet
955(layer 2),
956or
957.Dq no .
958Specifying
959.Dq yes
960requests the default tunnel mode, which is
961.Dq point-to-point .
962The default is
963.Dq no .
964.It Cm TunnelDevice
965Specifies the
966.Xr tun 4
967devices to open on the client
968.Pq Ar local_tun
969and the server
970.Pq Ar remote_tun .
971.Pp
972The argument must be
973.Sm off
974.Ar local_tun Op : Ar remote_tun .
975.Sm on
976The devices may be specified by numerical ID or the keyword
977.Dq any ,
978which uses the next available tunnel device.
979If
980.Ar remote_tun
981is not specified, it defaults to
982.Dq any .
983The default is
984.Dq any:any .
985.It Cm UsePrivilegedPort
986Specifies whether to use a privileged port for outgoing connections.
987The argument must be
988.Dq yes
989or
990.Dq no .
991The default is
992.Dq no .
993If set to
994.Dq yes ,
995.Xr ssh 1
996must be setuid root.
997Note that this option must be set to
998.Dq yes
999for
1000.Cm RhostsRSAAuthentication
1001with older servers.
1002.It Cm User
1003Specifies the user to log in as.
1004This can be useful when a different user name is used on different machines.
1005This saves the trouble of
1006having to remember to give the user name on the command line.
1007.It Cm UserKnownHostsFile
1008Specifies a file to use for the user
1009host key database instead of
1010.Pa ~/.ssh/known_hosts .
1011.It Cm VerifyHostKeyDNS
1012Specifies whether to verify the remote key using DNS and SSHFP resource
1013records.
1014If this option is set to
1015.Dq yes ,
1016the client will implicitly trust keys that match a secure fingerprint
1017from DNS.
1018Insecure fingerprints will be handled as if this option was set to
1019.Dq ask .
1020If this option is set to
1021.Dq ask ,
1022information on fingerprint match will be displayed, but the user will still
1023need to confirm new host keys according to the
1024.Cm StrictHostKeyChecking
1025option.
1026The argument must be
1027.Dq yes ,
1028.Dq no ,
1029or
1030.Dq ask .
1031The default is
1032.Dq no .
1033Note that this option applies to protocol version 2 only.
1034.Pp
1035See also
1036.Sx VERIFYING HOST KEYS
1037in
1038.Xr ssh 1 .
1039.It Cm VersionAddendum
1040Specifies a string to append to the regular version string to identify
1041OS- or site-specific modifications.
1042The default is
1043.Dq FreeBSD-20061110 .
1044.It Cm XAuthLocation
1045Specifies the full pathname of the
1046.Xr xauth 1
1047program.
1048The default is
|