[project @ 2003-06-03 11:44:28 by simonpj]

Windows ssh info

diff --git a/docs/building/building.sgml b/docs/building/building.sgml
index 30353c5..9765ba3 100644 (file)
--- a/docs/building/building.sgml
+++ b/docs/building/building.sgml
@@ -240,34 +240,10 @@
 
 
        <para>
-       [Windows users.] The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
-       seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
-       they ask for a password).  To solve this, start up <filename>cmd.exe</filename> 
-       and run it as follows:
-       <Screen>
-       c:\tmp> set CYGWIN32=tty
-       c:\tmp> c:/user/local/bin/ssh-keygen1
-       </Screen> </para>
+       <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"> about <command>ssh</command> wrinkles!</emphasis>
+         </para>
+
 
-           <para>[Windows users.] To protect your
-            <literal>.ssh</literal> from access by anyone else,
-            right-click your <literal>.ssh</literal> directory, and
-            select <literal>Properties</literal>.  If you are not on
-            the access control list, add yourself, and give yourself
-            full permissions (the second panel).  Remove everyone else
-            from the access control list.  Don't leave them there but
-            deny them access, because 'they' may be a list that
-            includes you!</para>
-           <para>[March 2003] In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
-             you to have Unix permissions 600 (read/write for owner only) 
-             on the <literal>.ssh/identity</literal> file, else it 
-             bombs out.  For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
-             but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).  
-             The solution seems to be to set the CYGWIN environment
-             variable to "<literal>ntsec neta</literal>".  The CYGWIN environment variable is discussed
-             in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
-             and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
-             </para>
          </listitem>
 
          <listitem>
@@ -4348,6 +4324,73 @@ variable.  You can always invoke <command>find</command> with an absolute path,
 
 </Sect2>
 
+<Sect2 id="configure-ssh"><Title>Configuring SSH</Title>
+
+<para><command>ssh</command> comes with Cygwin, provided you remember to ask for it when
+you install Cygwin.  (If not, the installer lets you update easily.)  Look for <command>openssh</command> 
+(not ssh) in the Cygwin list of applications!</para>
+
+<para>There are several strange things about <command>ssh</command> on Windows that you need to know.
+<itemizedlist>
+<listitem>
+<para>
+       The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
+       seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
+       they ask for a password).  To solve this, start up <filename>cmd.exe</filename> 
+       and run it as follows:
+       <Screen>
+       c:\tmp> set CYGWIN32=tty
+       c:\tmp> c:/user/local/bin/ssh-keygen1
+       </Screen> </para>
+</listitem>
+
+<listitem><para>
+<command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.  
+To determine your home directory <command>ssh</command> first looks in 
+<filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed).  If there's an entry
+there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
+the setting of the environment variable $HOME</emphasis>.  If the home directory is
+bogus, <command>ssh</command> fails horribly.   The best way to see what is going on is to say
+<programlisting>
+  ssh -v cvs.haskell.org
+</programlisting>
+which makes <command>ssh</command> print out information about its activity.
+</para>
+<para> You can fix this problem, either by correcting the home-directory field in 
+<filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
+you do that, <command>ssh</command> uses the $HOME environment variable instead.
+</para>
+
+</listitem>
+
+<listitem>
+           <para>To protect your
+            <literal>.ssh</literal> from access by anyone else,
+            right-click your <literal>.ssh</literal> directory, and
+            select <literal>Properties</literal>.  If you are not on
+            the access control list, add yourself, and give yourself
+            full permissions (the second panel).  Remove everyone else
+            from the access control list.  Don't leave them there but
+            deny them access, because 'they' may be a list that
+            includes you!</para>
+</listitem>
+
+<listitem>
+           <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
+             you to have Unix permissions 600 (read/write for owner only) 
+             on the <literal>.ssh/identity</literal> file, else it 
+             bombs out.  For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
+             but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).  
+             The solution seems to be to set the $CYGWIN environment
+             variable to "<literal>ntsec neta</literal>".  The $CYGWIN environment variable is discussed
+             in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
+             and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
+             </para>
+</listitem>
+</itemizedlist>
+</para>
+</sect2>
+
 <Sect2><Title>Other things you need to install</Title>
 
 <para>You have to install the following other things to build GHC: