Skip site navigation (1)Skip section navigation (2)
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:&lt;path_to_remote_file&gt;</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>