Date: Thu, 10 Apr 2014 20:37:05 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> 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 Message-ID: <201404102037.s3AKb52d024905@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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"</programlisting> steal user/password information or data transferred during the session. <application>OpenSSH</application> offers a variety of authentication and encryption methods to prevent this from - happening.</para> + happening. More information about + <application>OpenSSH</application> is available from <link + xlink:href="http://www.openssh.com/">http://www.openssh.com/</link>.</para>; - <para>This section describes how to use the built-in client + <para>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 - <acronym>SSH</acronym> server on a &os; system.</para> + <acronym>SSH</acronym> server on a &os; system. More + information is available in the man pages mentioned in this + chapter.</para> <sect2> <title>Using the SSH Client Utilities</title> @@ -2501,7 +2505,8 @@ Password for user@example.com: <userinpu version 2 if possible and will fall back to version 1 if the server does not support version 2. To force <command>ssh</command> to only use the specified protocol, include - <option>-1</option> or <option>-2</option>.</para> + <option>-1</option> or <option>-2</option>. Additional + options are described in &man.ssh.1;.</para> <indexterm> <primary>OpenSSH</primary> @@ -2532,6 +2537,11 @@ COPYRIGHT 100% |************* is fetched over the network, one or more of the file arguments takes the form <option>user@host:<path_to_remote_file></option>.</para> + + <para>To open an interactive session for copying files, use + <command>sftp</command>. Refer to &man.sftp.1; for a list of + available commands while in an <command>sftp</command> + session.</para> <sect3 xml:id="security-ssh-keygen"> <title>Key-based Authentication</title> @@ -2641,8 +2651,8 @@ Identity added: /usr/home/user/.ssh/id_d create a tunnel to encapsulate another protocol in an encrypted session.</para> - <para>The following command tells &man.ssh.1; to create a - tunnel for &man.telnet.1;:</para> + <para>The following command tells <command>ssh</command> to create a + tunnel for <application>telnet</application>:</para> <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5023:localhost:23 user@foo.example.com</replaceable></userinput> &prompt.user;</screen> @@ -2654,7 +2664,7 @@ Identity added: /usr/home/user/.ssh/id_d <term><option>-2</option></term> <listitem> - <para>Forces &man.ssh.1; to use version 2 to connect to + <para>Forces <command>ssh</command> to use version 2 to connect to the server.</para> </listitem> </varlistentry> @@ -2664,7 +2674,7 @@ Identity added: /usr/home/user/.ssh/id_d <listitem> <para>Indicates no command, or tunnel only. If omitted, - &man.ssh.1; initiates a normal session.</para> + <command>ssh</command> initiates a normal session.</para> </listitem> </varlistentry> @@ -2672,7 +2682,7 @@ Identity added: /usr/home/user/.ssh/id_d <term><option>-f</option></term> <listitem> - <para>Forces &man.ssh.1; to run in the + <para>Forces <command>ssh</command> to run in the background.</para> </listitem> </varlistentry> @@ -2699,24 +2709,25 @@ Identity added: /usr/home/user/.ssh/id_d <para>An <acronym>SSH</acronym> tunnel works by creating a listen socket on <systemitem>localhost</systemitem> on the - specified port. It then forwards any connections received - on the local host/port via the <acronym>SSH</acronym> - connection to the specified remote host and port.</para> - - <para>In the example, port <replaceable>5023</replaceable> on - <systemitem>localhost</systemitem> is forwarded to port - <replaceable>23</replaceable> on - <systemitem>localhost</systemitem> of the remote machine. - Since <replaceable>23</replaceable> is used by - &man.telnet.1;, this creates an encrypted &man.telnet.1; + specified <literal>localport</literal>. It then forwards any connections received + on <literal>localport</literal> via the <acronym>SSH</acronym> + connection to the specified <literal>remotehost:remoteport</literal>. + In the example, port <literal>5023</literal> on + the client is forwarded to port + <literal>23</literal> on + the remote machine. + Since port 23 is used by + <application>telnet</application>, this creates an encrypted <application>telnet</application> session through an <acronym>SSH</acronym> tunnel.</para> - <para>This can be used to wrap any number of insecure TCP - protocols such as SMTP, POP3, and FTP.</para> + <para>This method can be used to wrap any number of insecure <acronym>TCP</acronym> + protocols such as <acronym>SMTP</acronym>, + <acronym>POP3</acronym>, and <acronym>FTP</acronym>, as seen + in the following examples.</para> <example> - <title>Using &man.ssh.1; to Create a Secure Tunnel for - SMTP</title> + <title>Create a Secure Tunnel for + <acronym>SMTP</acronym></title> <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5025:localhost:25 user@mailserver.example.com</replaceable></userinput> user@mailserver.example.com's password: <userinput>*****</userinput> @@ -2727,7 +2738,7 @@ Escape character is '^]'. 220 mailserver.example.com ESMTP</screen> <para>This can be used in conjunction with - &man.ssh-keygen.1; and additional user accounts to create + <command>ssh-keygen</command> and additional user accounts to create a more seamless <acronym>SSH</acronym> 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 '^]'. </example> <example> - <title>Secure Access of a POP3 Server</title> + <title>Secure Access of a <acronym>POP3</acronym> Server</title> <para>In this example, there is an <acronym>SSH</acronym> 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 <acronym>POP3</acronym> server. To check email in a secure manner, create an <acronym>SSH</acronym> connection to the - <acronym>SSH</acronym> server, and tunnel through to the - mail server.</para> + <acronym>SSH</acronym> server and tunnel through to the + mail server:</para> <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>2110:mail.example.com:110 user@ssh-server.example.com</replaceable></userinput> user@ssh-server.example.com's password: <userinput>******</userinput></screen> <para>Once the tunnel is up and running, point the email - client to send POP3 requests to + client to send <acronym>POP3</acronym> requests to <systemitem>localhost</systemitem> on port 2110. This connection will be forwarded securely across the tunnel to <systemitem>mail.example.com</systemitem>.</para> </example> <example> - <title>Bypassing a Draconian Firewall</title> + <title>Bypassing a Firewall</title> - <para>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. + <para>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 <acronym>SSH</acronym> and web surfing. This prevents access to any other service which uses a port other than 22 or 80.</para> <para>The solution is to create an <acronym>SSH</acronym> connection to a machine outside of the network's firewall - and use it to tunnel to the desired service.</para> + and use it to tunnel to the desired service:</para> <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>8888:music.example.com:8000 user@unfirewalled-system.example.org</replaceable></userinput> user@unfirewalled-system.example.org's password: <userinput>*******</userinput></screen> @@ -2789,21 +2800,39 @@ user@unfirewalled-system.example.org's p <secondary>enabling</secondary> </indexterm> - <para>To see if &man.sshd.8; is enabled, check - <filename>/etc/rc.conf</filename> for this line:</para> + <para>In addition to providing built-in <acronym>SSH</acronym> + client utilities, a &os; system can be configured as an + <acronym>SSH</acronym> server, accepting connections from + other <acronym>SSH</acronym> clients.</para> + + <para>To see if <application>sshd</application> is enabled, check + <filename>/etc/rc.conf</filename> for this line and add it if + it is missing:</para> <programlisting>sshd_enable="YES"</programlisting> - <para>This will start &man.sshd.8;, the daemon program for + <para>This will start <application>sshd</application>, the daemon program for <application>OpenSSH</application>, the next time the system - initializes. Alternatively, it is possible to use - &man.service.8; to start <application>OpenSSH</application> + boots. To start it now:</para> <screen>&prompt.root; <userinput>service sshd start</userinput></screen> - <para>It is often a good idea to limit which users can log in - and from where using <literal>AllowUsers</literal>. For + <para>The first time <application>sshd</application> 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.</para> + + <para>Refer to &man.sshd.8; for the list of available options + when starting <application>sshd</application> and a more + complete discussion about authentication, the login process, + and the various configuration files.</para> + + <para>It is a good idea to limit which users can log into the + <acronym>SSH</acronym> server + and from where using the <literal>AllowUsers</literal> keyword + in the <application>OpenSSH</application> server configuration file. For example, to only allow <systemitem class="username">root</systemitem> to log in from <systemitem class="ipaddress">192.168.1.32</systemitem>, add @@ -2812,7 +2841,8 @@ user@unfirewalled-system.example.org's p <programlisting>AllowUsers root@192.168.1.32</programlisting> <para>To allow <systemitem class="username">admin</systemitem> - to log in from anywhere, list that username by itself:</para> + to log in from anywhere, list that user without specifying an + <acronym>IP</acronym> address:</para> <programlisting>AllowUsers admin</programlisting> @@ -2820,50 +2850,32 @@ user@unfirewalled-system.example.org's p so:</para> <programlisting>AllowUsers root@192.168.1.32 admin</programlisting> - - <note> - <para>It is important to list each user that needs to log into - this machine; otherwise, they will be locked out.</para> - </note> - <para>After making changes to - <filename>/etc/ssh/sshd_config</filename>, tell &man.sshd.8; + <filename>/etc/ssh/sshd_config</filename>, tell <application>sshd</application> to reload its configuration file by running:</para> <screen>&prompt.root; <userinput>service sshd reload</userinput></screen> - </sect2> - <sect2> - <title>Configuration</title> - - <indexterm> - <primary>OpenSSH</primary> - <secondary>configuration</secondary> - </indexterm> - - <para>The system-wide configuration files for both the - <application>OpenSSH</application> daemon and client reside - in <filename>/etc/ssh</filename>.</para> - - <para><filename>ssh_config</filename> configures the client - settings, while <filename>sshd_config</filename> configures - the daemon. Each file has its own manual page which describes - the available configuration options.</para> - </sect2> - - <sect2> - <title>Further Reading</title> - - <para>The <link - xlink:href="http://www.openssh.com/">OpenSSH</link>; - website.</para> - - <para>&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.</para> + <note> + <para>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 <application>OpenSSH</application> + 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.</para> + </note> - <para>&man.sshd.8;, &man.sftp-server.8;, and &man.sshd.config.5; - for server options.</para> + <tip> + <para>Don't confuse <filename>/etc/ssh/sshd_config</filename> + with <filename>/etc/ssh/ssh_config</filename> (note the extra + <literal>d</literal> 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,.</para> + </tip> </sect2> </sect1>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404102037.s3AKb52d024905>