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

sshd.8 (32779B)


  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: sshd.8,v 1.327 2024/09/15 01:19:56 djm Exp $
  37. .Dd $Mdocdate: September 15 2024 $
  38. .Dt SSHD 8
  39. .Os
  40. .Sh NAME
  41. .Nm sshd
  42. .Nd OpenSSH daemon
  43. .Sh SYNOPSIS
  44. .Nm sshd
  45. .Bk -words
  46. .Op Fl 46DdeGiqTtV
  47. .Op Fl C Ar connection_spec
  48. .Op Fl c Ar host_certificate_file
  49. .Op Fl E Ar log_file
  50. .Op Fl f Ar config_file
  51. .Op Fl g Ar login_grace_time
  52. .Op Fl h Ar host_key_file
  53. .Op Fl o Ar option
  54. .Op Fl p Ar port
  55. .Op Fl u Ar len
  56. .Ek
  57. .Sh DESCRIPTION
  58. .Nm
  59. (OpenSSH Daemon) is the daemon program for
  60. .Xr ssh 1 .
  61. It provides secure encrypted communications between two untrusted hosts
  62. over an insecure network.
  63. .Pp
  64. .Nm
  65. listens for connections from clients.
  66. It is normally started at boot from
  67. .Pa /etc/rc .
  68. It forks a new
  69. daemon for each incoming connection.
  70. The forked daemons handle
  71. key exchange, encryption, authentication, command execution,
  72. and data exchange.
  73. .Pp
  74. .Nm
  75. can be configured using command-line options or a configuration file
  76. (by default
  77. .Xr sshd_config 5 ) ;
  78. command-line options override values specified in the
  79. configuration file.
  80. .Nm
  81. rereads its configuration file when it receives a hangup signal,
  82. .Dv SIGHUP ,
  83. by executing itself with the name and options it was started with, e.g.\&
  84. .Pa /usr/sbin/sshd .
  85. .Pp
  86. The options are as follows:
  87. .Bl -tag -width Ds
  88. .It Fl 4
  89. Forces
  90. .Nm
  91. to use IPv4 addresses only.
  92. .It Fl 6
  93. Forces
  94. .Nm
  95. to use IPv6 addresses only.
  96. .It Fl C Ar connection_spec
  97. Specify the connection parameters to use for the
  98. .Fl T
  99. extended test mode.
  100. If provided, any
  101. .Cm Match
  102. directives in the configuration file that would apply are applied before the
  103. configuration is written to standard output.
  104. The connection parameters are supplied as keyword=value pairs and may be
  105. supplied in any order, either with multiple
  106. .Fl C
  107. options or as a comma-separated list.
  108. The keywords are
  109. .Dq addr ,
  110. .Dq user ,
  111. .Dq host ,
  112. .Dq laddr ,
  113. .Dq lport ,
  114. and
  115. .Dq rdomain
  116. and correspond to source address, user, resolved source host name,
  117. local address, local port number and routing domain respectively.
  118. Additionally the
  119. .Dq invalid-user
  120. flag (which does not take a value argument) may be specified to simulate
  121. a connection from an unrecognised username.
  122. .It Fl c Ar host_certificate_file
  123. Specifies a path to a certificate file to identify
  124. .Nm
  125. during key exchange.
  126. The certificate file must match a host key file specified using the
  127. .Fl h
  128. option or the
  129. .Cm HostKey
  130. configuration directive.
  131. .It Fl D
  132. When this option is specified,
  133. .Nm
  134. will not detach and does not become a daemon.
  135. This allows easy monitoring of
  136. .Nm sshd .
  137. .It Fl d
  138. Debug mode.
  139. The server sends verbose debug output to standard error,
  140. and does not put itself in the background.
  141. The server also will not
  142. .Xr fork 2
  143. and will only process one connection.
  144. This option is only intended for debugging for the server.
  145. Multiple
  146. .Fl d
  147. options increase the debugging level.
  148. Maximum is 3.
  149. .It Fl E Ar log_file
  150. Append debug logs to
  151. .Ar log_file
  152. instead of the system log.
  153. .It Fl e
  154. Write debug logs to standard error instead of the system log.
  155. .It Fl f Ar config_file
  156. Specifies the name of the configuration file.
  157. The default is
  158. .Pa /etc/ssh/sshd_config .
  159. .Nm
  160. refuses to start if there is no configuration file.
  161. .It Fl G
  162. Parse and print configuration file.
  163. Check the validity of the configuration file, output the effective configuration
  164. to stdout and then exit.
  165. Optionally,
  166. .Cm Match
  167. rules may be applied by specifying the connection parameters using one or more
  168. .Fl C
  169. options.
  170. .It Fl g Ar login_grace_time
  171. Gives the grace time for clients to authenticate themselves (default
  172. 120 seconds).
  173. If the client fails to authenticate the user within
  174. this many seconds, the server disconnects and exits.
  175. A value of zero indicates no limit.
  176. .It Fl h Ar host_key_file
  177. Specifies a file from which a host key is read.
  178. This option must be given if
  179. .Nm
  180. is not run as root (as the normal
  181. host key files are normally not readable by anyone but root).
  182. The default is
  183. .Pa /etc/ssh/ssh_host_ecdsa_key ,
  184. .Pa /etc/ssh/ssh_host_ed25519_key
  185. and
  186. .Pa /etc/ssh/ssh_host_rsa_key .
  187. It is possible to have multiple host key files for
  188. the different host key algorithms.
  189. .It Fl i
  190. Specifies that
  191. .Nm
  192. is being run from
  193. .Xr inetd 8 .
  194. .It Fl o Ar option
  195. Can be used to give options in the format used in the configuration file.
  196. This is useful for specifying options for which there is no separate
  197. command-line flag.
  198. For full details of the options, and their values, see
  199. .Xr sshd_config 5 .
  200. .It Fl p Ar port
  201. Specifies the port on which the server listens for connections
  202. (default 22).
  203. Multiple port options are permitted.
  204. Ports specified in the configuration file with the
  205. .Cm Port
  206. option are ignored when a command-line port is specified.
  207. Ports specified using the
  208. .Cm ListenAddress
  209. option override command-line ports.
  210. .It Fl q
  211. Quiet mode.
  212. Nothing is sent to the system log.
  213. Normally the beginning,
  214. authentication, and termination of each connection is logged.
  215. .It Fl T
  216. Extended test mode.
  217. Check the validity of the configuration file, output the effective configuration
  218. to stdout and then exit.
  219. Optionally,
  220. .Cm Match
  221. rules may be applied by specifying the connection parameters using one or more
  222. .Fl C
  223. options.
  224. This is similar to the
  225. .Fl G
  226. flag, but it includes the additional testing performed by the
  227. .Fl t
  228. flag.
  229. .It Fl t
  230. Test mode.
  231. Only check the validity of the configuration file and sanity of the keys.
  232. This is useful for updating
  233. .Nm
  234. reliably as configuration options may change.
  235. .It Fl u Ar len
  236. This option is used to specify the size of the field
  237. in the
  238. .Vt utmp
  239. structure that holds the remote host name.
  240. If the resolved host name is longer than
  241. .Ar len ,
  242. the dotted decimal value will be used instead.
  243. This allows hosts with very long host names that
  244. overflow this field to still be uniquely identified.
  245. Specifying
  246. .Fl u0
  247. indicates that only dotted decimal addresses
  248. should be put into the
  249. .Pa utmp
  250. file.
  251. .Fl u0
  252. may also be used to prevent
  253. .Nm
  254. from making DNS requests unless the authentication
  255. mechanism or configuration requires it.
  256. Authentication mechanisms that may require DNS include
  257. .Cm HostbasedAuthentication
  258. and using a
  259. .Cm from="pattern-list"
  260. option in a key file.
  261. Configuration options that require DNS include using a
  262. USER@HOST pattern in
  263. .Cm AllowUsers
  264. or
  265. .Cm DenyUsers .
  266. .It Fl V
  267. Display the version number and exit.
  268. .El
  269. .Sh AUTHENTICATION
  270. The OpenSSH SSH daemon supports SSH protocol 2 only.
  271. Each host has a host-specific key,
  272. used to identify the host.
  273. Whenever a client connects, the daemon responds with its public
  274. host key.
  275. The client compares the
  276. host key against its own database to verify that it has not changed.
  277. Forward secrecy is provided through a Diffie-Hellman key agreement.
  278. This key agreement results in a shared session key.
  279. The rest of the session is encrypted using a symmetric cipher.
  280. The client selects the encryption algorithm
  281. to use from those offered by the server.
  282. Additionally, session integrity is provided
  283. through a cryptographic message authentication code (MAC).
  284. .Pp
  285. Finally, the server and the client enter an authentication dialog.
  286. The client tries to authenticate itself using
  287. host-based authentication,
  288. public key authentication,
  289. challenge-response authentication,
  290. or password authentication.
  291. .Pp
  292. Regardless of the authentication type, the account is checked to
  293. ensure that it is accessible. An account is not accessible if it is
  294. locked, listed in
  295. .Cm DenyUsers
  296. or its group is listed in
  297. .Cm DenyGroups
  298. \&. The definition of a locked account is system dependent. Some platforms
  299. have their own account database (eg AIX) and some modify the passwd field (
  300. .Ql \&*LK\&*
  301. on Solaris and UnixWare,
  302. .Ql \&*
  303. on HP-UX, containing
  304. .Ql Nologin
  305. on Tru64,
  306. a leading
  307. .Ql \&*LOCKED\&*
  308. on FreeBSD and a leading
  309. .Ql \&!
  310. on most Linuxes).
  311. If there is a requirement to disable password authentication
  312. for the account while allowing still public-key, then the passwd field
  313. should be set to something other than these values (eg
  314. .Ql NP
  315. or
  316. .Ql \&*NP\&*
  317. ).
  318. .Pp
  319. If the client successfully authenticates itself, a dialog for
  320. preparing the session is entered.
  321. At this time the client may request
  322. things like allocating a pseudo-tty, forwarding X11 connections,
  323. forwarding TCP connections, or forwarding the authentication agent
  324. connection over the secure channel.
  325. .Pp
  326. After this, the client either requests an interactive shell or execution
  327. of a non-interactive command, which
  328. .Nm
  329. will execute via the user's shell using its
  330. .Fl c
  331. option.
  332. The sides then enter session mode.
  333. In this mode, either side may send
  334. data at any time, and such data is forwarded to/from the shell or
  335. command on the server side, and the user terminal in the client side.
  336. .Pp
  337. When the user program terminates and all forwarded X11 and other
  338. connections have been closed, the server sends command exit status to
  339. the client, and both sides exit.
  340. .Sh LOGIN PROCESS
  341. When a user successfully logs in,
  342. .Nm
  343. does the following:
  344. .Bl -enum -offset indent
  345. .It
  346. If the login is on a tty, and no command has been specified,
  347. prints last login time and
  348. .Pa /etc/motd
  349. (unless prevented in the configuration file or by
  350. .Pa ~/.hushlogin ;
  351. see the
  352. .Sx FILES
  353. section).
  354. .It
  355. If the login is on a tty, records login time.
  356. .It
  357. Checks
  358. .Pa /etc/nologin ;
  359. if it exists, prints contents and quits
  360. (unless root).
  361. .It
  362. Changes to run with normal user privileges.
  363. .It
  364. Sets up basic environment.
  365. .It
  366. Reads the file
  367. .Pa ~/.ssh/environment ,
  368. if it exists, and users are allowed to change their environment.
  369. See the
  370. .Cm PermitUserEnvironment
  371. option in
  372. .Xr sshd_config 5 .
  373. .It
  374. Changes to user's home directory.
  375. .It
  376. If
  377. .Pa ~/.ssh/rc
  378. exists and the
  379. .Xr sshd_config 5
  380. .Cm PermitUserRC
  381. option is set, runs it; else if
  382. .Pa /etc/ssh/sshrc
  383. exists, runs
  384. it; otherwise runs
  385. .Xr xauth 1 .
  386. The
  387. .Dq rc
  388. files are given the X11
  389. authentication protocol and cookie in standard input.
  390. See
  391. .Sx SSHRC ,
  392. below.
  393. .It
  394. Runs user's shell or command.
  395. All commands are run under the user's login shell as specified in the
  396. system password database.
  397. .El
  398. .Sh SSHRC
  399. If the file
  400. .Pa ~/.ssh/rc
  401. exists,
  402. .Xr sh 1
  403. runs it after reading the
  404. environment files but before starting the user's shell or command.
  405. It must not produce any output on stdout; stderr must be used
  406. instead.
  407. If X11 forwarding is in use, it will receive the "proto cookie" pair in
  408. its standard input (and
  409. .Ev DISPLAY
  410. in its environment).
  411. The script must call
  412. .Xr xauth 1
  413. because
  414. .Nm
  415. will not run xauth automatically to add X11 cookies.
  416. .Pp
  417. The primary purpose of this file is to run any initialization routines
  418. which may be needed before the user's home directory becomes
  419. accessible; AFS is a particular example of such an environment.
  420. .Pp
  421. This file will probably contain some initialization code followed by
  422. something similar to:
  423. .Bd -literal -offset 3n
  424. if read proto cookie && [ -n "$DISPLAY" ]; then
  425. if [ `echo $DISPLAY | cut -c1-10` = 'localhost:' ]; then
  426. # X11UseLocalhost=yes
  427. echo add unix:`echo $DISPLAY |
  428. cut -c11-` $proto $cookie
  429. else
  430. # X11UseLocalhost=no
  431. echo add $DISPLAY $proto $cookie
  432. fi | xauth -q -
  433. fi
  434. .Ed
  435. .Pp
  436. If this file does not exist,
  437. .Pa /etc/ssh/sshrc
  438. is run, and if that
  439. does not exist either, xauth is used to add the cookie.
  440. .Sh AUTHORIZED_KEYS FILE FORMAT
  441. .Cm AuthorizedKeysFile
  442. specifies the files containing public keys for
  443. public key authentication;
  444. if this option is not specified, the default is
  445. .Pa ~/.ssh/authorized_keys
  446. and
  447. .Pa ~/.ssh/authorized_keys2 .
  448. Each line of the file contains one
  449. key (empty lines and lines starting with a
  450. .Ql #
  451. are ignored as
  452. comments).
  453. Public keys consist of the following space-separated fields:
  454. options, keytype, base64-encoded key, comment.
  455. The options field is optional.
  456. The supported key types are:
  457. .Pp
  458. .Bl -item -compact -offset indent
  459. .It
  460. sk-ecdsa-sha2-nistp256@openssh.com
  461. .It
  462. ecdsa-sha2-nistp256
  463. .It
  464. ecdsa-sha2-nistp384
  465. .It
  466. ecdsa-sha2-nistp521
  467. .It
  468. sk-ssh-ed25519@openssh.com
  469. .It
  470. ssh-ed25519
  471. .It
  472. ssh-rsa
  473. .El
  474. .Pp
  475. The comment field is not used for anything (but may be convenient for the
  476. user to identify the key).
  477. .Pp
  478. Note that lines in this file can be several hundred bytes long
  479. (because of the size of the public key encoding) up to a limit of
  480. 8 kilobytes, which permits RSA keys up to 16 kilobits.
  481. You don't want to type them in; instead, copy the
  482. .Pa id_ecdsa.pub ,
  483. .Pa id_ecdsa_sk.pub ,
  484. .Pa id_ed25519.pub ,
  485. .Pa id_ed25519_sk.pub ,
  486. or the
  487. .Pa id_rsa.pub
  488. file and edit it.
  489. .Pp
  490. .Nm
  491. enforces a minimum RSA key modulus size of 1024 bits.
  492. .Pp
  493. The options (if present) consist of comma-separated option
  494. specifications.
  495. No spaces are permitted, except within double quotes.
  496. The following option specifications are supported (note
  497. that option keywords are case-insensitive):
  498. .Bl -tag -width Ds
  499. .It Cm agent-forwarding
  500. Enable authentication agent forwarding previously disabled by the
  501. .Cm restrict
  502. option.
  503. .It Cm cert-authority
  504. Specifies that the listed key is a certification authority (CA) that is
  505. trusted to validate signed certificates for user authentication.
  506. .Pp
  507. Certificates may encode access restrictions similar to these key options.
  508. If both certificate restrictions and key options are present, the most
  509. restrictive union of the two is applied.
  510. .It Cm command="command"
  511. Specifies that the command is executed whenever this key is used for
  512. authentication.
  513. The command supplied by the user (if any) is ignored.
  514. The command is run on a pty if the client requests a pty;
  515. otherwise it is run without a tty.
  516. If an 8-bit clean channel is required,
  517. one must not request a pty or should specify
  518. .Cm no-pty .
  519. A quote may be included in the command by quoting it with a backslash.
  520. .Pp
  521. This option might be useful
  522. to restrict certain public keys to perform just a specific operation.
  523. An example might be a key that permits remote backups but nothing else.
  524. Note that the client may specify TCP and/or X11
  525. forwarding unless they are explicitly prohibited, e.g. using the
  526. .Cm restrict
  527. key option.
  528. .Pp
  529. The command originally supplied by the client is available in the
  530. .Ev SSH_ORIGINAL_COMMAND
  531. environment variable.
  532. Note that this option applies to shell, command or subsystem execution.
  533. Also note that this command may be superseded by a
  534. .Xr sshd_config 5
  535. .Cm ForceCommand
  536. directive.
  537. .Pp
  538. If a command is specified and a forced-command is embedded in a certificate
  539. used for authentication, then the certificate will be accepted only if the
  540. two commands are identical.
  541. .It Cm environment="NAME=value"
  542. Specifies that the string is to be added to the environment when
  543. logging in using this key.
  544. Environment variables set this way
  545. override other default environment values.
  546. Multiple options of this type are permitted.
  547. Environment processing is disabled by default and is
  548. controlled via the
  549. .Cm PermitUserEnvironment
  550. option.
  551. .It Cm expiry-time="timespec"
  552. Specifies a time after which the key will not be accepted.
  553. The time may be specified as a YYYYMMDD[Z] date or a YYYYMMDDHHMM[SS][Z] time.
  554. Dates and times will be interpreted in the system time zone unless suffixed
  555. by a Z character, in which case they will be interpreted in the UTC time zone.
  556. .It Cm from="pattern-list"
  557. Specifies that in addition to public key authentication, either the canonical
  558. name of the remote host or its IP address must be present in the
  559. comma-separated list of patterns.
  560. See PATTERNS in
  561. .Xr ssh_config 5
  562. for more information on patterns.
  563. .Pp
  564. In addition to the wildcard matching that may be applied to hostnames or
  565. addresses, a
  566. .Cm from
  567. stanza may match IP addresses using CIDR address/masklen notation.
  568. .Pp
  569. The purpose of this option is to optionally increase security: public key
  570. authentication by itself does not trust the network or name servers or
  571. anything (but the key); however, if somebody somehow steals the key, the key
  572. permits an intruder to log in from anywhere in the world.
  573. This additional option makes using a stolen key more difficult (name
  574. servers and/or routers would have to be compromised in addition to
  575. just the key).
  576. .It Cm no-agent-forwarding
  577. Forbids authentication agent forwarding when this key is used for
  578. authentication.
  579. .It Cm no-port-forwarding
  580. Forbids TCP forwarding when this key is used for authentication.
  581. Any port forward requests by the client will return an error.
  582. This might be used, e.g. in connection with the
  583. .Cm command
  584. option.
  585. .It Cm no-pty
  586. Prevents tty allocation (a request to allocate a pty will fail).
  587. .It Cm no-user-rc
  588. Disables execution of
  589. .Pa ~/.ssh/rc .
  590. .It Cm no-X11-forwarding
  591. Forbids X11 forwarding when this key is used for authentication.
  592. Any X11 forward requests by the client will return an error.
  593. .It Cm permitlisten="[host:]port"
  594. Limit remote port forwarding with the
  595. .Xr ssh 1
  596. .Fl R
  597. option such that it may only listen on the specified host (optional) and port.
  598. IPv6 addresses can be specified by enclosing the address in square brackets.
  599. Multiple
  600. .Cm permitlisten
  601. options may be applied separated by commas.
  602. Hostnames may include wildcards as described in the PATTERNS section in
  603. .Xr ssh_config 5 .
  604. A port specification of
  605. .Cm *
  606. matches any port.
  607. Note that the setting of
  608. .Cm GatewayPorts
  609. may further restrict listen addresses.
  610. Note that
  611. .Xr ssh 1
  612. will send a hostname of
  613. .Dq localhost
  614. if a listen host was not specified when the forwarding was requested, and
  615. that this name is treated differently to the explicit localhost addresses
  616. .Dq 127.0.0.1
  617. and
  618. .Dq ::1 .
  619. .It Cm permitopen="host:port"
  620. Limit local port forwarding with the
  621. .Xr ssh 1
  622. .Fl L
  623. option such that it may only connect to the specified host and port.
  624. IPv6 addresses can be specified by enclosing the address in square brackets.
  625. Multiple
  626. .Cm permitopen
  627. options may be applied separated by commas.
  628. No pattern matching or name lookup is performed on the
  629. specified hostnames, they must be literal host names and/or addresses.
  630. A port specification of
  631. .Cm *
  632. matches any port.
  633. .It Cm port-forwarding
  634. Enable port forwarding previously disabled by the
  635. .Cm restrict
  636. option.
  637. .It Cm principals="principals"
  638. On a
  639. .Cm cert-authority
  640. line, specifies allowed principals for certificate authentication as a
  641. comma-separated list.
  642. At least one name from the list must appear in the certificate's
  643. list of principals for the certificate to be accepted.
  644. This option is ignored for keys that are not marked as trusted certificate
  645. signers using the
  646. .Cm cert-authority
  647. option.
  648. .It Cm pty
  649. Permits tty allocation previously disabled by the
  650. .Cm restrict
  651. option.
  652. .It Cm no-touch-required
  653. Do not require demonstration of user presence
  654. for signatures made using this key.
  655. This option only makes sense for the FIDO authenticator algorithms
  656. .Cm ecdsa-sk
  657. and
  658. .Cm ed25519-sk .
  659. .It Cm verify-required
  660. Require that signatures made using this key attest that they verified
  661. the user, e.g. via a PIN.
  662. This option only makes sense for the FIDO authenticator algorithms
  663. .Cm ecdsa-sk
  664. and
  665. .Cm ed25519-sk .
  666. .It Cm restrict
  667. Enable all restrictions, i.e. disable port, agent and X11 forwarding,
  668. as well as disabling PTY allocation
  669. and execution of
  670. .Pa ~/.ssh/rc .
  671. If any future restriction capabilities are added to authorized_keys files,
  672. they will be included in this set.
  673. .It Cm tunnel="n"
  674. Force a
  675. .Xr tun 4
  676. device on the server.
  677. Without this option, the next available device will be used if
  678. the client requests a tunnel.
  679. .It Cm user-rc
  680. Enables execution of
  681. .Pa ~/.ssh/rc
  682. previously disabled by the
  683. .Cm restrict
  684. option.
  685. .It Cm X11-forwarding
  686. Permits X11 forwarding previously disabled by the
  687. .Cm restrict
  688. option.
  689. .El
  690. .Pp
  691. An example authorized_keys file:
  692. .Bd -literal -offset 3n
  693. # Comments are allowed at start of line. Blank lines are allowed.
  694. # Plain key, no restrictions
  695. ssh-rsa ...
  696. # Forced command, disable PTY and all forwarding
  697. restrict,command="dump /home" ssh-rsa ...
  698. # Restriction of ssh -L forwarding destinations
  699. permitopen="192.0.2.1:80",permitopen="192.0.2.2:25" ssh-rsa ...
  700. # Restriction of ssh -R forwarding listeners
  701. permitlisten="localhost:8080",permitlisten="[::1]:22000" ssh-rsa ...
  702. # Configuration for tunnel forwarding
  703. tunnel="0",command="sh /etc/netstart tun0" ssh-rsa ...
  704. # Override of restriction to allow PTY allocation
  705. restrict,pty,command="nethack" ssh-rsa ...
  706. # Allow FIDO key without requiring touch
  707. no-touch-required sk-ecdsa-sha2-nistp256@openssh.com ...
  708. # Require user-verification (e.g. PIN or biometric) for FIDO key
  709. verify-required sk-ecdsa-sha2-nistp256@openssh.com ...
  710. # Trust CA key, allow touch-less FIDO if requested in certificate
  711. cert-authority,no-touch-required,principals="user_a" ssh-rsa ...
  712. .Ed
  713. .Sh SSH_KNOWN_HOSTS FILE FORMAT
  714. The
  715. .Pa /etc/ssh/ssh_known_hosts
  716. and
  717. .Pa ~/.ssh/known_hosts
  718. files contain host public keys for all known hosts.
  719. The global file should
  720. be prepared by the administrator (optional), and the per-user file is
  721. maintained automatically: whenever the user connects to an unknown host,
  722. its key is added to the per-user file.
  723. .Pp
  724. Each line in these files contains the following fields: marker (optional),
  725. hostnames, keytype, base64-encoded key, comment.
  726. The fields are separated by spaces.
  727. .Pp
  728. The marker is optional, but if it is present then it must be one of
  729. .Dq @cert-authority ,
  730. to indicate that the line contains a certification authority (CA) key,
  731. or
  732. .Dq @revoked ,
  733. to indicate that the key contained on the line is revoked and must not ever
  734. be accepted.
  735. Only one marker should be used on a key line.
  736. .Pp
  737. Hostnames is a comma-separated list of patterns
  738. .Pf ( Ql *
  739. and
  740. .Ql \&?
  741. act as
  742. wildcards); each pattern in turn is matched against the host name.
  743. When
  744. .Nm sshd
  745. is authenticating a client, such as when using
  746. .Cm HostbasedAuthentication ,
  747. this will be the canonical client host name.
  748. When
  749. .Xr ssh 1
  750. is authenticating a server, this will be the host name
  751. given by the user, the value of the
  752. .Xr ssh 1
  753. .Cm HostkeyAlias
  754. if it was specified, or the canonical server hostname if the
  755. .Xr ssh 1
  756. .Cm CanonicalizeHostname
  757. option was used.
  758. .Pp
  759. A pattern may also be preceded by
  760. .Ql \&!
  761. to indicate negation: if the host name matches a negated
  762. pattern, it is not accepted (by that line) even if it matched another
  763. pattern on the line.
  764. A hostname or address may optionally be enclosed within
  765. .Ql \&[
  766. and
  767. .Ql \&]
  768. brackets then followed by
  769. .Ql \&:
  770. and a non-standard port number.
  771. .Pp
  772. Alternately, hostnames may be stored in a hashed form which hides host names
  773. and addresses should the file's contents be disclosed.
  774. Hashed hostnames start with a
  775. .Ql |
  776. character.
  777. Only one hashed hostname may appear on a single line and none of the above
  778. negation or wildcard operators may be applied.
  779. .Pp
  780. The keytype and base64-encoded key are taken directly from the host key; they
  781. can be obtained, for example, from
  782. .Pa /etc/ssh/ssh_host_rsa_key.pub .
  783. The optional comment field continues to the end of the line, and is not used.
  784. .Pp
  785. Lines starting with
  786. .Ql #
  787. and empty lines are ignored as comments.
  788. .Pp
  789. When performing host authentication, authentication is accepted if any
  790. matching line has the proper key; either one that matches exactly or,
  791. if the server has presented a certificate for authentication, the key
  792. of the certification authority that signed the certificate.
  793. For a key to be trusted as a certification authority, it must use the
  794. .Dq @cert-authority
  795. marker described above.
  796. .Pp
  797. The known hosts file also provides a facility to mark keys as revoked,
  798. for example when it is known that the associated private key has been
  799. stolen.
  800. Revoked keys are specified by including the
  801. .Dq @revoked
  802. marker at the beginning of the key line, and are never accepted for
  803. authentication or as certification authorities, but instead will
  804. produce a warning from
  805. .Xr ssh 1
  806. when they are encountered.
  807. .Pp
  808. It is permissible (but not
  809. recommended) to have several lines or different host keys for the same
  810. names.
  811. This will inevitably happen when short forms of host names
  812. from different domains are put in the file.
  813. It is possible
  814. that the files contain conflicting information; authentication is
  815. accepted if valid information can be found from either file.
  816. .Pp
  817. Note that the lines in these files are typically hundreds of characters
  818. long, and you definitely don't want to type in the host keys by hand.
  819. Rather, generate them by a script,
  820. .Xr ssh-keyscan 1
  821. or by taking, for example,
  822. .Pa /etc/ssh/ssh_host_rsa_key.pub
  823. and adding the host names at the front.
  824. .Xr ssh-keygen 1
  825. also offers some basic automated editing for
  826. .Pa ~/.ssh/known_hosts
  827. including removing hosts matching a host name and converting all host
  828. names to their hashed representations.
  829. .Pp
  830. An example ssh_known_hosts file:
  831. .Bd -literal -offset 3n
  832. # Comments allowed at start of line
  833. cvs.example.net,192.0.2.10 ssh-rsa AAAA1234.....=
  834. # A hashed hostname
  835. |1|JfKTdBh7rNbXkVAQCRp4OQoPfmI=|USECr3SWf1JUPsms5AqfD5QfxkM= ssh-rsa
  836. AAAA1234.....=
  837. # A revoked key
  838. @revoked * ssh-rsa AAAAB5W...
  839. # A CA key, accepted for any host in *.mydomain.com or *.mydomain.org
  840. @cert-authority *.mydomain.org,*.mydomain.com ssh-rsa AAAAB5W...
  841. .Ed
  842. .Sh FILES
  843. .Bl -tag -width Ds -compact
  844. .It Pa ~/.hushlogin
  845. This file is used to suppress printing the last login time and
  846. .Pa /etc/motd ,
  847. if
  848. .Cm PrintLastLog
  849. and
  850. .Cm PrintMotd ,
  851. respectively,
  852. are enabled.
  853. It does not suppress printing of the banner specified by
  854. .Cm Banner .
  855. .Pp
  856. .It Pa ~/.rhosts
  857. This file is used for host-based authentication (see
  858. .Xr ssh 1
  859. for more information).
  860. On some machines this file may need to be
  861. world-readable if the user's home directory is on an NFS partition,
  862. because
  863. .Nm
  864. reads it as root.
  865. Additionally, this file must be owned by the user,
  866. and must not have write permissions for anyone else.
  867. The recommended
  868. permission for most machines is read/write for the user, and not
  869. accessible by others.
  870. .Pp
  871. .It Pa ~/.shosts
  872. This file is used in exactly the same way as
  873. .Pa .rhosts ,
  874. but allows host-based authentication without permitting login with
  875. rlogin/rsh.
  876. .Pp
  877. .It Pa ~/.ssh/
  878. This directory is the default location for all user-specific configuration
  879. and authentication information.
  880. There is no general requirement to keep the entire contents of this directory
  881. secret, but the recommended permissions are read/write/execute for the user,
  882. and not accessible by others.
  883. .Pp
  884. .It Pa ~/.ssh/authorized_keys
  885. Lists the public keys (ECDSA, Ed25519, RSA)
  886. that can be used for logging in as this user.
  887. The format of this file is described above.
  888. The content of the file is not highly sensitive, but the recommended
  889. permissions are read/write for the user, and not accessible by others.
  890. .Pp
  891. If this file, the
  892. .Pa ~/.ssh
  893. directory, or the user's home directory are writable
  894. by other users, then the file could be modified or replaced by unauthorized
  895. users.
  896. In this case,
  897. .Nm
  898. will not allow it to be used unless the
  899. .Cm StrictModes
  900. option has been set to
  901. .Dq no .
  902. .Pp
  903. .It Pa ~/.ssh/environment
  904. This file is read into the environment at login (if it exists).
  905. It can only contain empty lines, comment lines (that start with
  906. .Ql # ) ,
  907. and assignment lines of the form name=value.
  908. The file should be writable
  909. only by the user; it need not be readable by anyone else.
  910. Environment processing is disabled by default and is
  911. controlled via the
  912. .Cm PermitUserEnvironment
  913. option.
  914. .Pp
  915. .It Pa ~/.ssh/known_hosts
  916. Contains a list of host keys for all hosts the user has logged into
  917. that are not already in the systemwide list of known host keys.
  918. The format of this file is described above.
  919. This file should be writable only by root/the owner and
  920. can, but need not be, world-readable.
  921. .Pp
  922. .It Pa ~/.ssh/rc
  923. Contains initialization routines to be run before
  924. the user's home directory becomes accessible.
  925. This file should be writable only by the user, and need not be
  926. readable by anyone else.
  927. .Pp
  928. .It Pa /etc/hosts.equiv
  929. This file is for host-based authentication (see
  930. .Xr ssh 1 ) .
  931. It should only be writable by root.
  932. .Pp
  933. .It Pa /etc/moduli
  934. Contains Diffie-Hellman groups used for the "Diffie-Hellman Group Exchange"
  935. key exchange method.
  936. The file format is described in
  937. .Xr moduli 5 .
  938. If no usable groups are found in this file then fixed internal groups will
  939. be used.
  940. .Pp
  941. .It Pa /etc/motd
  942. See
  943. .Xr motd 5 .
  944. .Pp
  945. .It Pa /etc/nologin
  946. If this file exists,
  947. .Nm
  948. refuses to let anyone except root log in.
  949. The contents of the file
  950. are displayed to anyone trying to log in, and non-root connections are
  951. refused.
  952. The file should be world-readable.
  953. .Pp
  954. .It Pa /etc/shosts.equiv
  955. This file is used in exactly the same way as
  956. .Pa hosts.equiv ,
  957. but allows host-based authentication without permitting login with
  958. rlogin/rsh.
  959. .Pp
  960. .It Pa /etc/ssh/ssh_host_ecdsa_key
  961. .It Pa /etc/ssh/ssh_host_ed25519_key
  962. .It Pa /etc/ssh/ssh_host_rsa_key
  963. These files contain the private parts of the host keys.
  964. These files should only be owned by root, readable only by root, and not
  965. accessible to others.
  966. Note that
  967. .Nm
  968. does not start if these files are group/world-accessible.
  969. .Pp
  970. .It Pa /etc/ssh/ssh_host_ecdsa_key.pub
  971. .It Pa /etc/ssh/ssh_host_ed25519_key.pub
  972. .It Pa /etc/ssh/ssh_host_rsa_key.pub
  973. These files contain the public parts of the host keys.
  974. These files should be world-readable but writable only by
  975. root.
  976. Their contents should match the respective private parts.
  977. These files are not
  978. really used for anything; they are provided for the convenience of
  979. the user so their contents can be copied to known hosts files.
  980. These files are created using
  981. .Xr ssh-keygen 1 .
  982. .Pp
  983. .It Pa /etc/ssh/ssh_known_hosts
  984. Systemwide list of known host keys.
  985. This file should be prepared by the
  986. system administrator to contain the public host keys of all machines in the
  987. organization.
  988. The format of this file is described above.
  989. This file should be writable only by root/the owner and
  990. should be world-readable.
  991. .Pp
  992. .It Pa /etc/ssh/sshd_config
  993. Contains configuration data for
  994. .Nm sshd .
  995. The file format and configuration options are described in
  996. .Xr sshd_config 5 .
  997. .Pp
  998. .It Pa /etc/ssh/sshrc
  999. Similar to
  1000. .Pa ~/.ssh/rc ,
  1001. it can be used to specify
  1002. machine-specific login-time initializations globally.
  1003. This file should be writable only by root, and should be world-readable.
  1004. .Pp
  1005. .It Pa /var/empty
  1006. .Xr chroot 2
  1007. directory used by
  1008. .Nm
  1009. during privilege separation in the pre-authentication phase.
  1010. The directory should not contain any files and must be owned by root
  1011. and not group or world-writable.
  1012. .Pp
  1013. .It Pa /var/run/sshd.pid
  1014. Contains the process ID of the
  1015. .Nm
  1016. listening for connections (if there are several daemons running
  1017. concurrently for different ports, this contains the process ID of the one
  1018. started last).
  1019. The content of this file is not sensitive; it can be world-readable.
  1020. .El
  1021. .Sh SEE ALSO
  1022. .Xr scp 1 ,
  1023. .Xr sftp 1 ,
  1024. .Xr ssh 1 ,
  1025. .Xr ssh-add 1 ,
  1026. .Xr ssh-agent 1 ,
  1027. .Xr ssh-keygen 1 ,
  1028. .Xr ssh-keyscan 1 ,
  1029. .Xr chroot 2 ,
  1030. .Xr login.conf 5 ,
  1031. .Xr moduli 5 ,
  1032. .Xr sshd_config 5 ,
  1033. .Xr inetd 8 ,
  1034. .Xr sftp-server 8
  1035. .Sh AUTHORS
  1036. OpenSSH is a derivative of the original and free
  1037. ssh 1.2.12 release by Tatu Ylonen.
  1038. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
  1039. Theo de Raadt and Dug Song
  1040. removed many bugs, re-added newer features and
  1041. created OpenSSH.
  1042. Markus Friedl contributed the support for SSH
  1043. protocol versions 1.5 and 2.0.
  1044. Niels Provos and Markus Friedl contributed support
  1045. for privilege separation.