[deployment-guide/comm-rel: 21/41] Updated the Using the ssh Utility section.

[dsilas]

commit 72b91f243ad28d6817506fdec2eaeca5e5654dab
Author: Jaromir Hradilek <jhradile at redhat.com>
Date:   Tue Jul 13 14:07:12 2010 +0200

    Updated the Using the ssh Utility section.

 en-US/OpenSSH.xml |   56 ++++++++++++++++++++++++++++++++--------------------
 1 files changed, 34 insertions(+), 22 deletions(-)
---
diff --git a/en-US/OpenSSH.xml b/en-US/OpenSSH.xml
index 3bee379..0f973b7 100644
--- a/en-US/OpenSSH.xml
+++ b/en-US/OpenSSH.xml
@@ -549,17 +549,20 @@ It is also possible that the RSA host key has just been changed.</screen>
       </para>
     </section>
   </section>
-  <section id="s1-openssh-client-config">
-    <title>Configuring an OpenSSH Client</title>
+  <section id="s1-ssh-clients">
+    <title>OpenSSH Clients</title>
     <indexterm>
       <primary>OpenSSH</primary>
       <secondary>client</secondary>
     </indexterm>
-    <para>
-      To connect to an OpenSSH server from a client machine, you must have the <filename>openssh-clients</filename> and <filename>openssh</filename> packages installed on the client machine.
-    </para>
-    <section id="s2-openssh-using-ssh">
-      <title>Using the <command>ssh</command> Command</title>
+    <note>
+      <title>Note: Make Sure You Have Relevant Packages Installed</title>
+      <para>
+        To connect to an OpenSSH server from a client machine, you must have the <package>openssh-clients</package> and <package>openssh</package> packages installed.
+      </para>
+    </note>
+    <section id="s2-ssh-clients-ssh">
+      <title>Using the <command>ssh</command> Utility</title>
       <indexterm>
         <primary>
           <command>ssh</command>
@@ -574,35 +577,44 @@ It is also possible that the RSA host key has just been changed.</screen>
         </tertiary>
       </indexterm>
       <para>
-        The <command>ssh</command> command is a secure replacement for the <command>rlogin</command>, <command>rsh</command>, and <command>telnet</command> commands. It allows you to log in to a remote machine as well as execute commands on a remote machine.
+        <command>ssh</command> allows you to log in to a remote machine and execute commands there. It is a secure replacement for the <command>rlogin</command>, <command>rsh</command>, and <command>telnet</command> programs.
       </para>
       <para>
-        Logging in to a remote machine with <command>ssh</command> is similar to using <command>telnet</command>. To log in to a remote machine named penguin.example.net, type the following command at a shell prompt:
+        Similarly to <command>telnet</command>, to log in to a remote machine named <systemitem class="domainname">penguin.example.net</systemitem>, type the following command at a shell prompt:
       </para>
-      <screen>ssh penguin.example.net</screen>
+      <screen>~]$ <command>ssh penguin.example.com</command></screen>
       <para>
-        The first time you <command>ssh</command> to a remote machine, you will see a message similar to the following:
+        This will log you in with the same username you are using on a local machine. If you want to specify a different one, use the command in the <command>ssh <replaceable>username</replaceable>@<replaceable>hostname</replaceable></command> form. For example, to log in as <systemitem class="username">john</systemitem>, type:
       </para>
-      <screen>The authenticity of host 'penguin.example.net' can't be established.
-DSA key fingerprint is 94:68:3a:3a:bc:f3:9a:9b:01:5d:b3:07:38:e2:11:0c.
-Are you sure you want to continue connecting (yes/no)?</screen>
+      <screen>~]$ <command>ssh john at penguin.example.com</command></screen>
       <para>
-        Type <userinput>yes</userinput> to continue. This will add the server to your list of known hosts (<filename>~/.ssh/known_hosts</filename>) as seen in the following message:
+        The first time you initiate a connection, you will be presented with a message similar to this:
       </para>
-      <screen>Warning: Permanently added 'penguin.example.net' (RSA) to the list of known hosts.</screen>
+      <screen>The authenticity of host 'penguin.example.com' can't be established.
+RSA key fingerprint is 94:68:3a:3a:bc:f3:9a:9b:01:5d:b3:07:38:e2:11:0c.
+Are you sure you want to continue connecting (yes/no)?</screen>
       <para>
-        Next, you will see a prompt asking for your password for the remote machine. After entering your password, you will be at a shell prompt for the remote machine. If you do not specify a username the username that you are logged in as on the local client machine is passed to the remote machine. If you want to specify a different username, use the following command:
+        Type <userinput>yes</userinput> to confirm. You will see a notice that the server has been added to the list of known hosts, and a prompt asking for your password:
       </para>
-      <screen>ssh <replaceable>username</replaceable>@penguin.example.net</screen>
+      <screen>Warning: Permanently added 'penguin.example.net' (RSA) to the list of known hosts.
+john at penguin.example.net's password:</screen>
+      <important>
+        <title>Important</title>
+        <para>
+          If the SSH server's host key changes, the client notifies the user that the connection cannot proceed until the server's host key is deleted from the <filename>~/.ssh/known_hosts</filename> file. To do so, open the file in a text editor, and remove a line containing the remote machine name at the beginning. Before doing this, however, contact the system administrator of the SSH server to verify the server is not compromised.
+        </para>
+      </important>
       <para>
-        You can also use the syntax <command>ssh -l <replaceable>username</replaceable> penguin.example.net</command>.
+        After entering the password, you will be provided with a shell prompt for the remote machine.
       </para>
       <para>
-        The <command>ssh</command> command can be used to execute a command on the remote machine without logging in to a shell prompt. The syntax is <command> ssh <replaceable>hostname</replaceable> <replaceable>command</replaceable></command>. For example, if you want to execute the command <command>ls /usr/share/doc</command> on the remote machine penguin.example.net, type the following command at a shell prompt:
+        Alternatively, the <command>ssh</command> program can be used to execute a command on the remote machine without logging in to a shell prompt. The syntax for that is <command>ssh [<replaceable>username</replaceable>@]<replaceable>hostname</replaceable> <replaceable>command</replaceable></command>. For example, if you want to execute the command <command>whoami</command> on <systemitem class="domainname">penguin.example.com</systemitem>, type:
       </para>
-      <screen>ssh penguin.example.net ls /usr/share/doc</screen>
+      <screen>~]$ <command>ssh john at penguin.example.com whoami</command>
+john at penguin.example.com's password:
+john</screen>
       <para>
-        After you enter the correct password, the contents of the remote directory <filename>/usr/share/doc</filename> will be displayed, and you will return to your local shell prompt.
+        After you enter the correct password, the username will be displayed, and you will return to your local shell prompt.
       </para>
     </section>
     <section id="s2-openssh-using-scp">