logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

ssh_config.5 (70141B)


  1. .\"
  2. .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
  3. .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
  4. .\" All rights reserved
  5. .\"
  6. .\" As far as I am concerned, the code I have written for this software
  7. .\" can be used freely for any purpose. Any derived versions of this
  8. .\" software must be clearly marked as such, and if the derived work is
  9. .\" incompatible with the protocol description in the RFC file, it must be
  10. .\" called by a name other than "ssh" or "Secure Shell".
  11. .\"
  12. .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
  13. .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
  14. .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
  15. .\"
  16. .\" Redistribution and use in source and binary forms, with or without
  17. .\" modification, are permitted provided that the following conditions
  18. .\" are met:
  19. .\" 1. Redistributions of source code must retain the above copyright
  20. .\" notice, this list of conditions and the following disclaimer.
  21. .\" 2. Redistributions in binary form must reproduce the above copyright
  22. .\" notice, this list of conditions and the following disclaimer in the
  23. .\" documentation and/or other materials provided with the distribution.
  24. .\"
  25. .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  26. .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  27. .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  28. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  29. .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  30. .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  31. .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  32. .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  33. .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  34. .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  35. .\"
  36. .\" $OpenBSD: ssh_config.5,v 1.413 2025/03/03 06:53:09 dtucker Exp $
  37. .Dd $Mdocdate: March 3 2025 $
  38. .Dt SSH_CONFIG 5
  39. .Os
  40. .Sh NAME
  41. .Nm ssh_config
  42. .Nd OpenSSH client configuration file
  43. .Sh DESCRIPTION
  44. .Xr ssh 1
  45. obtains configuration data from the following sources in
  46. the following order:
  47. .Pp
  48. .Bl -enum -offset indent -compact
  49. .It
  50. command-line options
  51. .It
  52. user's configuration file
  53. .Pq Pa ~/.ssh/config
  54. .It
  55. system-wide configuration file
  56. .Pq Pa /etc/ssh/ssh_config
  57. .El
  58. .Pp
  59. Unless noted otherwise, for each parameter, the first obtained value
  60. will be used.
  61. The configuration files contain sections separated by
  62. .Cm Host
  63. specifications, and that section is only applied for hosts that
  64. match one of the patterns given in the specification.
  65. The matched host name is usually the one given on the command line
  66. (see the
  67. .Cm CanonicalizeHostname
  68. option for exceptions).
  69. .Pp
  70. Since the first obtained value for each parameter is used, more
  71. host-specific declarations should be given near the beginning of the
  72. file, and general defaults at the end.
  73. .Pp
  74. The file contains keyword-argument pairs, one per line.
  75. Lines starting with
  76. .Ql #
  77. and empty lines are interpreted as comments.
  78. Arguments may optionally be enclosed in double quotes
  79. .Pq \&"
  80. in order to represent arguments containing spaces.
  81. Configuration options may be separated by whitespace or
  82. optional whitespace and exactly one
  83. .Ql = ;
  84. the latter format is useful to avoid the need to quote whitespace
  85. when specifying configuration options using the
  86. .Nm ssh ,
  87. .Nm scp ,
  88. and
  89. .Nm sftp
  90. .Fl o
  91. option.
  92. .Pp
  93. The possible
  94. keywords and their meanings are as follows (note that
  95. keywords are case-insensitive and arguments are case-sensitive):
  96. .Bl -tag -width Ds
  97. .It Cm Host
  98. Restricts the following declarations (up to the next
  99. .Cm Host
  100. or
  101. .Cm Match
  102. keyword) to be only for those hosts that match one of the patterns
  103. given after the keyword.
  104. If more than one pattern is provided, they should be separated by whitespace.
  105. A single
  106. .Ql *
  107. as a pattern can be used to provide global
  108. defaults for all hosts.
  109. The host is usually the
  110. .Ar hostname
  111. argument given on the command line
  112. (see the
  113. .Cm CanonicalizeHostname
  114. keyword for exceptions).
  115. .Pp
  116. A pattern entry may be negated by prefixing it with an exclamation mark
  117. .Pq Sq !\& .
  118. If a negated entry is matched, then the
  119. .Cm Host
  120. entry is ignored, regardless of whether any other patterns on the line
  121. match.
  122. Negated matches are therefore useful to provide exceptions for wildcard
  123. matches.
  124. .Pp
  125. See
  126. .Sx PATTERNS
  127. for more information on patterns.
  128. .It Cm Match
  129. Restricts the following declarations (up to the next
  130. .Cm Host
  131. or
  132. .Cm Match
  133. keyword) to be used only when the conditions following the
  134. .Cm Match
  135. keyword are satisfied.
  136. Match conditions are specified using one or more criteria
  137. or the single token
  138. .Cm all
  139. which always matches.
  140. The available criteria keywords are:
  141. .Cm canonical ,
  142. .Cm final ,
  143. .Cm exec ,
  144. .Cm localnetwork ,
  145. .Cm host ,
  146. .Cm originalhost ,
  147. .Cm tagged ,
  148. .Cm command ,
  149. .Cm user ,
  150. .Cm localuser ,
  151. and
  152. .Cm version .
  153. The
  154. .Cm all
  155. criteria must appear alone or immediately after
  156. .Cm canonical
  157. or
  158. .Cm final .
  159. Other criteria may be combined arbitrarily.
  160. All criteria but
  161. .Cm all ,
  162. .Cm canonical ,
  163. and
  164. .Cm final
  165. require an argument.
  166. Criteria may be negated by prepending an exclamation mark
  167. .Pq Sq !\& .
  168. .Pp
  169. The
  170. .Cm canonical
  171. keyword matches only when the configuration file is being re-parsed
  172. after hostname canonicalization (see the
  173. .Cm CanonicalizeHostname
  174. option).
  175. This may be useful to specify conditions that work with canonical host
  176. names only.
  177. .Pp
  178. The
  179. .Cm final
  180. keyword requests that the configuration be re-parsed (regardless of whether
  181. .Cm CanonicalizeHostname
  182. is enabled), and matches only during this final pass.
  183. If
  184. .Cm CanonicalizeHostname
  185. is enabled, then
  186. .Cm canonical
  187. and
  188. .Cm final
  189. match during the same pass.
  190. .Pp
  191. The
  192. .Cm exec
  193. keyword executes the specified command under the user's shell.
  194. If the command returns a zero exit status then the condition is considered true.
  195. Commands containing whitespace characters must be quoted.
  196. Arguments to
  197. .Cm exec
  198. accept the tokens described in the
  199. .Sx TOKENS
  200. section.
  201. .Pp
  202. The
  203. .Cm localnetwork
  204. keyword matches the addresses of active local network interfaces against the
  205. supplied list of networks in CIDR format.
  206. This may be convenient for varying the effective configuration on devices that
  207. roam between networks.
  208. Note that network address is not a trustworthy criteria in many
  209. situations (e.g. when the network is automatically configured using DHCP)
  210. and so caution should be applied if using it to control security-sensitive
  211. configuration.
  212. .Pp
  213. The other keywords' criteria must be single entries or comma-separated
  214. lists and may use the wildcard and negation operators described in the
  215. .Sx PATTERNS
  216. section.
  217. .Pp
  218. The criteria for the
  219. .Cm host
  220. keyword are matched against the target hostname, after any substitution
  221. by the
  222. .Cm Hostname
  223. or
  224. .Cm CanonicalizeHostname
  225. options.
  226. The
  227. .Cm originalhost
  228. keyword matches against the hostname as it was specified on the command-line.
  229. .Pp
  230. The
  231. .Cm tagged
  232. keyword matches a tag name specified by a prior
  233. .Cm Tag
  234. directive or on the
  235. .Xr ssh 1
  236. command-line using the
  237. .Fl P
  238. flag.
  239. The
  240. .Cm command
  241. keyword matches the remote command that has been requested, or the subsystem
  242. name that is being invoked (e.g.\&
  243. .Qq sftp
  244. for an SFTP session).
  245. The empty string will match the case where a command or tag has not been
  246. specified, i.e.\&
  247. .Sq Match tag \&"\&" .
  248. The
  249. .Cm version
  250. keyword matches against the version string of
  251. .Xr ssh 1 ,
  252. for example
  253. .Dq OpenSSH_10.0 .
  254. .Pp
  255. The
  256. .Cm user
  257. keyword matches against the target username on the remote host.
  258. The
  259. .Cm localuser
  260. keyword matches against the name of the local user running
  261. .Xr ssh 1
  262. (this keyword may be useful in system-wide
  263. .Nm
  264. files).
  265. .Pp
  266. Finally, the
  267. .Cm sessiontype
  268. keyword matches the requested session type, which may be one of
  269. .Cm shell
  270. for interactive sessions,
  271. .Cm exec
  272. for command execution sessions,
  273. .Cm subsystem
  274. for subsystem invocations such as
  275. .Xr sftp 1 ,
  276. or
  277. .Cm none
  278. for transport-only sessions, such as when
  279. .Xr ssh 1
  280. is started with the
  281. .Fl N
  282. flag.
  283. .It Cm AddKeysToAgent
  284. Specifies whether keys should be automatically added to a running
  285. .Xr ssh-agent 1 .
  286. If this option is set to
  287. .Cm yes
  288. and a key is loaded from a file, the key and its passphrase are added to
  289. the agent with the default lifetime, as if by
  290. .Xr ssh-add 1 .
  291. If this option is set to
  292. .Cm ask ,
  293. .Xr ssh 1
  294. will require confirmation using the
  295. .Ev SSH_ASKPASS
  296. program before adding a key (see
  297. .Xr ssh-add 1
  298. for details).
  299. If this option is set to
  300. .Cm confirm ,
  301. each use of the key must be confirmed, as if the
  302. .Fl c
  303. option was specified to
  304. .Xr ssh-add 1 .
  305. If this option is set to
  306. .Cm no ,
  307. no keys are added to the agent.
  308. Alternately, this option may be specified as a time interval
  309. using the format described in the
  310. .Sx TIME FORMATS
  311. section of
  312. .Xr sshd_config 5
  313. to specify the key's lifetime in
  314. .Xr ssh-agent 1 ,
  315. after which it will automatically be removed.
  316. The argument must be
  317. .Cm no
  318. (the default),
  319. .Cm yes ,
  320. .Cm confirm
  321. (optionally followed by a time interval),
  322. .Cm ask
  323. or a time interval.
  324. .It Cm AddressFamily
  325. Specifies which address family to use when connecting.
  326. Valid arguments are
  327. .Cm any
  328. (the default),
  329. .Cm inet
  330. (use IPv4 only), or
  331. .Cm inet6
  332. (use IPv6 only).
  333. .It Cm BatchMode
  334. If set to
  335. .Cm yes ,
  336. user interaction such as password prompts and host key confirmation requests
  337. will be disabled.
  338. This option is useful in scripts and other batch jobs where no user
  339. is present to interact with
  340. .Xr ssh 1 .
  341. The argument must be
  342. .Cm yes
  343. or
  344. .Cm no
  345. (the default).
  346. .It Cm BindAddress
  347. Use the specified address on the local machine as the source address of
  348. the connection.
  349. Only useful on systems with more than one address.
  350. .It Cm BindInterface
  351. Use the address of the specified interface on the local machine as the
  352. source address of the connection.
  353. .It Cm CanonicalDomains
  354. When
  355. .Cm CanonicalizeHostname
  356. is enabled, this option specifies the list of domain suffixes in which to
  357. search for the specified destination host.
  358. .It Cm CanonicalizeFallbackLocal
  359. Specifies whether to fail with an error when hostname canonicalization fails.
  360. The default,
  361. .Cm yes ,
  362. will attempt to look up the unqualified hostname using the system resolver's
  363. search rules.
  364. A value of
  365. .Cm no
  366. will cause
  367. .Xr ssh 1
  368. to fail instantly if
  369. .Cm CanonicalizeHostname
  370. is enabled and the target hostname cannot be found in any of the domains
  371. specified by
  372. .Cm CanonicalDomains .
  373. .It Cm CanonicalizeHostname
  374. Controls whether explicit hostname canonicalization is performed.
  375. The default,
  376. .Cm no ,
  377. is not to perform any name rewriting and let the system resolver handle all
  378. hostname lookups.
  379. If set to
  380. .Cm yes
  381. then, for connections that do not use a
  382. .Cm ProxyCommand
  383. or
  384. .Cm ProxyJump ,
  385. .Xr ssh 1
  386. will attempt to canonicalize the hostname specified on the command line
  387. using the
  388. .Cm CanonicalDomains
  389. suffixes and
  390. .Cm CanonicalizePermittedCNAMEs
  391. rules.
  392. If
  393. .Cm CanonicalizeHostname
  394. is set to
  395. .Cm always ,
  396. then canonicalization is applied to proxied connections too.
  397. .Pp
  398. If this option is enabled, then the configuration files are processed
  399. again using the new target name to pick up any new configuration in matching
  400. .Cm Host
  401. and
  402. .Cm Match
  403. stanzas.
  404. A value of
  405. .Cm none
  406. disables the use of a
  407. .Cm ProxyJump
  408. host.
  409. .It Cm CanonicalizeMaxDots
  410. Specifies the maximum number of dot characters in a hostname before
  411. canonicalization is disabled.
  412. The default, 1,
  413. allows a single dot (i.e. hostname.subdomain).
  414. .It Cm CanonicalizePermittedCNAMEs
  415. Specifies rules to determine whether CNAMEs should be followed when
  416. canonicalizing hostnames.
  417. The rules consist of one or more arguments of
  418. .Ar source_domain_list : Ns Ar target_domain_list ,
  419. where
  420. .Ar source_domain_list
  421. is a pattern-list of domains that may follow CNAMEs in canonicalization,
  422. and
  423. .Ar target_domain_list
  424. is a pattern-list of domains that they may resolve to.
  425. .Pp
  426. For example,
  427. .Qq *.a.example.com:*.b.example.com,*.c.example.com
  428. will allow hostnames matching
  429. .Qq *.a.example.com
  430. to be canonicalized to names in the
  431. .Qq *.b.example.com
  432. or
  433. .Qq *.c.example.com
  434. domains.
  435. .Pp
  436. A single argument of
  437. .Qq none
  438. causes no CNAMEs to be considered for canonicalization.
  439. This is the default behaviour.
  440. .It Cm CASignatureAlgorithms
  441. Specifies which algorithms are allowed for signing of certificates
  442. by certificate authorities (CAs).
  443. The default is:
  444. .Bd -literal -offset indent
  445. ssh-ed25519,ecdsa-sha2-nistp256,
  446. ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
  447. sk-ssh-ed25519@openssh.com,
  448. sk-ecdsa-sha2-nistp256@openssh.com,
  449. rsa-sha2-512,rsa-sha2-256
  450. .Ed
  451. .Pp
  452. If the specified list begins with a
  453. .Sq +
  454. character, then the specified algorithms will be appended to the default set
  455. instead of replacing them.
  456. If the specified list begins with a
  457. .Sq -
  458. character, then the specified algorithms (including wildcards) will be removed
  459. from the default set instead of replacing them.
  460. .Pp
  461. .Xr ssh 1
  462. will not accept host certificates signed using algorithms other than those
  463. specified.
  464. .It Cm CertificateFile
  465. Specifies a file from which the user's certificate is read.
  466. A corresponding private key must be provided separately in order
  467. to use this certificate either
  468. from an
  469. .Cm IdentityFile
  470. directive or
  471. .Fl i
  472. flag to
  473. .Xr ssh 1 ,
  474. via
  475. .Xr ssh-agent 1 ,
  476. or via a
  477. .Cm PKCS11Provider
  478. or
  479. .Cm SecurityKeyProvider .
  480. .Pp
  481. Arguments to
  482. .Cm CertificateFile
  483. may use the tilde syntax to refer to a user's home directory,
  484. the tokens described in the
  485. .Sx TOKENS
  486. section and environment variables as described in the
  487. .Sx ENVIRONMENT VARIABLES
  488. section.
  489. .Pp
  490. It is possible to have multiple certificate files specified in
  491. configuration files; these certificates will be tried in sequence.
  492. Multiple
  493. .Cm CertificateFile
  494. directives will add to the list of certificates used for
  495. authentication.
  496. .It Cm ChannelTimeout
  497. Specifies whether and how quickly
  498. .Xr ssh 1
  499. should close inactive channels.
  500. Timeouts are specified as one or more
  501. .Dq type=interval
  502. pairs separated by whitespace, where the
  503. .Dq type
  504. must be the special keyword
  505. .Dq global
  506. or a channel type name from the list below, optionally containing
  507. wildcard characters.
  508. .Pp
  509. The timeout value
  510. .Dq interval
  511. is specified in seconds or may use any of the units documented in the
  512. .Sx TIME FORMATS
  513. section.
  514. For example,
  515. .Dq session=5m
  516. would cause interactive sessions to terminate after five minutes of
  517. inactivity.
  518. Specifying a zero value disables the inactivity timeout.
  519. .Pp
  520. The special timeout
  521. .Dq global
  522. applies to all active channels, taken together.
  523. Traffic on any active channel will reset the timeout, but when the timeout
  524. expires then all open channels will be closed.
  525. Note that this global timeout is not matched by wildcards and must be
  526. specified explicitly.
  527. .Pp
  528. The available channel type names include:
  529. .Bl -tag -width Ds
  530. .It Cm agent-connection
  531. Open connections to
  532. .Xr ssh-agent 1 .
  533. .It Cm direct-tcpip , Cm direct-streamlocal@openssh.com
  534. Open TCP or Unix socket (respectively) connections that have
  535. been established from a
  536. .Xr ssh 1
  537. local forwarding, i.e.\&
  538. .Cm LocalForward
  539. or
  540. .Cm DynamicForward .
  541. .It Cm forwarded-tcpip , Cm forwarded-streamlocal@openssh.com
  542. Open TCP or Unix socket (respectively) connections that have been
  543. established to a
  544. .Xr sshd 8
  545. listening on behalf of a
  546. .Xr ssh 1
  547. remote forwarding, i.e.\&
  548. .Cm RemoteForward .
  549. .It Cm session
  550. The interactive main session, including shell session, command execution,
  551. .Xr scp 1 ,
  552. .Xr sftp 1 ,
  553. etc.
  554. .It Cm tun-connection
  555. Open
  556. .Cm TunnelForward
  557. connections.
  558. .It Cm x11-connection
  559. Open X11 forwarding sessions.
  560. .El
  561. .Pp
  562. Note that in all the above cases, terminating an inactive session does not
  563. guarantee to remove all resources associated with the session, e.g. shell
  564. processes or X11 clients relating to the session may continue to execute.
  565. .Pp
  566. Moreover, terminating an inactive channel or session does not necessarily
  567. close the SSH connection, nor does it prevent a client from
  568. requesting another channel of the same type.
  569. In particular, expiring an inactive forwarding session does not prevent
  570. another identical forwarding from being subsequently created.
  571. .Pp
  572. The default is not to expire channels of any type for inactivity.
  573. .It Cm CheckHostIP
  574. If set to
  575. .Cm yes ,
  576. .Xr ssh 1
  577. will additionally check the host IP address in the
  578. .Pa known_hosts
  579. file.
  580. This allows it to detect if a host key changed due to DNS spoofing
  581. and will add addresses of destination hosts to
  582. .Pa ~/.ssh/known_hosts
  583. in the process, regardless of the setting of
  584. .Cm StrictHostKeyChecking .
  585. If the option is set to
  586. .Cm no
  587. (the default),
  588. the check will not be executed.
  589. .It Cm Ciphers
  590. Specifies the ciphers allowed and their order of preference.
  591. Multiple ciphers must be comma-separated.
  592. If the specified list begins with a
  593. .Sq +
  594. character, then the specified ciphers will be appended to the default set
  595. instead of replacing them.
  596. If the specified list begins with a
  597. .Sq -
  598. character, then the specified ciphers (including wildcards) will be removed
  599. from the default set instead of replacing them.
  600. If the specified list begins with a
  601. .Sq ^
  602. character, then the specified ciphers will be placed at the head of the
  603. default set.
  604. .Pp
  605. The supported ciphers are:
  606. .Bd -literal -offset indent
  607. 3des-cbc
  608. aes128-cbc
  609. aes192-cbc
  610. aes256-cbc
  611. aes128-ctr
  612. aes192-ctr
  613. aes256-ctr
  614. aes128-gcm@openssh.com
  615. aes256-gcm@openssh.com
  616. chacha20-poly1305@openssh.com
  617. .Ed
  618. .Pp
  619. The default is:
  620. .Bd -literal -offset indent
  621. chacha20-poly1305@openssh.com,
  622. aes128-gcm@openssh.com,aes256-gcm@openssh.com,
  623. aes128-ctr,aes192-ctr,aes256-ctr
  624. .Ed
  625. .Pp
  626. The list of available ciphers may also be obtained using
  627. .Qq ssh -Q cipher .
  628. .It Cm ClearAllForwardings
  629. Specifies that all local, remote, and dynamic port forwardings
  630. specified in the configuration files or on the command line be
  631. cleared.
  632. This option is primarily useful when used from the
  633. .Xr ssh 1
  634. command line to clear port forwardings set in
  635. configuration files, and is automatically set by
  636. .Xr scp 1
  637. and
  638. .Xr sftp 1 .
  639. The argument must be
  640. .Cm yes
  641. or
  642. .Cm no
  643. (the default).
  644. .It Cm Compression
  645. Specifies whether to use compression.
  646. The argument must be
  647. .Cm yes
  648. or
  649. .Cm no
  650. (the default).
  651. .It Cm ConnectionAttempts
  652. Specifies the number of tries (one per second) to make before exiting.
  653. The argument must be an integer.
  654. This may be useful in scripts if the connection sometimes fails.
  655. The default is 1.
  656. .It Cm ConnectTimeout
  657. Specifies the timeout (in seconds) used when connecting to the
  658. SSH server, instead of using the default system TCP timeout.
  659. This timeout is applied both to establishing the connection and to performing
  660. the initial SSH protocol handshake and key exchange.
  661. .It Cm ControlMaster
  662. Enables the sharing of multiple sessions over a single network connection.
  663. When set to
  664. .Cm yes ,
  665. .Xr ssh 1
  666. will listen for connections on a control socket specified using the
  667. .Cm ControlPath
  668. argument.
  669. Additional sessions can connect to this socket using the same
  670. .Cm ControlPath
  671. with
  672. .Cm ControlMaster
  673. set to
  674. .Cm no
  675. (the default).
  676. These sessions will try to reuse the master instance's network connection
  677. rather than initiating new ones, but will fall back to connecting normally
  678. if the control socket does not exist, or is not listening.
  679. .Pp
  680. Setting this to
  681. .Cm ask
  682. will cause
  683. .Xr ssh 1
  684. to listen for control connections, but require confirmation using
  685. .Xr ssh-askpass 1 .
  686. If the
  687. .Cm ControlPath
  688. cannot be opened,
  689. .Xr ssh 1
  690. will continue without connecting to a master instance.
  691. .Pp
  692. X11 and
  693. .Xr ssh-agent 1
  694. forwarding is supported over these multiplexed connections, however the
  695. display and agent forwarded will be the one belonging to the master
  696. connection i.e. it is not possible to forward multiple displays or agents.
  697. .Pp
  698. Two additional options allow for opportunistic multiplexing: try to use a
  699. master connection but fall back to creating a new one if one does not already
  700. exist.
  701. These options are:
  702. .Cm auto
  703. and
  704. .Cm autoask .
  705. The latter requires confirmation like the
  706. .Cm ask
  707. option.
  708. .It Cm ControlPath
  709. Specify the path to the control socket used for connection sharing as described
  710. in the
  711. .Cm ControlMaster
  712. section above or the string
  713. .Cm none
  714. to disable connection sharing.
  715. Arguments to
  716. .Cm ControlPath
  717. may use the tilde syntax to refer to a user's home directory,
  718. the tokens described in the
  719. .Sx TOKENS
  720. section and environment variables as described in the
  721. .Sx ENVIRONMENT VARIABLES
  722. section.
  723. It is recommended that any
  724. .Cm ControlPath
  725. used for opportunistic connection sharing include
  726. at least %h, %p, and %r (or alternatively %C) and be placed in a directory
  727. that is not writable by other users.
  728. This ensures that shared connections are uniquely identified.
  729. .It Cm ControlPersist
  730. When used in conjunction with
  731. .Cm ControlMaster ,
  732. specifies that the master connection should remain open
  733. in the background (waiting for future client connections)
  734. after the initial client connection has been closed.
  735. If set to
  736. .Cm no
  737. (the default),
  738. then the master connection will not be placed into the background,
  739. and will close as soon as the initial client connection is closed.
  740. If set to
  741. .Cm yes
  742. or 0,
  743. then the master connection will remain in the background indefinitely
  744. (until killed or closed via a mechanism such as the
  745. .Qq ssh -O exit ) .
  746. If set to a time in seconds, or a time in any of the formats documented in
  747. .Xr sshd_config 5 ,
  748. then the backgrounded master connection will automatically terminate
  749. after it has remained idle (with no client connections) for the
  750. specified time.
  751. .It Cm DynamicForward
  752. Specifies that a TCP port on the local machine be forwarded
  753. over the secure channel, and the application
  754. protocol is then used to determine where to connect to from the
  755. remote machine.
  756. .Pp
  757. The argument must be
  758. .Sm off
  759. .Oo Ar bind_address : Oc Ar port .
  760. .Sm on
  761. IPv6 addresses can be specified by enclosing addresses in square brackets.
  762. By default, the local port is bound in accordance with the
  763. .Cm GatewayPorts
  764. setting.
  765. However, an explicit
  766. .Ar bind_address
  767. may be used to bind the connection to a specific address.
  768. The
  769. .Ar bind_address
  770. of
  771. .Cm localhost
  772. indicates that the listening port be bound for local use only, while an
  773. empty address or
  774. .Sq *
  775. indicates that the port should be available from all interfaces.
  776. .Pp
  777. Currently the SOCKS4 and SOCKS5 protocols are supported, and
  778. .Xr ssh 1
  779. will act as a SOCKS server.
  780. Multiple forwardings may be specified, and
  781. additional forwardings can be given on the command line.
  782. Only the superuser can forward privileged ports.
  783. .It Cm EnableEscapeCommandline
  784. Enables the command line option in the
  785. .Cm EscapeChar
  786. menu for interactive sessions (default
  787. .Ql ~C ) .
  788. By default, the command line is disabled.
  789. .It Cm EnableSSHKeysign
  790. Setting this option to
  791. .Cm yes
  792. in the global client configuration file
  793. .Pa /etc/ssh/ssh_config
  794. enables the use of the helper program
  795. .Xr ssh-keysign 8
  796. during
  797. .Cm HostbasedAuthentication .
  798. The argument must be
  799. .Cm yes
  800. or
  801. .Cm no
  802. (the default).
  803. This option should be placed in the non-hostspecific section.
  804. See
  805. .Xr ssh-keysign 8
  806. for more information.
  807. .It Cm EscapeChar
  808. Sets the escape character (default:
  809. .Ql ~ ) .
  810. The escape character can also
  811. be set on the command line.
  812. The argument should be a single character,
  813. .Ql ^
  814. followed by a letter, or
  815. .Cm none
  816. to disable the escape
  817. character entirely (making the connection transparent for binary
  818. data).
  819. .It Cm ExitOnForwardFailure
  820. Specifies whether
  821. .Xr ssh 1
  822. should terminate the connection if it cannot set up all requested
  823. dynamic, tunnel, local, and remote port forwardings, (e.g.\&
  824. if either end is unable to bind and listen on a specified port).
  825. Note that
  826. .Cm ExitOnForwardFailure
  827. does not apply to connections made over port forwardings and will not,
  828. for example, cause
  829. .Xr ssh 1
  830. to exit if TCP connections to the ultimate forwarding destination fail.
  831. The argument must be
  832. .Cm yes
  833. or
  834. .Cm no
  835. (the default).
  836. .It Cm FingerprintHash
  837. Specifies the hash algorithm used when displaying key fingerprints.
  838. Valid options are:
  839. .Cm md5
  840. and
  841. .Cm sha256
  842. (the default).
  843. .It Cm ForkAfterAuthentication
  844. Requests
  845. .Nm ssh
  846. to go to background just before command execution.
  847. This is useful if
  848. .Nm ssh
  849. is going to ask for passwords or passphrases, but the user
  850. wants it in the background.
  851. This implies the
  852. .Cm StdinNull
  853. configuration option being set to
  854. .Dq yes .
  855. The recommended way to start X11 programs at a remote site is with
  856. something like
  857. .Ic ssh -f host xterm ,
  858. which is the same as
  859. .Ic ssh host xterm
  860. if the
  861. .Cm ForkAfterAuthentication
  862. configuration option is set to
  863. .Dq yes .
  864. .Pp
  865. If the
  866. .Cm ExitOnForwardFailure
  867. configuration option is set to
  868. .Dq yes ,
  869. then a client started with the
  870. .Cm ForkAfterAuthentication
  871. configuration option being set to
  872. .Dq yes
  873. will wait for all remote port forwards to be successfully established
  874. before placing itself in the background.
  875. The argument to this keyword must be
  876. .Cm yes
  877. (same as the
  878. .Fl f
  879. option) or
  880. .Cm no
  881. (the default).
  882. .It Cm ForwardAgent
  883. Specifies whether the connection to the authentication agent (if any)
  884. will be forwarded to the remote machine.
  885. The argument may be
  886. .Cm yes ,
  887. .Cm no
  888. (the default),
  889. an explicit path to an agent socket or the name of an environment variable
  890. (beginning with
  891. .Sq $ )
  892. in which to find the path.
  893. .Pp
  894. Agent forwarding should be enabled with caution.
  895. Users with the ability to bypass file permissions on the remote host
  896. (for the agent's Unix-domain socket)
  897. can access the local agent through the forwarded connection.
  898. An attacker cannot obtain key material from the agent,
  899. however they can perform operations on the keys that enable them to
  900. authenticate using the identities loaded into the agent.
  901. .It Cm ForwardX11
  902. Specifies whether X11 connections will be automatically redirected
  903. over the secure channel and
  904. .Ev DISPLAY
  905. set.
  906. The argument must be
  907. .Cm yes
  908. or
  909. .Cm no
  910. (the default).
  911. .Pp
  912. X11 forwarding should be enabled with caution.
  913. Users with the ability to bypass file permissions on the remote host
  914. (for the user's X11 authorization database)
  915. can access the local X11 display through the forwarded connection.
  916. An attacker may then be able to perform activities such as keystroke monitoring
  917. if the
  918. .Cm ForwardX11Trusted
  919. option is also enabled.
  920. .It Cm ForwardX11Timeout
  921. Specify a timeout for untrusted X11 forwarding
  922. using the format described in the
  923. .Sx TIME FORMATS
  924. section of
  925. .Xr sshd_config 5 .
  926. X11 connections received by
  927. .Xr ssh 1
  928. after this time will be refused.
  929. Setting
  930. .Cm ForwardX11Timeout
  931. to zero will disable the timeout and permit X11 forwarding for the life
  932. of the connection.
  933. The default is to disable untrusted X11 forwarding after twenty minutes has
  934. elapsed.
  935. .It Cm ForwardX11Trusted
  936. If this option is set to
  937. .Cm yes ,
  938. remote X11 clients will have full access to the original X11 display.
  939. .Pp
  940. If this option is set to
  941. .Cm no
  942. (the default),
  943. remote X11 clients will be considered untrusted and prevented
  944. from stealing or tampering with data belonging to trusted X11
  945. clients.
  946. Furthermore, the
  947. .Xr xauth 1
  948. token used for the session will be set to expire after 20 minutes.
  949. Remote clients will be refused access after this time.
  950. .Pp
  951. See the X11 SECURITY extension specification for full details on
  952. the restrictions imposed on untrusted clients.
  953. .It Cm GatewayPorts
  954. Specifies whether remote hosts are allowed to connect to local
  955. forwarded ports.
  956. By default,
  957. .Xr ssh 1
  958. binds local port forwardings to the loopback address.
  959. This prevents other remote hosts from connecting to forwarded ports.
  960. .Cm GatewayPorts
  961. can be used to specify that ssh
  962. should bind local port forwardings to the wildcard address,
  963. thus allowing remote hosts to connect to forwarded ports.
  964. The argument must be
  965. .Cm yes
  966. or
  967. .Cm no
  968. (the default).
  969. .It Cm GlobalKnownHostsFile
  970. Specifies one or more files to use for the global
  971. host key database, separated by whitespace.
  972. The default is
  973. .Pa /etc/ssh/ssh_known_hosts ,
  974. .Pa /etc/ssh/ssh_known_hosts2 .
  975. .It Cm GSSAPIAuthentication
  976. Specifies whether user authentication based on GSSAPI is allowed.
  977. The default is
  978. .Cm no .
  979. .It Cm GSSAPIDelegateCredentials
  980. Forward (delegate) credentials to the server.
  981. The default is
  982. .Cm no .
  983. .It Cm HashKnownHosts
  984. Indicates that
  985. .Xr ssh 1
  986. should hash host names and addresses when they are added to
  987. .Pa ~/.ssh/known_hosts .
  988. These hashed names may be used normally by
  989. .Xr ssh 1
  990. and
  991. .Xr sshd 8 ,
  992. but they do not visually reveal identifying information if the
  993. file's contents are disclosed.
  994. The default is
  995. .Cm no .
  996. Note that existing names and addresses in known hosts files
  997. will not be converted automatically,
  998. but may be manually hashed using
  999. .Xr ssh-keygen 1 .
  1000. .It Cm HostbasedAcceptedAlgorithms
  1001. Specifies the signature algorithms that will be used for hostbased
  1002. authentication as a comma-separated list of patterns.
  1003. Alternately if the specified list begins with a
  1004. .Sq +
  1005. character, then the specified signature algorithms will be appended
  1006. to the default set instead of replacing them.
  1007. If the specified list begins with a
  1008. .Sq -
  1009. character, then the specified signature algorithms (including wildcards)
  1010. will be removed from the default set instead of replacing them.
  1011. If the specified list begins with a
  1012. .Sq ^
  1013. character, then the specified signature algorithms will be placed
  1014. at the head of the default set.
  1015. The default for this option is:
  1016. .Bd -literal -offset 3n
  1017. ssh-ed25519-cert-v01@openssh.com,
  1018. ecdsa-sha2-nistp256-cert-v01@openssh.com,
  1019. ecdsa-sha2-nistp384-cert-v01@openssh.com,
  1020. ecdsa-sha2-nistp521-cert-v01@openssh.com,
  1021. sk-ssh-ed25519-cert-v01@openssh.com,
  1022. sk-ecdsa-sha2-nistp256-cert-v01@openssh.com,
  1023. rsa-sha2-512-cert-v01@openssh.com,
  1024. rsa-sha2-256-cert-v01@openssh.com,
  1025. ssh-ed25519,
  1026. ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
  1027. sk-ssh-ed25519@openssh.com,
  1028. sk-ecdsa-sha2-nistp256@openssh.com,
  1029. rsa-sha2-512,rsa-sha2-256
  1030. .Ed
  1031. .Pp
  1032. The
  1033. .Fl Q
  1034. option of
  1035. .Xr ssh 1
  1036. may be used to list supported signature algorithms.
  1037. This was formerly named HostbasedKeyTypes.
  1038. .It Cm HostbasedAuthentication
  1039. Specifies whether to try rhosts based authentication with public key
  1040. authentication.
  1041. The argument must be
  1042. .Cm yes
  1043. or
  1044. .Cm no
  1045. (the default).
  1046. .It Cm HostKeyAlgorithms
  1047. Specifies the host key signature algorithms
  1048. that the client wants to use in order of preference.
  1049. Alternately if the specified list begins with a
  1050. .Sq +
  1051. character, then the specified signature algorithms will be appended to
  1052. the default set instead of replacing them.
  1053. If the specified list begins with a
  1054. .Sq -
  1055. character, then the specified signature algorithms (including wildcards)
  1056. will be removed from the default set instead of replacing them.
  1057. If the specified list begins with a
  1058. .Sq ^
  1059. character, then the specified signature algorithms will be placed
  1060. at the head of the default set.
  1061. The default for this option is:
  1062. .Bd -literal -offset 3n
  1063. ssh-ed25519-cert-v01@openssh.com,
  1064. ecdsa-sha2-nistp256-cert-v01@openssh.com,
  1065. ecdsa-sha2-nistp384-cert-v01@openssh.com,
  1066. ecdsa-sha2-nistp521-cert-v01@openssh.com,
  1067. sk-ssh-ed25519-cert-v01@openssh.com,
  1068. sk-ecdsa-sha2-nistp256-cert-v01@openssh.com,
  1069. rsa-sha2-512-cert-v01@openssh.com,
  1070. rsa-sha2-256-cert-v01@openssh.com,
  1071. ssh-ed25519,
  1072. ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
  1073. sk-ecdsa-sha2-nistp256@openssh.com,
  1074. sk-ssh-ed25519@openssh.com,
  1075. rsa-sha2-512,rsa-sha2-256
  1076. .Ed
  1077. .Pp
  1078. If hostkeys are known for the destination host then this default is modified
  1079. to prefer their algorithms.
  1080. .Pp
  1081. The list of available signature algorithms may also be obtained using
  1082. .Qq ssh -Q HostKeyAlgorithms .
  1083. .It Cm HostKeyAlias
  1084. Specifies an alias that should be used instead of the
  1085. real host name when looking up or saving the host key
  1086. in the host key database files and when validating host certificates.
  1087. This option is useful for tunneling SSH connections
  1088. or for multiple servers running on a single host.
  1089. .It Cm Hostname
  1090. Specifies the real host name to log into.
  1091. This can be used to specify nicknames or abbreviations for hosts.
  1092. Arguments to
  1093. .Cm Hostname
  1094. accept the tokens described in the
  1095. .Sx TOKENS
  1096. section.
  1097. Numeric IP addresses are also permitted (both on the command line and in
  1098. .Cm Hostname
  1099. specifications).
  1100. The default is the name given on the command line.
  1101. .It Cm IdentitiesOnly
  1102. Specifies that
  1103. .Xr ssh 1
  1104. should only use the configured authentication identity and certificate files
  1105. (either the default files, or those explicitly configured in the
  1106. .Nm
  1107. files
  1108. or passed on the
  1109. .Xr ssh 1
  1110. command-line),
  1111. even if
  1112. .Xr ssh-agent 1
  1113. or a
  1114. .Cm PKCS11Provider
  1115. or
  1116. .Cm SecurityKeyProvider
  1117. offers more identities.
  1118. The argument to this keyword must be
  1119. .Cm yes
  1120. or
  1121. .Cm no
  1122. (the default).
  1123. This option is intended for situations where ssh-agent
  1124. offers many different identities.
  1125. .It Cm IdentityAgent
  1126. Specifies the
  1127. .Ux Ns -domain
  1128. socket used to communicate with the authentication agent.
  1129. .Pp
  1130. This option overrides the
  1131. .Ev SSH_AUTH_SOCK
  1132. environment variable and can be used to select a specific agent.
  1133. Setting the socket name to
  1134. .Cm none
  1135. disables the use of an authentication agent.
  1136. If the string
  1137. .Qq SSH_AUTH_SOCK
  1138. is specified, the location of the socket will be read from the
  1139. .Ev SSH_AUTH_SOCK
  1140. environment variable.
  1141. Otherwise if the specified value begins with a
  1142. .Sq $
  1143. character, then it will be treated as an environment variable containing
  1144. the location of the socket.
  1145. .Pp
  1146. Arguments to
  1147. .Cm IdentityAgent
  1148. may use the tilde syntax to refer to a user's home directory,
  1149. the tokens described in the
  1150. .Sx TOKENS
  1151. section and environment variables as described in the
  1152. .Sx ENVIRONMENT VARIABLES
  1153. section.
  1154. .It Cm IdentityFile
  1155. Specifies a file from which the user's ECDSA, authenticator-hosted ECDSA,
  1156. Ed25519, authenticator-hosted Ed25519 or RSA authentication identity is read.
  1157. You can also specify a public key file to use the corresponding
  1158. private key that is loaded in
  1159. .Xr ssh-agent 1
  1160. when the private key file is not present locally.
  1161. The default is
  1162. .Pa ~/.ssh/id_rsa ,
  1163. .Pa ~/.ssh/id_ecdsa ,
  1164. .Pa ~/.ssh/id_ecdsa_sk ,
  1165. .Pa ~/.ssh/id_ed25519
  1166. and
  1167. .Pa ~/.ssh/id_ed25519_sk .
  1168. Additionally, any identities represented by the authentication agent
  1169. will be used for authentication unless
  1170. .Cm IdentitiesOnly
  1171. is set.
  1172. If no certificates have been explicitly specified by
  1173. .Cm CertificateFile ,
  1174. .Xr ssh 1
  1175. will try to load certificate information from the filename obtained by
  1176. appending
  1177. .Pa -cert.pub
  1178. to the path of a specified
  1179. .Cm IdentityFile .
  1180. .Pp
  1181. Arguments to
  1182. .Cm IdentityFile
  1183. may use the tilde syntax to refer to a user's home directory
  1184. or the tokens described in the
  1185. .Sx TOKENS
  1186. section.
  1187. Alternately an argument of
  1188. .Cm none
  1189. may be used to indicate no identity files should be loaded.
  1190. .Pp
  1191. It is possible to have
  1192. multiple identity files specified in configuration files; all these
  1193. identities will be tried in sequence.
  1194. Multiple
  1195. .Cm IdentityFile
  1196. directives will add to the list of identities tried (this behaviour
  1197. differs from that of other configuration directives).
  1198. .Pp
  1199. .Cm IdentityFile
  1200. may be used in conjunction with
  1201. .Cm IdentitiesOnly
  1202. to select which identities in an agent are offered during authentication.
  1203. .Cm IdentityFile
  1204. may also be used in conjunction with
  1205. .Cm CertificateFile
  1206. in order to provide any certificate also needed for authentication with
  1207. the identity.
  1208. .It Cm IgnoreUnknown
  1209. Specifies a pattern-list of unknown options to be ignored if they are
  1210. encountered in configuration parsing.
  1211. This may be used to suppress errors if
  1212. .Nm
  1213. contains options that are unrecognised by
  1214. .Xr ssh 1 .
  1215. It is recommended that
  1216. .Cm IgnoreUnknown
  1217. be listed early in the configuration file as it will not be applied
  1218. to unknown options that appear before it.
  1219. .It Cm Include
  1220. Include the specified configuration file(s).
  1221. Multiple pathnames may be specified and each pathname may contain
  1222. .Xr glob 7
  1223. wildcards,
  1224. tokens as described in the
  1225. .Sx TOKENS
  1226. section, environment variables as described in the
  1227. .Sx ENVIRONMENT VARIABLES
  1228. section and, for user configurations, shell-like
  1229. .Sq ~
  1230. references to user home directories.
  1231. Wildcards will be expanded and processed in lexical order.
  1232. Files without absolute paths are assumed to be in
  1233. .Pa ~/.ssh
  1234. if included in a user configuration file or
  1235. .Pa /etc/ssh
  1236. if included from the system configuration file.
  1237. .Cm Include
  1238. directive may appear inside a
  1239. .Cm Match
  1240. or
  1241. .Cm Host
  1242. block
  1243. to perform conditional inclusion.
  1244. .It Cm IPQoS
  1245. Specifies the IPv4 type-of-service or DSCP class for connections.
  1246. Accepted values are
  1247. .Cm af11 ,
  1248. .Cm af12 ,
  1249. .Cm af13 ,
  1250. .Cm af21 ,
  1251. .Cm af22 ,
  1252. .Cm af23 ,
  1253. .Cm af31 ,
  1254. .Cm af32 ,
  1255. .Cm af33 ,
  1256. .Cm af41 ,
  1257. .Cm af42 ,
  1258. .Cm af43 ,
  1259. .Cm cs0 ,
  1260. .Cm cs1 ,
  1261. .Cm cs2 ,
  1262. .Cm cs3 ,
  1263. .Cm cs4 ,
  1264. .Cm cs5 ,
  1265. .Cm cs6 ,
  1266. .Cm cs7 ,
  1267. .Cm ef ,
  1268. .Cm le ,
  1269. .Cm lowdelay ,
  1270. .Cm throughput ,
  1271. .Cm reliability ,
  1272. a numeric value, or
  1273. .Cm none
  1274. to use the operating system default.
  1275. This option may take one or two arguments, separated by whitespace.
  1276. If one argument is specified, it is used as the packet class unconditionally.
  1277. If two values are specified, the first is automatically selected for
  1278. interactive sessions and the second for non-interactive sessions.
  1279. The default is
  1280. .Cm af21
  1281. (Low-Latency Data)
  1282. for interactive sessions and
  1283. .Cm cs1
  1284. (Lower Effort)
  1285. for non-interactive sessions.
  1286. .It Cm KbdInteractiveAuthentication
  1287. Specifies whether to use keyboard-interactive authentication.
  1288. The argument to this keyword must be
  1289. .Cm yes
  1290. (the default)
  1291. or
  1292. .Cm no .
  1293. .Cm ChallengeResponseAuthentication
  1294. is a deprecated alias for this.
  1295. .It Cm KbdInteractiveDevices
  1296. Specifies the list of methods to use in keyboard-interactive authentication.
  1297. Multiple method names must be comma-separated.
  1298. The default is to use the server specified list.
  1299. The methods available vary depending on what the server supports.
  1300. For an OpenSSH server,
  1301. it may be zero or more of:
  1302. .Cm bsdauth
  1303. and
  1304. .Cm pam .
  1305. .It Cm KexAlgorithms
  1306. Specifies the permitted KEX (Key Exchange) algorithms that will be used and
  1307. their preference order.
  1308. The selected algorithm will be the first algorithm in this list that
  1309. the server also supports.
  1310. Multiple algorithms must be comma-separated.
  1311. .Pp
  1312. If the specified list begins with a
  1313. .Sq +
  1314. character, then the specified algorithms will be appended to the default set
  1315. instead of replacing them.
  1316. If the specified list begins with a
  1317. .Sq -
  1318. character, then the specified algorithms (including wildcards) will be removed
  1319. from the default set instead of replacing them.
  1320. If the specified list begins with a
  1321. .Sq ^
  1322. character, then the specified algorithms will be placed at the head of the
  1323. default set.
  1324. .Pp
  1325. The default is:
  1326. .Bd -literal -offset indent
  1327. mlkem768x25519-sha256,
  1328. sntrup761x25519-sha512,sntrup761x25519-sha512@openssh.com,
  1329. curve25519-sha256,curve25519-sha256@libssh.org,
  1330. ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,
  1331. diffie-hellman-group-exchange-sha256,
  1332. diffie-hellman-group16-sha512,
  1333. diffie-hellman-group18-sha512,
  1334. diffie-hellman-group14-sha256
  1335. .Ed
  1336. .Pp
  1337. The list of supported key exchange algorithms may also be obtained using
  1338. .Qq ssh -Q kex .
  1339. .It Cm KnownHostsCommand
  1340. Specifies a command to use to obtain a list of host keys, in addition to
  1341. those listed in
  1342. .Cm UserKnownHostsFile
  1343. and
  1344. .Cm GlobalKnownHostsFile .
  1345. This command is executed after the files have been read.
  1346. It may write host key lines to standard output in identical format to the
  1347. usual files (described in the
  1348. .Sx VERIFYING HOST KEYS
  1349. section in
  1350. .Xr ssh 1 ) .
  1351. Arguments to
  1352. .Cm KnownHostsCommand
  1353. accept the tokens described in the
  1354. .Sx TOKENS
  1355. section.
  1356. The command may be invoked multiple times per connection: once when preparing
  1357. the preference list of host key algorithms to use, again to obtain the
  1358. host key for the requested host name and, if
  1359. .Cm CheckHostIP
  1360. is enabled, one more time to obtain the host key matching the server's
  1361. address.
  1362. If the command exits abnormally or returns a non-zero exit status then the
  1363. connection is terminated.
  1364. .It Cm LocalCommand
  1365. Specifies a command to execute on the local machine after successfully
  1366. connecting to the server.
  1367. The command string extends to the end of the line, and is executed with
  1368. the user's shell.
  1369. Arguments to
  1370. .Cm LocalCommand
  1371. accept the tokens described in the
  1372. .Sx TOKENS
  1373. section.
  1374. .Pp
  1375. The command is run synchronously and does not have access to the
  1376. session of the
  1377. .Xr ssh 1
  1378. that spawned it.
  1379. It should not be used for interactive commands.
  1380. .Pp
  1381. This directive is ignored unless
  1382. .Cm PermitLocalCommand
  1383. has been enabled.
  1384. .It Cm LocalForward
  1385. Specifies that a TCP port or Unix-domain socket on the local machine
  1386. be forwarded over
  1387. the secure channel to the specified host and port (or Unix-domain socket)
  1388. from the remote machine.
  1389. For a TCP port, the first argument must be
  1390. .Sm off
  1391. .Oo Ar bind_address : Oc Ar port
  1392. .Sm on
  1393. or a Unix domain socket path.
  1394. The second argument is the destination and may be
  1395. .Ar host : Ns Ar hostport
  1396. or a Unix domain socket path if the remote host supports it.
  1397. .Pp
  1398. IPv6 addresses can be specified by enclosing addresses in square brackets.
  1399. .Pp
  1400. If either argument contains a '/' in it, that argument will be
  1401. interpreted as a Unix-domain socket (on the corresponding host) rather
  1402. than a TCP port.
  1403. .Pp
  1404. Multiple forwardings may be specified, and additional forwardings can be
  1405. given on the command line.
  1406. Only the superuser can forward privileged ports.
  1407. By default, the local port is bound in accordance with the
  1408. .Cm GatewayPorts
  1409. setting.
  1410. However, an explicit
  1411. .Ar bind_address
  1412. may be used to bind the connection to a specific address.
  1413. The
  1414. .Ar bind_address
  1415. of
  1416. .Cm localhost
  1417. indicates that the listening port be bound for local use only, while an
  1418. empty address or
  1419. .Sq *
  1420. indicates that the port should be available from all interfaces.
  1421. Unix domain socket paths may use the tokens described in the
  1422. .Sx TOKENS
  1423. section and environment variables as described in the
  1424. .Sx ENVIRONMENT VARIABLES
  1425. section.
  1426. .It Cm LogLevel
  1427. Gives the verbosity level that is used when logging messages from
  1428. .Xr ssh 1 .
  1429. The possible values are:
  1430. QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3.
  1431. The default is INFO.
  1432. DEBUG and DEBUG1 are equivalent.
  1433. DEBUG2 and DEBUG3 each specify higher levels of verbose output.
  1434. .It Cm LogVerbose
  1435. Specify one or more overrides to LogLevel.
  1436. An override consists of one or more pattern lists that matches the
  1437. source file, function and line number to force detailed logging for.
  1438. For example, an override pattern of:
  1439. .Bd -literal -offset indent
  1440. kex.c:*:1000,*:kex_exchange_identification():*,packet.c:*
  1441. .Ed
  1442. .Pp
  1443. would enable detailed logging for line 1000 of
  1444. .Pa kex.c ,
  1445. everything in the
  1446. .Fn kex_exchange_identification
  1447. function, and all code in the
  1448. .Pa packet.c
  1449. file.
  1450. This option is intended for debugging and no overrides are enabled by default.
  1451. .It Cm MACs
  1452. Specifies the MAC (message authentication code) algorithms
  1453. in order of preference.
  1454. The MAC algorithm is used for data integrity protection.
  1455. Multiple algorithms must be comma-separated.
  1456. If the specified list begins with a
  1457. .Sq +
  1458. character, then the specified algorithms will be appended to the default set
  1459. instead of replacing them.
  1460. If the specified list begins with a
  1461. .Sq -
  1462. character, then the specified algorithms (including wildcards) will be removed
  1463. from the default set instead of replacing them.
  1464. If the specified list begins with a
  1465. .Sq ^
  1466. character, then the specified algorithms will be placed at the head of the
  1467. default set.
  1468. .Pp
  1469. The algorithms that contain
  1470. .Qq -etm
  1471. calculate the MAC after encryption (encrypt-then-mac).
  1472. These are considered safer and their use recommended.
  1473. .Pp
  1474. The default is:
  1475. .Bd -literal -offset indent
  1476. umac-64-etm@openssh.com,umac-128-etm@openssh.com,
  1477. hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,
  1478. hmac-sha1-etm@openssh.com,
  1479. umac-64@openssh.com,umac-128@openssh.com,
  1480. hmac-sha2-256,hmac-sha2-512,hmac-sha1
  1481. .Ed
  1482. .Pp
  1483. The list of available MAC algorithms may also be obtained using
  1484. .Qq ssh -Q mac .
  1485. .It Cm NoHostAuthenticationForLocalhost
  1486. Disable host authentication for localhost (loopback addresses).
  1487. The argument to this keyword must be
  1488. .Cm yes
  1489. or
  1490. .Cm no
  1491. (the default).
  1492. .It Cm NumberOfPasswordPrompts
  1493. Specifies the number of password prompts before giving up.
  1494. The argument to this keyword must be an integer.
  1495. The default is 3.
  1496. .It Cm ObscureKeystrokeTiming
  1497. Specifies whether
  1498. .Xr ssh 1
  1499. should try to obscure inter-keystroke timings from passive observers of
  1500. network traffic.
  1501. If enabled, then for interactive sessions,
  1502. .Xr ssh 1
  1503. will send keystrokes at fixed intervals of a few tens of milliseconds
  1504. and will send fake keystroke packets for some time after typing ceases.
  1505. The argument to this keyword must be
  1506. .Cm yes ,
  1507. .Cm no
  1508. or an interval specifier of the form
  1509. .Cm interval:milliseconds
  1510. (e.g.\&
  1511. .Cm interval:80
  1512. for 80 milliseconds).
  1513. The default is to obscure keystrokes using a 20ms packet interval.
  1514. Note that smaller intervals will result in higher fake keystroke packet rates.
  1515. .It Cm PasswordAuthentication
  1516. Specifies whether to use password authentication.
  1517. The argument to this keyword must be
  1518. .Cm yes
  1519. (the default)
  1520. or
  1521. .Cm no .
  1522. .It Cm PermitLocalCommand
  1523. Allow local command execution via the
  1524. .Ic LocalCommand
  1525. option or using the
  1526. .Ic !\& Ns Ar command
  1527. escape sequence in
  1528. .Xr ssh 1 .
  1529. The argument must be
  1530. .Cm yes
  1531. or
  1532. .Cm no
  1533. (the default).
  1534. .It Cm PermitRemoteOpen
  1535. Specifies the destinations to which remote TCP port forwarding is permitted when
  1536. .Cm RemoteForward
  1537. is used as a SOCKS proxy.
  1538. The forwarding specification must be one of the following forms:
  1539. .Pp
  1540. .Bl -item -offset indent -compact
  1541. .It
  1542. .Cm PermitRemoteOpen
  1543. .Sm off
  1544. .Ar host : port
  1545. .Sm on
  1546. .It
  1547. .Cm PermitRemoteOpen
  1548. .Sm off
  1549. .Ar IPv4_addr : port
  1550. .Sm on
  1551. .It
  1552. .Cm PermitRemoteOpen
  1553. .Sm off
  1554. .Ar \&[ IPv6_addr \&] : port
  1555. .Sm on
  1556. .El
  1557. .Pp
  1558. Multiple forwards may be specified by separating them with whitespace.
  1559. An argument of
  1560. .Cm any
  1561. can be used to remove all restrictions and permit any forwarding requests.
  1562. An argument of
  1563. .Cm none
  1564. can be used to prohibit all forwarding requests.
  1565. The wildcard
  1566. .Sq *
  1567. can be used for host or port to allow all hosts or ports respectively.
  1568. Otherwise, no pattern matching or address lookups are performed on supplied
  1569. names.
  1570. .It Cm PKCS11Provider
  1571. Specifies which PKCS#11 provider to use or
  1572. .Cm none
  1573. to indicate that no provider should be used (the default).
  1574. The argument to this keyword is a path to the PKCS#11 shared library
  1575. .Xr ssh 1
  1576. should use to communicate with a PKCS#11 token providing keys for user
  1577. authentication.
  1578. .It Cm Port
  1579. Specifies the port number to connect on the remote host.
  1580. The default is 22.
  1581. .It Cm PreferredAuthentications
  1582. Specifies the order in which the client should try authentication methods.
  1583. This allows a client to prefer one method (e.g.\&
  1584. .Cm keyboard-interactive )
  1585. over another method (e.g.\&
  1586. .Cm password ) .
  1587. The default is:
  1588. .Bd -literal -offset indent
  1589. gssapi-with-mic,hostbased,publickey,
  1590. keyboard-interactive,password
  1591. .Ed
  1592. .It Cm ProxyCommand
  1593. Specifies the command to use to connect to the server.
  1594. The command
  1595. string extends to the end of the line, and is executed
  1596. using the user's shell
  1597. .Ql exec
  1598. directive to avoid a lingering shell process.
  1599. .Pp
  1600. Arguments to
  1601. .Cm ProxyCommand
  1602. accept the tokens described in the
  1603. .Sx TOKENS
  1604. section.
  1605. The command can be basically anything,
  1606. and should read from its standard input and write to its standard output.
  1607. It should eventually connect an
  1608. .Xr sshd 8
  1609. server running on some machine, or execute
  1610. .Ic sshd -i
  1611. somewhere.
  1612. Host key management will be done using the
  1613. .Cm Hostname
  1614. of the host being connected (defaulting to the name typed by the user).
  1615. Setting the command to
  1616. .Cm none
  1617. disables this option entirely.
  1618. Note that
  1619. .Cm CheckHostIP
  1620. is not available for connects with a proxy command.
  1621. .Pp
  1622. This directive is useful in conjunction with
  1623. .Xr nc 1
  1624. and its proxy support.
  1625. For example, the following directive would connect via an HTTP proxy at
  1626. 192.0.2.0:
  1627. .Bd -literal -offset 3n
  1628. ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
  1629. .Ed
  1630. .It Cm ProxyJump
  1631. Specifies one or more jump proxies as either
  1632. .Sm off
  1633. .Op Ar user No @
  1634. .Ar host
  1635. .Op : Ns Ar port
  1636. .Sm on
  1637. or an ssh URI.
  1638. Multiple proxies may be separated by comma characters and will be visited
  1639. sequentially.
  1640. Setting this option will cause
  1641. .Xr ssh 1
  1642. to connect to the target host by first making a
  1643. .Xr ssh 1
  1644. connection to the specified
  1645. .Cm ProxyJump
  1646. host and then establishing a
  1647. TCP forwarding to the ultimate target from there.
  1648. Setting the host to
  1649. .Cm none
  1650. disables this option entirely.
  1651. .Pp
  1652. Note that this option will compete with the
  1653. .Cm ProxyCommand
  1654. option - whichever is specified first will prevent later instances of the
  1655. other from taking effect.
  1656. .Pp
  1657. Note also that the configuration for the destination host (either supplied
  1658. via the command-line or the configuration file) is not generally applied
  1659. to jump hosts.
  1660. .Pa ~/.ssh/config
  1661. should be used if specific configuration is required for jump hosts.
  1662. .It Cm ProxyUseFdpass
  1663. Specifies that
  1664. .Cm ProxyCommand
  1665. will pass a connected file descriptor back to
  1666. .Xr ssh 1
  1667. instead of continuing to execute and pass data.
  1668. The default is
  1669. .Cm no .
  1670. .It Cm PubkeyAcceptedAlgorithms
  1671. Specifies the signature algorithms that will be used for public key
  1672. authentication as a comma-separated list of patterns.
  1673. If the specified list begins with a
  1674. .Sq +
  1675. character, then the algorithms after it will be appended to the default
  1676. instead of replacing it.
  1677. If the specified list begins with a
  1678. .Sq -
  1679. character, then the specified algorithms (including wildcards) will be removed
  1680. from the default set instead of replacing them.
  1681. If the specified list begins with a
  1682. .Sq ^
  1683. character, then the specified algorithms will be placed at the head of the
  1684. default set.
  1685. The default for this option is:
  1686. .Bd -literal -offset 3n
  1687. ssh-ed25519-cert-v01@openssh.com,
  1688. ecdsa-sha2-nistp256-cert-v01@openssh.com,
  1689. ecdsa-sha2-nistp384-cert-v01@openssh.com,
  1690. ecdsa-sha2-nistp521-cert-v01@openssh.com,
  1691. sk-ssh-ed25519-cert-v01@openssh.com,
  1692. sk-ecdsa-sha2-nistp256-cert-v01@openssh.com,
  1693. rsa-sha2-512-cert-v01@openssh.com,
  1694. rsa-sha2-256-cert-v01@openssh.com,
  1695. ssh-ed25519,
  1696. ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
  1697. sk-ssh-ed25519@openssh.com,
  1698. sk-ecdsa-sha2-nistp256@openssh.com,
  1699. rsa-sha2-512,rsa-sha2-256
  1700. .Ed
  1701. .Pp
  1702. The list of available signature algorithms may also be obtained using
  1703. .Qq ssh -Q PubkeyAcceptedAlgorithms .
  1704. .It Cm PubkeyAuthentication
  1705. Specifies whether to try public key authentication.
  1706. The argument to this keyword must be
  1707. .Cm yes
  1708. (the default),
  1709. .Cm no ,
  1710. .Cm unbound
  1711. or
  1712. .Cm host-bound .
  1713. The final two options enable public key authentication while respectively
  1714. disabling or enabling the OpenSSH host-bound authentication protocol
  1715. extension required for restricted
  1716. .Xr ssh-agent 1
  1717. forwarding.
  1718. .It Cm RekeyLimit
  1719. Specifies the maximum amount of data that may be transmitted or received
  1720. before the session key is renegotiated, optionally followed by a maximum
  1721. amount of time that may pass before the session key is renegotiated.
  1722. The first argument is specified in bytes and may have a suffix of
  1723. .Sq K ,
  1724. .Sq M ,
  1725. or
  1726. .Sq G
  1727. to indicate Kilobytes, Megabytes, or Gigabytes, respectively.
  1728. The default is between
  1729. .Sq 1G
  1730. and
  1731. .Sq 4G ,
  1732. depending on the cipher.
  1733. The optional second value is specified in seconds and may use any of the
  1734. units documented in the TIME FORMATS section of
  1735. .Xr sshd_config 5 .
  1736. The default value for
  1737. .Cm RekeyLimit
  1738. is
  1739. .Cm default none ,
  1740. which means that rekeying is performed after the cipher's default amount
  1741. of data has been sent or received and no time based rekeying is done.
  1742. .It Cm RemoteCommand
  1743. Specifies a command to execute on the remote machine after successfully
  1744. connecting to the server.
  1745. The command string extends to the end of the line, and is executed with
  1746. the user's shell.
  1747. Arguments to
  1748. .Cm RemoteCommand
  1749. accept the tokens described in the
  1750. .Sx TOKENS
  1751. section.
  1752. .It Cm RemoteForward
  1753. Specifies that a TCP port or Unix-domain socket on the remote machine
  1754. be forwarded over the secure channel.
  1755. The remote port may either be forwarded to a specified host and port
  1756. or Unix-domain socket
  1757. from the local machine, or may act as a SOCKS 4/5 proxy that allows a remote
  1758. client to connect to arbitrary destinations from the local machine.
  1759. The first argument is the listening specification and may be
  1760. .Sm off
  1761. .Oo Ar bind_address : Oc Ar port
  1762. .Sm on
  1763. or, if the remote host supports it, a Unix domain socket path.
  1764. If forwarding to a specific destination then the second argument must be
  1765. .Ar host : Ns Ar hostport
  1766. or a Unix domain socket path,
  1767. otherwise if no destination argument is specified then the remote forwarding
  1768. will be established as a SOCKS proxy.
  1769. When acting as a SOCKS proxy, the destination of the connection can be
  1770. restricted by
  1771. .Cm PermitRemoteOpen .
  1772. .Pp
  1773. IPv6 addresses can be specified by enclosing addresses in square brackets.
  1774. .Pp
  1775. If either argument contains a '/' in it, that argument will be
  1776. interpreted as a Unix-domain socket (on the corresponding host) rather
  1777. than a TCP port.
  1778. .Pp
  1779. Multiple forwardings may be specified, and additional
  1780. forwardings can be given on the command line.
  1781. Privileged ports can be forwarded only when
  1782. logging in as root on the remote machine.
  1783. Unix domain socket paths may use the tokens described in the
  1784. .Sx TOKENS
  1785. section and environment variables as described in the
  1786. .Sx ENVIRONMENT VARIABLES
  1787. section.
  1788. .Pp
  1789. If the
  1790. .Ar port
  1791. argument is 0,
  1792. the listen port will be dynamically allocated on the server and reported
  1793. to the client at run time.
  1794. .Pp
  1795. If the
  1796. .Ar bind_address
  1797. is not specified, the default is to only bind to loopback addresses.
  1798. If the
  1799. .Ar bind_address
  1800. is
  1801. .Ql *
  1802. or an empty string, then the forwarding is requested to listen on all
  1803. interfaces.
  1804. Specifying a remote
  1805. .Ar bind_address
  1806. will only succeed if the server's
  1807. .Cm GatewayPorts
  1808. option is enabled (see
  1809. .Xr sshd_config 5 ) .
  1810. .It Cm RequestTTY
  1811. Specifies whether to request a pseudo-tty for the session.
  1812. The argument may be one of:
  1813. .Cm no
  1814. (never request a TTY),
  1815. .Cm yes
  1816. (always request a TTY when standard input is a TTY),
  1817. .Cm force
  1818. (always request a TTY) or
  1819. .Cm auto
  1820. (request a TTY when opening a login session).
  1821. This option mirrors the
  1822. .Fl t
  1823. and
  1824. .Fl T
  1825. flags for
  1826. .Xr ssh 1 .
  1827. .It Cm RequiredRSASize
  1828. Specifies the minimum RSA key size (in bits) that
  1829. .Xr ssh 1
  1830. will accept.
  1831. User authentication keys smaller than this limit will be ignored.
  1832. Servers that present host keys smaller than this limit will cause the
  1833. connection to be terminated.
  1834. The default is
  1835. .Cm 1024
  1836. bits.
  1837. Note that this limit may only be raised from the default.
  1838. .It Cm RevokedHostKeys
  1839. Specifies revoked host public keys.
  1840. Keys listed in this file will be refused for host authentication.
  1841. Note that if this file does not exist or is not readable,
  1842. then host authentication will be refused for all hosts.
  1843. Keys may be specified as a text file, listing one public key per line, or as
  1844. an OpenSSH Key Revocation List (KRL) as generated by
  1845. .Xr ssh-keygen 1 .
  1846. For more information on KRLs, see the KEY REVOCATION LISTS section in
  1847. .Xr ssh-keygen 1 .
  1848. Arguments to
  1849. .Cm RevokedHostKeys
  1850. may use the tilde syntax to refer to a user's home directory,
  1851. the tokens described in the
  1852. .Sx TOKENS
  1853. section and environment variables as described in the
  1854. .Sx ENVIRONMENT VARIABLES
  1855. section.
  1856. .It Cm SecurityKeyProvider
  1857. Specifies a path to a library that will be used when loading any
  1858. FIDO authenticator-hosted keys, overriding the default of using
  1859. the built-in USB HID support.
  1860. .Pp
  1861. If the specified value begins with a
  1862. .Sq $
  1863. character, then it will be treated as an environment variable containing
  1864. the path to the library.
  1865. .It Cm SendEnv
  1866. Specifies what variables from the local
  1867. .Xr environ 7
  1868. should be sent to the server.
  1869. The server must also support it, and the server must be configured to
  1870. accept these environment variables.
  1871. Note that the
  1872. .Ev TERM
  1873. environment variable is always sent whenever a
  1874. pseudo-terminal is requested as it is required by the protocol.
  1875. Refer to
  1876. .Cm AcceptEnv
  1877. in
  1878. .Xr sshd_config 5
  1879. for how to configure the server.
  1880. Variables are specified by name, which may contain wildcard characters.
  1881. Multiple environment variables may be separated by whitespace or spread
  1882. across multiple
  1883. .Cm SendEnv
  1884. directives.
  1885. .Pp
  1886. See
  1887. .Sx PATTERNS
  1888. for more information on patterns.
  1889. .Pp
  1890. It is possible to clear previously set
  1891. .Cm SendEnv
  1892. variable names by prefixing patterns with
  1893. .Pa - .
  1894. The default is not to send any environment variables.
  1895. .It Cm ServerAliveCountMax
  1896. Sets the number of server alive messages (see below) which may be
  1897. sent without
  1898. .Xr ssh 1
  1899. receiving any messages back from the server.
  1900. If this threshold is reached while server alive messages are being sent,
  1901. ssh will disconnect from the server, terminating the session.
  1902. It is important to note that the use of server alive messages is very
  1903. different from
  1904. .Cm TCPKeepAlive
  1905. (below).
  1906. The server alive messages are sent through the encrypted channel
  1907. and therefore will not be spoofable.
  1908. The TCP keepalive option enabled by
  1909. .Cm TCPKeepAlive
  1910. is spoofable.
  1911. The server alive mechanism is valuable when the client or
  1912. server depend on knowing when a connection has become unresponsive.
  1913. .Pp
  1914. The default value is 3.
  1915. If, for example,
  1916. .Cm ServerAliveInterval
  1917. (see below) is set to 15 and
  1918. .Cm ServerAliveCountMax
  1919. is left at the default, if the server becomes unresponsive,
  1920. ssh will disconnect after approximately 45 seconds.
  1921. .It Cm ServerAliveInterval
  1922. Sets a timeout interval in seconds after which if no data has been received
  1923. from the server,
  1924. .Xr ssh 1
  1925. will send a message through the encrypted
  1926. channel to request a response from the server.
  1927. The default
  1928. is 0, indicating that these messages will not be sent to the server.
  1929. .It Cm SessionType
  1930. May be used to either request invocation of a subsystem on the remote system,
  1931. or to prevent the execution of a remote command at all.
  1932. The latter is useful for just forwarding ports.
  1933. The argument to this keyword must be
  1934. .Cm none
  1935. (same as the
  1936. .Fl N
  1937. option),
  1938. .Cm subsystem
  1939. (same as the
  1940. .Fl s
  1941. option) or
  1942. .Cm default
  1943. (shell or command execution).
  1944. .It Cm SetEnv
  1945. Directly specify one or more environment variables and their contents to
  1946. be sent to the server in the form
  1947. .Dq NAME=VALUE .
  1948. Similarly to
  1949. .Cm SendEnv ,
  1950. with the exception of the
  1951. .Ev TERM
  1952. variable, the server must be prepared to accept the environment variable.
  1953. .Pp
  1954. The
  1955. .Dq VALUE
  1956. may use the tokens described in the
  1957. .Sx TOKENS
  1958. section and environment variables as described in the
  1959. .Sx ENVIRONMENT VARIABLES
  1960. section.
  1961. .It Cm StdinNull
  1962. Redirects stdin from
  1963. .Pa /dev/null
  1964. (actually, prevents reading from stdin).
  1965. Either this or the equivalent
  1966. .Fl n
  1967. option must be used when
  1968. .Nm ssh
  1969. is run in the background.
  1970. The argument to this keyword must be
  1971. .Cm yes
  1972. (same as the
  1973. .Fl n
  1974. option) or
  1975. .Cm no
  1976. (the default).
  1977. .It Cm StreamLocalBindMask
  1978. Sets the octal file creation mode mask
  1979. .Pq umask
  1980. used when creating a Unix-domain socket file for local or remote
  1981. port forwarding.
  1982. This option is only used for port forwarding to a Unix-domain socket file.
  1983. .Pp
  1984. The default value is 0177, which creates a Unix-domain socket file that is
  1985. readable and writable only by the owner.
  1986. Note that not all operating systems honor the file mode on Unix-domain
  1987. socket files.
  1988. .It Cm StreamLocalBindUnlink
  1989. Specifies whether to remove an existing Unix-domain socket file for local
  1990. or remote port forwarding before creating a new one.
  1991. If the socket file already exists and
  1992. .Cm StreamLocalBindUnlink
  1993. is not enabled,
  1994. .Nm ssh
  1995. will be unable to forward the port to the Unix-domain socket file.
  1996. This option is only used for port forwarding to a Unix-domain socket file.
  1997. .Pp
  1998. The argument must be
  1999. .Cm yes
  2000. or
  2001. .Cm no
  2002. (the default).
  2003. .It Cm StrictHostKeyChecking
  2004. If this flag is set to
  2005. .Cm yes ,
  2006. .Xr ssh 1
  2007. will never automatically add host keys to the
  2008. .Pa ~/.ssh/known_hosts
  2009. file, and refuses to connect to hosts whose host key has changed.
  2010. This provides maximum protection against man-in-the-middle (MITM) attacks,
  2011. though it can be annoying when the
  2012. .Pa /etc/ssh/ssh_known_hosts
  2013. file is poorly maintained or when connections to new hosts are
  2014. frequently made.
  2015. This option forces the user to manually
  2016. add all new hosts.
  2017. .Pp
  2018. If this flag is set to
  2019. .Cm accept-new
  2020. then ssh will automatically add new host keys to the user's
  2021. .Pa known_hosts
  2022. file, but will not permit connections to hosts with
  2023. changed host keys.
  2024. If this flag is set to
  2025. .Cm no
  2026. or
  2027. .Cm off ,
  2028. ssh will automatically add new host keys to the user known hosts files
  2029. and allow connections to hosts with changed hostkeys to proceed,
  2030. subject to some restrictions.
  2031. If this flag is set to
  2032. .Cm ask
  2033. (the default),
  2034. new host keys
  2035. will be added to the user known host files only after the user
  2036. has confirmed that is what they really want to do, and
  2037. ssh will refuse to connect to hosts whose host key has changed.
  2038. The host keys of
  2039. known hosts will be verified automatically in all cases.
  2040. .It Cm SyslogFacility
  2041. Gives the facility code that is used when logging messages from
  2042. .Xr ssh 1 .
  2043. The possible values are: DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2,
  2044. LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7.
  2045. The default is USER.
  2046. .It Cm TCPKeepAlive
  2047. Specifies whether the system should send TCP keepalive messages to the
  2048. other side.
  2049. If they are sent, death of the connection or crash of one
  2050. of the machines will be properly noticed.
  2051. However, this means that
  2052. connections will die if the route is down temporarily, and some people
  2053. find it annoying.
  2054. .Pp
  2055. The default is
  2056. .Cm yes
  2057. (to send TCP keepalive messages), and the client will notice
  2058. if the network goes down or the remote host dies.
  2059. This is important in scripts, and many users want it too.
  2060. .Pp
  2061. To disable TCP keepalive messages, the value should be set to
  2062. .Cm no .
  2063. See also
  2064. .Cm ServerAliveInterval
  2065. for protocol-level keepalives.
  2066. .It Cm Tag
  2067. Specify a configuration tag name that may be later used by a
  2068. .Cm Match
  2069. directive to select a block of configuration.
  2070. .It Cm Tunnel
  2071. Request
  2072. .Xr tun 4
  2073. device forwarding between the client and the server.
  2074. The argument must be
  2075. .Cm yes ,
  2076. .Cm point-to-point
  2077. (layer 3),
  2078. .Cm ethernet
  2079. (layer 2),
  2080. or
  2081. .Cm no
  2082. (the default).
  2083. Specifying
  2084. .Cm yes
  2085. requests the default tunnel mode, which is
  2086. .Cm point-to-point .
  2087. .It Cm TunnelDevice
  2088. Specifies the
  2089. .Xr tun 4
  2090. devices to open on the client
  2091. .Pq Ar local_tun
  2092. and the server
  2093. .Pq Ar remote_tun .
  2094. .Pp
  2095. The argument must be
  2096. .Sm off
  2097. .Ar local_tun Op : Ar remote_tun .
  2098. .Sm on
  2099. The devices may be specified by numerical ID or the keyword
  2100. .Cm any ,
  2101. which uses the next available tunnel device.
  2102. If
  2103. .Ar remote_tun
  2104. is not specified, it defaults to
  2105. .Cm any .
  2106. The default is
  2107. .Cm any:any .
  2108. .It Cm UpdateHostKeys
  2109. Specifies whether
  2110. .Xr ssh 1
  2111. should accept notifications of additional hostkeys from the server sent
  2112. after authentication has completed and add them to
  2113. .Cm UserKnownHostsFile .
  2114. The argument must be
  2115. .Cm yes ,
  2116. .Cm no
  2117. or
  2118. .Cm ask .
  2119. This option allows learning alternate hostkeys for a server
  2120. and supports graceful key rotation by allowing a server to send replacement
  2121. public keys before old ones are removed.
  2122. .Pp
  2123. Additional hostkeys are only accepted if the key used to authenticate the
  2124. host was already trusted or explicitly accepted by the user, the host was
  2125. authenticated via
  2126. .Cm UserKnownHostsFile
  2127. (i.e. not
  2128. .Cm GlobalKnownHostsFile )
  2129. and the host was authenticated using a plain key and not a certificate.
  2130. .Pp
  2131. .Cm UpdateHostKeys
  2132. is enabled by default if the user has not overridden the default
  2133. .Cm UserKnownHostsFile
  2134. setting and has not enabled
  2135. .Cm VerifyHostKeyDNS ,
  2136. otherwise
  2137. .Cm UpdateHostKeys
  2138. will be set to
  2139. .Cm no .
  2140. .Pp
  2141. If
  2142. .Cm UpdateHostKeys
  2143. is set to
  2144. .Cm ask ,
  2145. then the user is asked to confirm the modifications to the known_hosts file.
  2146. Confirmation is currently incompatible with
  2147. .Cm ControlPersist ,
  2148. and will be disabled if it is enabled.
  2149. .Pp
  2150. Presently, only
  2151. .Xr sshd 8
  2152. from OpenSSH 6.8 and greater support the
  2153. .Qq hostkeys@openssh.com
  2154. protocol extension used to inform the client of all the server's hostkeys.
  2155. .It Cm User
  2156. Specifies the user to log in as.
  2157. This can be useful when a different user name is used on different machines.
  2158. This saves the trouble of
  2159. having to remember to give the user name on the command line.
  2160. Arguments to
  2161. .Cm User
  2162. may use the tokens described in the
  2163. .Sx TOKENS
  2164. section
  2165. (with the exception of %r and %C)
  2166. and environment variables as described in the
  2167. .Sx ENVIRONMENT VARIABLES
  2168. section.
  2169. .It Cm UserKnownHostsFile
  2170. Specifies one or more files to use for the user
  2171. host key database, separated by whitespace.
  2172. Each filename may use tilde notation to refer to the user's home directory,
  2173. the tokens described in the
  2174. .Sx TOKENS
  2175. section and environment variables as described in the
  2176. .Sx ENVIRONMENT VARIABLES
  2177. section.
  2178. A value of
  2179. .Cm none
  2180. causes
  2181. .Xr ssh 1
  2182. to ignore any user-specific known hosts files.
  2183. The default is
  2184. .Pa ~/.ssh/known_hosts ,
  2185. .Pa ~/.ssh/known_hosts2 .
  2186. .It Cm VerifyHostKeyDNS
  2187. Specifies whether to verify the remote key using DNS and SSHFP resource
  2188. records.
  2189. If this option is set to
  2190. .Cm yes ,
  2191. the client will implicitly trust keys that match a secure fingerprint
  2192. from DNS.
  2193. Insecure fingerprints will be handled as if this option was set to
  2194. .Cm ask .
  2195. If this option is set to
  2196. .Cm ask ,
  2197. information on fingerprint match will be displayed, but the user will still
  2198. need to confirm new host keys according to the
  2199. .Cm StrictHostKeyChecking
  2200. option.
  2201. The default is
  2202. .Cm no .
  2203. .Pp
  2204. See also
  2205. .Sx VERIFYING HOST KEYS
  2206. in
  2207. .Xr ssh 1 .
  2208. .It Cm VersionAddendum
  2209. Optionally specifies additional text to append to the SSH protocol banner
  2210. sent by the client upon connection.
  2211. The default is
  2212. .Cm none .
  2213. .It Cm VisualHostKey
  2214. If this flag is set to
  2215. .Cm yes ,
  2216. an ASCII art representation of the remote host key fingerprint is
  2217. printed in addition to the fingerprint string at login and
  2218. for unknown host keys.
  2219. If this flag is set to
  2220. .Cm no
  2221. (the default),
  2222. no fingerprint strings are printed at login and
  2223. only the fingerprint string will be printed for unknown host keys.
  2224. .It Cm XAuthLocation
  2225. Specifies the full pathname of the
  2226. .Xr xauth 1
  2227. program.
  2228. The default is
  2229. .Pa /usr/X11R6/bin/xauth .
  2230. .El
  2231. .Sh PATTERNS
  2232. A
  2233. .Em pattern
  2234. consists of zero or more non-whitespace characters,
  2235. .Sq *
  2236. (a wildcard that matches zero or more characters),
  2237. or
  2238. .Sq ?\&
  2239. (a wildcard that matches exactly one character).
  2240. For example, to specify a set of declarations for any host in the
  2241. .Qq .co.uk
  2242. set of domains,
  2243. the following pattern could be used:
  2244. .Pp
  2245. .Dl Host *.co.uk
  2246. .Pp
  2247. The following pattern
  2248. would match any host in the 192.168.0.[0-9] network range:
  2249. .Pp
  2250. .Dl Host 192.168.0.?
  2251. .Pp
  2252. A
  2253. .Em pattern-list
  2254. is a comma-separated list of patterns.
  2255. Patterns within pattern-lists may be negated
  2256. by preceding them with an exclamation mark
  2257. .Pq Sq !\& .
  2258. For example,
  2259. to allow a key to be used from anywhere within an organization
  2260. except from the
  2261. .Qq dialup
  2262. pool,
  2263. the following entry (in authorized_keys) could be used:
  2264. .Pp
  2265. .Dl from=\&"!*.dialup.example.com,*.example.com\&"
  2266. .Pp
  2267. Note that a negated match will never produce a positive result by itself.
  2268. For example, attempting to match
  2269. .Qq host3
  2270. against the following pattern-list will fail:
  2271. .Pp
  2272. .Dl from=\&"!host1,!host2\&"
  2273. .Pp
  2274. The solution here is to include a term that will yield a positive match,
  2275. such as a wildcard:
  2276. .Pp
  2277. .Dl from=\&"!host1,!host2,*\&"
  2278. .Sh TOKENS
  2279. Arguments to some keywords can make use of tokens,
  2280. which are expanded at runtime:
  2281. .Pp
  2282. .Bl -tag -width XXXX -offset indent -compact
  2283. .It %%
  2284. A literal
  2285. .Sq % .
  2286. .It \&%C
  2287. Hash of %l%h%p%r%j.
  2288. .It %d
  2289. Local user's home directory.
  2290. .It %f
  2291. The fingerprint of the server's host key.
  2292. .It %H
  2293. The
  2294. .Pa known_hosts
  2295. hostname or address that is being searched for.
  2296. .It %h
  2297. The remote hostname.
  2298. .It \%%I
  2299. A string describing the reason for a
  2300. .Cm KnownHostsCommand
  2301. execution: either
  2302. .Cm ADDRESS
  2303. when looking up a host by address (only when
  2304. .Cm CheckHostIP
  2305. is enabled),
  2306. .Cm HOSTNAME
  2307. when searching by hostname, or
  2308. .Cm ORDER
  2309. when preparing the host key algorithm preference list to use for the
  2310. destination host.
  2311. .It %i
  2312. The local user ID.
  2313. .It %j
  2314. The contents of the ProxyJump option, or the empty string if this
  2315. option is unset.
  2316. .It %K
  2317. The base64 encoded host key.
  2318. .It %k
  2319. The host key alias if specified, otherwise the original remote hostname given
  2320. on the command line.
  2321. .It %L
  2322. The local hostname.
  2323. .It %l
  2324. The local hostname, including the domain name.
  2325. .It %n
  2326. The original remote hostname, as given on the command line.
  2327. .It %p
  2328. The remote port.
  2329. .It %r
  2330. The remote username.
  2331. .It \&%T
  2332. The local
  2333. .Xr tun 4
  2334. or
  2335. .Xr tap 4
  2336. network interface assigned if
  2337. tunnel forwarding was requested, or
  2338. .Qq NONE
  2339. otherwise.
  2340. .It %t
  2341. The type of the server host key, e.g.
  2342. .Cm ssh-ed25519 .
  2343. .It %u
  2344. The local username.
  2345. .El
  2346. .Pp
  2347. .Cm CertificateFile ,
  2348. .Cm ControlPath ,
  2349. .Cm IdentityAgent ,
  2350. .Cm IdentityFile ,
  2351. .Cm Include ,
  2352. .Cm KnownHostsCommand ,
  2353. .Cm LocalForward ,
  2354. .Cm Match exec ,
  2355. .Cm RemoteCommand ,
  2356. .Cm RemoteForward ,
  2357. .Cm RevokedHostKeys ,
  2358. .Cm UserKnownHostsFile
  2359. and
  2360. .Cm VersionAddendum
  2361. accept the tokens %%, %C, %d, %h, %i, %j, %k, %L, %l, %n, %p, %r, and %u.
  2362. .Pp
  2363. .Cm KnownHostsCommand
  2364. additionally accepts the tokens %f, %H, %I, %K and %t.
  2365. .Pp
  2366. .Cm Hostname
  2367. accepts the tokens %% and %h.
  2368. .Pp
  2369. .Cm LocalCommand
  2370. accepts all tokens.
  2371. .Pp
  2372. .Cm ProxyCommand
  2373. and
  2374. .Cm ProxyJump
  2375. accept the tokens %%, %h, %n, %p, and %r.
  2376. .Pp
  2377. Note that some of these directives build commands for execution via the shell.
  2378. Because
  2379. .Xr ssh 1
  2380. performs no filtering or escaping of characters that have special meaning in
  2381. shell commands (e.g. quotes), it is the user's responsibility to ensure that
  2382. the arguments passed to
  2383. .Xr ssh 1
  2384. do not contain such characters and that tokens are appropriately quoted
  2385. when used.
  2386. .Sh ENVIRONMENT VARIABLES
  2387. Arguments to some keywords can be expanded at runtime from environment
  2388. variables on the client by enclosing them in
  2389. .Ic ${} ,
  2390. for example
  2391. .Ic ${HOME}/.ssh
  2392. would refer to the user's .ssh directory.
  2393. If a specified environment variable does not exist then an error will be
  2394. returned and the setting for that keyword will be ignored.
  2395. .Pp
  2396. The keywords
  2397. .Cm CertificateFile ,
  2398. .Cm ControlPath ,
  2399. .Cm IdentityAgent ,
  2400. .Cm IdentityFile ,
  2401. .Cm Include ,
  2402. .Cm KnownHostsCommand ,
  2403. and
  2404. .Cm UserKnownHostsFile
  2405. support environment variables.
  2406. The keywords
  2407. .Cm LocalForward
  2408. and
  2409. .Cm RemoteForward
  2410. support environment variables only for Unix domain socket paths.
  2411. .Sh FILES
  2412. .Bl -tag -width Ds
  2413. .It Pa ~/.ssh/config
  2414. This is the per-user configuration file.
  2415. The format of this file is described above.
  2416. This file is used by the SSH client.
  2417. Because of the potential for abuse, this file must have strict permissions:
  2418. read/write for the user, and not writable by others.
  2419. .It Pa /etc/ssh/ssh_config
  2420. Systemwide configuration file.
  2421. This file provides defaults for those
  2422. values that are not specified in the user's configuration file, and
  2423. for those users who do not have a configuration file.
  2424. This file must be world-readable.
  2425. .El
  2426. .Sh SEE ALSO
  2427. .Xr ssh 1
  2428. .Sh AUTHORS
  2429. .An -nosplit
  2430. OpenSSH is a derivative of the original and free
  2431. ssh 1.2.12 release by
  2432. .An Tatu Ylonen .
  2433. .An Aaron Campbell , Bob Beck , Markus Friedl ,
  2434. .An Niels Provos , Theo de Raadt
  2435. and
  2436. .An Dug Song
  2437. removed many bugs, re-added newer features and
  2438. created OpenSSH.
  2439. .An Markus Friedl
  2440. contributed the support for SSH protocol versions 1.5 and 2.0.