From owner-svn-doc-head@FreeBSD.ORG Thu Apr 10 20:37:05 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id C7168730; Thu, 10 Apr 2014 20:37:05 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 98AE311B5; Thu, 10 Apr 2014 20:37:05 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3AKb5Dw024906; Thu, 10 Apr 2014 20:37:05 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3AKb52d024905; Thu, 10 Apr 2014 20:37:05 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404102037.s3AKb52d024905@svn.freebsd.org> From: Dru Lavigne Date: Thu, 10 Apr 2014 20:37:05 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44524 - head/en_US.ISO8859-1/books/handbook/security X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 10 Apr 2014 20:37:06 -0000 Author: dru Date: Thu Apr 10 20:37:05 2014 New Revision: 44524 URL: http://svnweb.freebsd.org/changeset/doc/44524 Log: Finish editorial review of OpenSSH chapter. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/security/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/security/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/security/chapter.xml Thu Apr 10 20:15:39 2014 (r44523) +++ head/en_US.ISO8859-1/books/handbook/security/chapter.xml Thu Apr 10 20:37:05 2014 (r44524) @@ -2454,12 +2454,16 @@ racoon_enable="yes" steal user/password information or data transferred during the session. OpenSSH offers a variety of authentication and encryption methods to prevent this from - happening. + happening. More information about + OpenSSH is available from http://www.openssh.com/. - This section describes how to use the built-in client + This section provides an overview of the built-in client utilities to securely access other systems and securely transfer files from a &os; system. It then describes how to configure a - SSH server on a &os; system. + SSH server on a &os; system. More + information is available in the man pages mentioned in this + chapter. Using the SSH Client Utilities @@ -2501,7 +2505,8 @@ Password for user@example.com: ssh to only use the specified protocol, include - or . + or . Additional + options are described in &man.ssh.1;. OpenSSH @@ -2532,6 +2537,11 @@ COPYRIGHT 100% |************* is fetched over the network, one or more of the file arguments takes the form . + + To open an interactive session for copying files, use + sftp. Refer to &man.sftp.1; for a list of + available commands while in an sftp + session. Key-based Authentication @@ -2641,8 +2651,8 @@ Identity added: /usr/home/user/.ssh/id_d create a tunnel to encapsulate another protocol in an encrypted session. - The following command tells &man.ssh.1; to create a - tunnel for &man.telnet.1;: + The following command tells ssh to create a + tunnel for telnet: &prompt.user; ssh -2 -N -f -L 5023:localhost:23 user@foo.example.com &prompt.user; @@ -2654,7 +2664,7 @@ Identity added: /usr/home/user/.ssh/id_d - Forces &man.ssh.1; to use version 2 to connect to + Forces ssh to use version 2 to connect to the server. @@ -2664,7 +2674,7 @@ Identity added: /usr/home/user/.ssh/id_d Indicates no command, or tunnel only. If omitted, - &man.ssh.1; initiates a normal session. + ssh initiates a normal session. @@ -2672,7 +2682,7 @@ Identity added: /usr/home/user/.ssh/id_d - Forces &man.ssh.1; to run in the + Forces ssh to run in the background. @@ -2699,24 +2709,25 @@ Identity added: /usr/home/user/.ssh/id_d An SSH tunnel works by creating a listen socket on localhost on the - specified port. It then forwards any connections received - on the local host/port via the SSH - connection to the specified remote host and port. - - In the example, port 5023 on - localhost is forwarded to port - 23 on - localhost of the remote machine. - Since 23 is used by - &man.telnet.1;, this creates an encrypted &man.telnet.1; + specified localport. It then forwards any connections received + on localport via the SSH + connection to the specified remotehost:remoteport. + In the example, port 5023 on + the client is forwarded to port + 23 on + the remote machine. + Since port 23 is used by + telnet, this creates an encrypted telnet session through an SSH tunnel. - This can be used to wrap any number of insecure TCP - protocols such as SMTP, POP3, and FTP. + This method can be used to wrap any number of insecure TCP + protocols such as SMTP, + POP3, and FTP, as seen + in the following examples. - Using &man.ssh.1; to Create a Secure Tunnel for - SMTP + Create a Secure Tunnel for + <acronym>SMTP</acronym> &prompt.user; ssh -2 -N -f -L 5025:localhost:25 user@mailserver.example.com user@mailserver.example.com's password: ***** @@ -2727,7 +2738,7 @@ Escape character is '^]'. 220 mailserver.example.com ESMTP This can be used in conjunction with - &man.ssh-keygen.1; and additional user accounts to create + ssh-keygen and additional user accounts to create a more seamless SSH tunneling environment. Keys can be used in place of typing a password, and the tunnels can be run as a separate @@ -2735,39 +2746,39 @@ Escape character is '^]'. - Secure Access of a POP3 Server + Secure Access of a <acronym>POP3</acronym> Server In this example, there is an SSH server that accepts connections from the outside. On the - same network resides a mail server running a POP3 server. + same network resides a mail server running a POP3 server. To check email in a secure manner, create an SSH connection to the - SSH server, and tunnel through to the - mail server. + SSH server and tunnel through to the + mail server: &prompt.user; ssh -2 -N -f -L 2110:mail.example.com:110 user@ssh-server.example.com user@ssh-server.example.com's password: ****** Once the tunnel is up and running, point the email - client to send POP3 requests to + client to send POP3 requests to localhost on port 2110. This connection will be forwarded securely across the tunnel to mail.example.com. - Bypassing a Draconian Firewall + Bypassing a Firewall - Some network administrators impose firewall rules - which filter both incoming and outgoing connections. For - example, it might limit access from remote machines to - ports 22 and 80 to only allow &man.ssh.1; and web surfing. + Some firewalls + filter both incoming and outgoing connections. For + example, a firewall might limit access from remote machines to + ports 22 and 80 to only allow SSH and web surfing. This prevents access to any other service which uses a port other than 22 or 80. The solution is to create an SSH connection to a machine outside of the network's firewall - and use it to tunnel to the desired service. + and use it to tunnel to the desired service: &prompt.user; ssh -2 -N -f -L 8888:music.example.com:8000 user@unfirewalled-system.example.org user@unfirewalled-system.example.org's password: ******* @@ -2789,21 +2800,39 @@ user@unfirewalled-system.example.org's p enabling - To see if &man.sshd.8; is enabled, check - /etc/rc.conf for this line: + In addition to providing built-in SSH + client utilities, a &os; system can be configured as an + SSH server, accepting connections from + other SSH clients. + + To see if sshd is enabled, check + /etc/rc.conf for this line and add it if + it is missing: sshd_enable="YES" - This will start &man.sshd.8;, the daemon program for + This will start sshd, the daemon program for OpenSSH, the next time the system - initializes. Alternatively, it is possible to use - &man.service.8; to start OpenSSH + boots. To start it now: &prompt.root; service sshd start - It is often a good idea to limit which users can log in - and from where using AllowUsers. For + The first time sshd starts on a + &os; system, the system's host keys will be automatically + created and the fingerprint will be displayed on the console. + Provide users with the fingerprint so that they can verify it + the first time they connect to the server. + + Refer to &man.sshd.8; for the list of available options + when starting sshd and a more + complete discussion about authentication, the login process, + and the various configuration files. + + It is a good idea to limit which users can log into the + SSH server + and from where using the AllowUsers keyword + in the OpenSSH server configuration file. For example, to only allow root to log in from 192.168.1.32, add @@ -2812,7 +2841,8 @@ user@unfirewalled-system.example.org's p AllowUsers root@192.168.1.32 To allow admin - to log in from anywhere, list that username by itself: + to log in from anywhere, list that user without specifying an + IP address: AllowUsers admin @@ -2820,50 +2850,32 @@ user@unfirewalled-system.example.org's p so: AllowUsers root@192.168.1.32 admin - - - It is important to list each user that needs to log into - this machine; otherwise, they will be locked out. - - After making changes to - /etc/ssh/sshd_config, tell &man.sshd.8; + /etc/ssh/sshd_config, tell sshd to reload its configuration file by running: &prompt.root; service sshd reload - - - Configuration - - - OpenSSH - configuration - - - The system-wide configuration files for both the - OpenSSH daemon and client reside - in /etc/ssh. - - ssh_config configures the client - settings, while sshd_config configures - the daemon. Each file has its own manual page which describes - the available configuration options. - - - - Further Reading - - The OpenSSH - website. - - &man.ssh.1;, &man.scp.1;, &man.ssh-keygen.1;, - &man.ssh-agent.1;, &man.ssh-add.1;, and &man.ssh.config.5; for - client options. + + When this keyword is used, it is important to list each user that needs to log into + this machine. Any user that is not specified in that line will be locked out. Also, the + keywords used in the OpenSSH + server configuration file are case-sensitive. If the + keyword is not spelled correctly, including its case, it will + be ignored. Always test changes to this file to make sure + that the edits are working as expected. Refer to + &man.sshd.config.5; to verify the spelling and use of the + available keywords. + - &man.sshd.8;, &man.sftp-server.8;, and &man.sshd.config.5; - for server options. + + Don't confuse /etc/ssh/sshd_config + with /etc/ssh/ssh_config (note the extra + d in the first filename). The first file + configures the server and the second file configures the + client. Refer to &man.ssh.config.5; for a listing of the + available client settings,. +