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.1 (47498B)


  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.1,v 1.444 2024/12/04 14:37:55 djm Exp $
  37. .Dd $Mdocdate: December 4 2024 $
  38. .Dt SSH 1
  39. .Os
  40. .Sh NAME
  41. .Nm ssh
  42. .Nd OpenSSH remote login client
  43. .Sh SYNOPSIS
  44. .Nm ssh
  45. .Op Fl 46AaCfGgKkMNnqsTtVvXxYy
  46. .Op Fl B Ar bind_interface
  47. .Op Fl b Ar bind_address
  48. .Op Fl c Ar cipher_spec
  49. .Op Fl D Oo Ar bind_address : Oc Ns Ar port
  50. .Op Fl E Ar log_file
  51. .Op Fl e Ar escape_char
  52. .Op Fl F Ar configfile
  53. .Op Fl I Ar pkcs11
  54. .Op Fl i Ar identity_file
  55. .Op Fl J Ar destination
  56. .Op Fl L Ar address
  57. .Op Fl l Ar login_name
  58. .Op Fl m Ar mac_spec
  59. .Op Fl O Ar ctl_cmd
  60. .Op Fl o Ar option
  61. .Op Fl P Ar tag
  62. .Op Fl p Ar port
  63. .Op Fl R Ar address
  64. .Op Fl S Ar ctl_path
  65. .Op Fl W Ar host : Ns Ar port
  66. .Op Fl w Ar local_tun Ns Op : Ns Ar remote_tun
  67. .Ar destination
  68. .Op Ar command Op Ar argument ...
  69. .Nm
  70. .Op Fl Q Ar query_option
  71. .Sh DESCRIPTION
  72. .Nm
  73. (SSH client) is a program for logging into a remote machine and for
  74. executing commands on a remote machine.
  75. It is intended to provide secure encrypted communications between
  76. two untrusted hosts over an insecure network.
  77. X11 connections, arbitrary TCP ports and
  78. .Ux Ns -domain
  79. sockets can also be forwarded over the secure channel.
  80. .Pp
  81. .Nm
  82. connects and logs into the specified
  83. .Ar destination ,
  84. which may be specified as either
  85. .Sm off
  86. .Oo user @ Oc hostname
  87. .Sm on
  88. or a URI of the form
  89. .Sm off
  90. .No ssh:// Oo user @ Oc hostname Op : port .
  91. .Sm on
  92. The user must prove
  93. their identity to the remote machine using one of several methods
  94. (see below).
  95. .Pp
  96. If a
  97. .Ar command
  98. is specified,
  99. it will be executed on the remote host instead of a login shell.
  100. A complete command line may be specified as
  101. .Ar command ,
  102. or it may have additional arguments.
  103. If supplied, the arguments will be appended to the command, separated by
  104. spaces, before it is sent to the server to be executed.
  105. .Pp
  106. The options are as follows:
  107. .Pp
  108. .Bl -tag -width Ds -compact
  109. .It Fl 4
  110. Forces
  111. .Nm
  112. to use IPv4 addresses only.
  113. .Pp
  114. .It Fl 6
  115. Forces
  116. .Nm
  117. to use IPv6 addresses only.
  118. .Pp
  119. .It Fl A
  120. Enables forwarding of connections from an authentication agent such as
  121. .Xr ssh-agent 1 .
  122. This can also be specified on a per-host basis in a configuration file.
  123. .Pp
  124. Agent forwarding should be enabled with caution.
  125. Users with the ability to bypass file permissions on the remote host
  126. (for the agent's
  127. .Ux Ns -domain
  128. socket) can access the local agent through the forwarded connection.
  129. An attacker cannot obtain key material from the agent,
  130. however they can perform operations on the keys that enable them to
  131. authenticate using the identities loaded into the agent.
  132. A safer alternative may be to use a jump host
  133. (see
  134. .Fl J ) .
  135. .Pp
  136. .It Fl a
  137. Disables forwarding of the authentication agent connection.
  138. .Pp
  139. .It Fl B Ar bind_interface
  140. Bind to the address of
  141. .Ar bind_interface
  142. before attempting to connect to the destination host.
  143. This is only useful on systems with more than one address.
  144. .Pp
  145. .It Fl b Ar bind_address
  146. Use
  147. .Ar bind_address
  148. on the local machine as the source address
  149. of the connection.
  150. Only useful on systems with more than one address.
  151. .Pp
  152. .It Fl C
  153. Requests compression of all data (including stdin, stdout, stderr, and
  154. data for forwarded X11, TCP and
  155. .Ux Ns -domain
  156. connections).
  157. The compression algorithm is the same used by
  158. .Xr gzip 1 .
  159. Compression is desirable on modem lines and other
  160. slow connections, but will only slow down things on fast networks.
  161. The default value can be set on a host-by-host basis in the
  162. configuration files; see the
  163. .Cm Compression
  164. option in
  165. .Xr ssh_config 5 .
  166. .Pp
  167. .It Fl c Ar cipher_spec
  168. Selects the cipher specification for encrypting the session.
  169. .Ar cipher_spec
  170. is a comma-separated list of ciphers
  171. listed in order of preference.
  172. See the
  173. .Cm Ciphers
  174. keyword in
  175. .Xr ssh_config 5
  176. for more information.
  177. .Pp
  178. .It Fl D Xo
  179. .Sm off
  180. .Oo Ar bind_address : Oc
  181. .Ar port
  182. .Sm on
  183. .Xc
  184. Specifies a local
  185. .Dq dynamic
  186. application-level port forwarding.
  187. This works by allocating a socket to listen to
  188. .Ar port
  189. on the local side, optionally bound to the specified
  190. .Ar bind_address .
  191. Whenever a connection is made to this port, the
  192. connection is forwarded over the secure channel, and the application
  193. protocol is then used to determine where to connect to from the
  194. remote machine.
  195. Currently the SOCKS4 and SOCKS5 protocols are supported, and
  196. .Nm
  197. will act as a SOCKS server.
  198. Only root can forward privileged ports.
  199. Dynamic port forwardings can also be specified in the configuration file.
  200. .Pp
  201. IPv6 addresses can be specified by enclosing the address in square brackets.
  202. Only the superuser can forward privileged ports.
  203. By default, the local port is bound in accordance with the
  204. .Cm GatewayPorts
  205. setting.
  206. However, an explicit
  207. .Ar bind_address
  208. may be used to bind the connection to a specific address.
  209. The
  210. .Ar bind_address
  211. of
  212. .Dq localhost
  213. indicates that the listening port be bound for local use only, while an
  214. empty address or
  215. .Sq *
  216. indicates that the port should be available from all interfaces.
  217. .Pp
  218. .It Fl E Ar log_file
  219. Append debug logs to
  220. .Ar log_file
  221. instead of standard error.
  222. .Pp
  223. .It Fl e Ar escape_char
  224. Sets the escape character for sessions with a pty (default:
  225. .Ql ~ ) .
  226. The escape character is only recognized at the beginning of a line.
  227. The escape character followed by a dot
  228. .Pq Ql \&.
  229. closes the connection;
  230. followed by control-Z suspends the connection;
  231. and followed by itself sends the escape character once.
  232. Setting the character to
  233. .Dq none
  234. disables any escapes and makes the session fully transparent.
  235. .Pp
  236. .It Fl F Ar configfile
  237. Specifies an alternative per-user configuration file.
  238. If a configuration file is given on the command line,
  239. the system-wide configuration file
  240. .Pq Pa /etc/ssh/ssh_config
  241. will be ignored.
  242. The default for the per-user configuration file is
  243. .Pa ~/.ssh/config .
  244. If set to
  245. .Dq none ,
  246. no configuration files will be read.
  247. .Pp
  248. .It Fl f
  249. Requests
  250. .Nm
  251. to go to background just before command execution.
  252. This is useful if
  253. .Nm
  254. is going to ask for passwords or passphrases, but the user
  255. wants it in the background.
  256. This implies
  257. .Fl n .
  258. The recommended way to start X11 programs at a remote site is with
  259. something like
  260. .Ic ssh -f host xterm .
  261. .Pp
  262. If the
  263. .Cm ExitOnForwardFailure
  264. configuration option is set to
  265. .Dq yes ,
  266. then a client started with
  267. .Fl f
  268. will wait for all remote port forwards to be successfully established
  269. before placing itself in the background.
  270. Refer to the description of
  271. .Cm ForkAfterAuthentication
  272. in
  273. .Xr ssh_config 5
  274. for details.
  275. .Pp
  276. .It Fl G
  277. Causes
  278. .Nm
  279. to print its configuration after evaluating
  280. .Cm Host
  281. and
  282. .Cm Match
  283. blocks and exit.
  284. .Pp
  285. .It Fl g
  286. Allows remote hosts to connect to local forwarded ports.
  287. If used on a multiplexed connection, then this option must be specified
  288. on the master process.
  289. .Pp
  290. .It Fl I Ar pkcs11
  291. Specify the PKCS#11 shared library
  292. .Nm
  293. should use to communicate with a PKCS#11 token providing keys for user
  294. authentication.
  295. .Pp
  296. .It Fl i Ar identity_file
  297. Selects a file from which the identity (private key) for
  298. public key authentication is read.
  299. You can also specify a public key file to use the corresponding
  300. private key that is loaded in
  301. .Xr ssh-agent 1
  302. when the private key file is not present locally.
  303. The default is
  304. .Pa ~/.ssh/id_rsa ,
  305. .Pa ~/.ssh/id_ecdsa ,
  306. .Pa ~/.ssh/id_ecdsa_sk ,
  307. .Pa ~/.ssh/id_ed25519
  308. and
  309. .Pa ~/.ssh/id_ed25519_sk .
  310. Identity files may also be specified on
  311. a per-host basis in the configuration file.
  312. It is possible to have multiple
  313. .Fl i
  314. options (and multiple identities specified in
  315. configuration files).
  316. If no certificates have been explicitly specified by the
  317. .Cm CertificateFile
  318. directive,
  319. .Nm
  320. will also try to load certificate information from the filename obtained
  321. by appending
  322. .Pa -cert.pub
  323. to identity filenames.
  324. .Pp
  325. .It Fl J Ar destination
  326. Connect to the target host by first making an
  327. .Nm
  328. connection to the jump host described by
  329. .Ar destination
  330. and then establishing a TCP forwarding to the ultimate destination from
  331. there.
  332. Multiple jump hops may be specified separated by comma characters.
  333. IPv6 addresses can be specified by enclosing the address in square brackets.
  334. This is a shortcut to specify a
  335. .Cm ProxyJump
  336. configuration directive.
  337. Note that configuration directives supplied on the command-line generally
  338. apply to the destination host and not any specified jump hosts.
  339. Use
  340. .Pa ~/.ssh/config
  341. to specify configuration for jump hosts.
  342. .Pp
  343. .It Fl K
  344. Enables GSSAPI-based authentication and forwarding (delegation) of GSSAPI
  345. credentials to the server.
  346. .Pp
  347. .It Fl k
  348. Disables forwarding (delegation) of GSSAPI credentials to the server.
  349. .Pp
  350. .It Fl L Xo
  351. .Sm off
  352. .Oo Ar bind_address : Oc
  353. .Ar port : host : hostport
  354. .Sm on
  355. .Xc
  356. .It Fl L Xo
  357. .Sm off
  358. .Oo Ar bind_address : Oc
  359. .Ar port : remote_socket
  360. .Sm on
  361. .Xc
  362. .It Fl L Xo
  363. .Sm off
  364. .Ar local_socket : host : hostport
  365. .Sm on
  366. .Xc
  367. .It Fl L Xo
  368. .Sm off
  369. .Ar local_socket : remote_socket
  370. .Sm on
  371. .Xc
  372. Specifies that connections to the given TCP port or Unix socket on the local
  373. (client) host are to be forwarded to the given host and port, or Unix socket,
  374. on the remote side.
  375. This works by allocating a socket to listen to either a TCP
  376. .Ar port
  377. on the local side, optionally bound to the specified
  378. .Ar bind_address ,
  379. or to a Unix socket.
  380. Whenever a connection is made to the local port or socket, the
  381. connection is forwarded over the secure channel, and a connection is
  382. made to either
  383. .Ar host
  384. port
  385. .Ar hostport ,
  386. or the Unix socket
  387. .Ar remote_socket ,
  388. from the remote machine.
  389. .Pp
  390. Port forwardings can also be specified in the configuration file.
  391. Only the superuser can forward privileged ports.
  392. IPv6 addresses can be specified by enclosing the address in square brackets.
  393. .Pp
  394. By default, the local port is bound in accordance with the
  395. .Cm GatewayPorts
  396. setting.
  397. However, an explicit
  398. .Ar bind_address
  399. may be used to bind the connection to a specific address.
  400. The
  401. .Ar bind_address
  402. of
  403. .Dq localhost
  404. indicates that the listening port be bound for local use only, while an
  405. empty address or
  406. .Sq *
  407. indicates that the port should be available from all interfaces.
  408. .Pp
  409. .It Fl l Ar login_name
  410. Specifies the user to log in as on the remote machine.
  411. This also may be specified on a per-host basis in the configuration file.
  412. .Pp
  413. .It Fl M
  414. Places the
  415. .Nm
  416. client into
  417. .Dq master
  418. mode for connection sharing.
  419. Multiple
  420. .Fl M
  421. options places
  422. .Nm
  423. into
  424. .Dq master
  425. mode but with confirmation required using
  426. .Xr ssh-askpass 1
  427. before each operation that changes the multiplexing state
  428. (e.g. opening a new session).
  429. Refer to the description of
  430. .Cm ControlMaster
  431. in
  432. .Xr ssh_config 5
  433. for details.
  434. .Pp
  435. .It Fl m Ar mac_spec
  436. A comma-separated list of MAC (message authentication code) algorithms,
  437. specified in order of preference.
  438. See the
  439. .Cm MACs
  440. keyword in
  441. .Xr ssh_config 5
  442. for more information.
  443. .Pp
  444. .It Fl N
  445. Do not execute a remote command.
  446. This is useful for just forwarding ports.
  447. Refer to the description of
  448. .Cm SessionType
  449. in
  450. .Xr ssh_config 5
  451. for details.
  452. .Pp
  453. .It Fl n
  454. Redirects stdin from
  455. .Pa /dev/null
  456. (actually, prevents reading from stdin).
  457. This must be used when
  458. .Nm
  459. is run in the background.
  460. A common trick is to use this to run X11 programs on a remote machine.
  461. For example,
  462. .Ic ssh -n shadows.cs.hut.fi emacs &
  463. will start an emacs on shadows.cs.hut.fi, and the X11
  464. connection will be automatically forwarded over an encrypted channel.
  465. The
  466. .Nm
  467. program will be put in the background.
  468. (This does not work if
  469. .Nm
  470. needs to ask for a password or passphrase; see also the
  471. .Fl f
  472. option.)
  473. Refer to the description of
  474. .Cm StdinNull
  475. in
  476. .Xr ssh_config 5
  477. for details.
  478. .Pp
  479. .It Fl O Ar ctl_cmd
  480. Control an active connection multiplexing master process.
  481. When the
  482. .Fl O
  483. option is specified, the
  484. .Ar ctl_cmd
  485. argument is interpreted and passed to the master process.
  486. Valid commands are:
  487. .Dq check
  488. (check that the master process is running),
  489. .Dq forward
  490. (request forwardings without command execution),
  491. .Dq cancel
  492. (cancel forwardings),
  493. .Dq proxy
  494. (connect to a running multiplexing master in proxy mode),
  495. .Dq exit
  496. (request the master to exit), and
  497. .Dq stop
  498. (request the master to stop accepting further multiplexing requests).
  499. .Pp
  500. .It Fl o Ar option
  501. Can be used to give options in the format used in the configuration file.
  502. This is useful for specifying options for which there is no separate
  503. command-line flag.
  504. For full details of the options listed below, and their possible values, see
  505. .Xr ssh_config 5 .
  506. .Pp
  507. .Bl -tag -width Ds -offset indent -compact
  508. .It AddKeysToAgent
  509. .It AddressFamily
  510. .It BatchMode
  511. .It BindAddress
  512. .It BindInterface
  513. .It CASignatureAlgorithms
  514. .It CanonicalDomains
  515. .It CanonicalizeFallbackLocal
  516. .It CanonicalizeHostname
  517. .It CanonicalizeMaxDots
  518. .It CanonicalizePermittedCNAMEs
  519. .It CertificateFile
  520. .It ChannelTimeout
  521. .It CheckHostIP
  522. .It Ciphers
  523. .It ClearAllForwardings
  524. .It Compression
  525. .It ConnectTimeout
  526. .It ConnectionAttempts
  527. .It ControlMaster
  528. .It ControlPath
  529. .It ControlPersist
  530. .It DynamicForward
  531. .It EnableEscapeCommandline
  532. .It EnableSSHKeysign
  533. .It EscapeChar
  534. .It ExitOnForwardFailure
  535. .It FingerprintHash
  536. .It ForkAfterAuthentication
  537. .It ForwardAgent
  538. .It ForwardX11
  539. .It ForwardX11Timeout
  540. .It ForwardX11Trusted
  541. .It GSSAPIAuthentication
  542. .It GSSAPIDelegateCredentials
  543. .It GatewayPorts
  544. .It GlobalKnownHostsFile
  545. .It HashKnownHosts
  546. .It Host
  547. .It HostKeyAlgorithms
  548. .It HostKeyAlias
  549. .It HostbasedAcceptedAlgorithms
  550. .It HostbasedAuthentication
  551. .It Hostname
  552. .It IPQoS
  553. .It IdentitiesOnly
  554. .It IdentityAgent
  555. .It IdentityFile
  556. .It IgnoreUnknown
  557. .It Include
  558. .It KbdInteractiveAuthentication
  559. .It KbdInteractiveDevices
  560. .It KexAlgorithms
  561. .It KnownHostsCommand
  562. .It LocalCommand
  563. .It LocalForward
  564. .It LogLevel
  565. .It LogVerbose
  566. .It MACs
  567. .It NoHostAuthenticationForLocalhost
  568. .It NumberOfPasswordPrompts
  569. .It ObscureKeystrokeTiming
  570. .It PKCS11Provider
  571. .It PasswordAuthentication
  572. .It PermitLocalCommand
  573. .It PermitRemoteOpen
  574. .It Port
  575. .It PreferredAuthentications
  576. .It ProxyCommand
  577. .It ProxyJump
  578. .It ProxyUseFdpass
  579. .It PubkeyAcceptedAlgorithms
  580. .It PubkeyAuthentication
  581. .It RekeyLimit
  582. .It RemoteCommand
  583. .It RemoteForward
  584. .It RequestTTY
  585. .It RequiredRSASize
  586. .It RevokedHostKeys
  587. .It SecurityKeyProvider
  588. .It SendEnv
  589. .It ServerAliveCountMax
  590. .It ServerAliveInterval
  591. .It SessionType
  592. .It SetEnv
  593. .It StdinNull
  594. .It StreamLocalBindMask
  595. .It StreamLocalBindUnlink
  596. .It StrictHostKeyChecking
  597. .It SyslogFacility
  598. .It TCPKeepAlive
  599. .It Tag
  600. .It Tunnel
  601. .It TunnelDevice
  602. .It UpdateHostKeys
  603. .It User
  604. .It UserKnownHostsFile
  605. .It VerifyHostKeyDNS
  606. .It VisualHostKey
  607. .It XAuthLocation
  608. .El
  609. .Pp
  610. .It Fl P Ar tag
  611. Specify a tag name that may be used to select configuration in
  612. .Xr ssh_config 5 .
  613. Refer to the
  614. .Cm Tag
  615. and
  616. .Cm Match
  617. keywords in
  618. .Xr ssh_config 5
  619. for more information.
  620. .It Fl p Ar port
  621. Port to connect to on the remote host.
  622. This can be specified on a
  623. per-host basis in the configuration file.
  624. .Pp
  625. .It Fl Q Ar query_option
  626. Queries for the algorithms supported by one of the following features:
  627. .Ar cipher
  628. (supported symmetric ciphers),
  629. .Ar cipher-auth
  630. (supported symmetric ciphers that support authenticated encryption),
  631. .Ar help
  632. (supported query terms for use with the
  633. .Fl Q
  634. flag),
  635. .Ar mac
  636. (supported message integrity codes),
  637. .Ar kex
  638. (key exchange algorithms),
  639. .Ar key
  640. (key types),
  641. .Ar key-ca-sign
  642. (valid CA signature algorithms for certificates),
  643. .Ar key-cert
  644. (certificate key types),
  645. .Ar key-plain
  646. (non-certificate key types),
  647. .Ar key-sig
  648. (all key types and signature algorithms),
  649. .Ar protocol-version
  650. (supported SSH protocol versions), and
  651. .Ar sig
  652. (supported signature algorithms).
  653. Alternatively, any keyword from
  654. .Xr ssh_config 5
  655. or
  656. .Xr sshd_config 5
  657. that takes an algorithm list may be used as an alias for the corresponding
  658. query_option.
  659. .Pp
  660. .It Fl q
  661. Quiet mode.
  662. Causes most warning and diagnostic messages to be suppressed.
  663. .Pp
  664. .It Fl R Xo
  665. .Sm off
  666. .Oo Ar bind_address : Oc
  667. .Ar port : host : hostport
  668. .Sm on
  669. .Xc
  670. .It Fl R Xo
  671. .Sm off
  672. .Oo Ar bind_address : Oc
  673. .Ar port : local_socket
  674. .Sm on
  675. .Xc
  676. .It Fl R Xo
  677. .Sm off
  678. .Ar remote_socket : host : hostport
  679. .Sm on
  680. .Xc
  681. .It Fl R Xo
  682. .Sm off
  683. .Ar remote_socket : local_socket
  684. .Sm on
  685. .Xc
  686. .It Fl R Xo
  687. .Sm off
  688. .Oo Ar bind_address : Oc
  689. .Ar port
  690. .Sm on
  691. .Xc
  692. Specifies that connections to the given TCP port or Unix socket on the remote
  693. (server) host are to be forwarded to the local side.
  694. .Pp
  695. This works by allocating a socket to listen to either a TCP
  696. .Ar port
  697. or to a Unix socket on the remote side.
  698. Whenever a connection is made to this port or Unix socket, the
  699. connection is forwarded over the secure channel, and a connection
  700. is made from the local machine to either an explicit destination specified by
  701. .Ar host
  702. port
  703. .Ar hostport ,
  704. or
  705. .Ar local_socket ,
  706. or, if no explicit destination was specified,
  707. .Nm
  708. will act as a SOCKS 4/5 proxy and forward connections to the destinations
  709. requested by the remote SOCKS client.
  710. .Pp
  711. Port forwardings can also be specified in the configuration file.
  712. Privileged ports can be forwarded only when
  713. logging in as root on the remote machine.
  714. IPv6 addresses can be specified by enclosing the address in square brackets.
  715. .Pp
  716. By default, TCP listening sockets on the server will be bound to the loopback
  717. interface only.
  718. This may be overridden by specifying a
  719. .Ar bind_address .
  720. An empty
  721. .Ar bind_address ,
  722. or the address
  723. .Ql * ,
  724. indicates that the remote socket should listen on all interfaces.
  725. Specifying a remote
  726. .Ar bind_address
  727. will only succeed if the server's
  728. .Cm GatewayPorts
  729. option is enabled (see
  730. .Xr sshd_config 5 ) .
  731. .Pp
  732. If the
  733. .Ar port
  734. argument is
  735. .Ql 0 ,
  736. the listen port will be dynamically allocated on the server and reported
  737. to the client at run time.
  738. When used together with
  739. .Ic -O forward ,
  740. the allocated port will be printed to the standard output.
  741. .Pp
  742. .It Fl S Ar ctl_path
  743. Specifies the location of a control socket for connection sharing,
  744. or the string
  745. .Dq none
  746. to disable connection sharing.
  747. Refer to the description of
  748. .Cm ControlPath
  749. and
  750. .Cm ControlMaster
  751. in
  752. .Xr ssh_config 5
  753. for details.
  754. .Pp
  755. .It Fl s
  756. May be used to request invocation of a subsystem on the remote system.
  757. Subsystems facilitate the use of SSH
  758. as a secure transport for other applications (e.g.\&
  759. .Xr sftp 1 ) .
  760. The subsystem is specified as the remote command.
  761. Refer to the description of
  762. .Cm SessionType
  763. in
  764. .Xr ssh_config 5
  765. for details.
  766. .Pp
  767. .It Fl T
  768. Disable pseudo-terminal allocation.
  769. .Pp
  770. .It Fl t
  771. Force pseudo-terminal allocation.
  772. This can be used to execute arbitrary
  773. screen-based programs on a remote machine, which can be very useful,
  774. e.g. when implementing menu services.
  775. Multiple
  776. .Fl t
  777. options force tty allocation, even if
  778. .Nm
  779. has no local tty.
  780. .Pp
  781. .It Fl V
  782. Display the version number and exit.
  783. .Pp
  784. .It Fl v
  785. Verbose mode.
  786. Causes
  787. .Nm
  788. to print debugging messages about its progress.
  789. This is helpful in
  790. debugging connection, authentication, and configuration problems.
  791. Multiple
  792. .Fl v
  793. options increase the verbosity.
  794. The maximum is 3.
  795. .Pp
  796. .It Fl W Ar host : Ns Ar port
  797. Requests that standard input and output on the client be forwarded to
  798. .Ar host
  799. on
  800. .Ar port
  801. over the secure channel.
  802. Implies
  803. .Fl N ,
  804. .Fl T ,
  805. .Cm ExitOnForwardFailure
  806. and
  807. .Cm ClearAllForwardings ,
  808. though these can be overridden in the configuration file or using
  809. .Fl o
  810. command line options.
  811. .Pp
  812. .It Fl w Xo
  813. .Ar local_tun Ns Op : Ns Ar remote_tun
  814. .Xc
  815. Requests
  816. tunnel
  817. device forwarding with the specified
  818. .Xr tun 4
  819. devices between the client
  820. .Pq Ar local_tun
  821. and the server
  822. .Pq Ar remote_tun .
  823. .Pp
  824. The devices may be specified by numerical ID or the keyword
  825. .Dq any ,
  826. which uses the next available tunnel device.
  827. If
  828. .Ar remote_tun
  829. is not specified, it defaults to
  830. .Dq any .
  831. See also the
  832. .Cm Tunnel
  833. and
  834. .Cm TunnelDevice
  835. directives in
  836. .Xr ssh_config 5 .
  837. .Pp
  838. If the
  839. .Cm Tunnel
  840. directive is unset, it will be set to the default tunnel mode, which is
  841. .Dq point-to-point .
  842. If a different
  843. .Cm Tunnel
  844. forwarding mode it desired, then it should be specified before
  845. .Fl w .
  846. .Pp
  847. .It Fl X
  848. Enables X11 forwarding.
  849. This can also be specified on a per-host basis in a configuration file.
  850. .Pp
  851. X11 forwarding should be enabled with caution.
  852. Users with the ability to bypass file permissions on the remote host
  853. (for the user's X authorization database)
  854. can access the local X11 display through the forwarded connection.
  855. An attacker may then be able to perform activities such as keystroke monitoring.
  856. .Pp
  857. For this reason, X11 forwarding is subjected to X11 SECURITY extension
  858. restrictions by default.
  859. Refer to the
  860. .Nm
  861. .Fl Y
  862. option and the
  863. .Cm ForwardX11Trusted
  864. directive in
  865. .Xr ssh_config 5
  866. for more information.
  867. .Pp
  868. .It Fl x
  869. Disables X11 forwarding.
  870. .Pp
  871. .It Fl Y
  872. Enables trusted X11 forwarding.
  873. Trusted X11 forwardings are not subjected to the X11 SECURITY extension
  874. controls.
  875. .Pp
  876. .It Fl y
  877. Send log information using the
  878. .Xr syslog 3
  879. system module.
  880. By default this information is sent to stderr.
  881. .El
  882. .Pp
  883. .Nm
  884. may additionally obtain configuration data from
  885. a per-user configuration file and a system-wide configuration file.
  886. The file format and configuration options are described in
  887. .Xr ssh_config 5 .
  888. .Sh AUTHENTICATION
  889. The OpenSSH SSH client supports SSH protocol 2.
  890. .Pp
  891. The methods available for authentication are:
  892. GSSAPI-based authentication,
  893. host-based authentication,
  894. public key authentication,
  895. keyboard-interactive authentication,
  896. and password authentication.
  897. Authentication methods are tried in the order specified above,
  898. though
  899. .Cm PreferredAuthentications
  900. can be used to change the default order.
  901. .Pp
  902. Host-based authentication works as follows:
  903. If the machine the user logs in from is listed in
  904. .Pa /etc/hosts.equiv
  905. or
  906. .Pa /etc/shosts.equiv
  907. on the remote machine, the user is non-root and the user names are
  908. the same on both sides, or if the files
  909. .Pa ~/.rhosts
  910. or
  911. .Pa ~/.shosts
  912. exist in the user's home directory on the
  913. remote machine and contain a line containing the name of the client
  914. machine and the name of the user on that machine, the user is
  915. considered for login.
  916. Additionally, the server
  917. .Em must
  918. be able to verify the client's
  919. host key (see the description of
  920. .Pa /etc/ssh/ssh_known_hosts
  921. and
  922. .Pa ~/.ssh/known_hosts ,
  923. below)
  924. for login to be permitted.
  925. This authentication method closes security holes due to IP
  926. spoofing, DNS spoofing, and routing spoofing.
  927. [Note to the administrator:
  928. .Pa /etc/hosts.equiv ,
  929. .Pa ~/.rhosts ,
  930. and the rlogin/rsh protocol in general, are inherently insecure and should be
  931. disabled if security is desired.]
  932. .Pp
  933. Public key authentication works as follows:
  934. The scheme is based on public-key cryptography,
  935. using cryptosystems
  936. where encryption and decryption are done using separate keys,
  937. and it is unfeasible to derive the decryption key from the encryption key.
  938. The idea is that each user creates a public/private
  939. key pair for authentication purposes.
  940. The server knows the public key, and only the user knows the private key.
  941. .Nm
  942. implements public key authentication protocol automatically,
  943. using one of the ECDSA, Ed25519 or RSA algorithms.
  944. .Pp
  945. The file
  946. .Pa ~/.ssh/authorized_keys
  947. lists the public keys that are permitted for logging in.
  948. When the user logs in, the
  949. .Nm
  950. program tells the server which key pair it would like to use for
  951. authentication.
  952. The client proves that it has access to the private key
  953. and the server checks that the corresponding public key
  954. is authorized to accept the account.
  955. .Pp
  956. The server may inform the client of errors that prevented public key
  957. authentication from succeeding after authentication completes using a
  958. different method.
  959. These may be viewed by increasing the
  960. .Cm LogLevel
  961. to
  962. .Cm DEBUG
  963. or higher (e.g. by using the
  964. .Fl v
  965. flag).
  966. .Pp
  967. The user creates their key pair by running
  968. .Xr ssh-keygen 1 .
  969. This stores the private key in
  970. .Pa ~/.ssh/id_ecdsa
  971. (ECDSA),
  972. .Pa ~/.ssh/id_ecdsa_sk
  973. (authenticator-hosted ECDSA),
  974. .Pa ~/.ssh/id_ed25519
  975. (Ed25519),
  976. .Pa ~/.ssh/id_ed25519_sk
  977. (authenticator-hosted Ed25519),
  978. or
  979. .Pa ~/.ssh/id_rsa
  980. (RSA)
  981. and stores the public key in
  982. .Pa ~/.ssh/id_ecdsa.pub
  983. (ECDSA),
  984. .Pa ~/.ssh/id_ecdsa_sk.pub
  985. (authenticator-hosted ECDSA),
  986. .Pa ~/.ssh/id_ed25519.pub
  987. (Ed25519),
  988. .Pa ~/.ssh/id_ed25519_sk.pub
  989. (authenticator-hosted Ed25519),
  990. or
  991. .Pa ~/.ssh/id_rsa.pub
  992. (RSA)
  993. in the user's home directory.
  994. The user should then copy the public key
  995. to
  996. .Pa ~/.ssh/authorized_keys
  997. in their home directory on the remote machine.
  998. The
  999. .Pa authorized_keys
  1000. file corresponds to the conventional
  1001. .Pa ~/.rhosts
  1002. file, and has one key
  1003. per line, though the lines can be very long.
  1004. After this, the user can log in without giving the password.
  1005. .Pp
  1006. A variation on public key authentication
  1007. is available in the form of certificate authentication:
  1008. instead of a set of public/private keys,
  1009. signed certificates are used.
  1010. This has the advantage that a single trusted certification authority
  1011. can be used in place of many public/private keys.
  1012. See the CERTIFICATES section of
  1013. .Xr ssh-keygen 1
  1014. for more information.
  1015. .Pp
  1016. The most convenient way to use public key or certificate authentication
  1017. may be with an authentication agent.
  1018. See
  1019. .Xr ssh-agent 1
  1020. and (optionally) the
  1021. .Cm AddKeysToAgent
  1022. directive in
  1023. .Xr ssh_config 5
  1024. for more information.
  1025. .Pp
  1026. Keyboard-interactive authentication works as follows:
  1027. The server sends an arbitrary
  1028. .Qq challenge
  1029. text and prompts for a response, possibly multiple times.
  1030. Examples of keyboard-interactive authentication include
  1031. .Bx
  1032. Authentication (see
  1033. .Xr login.conf 5 )
  1034. and PAM (some
  1035. .Pf non- Ox
  1036. systems).
  1037. .Pp
  1038. Finally, if other authentication methods fail,
  1039. .Nm
  1040. prompts the user for a password.
  1041. The password is sent to the remote
  1042. host for checking; however, since all communications are encrypted,
  1043. the password cannot be seen by someone listening on the network.
  1044. .Pp
  1045. .Nm
  1046. automatically maintains and checks a database containing
  1047. identification for all hosts it has ever been used with.
  1048. Host keys are stored in
  1049. .Pa ~/.ssh/known_hosts
  1050. in the user's home directory.
  1051. Additionally, the file
  1052. .Pa /etc/ssh/ssh_known_hosts
  1053. is automatically checked for known hosts.
  1054. Any new hosts are automatically added to the user's file.
  1055. If a host's identification ever changes,
  1056. .Nm
  1057. warns about this and disables password authentication to prevent
  1058. server spoofing or man-in-the-middle attacks,
  1059. which could otherwise be used to circumvent the encryption.
  1060. The
  1061. .Cm StrictHostKeyChecking
  1062. option can be used to control logins to machines whose
  1063. host key is not known or has changed.
  1064. .Pp
  1065. When the user's identity has been accepted by the server, the server
  1066. either executes the given command in a non-interactive session or,
  1067. if no command has been specified, logs into the machine and gives
  1068. the user a normal shell as an interactive session.
  1069. All communication with
  1070. the remote command or shell will be automatically encrypted.
  1071. .Pp
  1072. If an interactive session is requested,
  1073. .Nm
  1074. by default will only request a pseudo-terminal (pty) for interactive
  1075. sessions when the client has one.
  1076. The flags
  1077. .Fl T
  1078. and
  1079. .Fl t
  1080. can be used to override this behaviour.
  1081. .Pp
  1082. If a pseudo-terminal has been allocated, the
  1083. user may use the escape characters noted below.
  1084. .Pp
  1085. If no pseudo-terminal has been allocated,
  1086. the session is transparent and can be used to reliably transfer binary data.
  1087. On most systems, setting the escape character to
  1088. .Dq none
  1089. will also make the session transparent even if a tty is used.
  1090. .Pp
  1091. The session terminates when the command or shell on the remote
  1092. machine exits and all X11 and TCP connections have been closed.
  1093. .Sh ESCAPE CHARACTERS
  1094. When a pseudo-terminal has been requested,
  1095. .Nm
  1096. supports a number of functions through the use of an escape character.
  1097. .Pp
  1098. A single tilde character can be sent as
  1099. .Ic ~~
  1100. or by following the tilde by a character other than those described below.
  1101. The escape character must always follow a newline to be interpreted as
  1102. special.
  1103. The escape character can be changed in configuration files using the
  1104. .Cm EscapeChar
  1105. configuration directive or on the command line by the
  1106. .Fl e
  1107. option.
  1108. .Pp
  1109. The supported escapes (assuming the default
  1110. .Ql ~ )
  1111. are:
  1112. .Bl -tag -width Ds
  1113. .It Cm ~.
  1114. Disconnect.
  1115. .It Cm ~^Z
  1116. Background
  1117. .Nm .
  1118. .It Cm ~#
  1119. List forwarded connections.
  1120. .It Cm ~&
  1121. Background
  1122. .Nm
  1123. at logout when waiting for forwarded connection / X11 sessions to terminate.
  1124. .It Cm ~?
  1125. Display a list of escape characters.
  1126. .It Cm ~B
  1127. Send a BREAK to the remote system
  1128. (only useful if the peer supports it).
  1129. .It Cm ~C
  1130. Open command line.
  1131. Currently this allows the addition of port forwardings using the
  1132. .Fl L ,
  1133. .Fl R
  1134. and
  1135. .Fl D
  1136. options (see above).
  1137. It also allows the cancellation of existing port-forwardings
  1138. with
  1139. .Sm off
  1140. .Fl KL Oo Ar bind_address : Oc Ar port
  1141. .Sm on
  1142. for local,
  1143. .Sm off
  1144. .Fl KR Oo Ar bind_address : Oc Ar port
  1145. .Sm on
  1146. for remote and
  1147. .Sm off
  1148. .Fl KD Oo Ar bind_address : Oc Ar port
  1149. .Sm on
  1150. for dynamic port-forwardings.
  1151. .Ic !\& Ns Ar command
  1152. allows the user to execute a local command if the
  1153. .Ic PermitLocalCommand
  1154. option is enabled in
  1155. .Xr ssh_config 5 .
  1156. Basic help is available, using the
  1157. .Fl h
  1158. option.
  1159. .It Cm ~R
  1160. Request rekeying of the connection
  1161. (only useful if the peer supports it).
  1162. .It Cm ~V
  1163. Decrease the verbosity
  1164. .Pq Ic LogLevel
  1165. when errors are being written to stderr.
  1166. .It Cm ~v
  1167. Increase the verbosity
  1168. .Pq Ic LogLevel
  1169. when errors are being written to stderr.
  1170. .El
  1171. .Sh TCP FORWARDING
  1172. Forwarding of arbitrary TCP connections over a secure channel
  1173. can be specified either on the command line or in a configuration file.
  1174. One possible application of TCP forwarding is a secure connection to a
  1175. mail server; another is going through firewalls.
  1176. .Pp
  1177. In the example below, we look at encrypting communication for an IRC client,
  1178. even though the IRC server it connects to does not directly
  1179. support encrypted communication.
  1180. This works as follows:
  1181. the user connects to the remote host using
  1182. .Nm ,
  1183. specifying the ports to be used to forward the connection.
  1184. After that it is possible to start the program locally,
  1185. and
  1186. .Nm
  1187. will encrypt and forward the connection to the remote server.
  1188. .Pp
  1189. The following example tunnels an IRC session from the client
  1190. to an IRC server at
  1191. .Dq server.example.com ,
  1192. joining channel
  1193. .Dq #users ,
  1194. nickname
  1195. .Dq pinky ,
  1196. using the standard IRC port, 6667:
  1197. .Bd -literal -offset 4n
  1198. $ ssh -f -L 6667:localhost:6667 server.example.com sleep 10
  1199. $ irc -c '#users' pinky IRC/127.0.0.1
  1200. .Ed
  1201. .Pp
  1202. The
  1203. .Fl f
  1204. option backgrounds
  1205. .Nm
  1206. and the remote command
  1207. .Dq sleep 10
  1208. is specified to allow an amount of time
  1209. (10 seconds, in the example)
  1210. to start the program which is going to use the tunnel.
  1211. If no connections are made within the time specified,
  1212. .Nm
  1213. will exit.
  1214. .Sh X11 FORWARDING
  1215. If the
  1216. .Cm ForwardX11
  1217. variable is set to
  1218. .Dq yes
  1219. (or see the description of the
  1220. .Fl X ,
  1221. .Fl x ,
  1222. and
  1223. .Fl Y
  1224. options above)
  1225. and the user is using X11 (the
  1226. .Ev DISPLAY
  1227. environment variable is set), the connection to the X11 display is
  1228. automatically forwarded to the remote side in such a way that any X11
  1229. programs started from the shell (or command) will go through the
  1230. encrypted channel, and the connection to the real X server will be made
  1231. from the local machine.
  1232. The user should not manually set
  1233. .Ev DISPLAY .
  1234. Forwarding of X11 connections can be
  1235. configured on the command line or in configuration files.
  1236. .Pp
  1237. The
  1238. .Ev DISPLAY
  1239. value set by
  1240. .Nm
  1241. will point to the server machine, but with a display number greater than zero.
  1242. This is normal, and happens because
  1243. .Nm
  1244. creates a
  1245. .Dq proxy
  1246. X server on the server machine for forwarding the
  1247. connections over the encrypted channel.
  1248. .Pp
  1249. .Nm
  1250. will also automatically set up Xauthority data on the server machine.
  1251. For this purpose, it will generate a random authorization cookie,
  1252. store it in Xauthority on the server, and verify that any forwarded
  1253. connections carry this cookie and replace it by the real cookie when
  1254. the connection is opened.
  1255. The real authentication cookie is never
  1256. sent to the server machine (and no cookies are sent in the plain).
  1257. .Pp
  1258. If the
  1259. .Cm ForwardAgent
  1260. variable is set to
  1261. .Dq yes
  1262. (or see the description of the
  1263. .Fl A
  1264. and
  1265. .Fl a
  1266. options above) and
  1267. the user is using an authentication agent, the connection to the agent
  1268. is automatically forwarded to the remote side.
  1269. .Sh VERIFYING HOST KEYS
  1270. When connecting to a server for the first time,
  1271. a fingerprint of the server's public key is presented to the user
  1272. (unless the option
  1273. .Cm StrictHostKeyChecking
  1274. has been disabled).
  1275. Fingerprints can be determined using
  1276. .Xr ssh-keygen 1 :
  1277. .Pp
  1278. .Dl $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key
  1279. .Pp
  1280. If the fingerprint is already known, it can be matched
  1281. and the key can be accepted or rejected.
  1282. If only legacy (MD5) fingerprints for the server are available, the
  1283. .Xr ssh-keygen 1
  1284. .Fl E
  1285. option may be used to downgrade the fingerprint algorithm to match.
  1286. .Pp
  1287. Because of the difficulty of comparing host keys
  1288. just by looking at fingerprint strings,
  1289. there is also support to compare host keys visually,
  1290. using
  1291. .Em random art .
  1292. By setting the
  1293. .Cm VisualHostKey
  1294. option to
  1295. .Dq yes ,
  1296. a small ASCII graphic gets displayed on every login to a server, no matter
  1297. if the session itself is interactive or not.
  1298. By learning the pattern a known server produces, a user can easily
  1299. find out that the host key has changed when a completely different pattern
  1300. is displayed.
  1301. Because these patterns are not unambiguous however, a pattern that looks
  1302. similar to the pattern remembered only gives a good probability that the
  1303. host key is the same, not guaranteed proof.
  1304. .Pp
  1305. To get a listing of the fingerprints along with their random art for
  1306. all known hosts, the following command line can be used:
  1307. .Pp
  1308. .Dl $ ssh-keygen -lv -f ~/.ssh/known_hosts
  1309. .Pp
  1310. If the fingerprint is unknown,
  1311. an alternative method of verification is available:
  1312. SSH fingerprints verified by DNS.
  1313. An additional resource record (RR),
  1314. SSHFP,
  1315. is added to a zonefile
  1316. and the connecting client is able to match the fingerprint
  1317. with that of the key presented.
  1318. .Pp
  1319. In this example, we are connecting a client to a server,
  1320. .Dq host.example.com .
  1321. The SSHFP resource records should first be added to the zonefile for
  1322. host.example.com:
  1323. .Bd -literal -offset indent
  1324. $ ssh-keygen -r host.example.com.
  1325. .Ed
  1326. .Pp
  1327. The output lines will have to be added to the zonefile.
  1328. To check that the zone is answering fingerprint queries:
  1329. .Pp
  1330. .Dl $ dig -t SSHFP host.example.com
  1331. .Pp
  1332. Finally the client connects:
  1333. .Bd -literal -offset indent
  1334. $ ssh -o "VerifyHostKeyDNS ask" host.example.com
  1335. [...]
  1336. Matching host key fingerprint found in DNS.
  1337. Are you sure you want to continue connecting (yes/no)?
  1338. .Ed
  1339. .Pp
  1340. See the
  1341. .Cm VerifyHostKeyDNS
  1342. option in
  1343. .Xr ssh_config 5
  1344. for more information.
  1345. .Sh SSH-BASED VIRTUAL PRIVATE NETWORKS
  1346. .Nm
  1347. contains support for Virtual Private Network (VPN) tunnelling
  1348. using the
  1349. .Xr tun 4
  1350. network pseudo-device,
  1351. allowing two networks to be joined securely.
  1352. The
  1353. .Xr sshd_config 5
  1354. configuration option
  1355. .Cm PermitTunnel
  1356. controls whether the server supports this,
  1357. and at what level (layer 2 or 3 traffic).
  1358. .Pp
  1359. The following example would connect client network 10.0.50.0/24
  1360. with remote network 10.0.99.0/24 using a point-to-point connection
  1361. from 10.1.1.1 to 10.1.1.2,
  1362. provided that the SSH server running on the gateway to the remote network,
  1363. at 192.168.1.15, allows it.
  1364. .Pp
  1365. On the client:
  1366. .Bd -literal -offset indent
  1367. # ssh -f -w 0:1 192.168.1.15 true
  1368. # ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252
  1369. # route add 10.0.99.0/24 10.1.1.2
  1370. .Ed
  1371. .Pp
  1372. On the server:
  1373. .Bd -literal -offset indent
  1374. # ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252
  1375. # route add 10.0.50.0/24 10.1.1.1
  1376. .Ed
  1377. .Pp
  1378. Client access may be more finely tuned via the
  1379. .Pa /root/.ssh/authorized_keys
  1380. file (see below) and the
  1381. .Cm PermitRootLogin
  1382. server option.
  1383. The following entry would permit connections on
  1384. .Xr tun 4
  1385. device 1 from user
  1386. .Dq jane
  1387. and on tun device 2 from user
  1388. .Dq john ,
  1389. if
  1390. .Cm PermitRootLogin
  1391. is set to
  1392. .Dq forced-commands-only :
  1393. .Bd -literal -offset 2n
  1394. tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane
  1395. tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john
  1396. .Ed
  1397. .Pp
  1398. Since an SSH-based setup entails a fair amount of overhead,
  1399. it may be more suited to temporary setups,
  1400. such as for wireless VPNs.
  1401. More permanent VPNs are better provided by tools such as
  1402. .Xr ipsecctl 8
  1403. and
  1404. .Xr isakmpd 8 .
  1405. .Sh ENVIRONMENT
  1406. .Nm
  1407. will normally set the following environment variables:
  1408. .Bl -tag -width "SSH_ORIGINAL_COMMAND"
  1409. .It Ev DISPLAY
  1410. The
  1411. .Ev DISPLAY
  1412. variable indicates the location of the X11 server.
  1413. It is automatically set by
  1414. .Nm
  1415. to point to a value of the form
  1416. .Dq hostname:n ,
  1417. where
  1418. .Dq hostname
  1419. indicates the host where the shell runs, and
  1420. .Sq n
  1421. is an integer \*(Ge 1.
  1422. .Nm
  1423. uses this special value to forward X11 connections over the secure
  1424. channel.
  1425. The user should normally not set
  1426. .Ev DISPLAY
  1427. explicitly, as that
  1428. will render the X11 connection insecure (and will require the user to
  1429. manually copy any required authorization cookies).
  1430. .It Ev HOME
  1431. Set to the path of the user's home directory.
  1432. .It Ev LOGNAME
  1433. Synonym for
  1434. .Ev USER ;
  1435. set for compatibility with systems that use this variable.
  1436. .It Ev MAIL
  1437. Set to the path of the user's mailbox.
  1438. .It Ev PATH
  1439. Set to the default
  1440. .Ev PATH ,
  1441. as specified when compiling
  1442. .Nm .
  1443. .It Ev SSH_ASKPASS
  1444. If
  1445. .Nm
  1446. needs a passphrase, it will read the passphrase from the current
  1447. terminal if it was run from a terminal.
  1448. If
  1449. .Nm
  1450. does not have a terminal associated with it but
  1451. .Ev DISPLAY
  1452. and
  1453. .Ev SSH_ASKPASS
  1454. are set, it will execute the program specified by
  1455. .Ev SSH_ASKPASS
  1456. and open an X11 window to read the passphrase.
  1457. This is particularly useful when calling
  1458. .Nm
  1459. from a
  1460. .Pa .xsession
  1461. or related script.
  1462. (Note that on some machines it
  1463. may be necessary to redirect the input from
  1464. .Pa /dev/null
  1465. to make this work.)
  1466. .It Ev SSH_ASKPASS_REQUIRE
  1467. Allows further control over the use of an askpass program.
  1468. If this variable is set to
  1469. .Dq never
  1470. then
  1471. .Nm
  1472. will never attempt to use one.
  1473. If it is set to
  1474. .Dq prefer ,
  1475. then
  1476. .Nm
  1477. will prefer to use the askpass program instead of the TTY when requesting
  1478. passwords.
  1479. Finally, if the variable is set to
  1480. .Dq force ,
  1481. then the askpass program will be used for all passphrase input regardless
  1482. of whether
  1483. .Ev DISPLAY
  1484. is set.
  1485. .It Ev SSH_AUTH_SOCK
  1486. Identifies the path of a
  1487. .Ux Ns -domain
  1488. socket used to communicate with the agent.
  1489. .It Ev SSH_CONNECTION
  1490. Identifies the client and server ends of the connection.
  1491. The variable contains
  1492. four space-separated values: client IP address, client port number,
  1493. server IP address, and server port number.
  1494. .It Ev SSH_ORIGINAL_COMMAND
  1495. This variable contains the original command line if a forced command
  1496. is executed.
  1497. It can be used to extract the original arguments.
  1498. .It Ev SSH_TTY
  1499. This is set to the name of the tty (path to the device) associated
  1500. with the current shell or command.
  1501. If the current session has no tty,
  1502. this variable is not set.
  1503. .It Ev SSH_TUNNEL
  1504. Optionally set by
  1505. .Xr sshd 8
  1506. to contain the interface names assigned if tunnel forwarding was
  1507. requested by the client.
  1508. .It Ev SSH_USER_AUTH
  1509. Optionally set by
  1510. .Xr sshd 8 ,
  1511. this variable may contain a pathname to a file that lists the authentication
  1512. methods successfully used when the session was established, including any
  1513. public keys that were used.
  1514. .It Ev TZ
  1515. This variable is set to indicate the present time zone if it
  1516. was set when the daemon was started (i.e. the daemon passes the value
  1517. on to new connections).
  1518. .It Ev USER
  1519. Set to the name of the user logging in.
  1520. .El
  1521. .Pp
  1522. Additionally,
  1523. .Nm
  1524. reads
  1525. .Pa ~/.ssh/environment ,
  1526. and adds lines of the format
  1527. .Dq VARNAME=value
  1528. to the environment if the file exists and users are allowed to
  1529. change their environment.
  1530. For more information, see the
  1531. .Cm PermitUserEnvironment
  1532. option in
  1533. .Xr sshd_config 5 .
  1534. .Sh FILES
  1535. .Bl -tag -width Ds -compact
  1536. .It Pa ~/.rhosts
  1537. This file is used for host-based authentication (see above).
  1538. On some machines this file may need to be
  1539. world-readable if the user's home directory is on an NFS partition,
  1540. because
  1541. .Xr sshd 8
  1542. reads it as root.
  1543. Additionally, this file must be owned by the user,
  1544. and must not have write permissions for anyone else.
  1545. The recommended
  1546. permission for most machines is read/write for the user, and not
  1547. accessible by others.
  1548. .Pp
  1549. .It Pa ~/.shosts
  1550. This file is used in exactly the same way as
  1551. .Pa .rhosts ,
  1552. but allows host-based authentication without permitting login with
  1553. rlogin/rsh.
  1554. .Pp
  1555. .It Pa ~/.ssh/
  1556. This directory is the default location for all user-specific configuration
  1557. and authentication information.
  1558. There is no general requirement to keep the entire contents of this directory
  1559. secret, but the recommended permissions are read/write/execute for the user,
  1560. and not accessible by others.
  1561. .Pp
  1562. .It Pa ~/.ssh/authorized_keys
  1563. Lists the public keys (ECDSA, Ed25519, RSA)
  1564. that can be used for logging in as this user.
  1565. The format of this file is described in the
  1566. .Xr sshd 8
  1567. manual page.
  1568. This file is not highly sensitive, but the recommended
  1569. permissions are read/write for the user, and not accessible by others.
  1570. .Pp
  1571. .It Pa ~/.ssh/config
  1572. This is the per-user configuration file.
  1573. The file format and configuration options are described in
  1574. .Xr ssh_config 5 .
  1575. Because of the potential for abuse, this file must have strict permissions:
  1576. read/write for the user, and not writable by others.
  1577. .Pp
  1578. .It Pa ~/.ssh/environment
  1579. Contains additional definitions for environment variables; see
  1580. .Sx ENVIRONMENT ,
  1581. above.
  1582. .Pp
  1583. .It Pa ~/.ssh/id_ecdsa
  1584. .It Pa ~/.ssh/id_ecdsa_sk
  1585. .It Pa ~/.ssh/id_ed25519
  1586. .It Pa ~/.ssh/id_ed25519_sk
  1587. .It Pa ~/.ssh/id_rsa
  1588. Contains the private key for authentication.
  1589. These files
  1590. contain sensitive data and should be readable by the user but not
  1591. accessible by others (read/write/execute).
  1592. .Nm
  1593. will simply ignore a private key file if it is accessible by others.
  1594. It is possible to specify a passphrase when
  1595. generating the key which will be used to encrypt the
  1596. sensitive part of this file using AES-128.
  1597. .Pp
  1598. .It Pa ~/.ssh/id_ecdsa.pub
  1599. .It Pa ~/.ssh/id_ecdsa_sk.pub
  1600. .It Pa ~/.ssh/id_ed25519.pub
  1601. .It Pa ~/.ssh/id_ed25519_sk.pub
  1602. .It Pa ~/.ssh/id_rsa.pub
  1603. Contains the public key for authentication.
  1604. These files are not
  1605. sensitive and can (but need not) be readable by anyone.
  1606. .Pp
  1607. .It Pa ~/.ssh/known_hosts
  1608. Contains a list of host keys for all hosts the user has logged into
  1609. that are not already in the systemwide list of known host keys.
  1610. See
  1611. .Xr sshd 8
  1612. for further details of the format of this file.
  1613. .Pp
  1614. .It Pa ~/.ssh/rc
  1615. Commands in this file are executed by
  1616. .Nm
  1617. when the user logs in, just before the user's shell (or command) is
  1618. started.
  1619. See the
  1620. .Xr sshd 8
  1621. manual page for more information.
  1622. .Pp
  1623. .It Pa /etc/hosts.equiv
  1624. This file is for host-based authentication (see above).
  1625. It should only be writable by root.
  1626. .Pp
  1627. .It Pa /etc/shosts.equiv
  1628. This file is used in exactly the same way as
  1629. .Pa hosts.equiv ,
  1630. but allows host-based authentication without permitting login with
  1631. rlogin/rsh.
  1632. .Pp
  1633. .It Pa /etc/ssh/ssh_config
  1634. Systemwide configuration file.
  1635. The file format and configuration options are described in
  1636. .Xr ssh_config 5 .
  1637. .Pp
  1638. .It Pa /etc/ssh/ssh_host_ecdsa_key
  1639. .It Pa /etc/ssh/ssh_host_ed25519_key
  1640. .It Pa /etc/ssh/ssh_host_rsa_key
  1641. These files contain the private parts of the host keys
  1642. and are used for host-based authentication.
  1643. .Pp
  1644. .It Pa /etc/ssh/ssh_known_hosts
  1645. Systemwide list of known host keys.
  1646. This file should be prepared by the
  1647. system administrator to contain the public host keys of all machines in the
  1648. organization.
  1649. It should be world-readable.
  1650. See
  1651. .Xr sshd 8
  1652. for further details of the format of this file.
  1653. .Pp
  1654. .It Pa /etc/ssh/sshrc
  1655. Commands in this file are executed by
  1656. .Nm
  1657. when the user logs in, just before the user's shell (or command) is started.
  1658. See the
  1659. .Xr sshd 8
  1660. manual page for more information.
  1661. .El
  1662. .Sh EXIT STATUS
  1663. .Nm
  1664. exits with the exit status of the remote command or with 255
  1665. if an error occurred.
  1666. .Sh SEE ALSO
  1667. .Xr scp 1 ,
  1668. .Xr sftp 1 ,
  1669. .Xr ssh-add 1 ,
  1670. .Xr ssh-agent 1 ,
  1671. .Xr ssh-keygen 1 ,
  1672. .Xr ssh-keyscan 1 ,
  1673. .Xr tun 4 ,
  1674. .Xr ssh_config 5 ,
  1675. .Xr ssh-keysign 8 ,
  1676. .Xr sshd 8
  1677. .Sh STANDARDS
  1678. .Rs
  1679. .%A S. Lehtinen
  1680. .%A C. Lonvick
  1681. .%D January 2006
  1682. .%R RFC 4250
  1683. .%T The Secure Shell (SSH) Protocol Assigned Numbers
  1684. .Re
  1685. .Pp
  1686. .Rs
  1687. .%A T. Ylonen
  1688. .%A C. Lonvick
  1689. .%D January 2006
  1690. .%R RFC 4251
  1691. .%T The Secure Shell (SSH) Protocol Architecture
  1692. .Re
  1693. .Pp
  1694. .Rs
  1695. .%A T. Ylonen
  1696. .%A C. Lonvick
  1697. .%D January 2006
  1698. .%R RFC 4252
  1699. .%T The Secure Shell (SSH) Authentication Protocol
  1700. .Re
  1701. .Pp
  1702. .Rs
  1703. .%A T. Ylonen
  1704. .%A C. Lonvick
  1705. .%D January 2006
  1706. .%R RFC 4253
  1707. .%T The Secure Shell (SSH) Transport Layer Protocol
  1708. .Re
  1709. .Pp
  1710. .Rs
  1711. .%A T. Ylonen
  1712. .%A C. Lonvick
  1713. .%D January 2006
  1714. .%R RFC 4254
  1715. .%T The Secure Shell (SSH) Connection Protocol
  1716. .Re
  1717. .Pp
  1718. .Rs
  1719. .%A J. Schlyter
  1720. .%A W. Griffin
  1721. .%D January 2006
  1722. .%R RFC 4255
  1723. .%T Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints
  1724. .Re
  1725. .Pp
  1726. .Rs
  1727. .%A F. Cusack
  1728. .%A M. Forssen
  1729. .%D January 2006
  1730. .%R RFC 4256
  1731. .%T Generic Message Exchange Authentication for the Secure Shell Protocol (SSH)
  1732. .Re
  1733. .Pp
  1734. .Rs
  1735. .%A J. Galbraith
  1736. .%A P. Remaker
  1737. .%D January 2006
  1738. .%R RFC 4335
  1739. .%T The Secure Shell (SSH) Session Channel Break Extension
  1740. .Re
  1741. .Pp
  1742. .Rs
  1743. .%A M. Bellare
  1744. .%A T. Kohno
  1745. .%A C. Namprempre
  1746. .%D January 2006
  1747. .%R RFC 4344
  1748. .%T The Secure Shell (SSH) Transport Layer Encryption Modes
  1749. .Re
  1750. .Pp
  1751. .Rs
  1752. .%A B. Harris
  1753. .%D January 2006
  1754. .%R RFC 4345
  1755. .%T Improved Arcfour Modes for the Secure Shell (SSH) Transport Layer Protocol
  1756. .Re
  1757. .Pp
  1758. .Rs
  1759. .%A M. Friedl
  1760. .%A N. Provos
  1761. .%A W. Simpson
  1762. .%D March 2006
  1763. .%R RFC 4419
  1764. .%T Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol
  1765. .Re
  1766. .Pp
  1767. .Rs
  1768. .%A J. Galbraith
  1769. .%A R. Thayer
  1770. .%D November 2006
  1771. .%R RFC 4716
  1772. .%T The Secure Shell (SSH) Public Key File Format
  1773. .Re
  1774. .Pp
  1775. .Rs
  1776. .%A D. Stebila
  1777. .%A J. Green
  1778. .%D December 2009
  1779. .%R RFC 5656
  1780. .%T Elliptic Curve Algorithm Integration in the Secure Shell Transport Layer
  1781. .Re
  1782. .Pp
  1783. .Rs
  1784. .%A A. Perrig
  1785. .%A D. Song
  1786. .%D 1999
  1787. .%O International Workshop on Cryptographic Techniques and E-Commerce (CrypTEC '99)
  1788. .%T Hash Visualization: a New Technique to improve Real-World Security
  1789. .Re
  1790. .Sh AUTHORS
  1791. OpenSSH is a derivative of the original and free
  1792. ssh 1.2.12 release by Tatu Ylonen.
  1793. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
  1794. Theo de Raadt and Dug Song
  1795. removed many bugs, re-added newer features and
  1796. created OpenSSH.
  1797. Markus Friedl contributed the support for SSH
  1798. protocol versions 1.5 and 2.0.