SSH2 FREQUENTLY ASKED QUESTIONS
===============================

Author: Sami Lehtinen <sjl@ssh.com>
Copyright (C) 1997-2002 SSH Communications Security Corp, Helsinki, Finland

Last modified: $Date: 2002/05/07 21:12:39 $

See also the online FAQs http://www.ssh.com/faq/ .

Note: this FAQ is very, very incomplete. I will add questions and
answers to this FAQ, as questions of importance roll in.

Note2: this is the first FAQ I've written, so excuse me about the
style.

Contents:
1. Setup
 1.1: Q: How do I setup sshd2 to support tcp-wrappers?
 1.2: Q: How do I make sshd2 start at boot time?

2. User Setup
 2.1: Q: How do I setup public key authentication to a remote host?
 2.2: Q: How can I log into remote host xxx from host yyy without supplying
 	 a password/passphrase? 
 2.3: Q: How do I set up hostbased authentication?
 2.4: Q: How do I set up chrooted accounts (w/ restricted shell access, and
 	 only file transfer access) with sshd2?
 2.5: Q: How do I set up PAM authentication with sshd2?

3. SSH2 Features
 3.1: Q: Is <insert feature here>, which is supported in ssh1 supported in
 	 ssh2? If not, when will it be implemented?

4. Troubleshooting
 4.1: Q: When running sshd2 from inetd, it fails with a "Packet too long"
 	 error. What's wrong?
 4.2: Q: When connecting to a host, where I know I have an account, ssh2
 	 says "Disconnected; authentication error (No further authentication 
 	 methods available.)." (for ssh-2.0.13 server), or
 	 doesn't let me in, even when I type the correct password (for newer 
 	 servers). What's wrong?

1. Setup
========
1.1: 
Q: How do I setup sshd2 to support tcp-wrappers?

A: First, ./configure --with-libwrap and whatever flags you need. Make
   sure that configure finds your libwrap.a and tcpd.h files. Recompile.
   (Note that if you don't have your tcp-wrappers in a standard place, 
    you can give the path as argument to configure;
    --with-libwrap=/path/to/libwrap/)

   After this you can edit your /etc/hosts.allow and /etc/hosts.deny
   files. These "daemon" strings are in use by sshd2:
   
   sshd, sshd2           (The name sshd2 was called with (usually "sshd"))
   sshdfwd-X11           (if you want to allow/deny X11-forwarding)
   sshdfwd-<port-number> (for tcp-forwarding)
   sshdfwd-<port-name>   (port-name defined in /etc/services. Used in
   			   tcp-forwarding.) 

1.2:

Q: How do I make sshd2 start at boot time?

A: This varies greatly from system to system. In systems using System
   V initialization, you can put the "sshd2.startup" script, which came
   with this distribution, to /etc/rc.d/init.d (or equivalent; consult
   your system manual), and name it to your liking. Then, go to
   rc.$number directory (where $number is your default runlevel), and
   symlink the startup script to a name like "S90sshd2". After that go to 
   matching directories for runlevels halt and shutdown, and symlink the
   startup script to name like "K90sshd2" (the "S" means start, and "K"
   means kill). Now, during initialization process, the system calls the
   script with arguments "start" or "stop", depending on the situation.
   
   There is no need to reboot after these steps! You can start sshd2
   simply by typing
   
      # /etc/rc.d/init.d/sshd2 start

   If your system doesn't support this kind of initialization, you can 
   add a "/usr/local/sbin/sshd2" call somewhere to your rc.local script.


2. User Setup
=============

2.1:

Q: How do I setup public key authentication to a remote host?

A: In remote_host (this is the host where you want to connect to):
   Add the following line to file ~/.ssh2/authorization:
   
	key id_dsa_1024_a.pub #or whatever is your pub keys name

   In local_host (this is the host you want to connect from):
   Add the following line to ~/.ssh2/identification:
     
	idkey id_dsa_1024_a #or whatever is your private keys name

   You have to create your keypair in local_host, and transfer
   the .pub-part to remote_host to your $HOME/.ssh2/ there. Generate
   the keys using ssh-keygen (see 'man ssh-keygen' for details).


2.2:

Q: How can I log into remote host xxx from host yyy without supplying
   a password/passphrase? 

A: Use ssh-agent. You can also use null-passphrases, however this is
   NOT RECOMMENDED. You can setup ssh-agent in the following way (Note
   that these depend on your shell and X-config), for example:

   In file $HOME/.xsession (or equivalent) add the following line (and
   move the rest of the relevant stuff to .xsession.real):

	exec ssh-agent2 ./.xsession.real

   In file $HOME/.xsession.real do the real stuff (like spawning
   xterms, etc.) and add keys to the agent like this:

	ssh-add2 $HOME/.ssh2/id_dsa_1024_a </dev/null > /dev/null 2>&1

   Or, if you only have a shell account, you could add similar
   statements to your shell's startup file, like this (example
   is for zsh and .zshrc (should work also for sh and .profile)):

   In $HOME/.zshrc:

	if [ -z "$SSH2_AGENT_PID" ] then
	  eval `ssh-agent2`
	  ssh-add2 $HOME/.ssh2/id_dsa_1024_a
	fi

   With csh (or tcsh):

   In $HOME/.cshrc:

	if ( $?SSH2_AGENT_PID == 0 ) then
          eval `ssh-agent2 -c`
          ssh-add2 $HOME/.ssh2/id_dsa_1024_a
	endif

2.3:

Q: How do I set up hostbased authentication?

A: Best way to answer is by example (kudos to Anne for writing this):

   Megatron is the SSH server into which you're trying to connect. 
   MegatronUser is the username on the Server into which you'd like to login. 
   Optimus is the machine running a SSH client. 
   OptimusUser is the username on the Client that you'd like to allow to 
   login to the megatron as the Server User. 
   
   Step 1.
   
   Of course, install SSH on the Megatron and Optimus machines. Do not
   forget to install the hostkey. If your installation did this, or you 
   already have a copy of your /etc/ssh2/hostkey and /etc/ssh2/hostkey.pub,
   you do not need to do this:
   
       # ssh-keygen2 -P /etc/ssh2/hostkey
   
   Step 2 - SSH2
   
   Copy the Optimus's /etc/ssh2/hostkey.pub file over to Megatron and 
   name it to /etc/ssh2/knownhosts/optimus.ssh.com.ssh-dss.pub 
   
   You'll want to use the long hostname (the fully qualified hostname). 
   At least Linux can be a real pain if the system doesn't recognize
   the hostname as megatron.ssh.com and recognizes it as megatron.
   You can find this out while running sshd2 in verbose mode when trying
   to make connections.
   
   To make sure that Secure Shell finds your complete domain name, not
   just the hostname, you can make sure you change the following line
   in the configuration file /etc/ssh2/ssh2_config:
   
       DefaultDomain    your.domain.here
   
   This gives Megatron Optimus's public key so Megatron can verify 
   Optimus's identity based on a public key signature. By contrast,
   rsh only uses the IP address for authentication. 
   
   Step 3.
   
   On Megatron, create a file in the megatronUser's home directory named 
   ".shosts". The contents of this file should be the Optimus hostname, 
   some tabs or spaces, and the optimusUser username. 
   
   Contents of ~/.shosts:
       optimus.ssh.com    optimusUser
   
   Be sure to chown and chmod the .shosts file. The .shosts file must be 
   owned by the remote user and should be mode 0400. 
   
   Step 4 - SSH2. 
   
   Check the file /etc/ssh2/sshd2_config and make sure that
   AllowedAuthentications contains the word "hostbased" For example, it
   may read:
   
       AllowedAuthentications  hostbased,passwd
   
   It doesn't matter what's in there, just make sure that the hostbased
   variable is in the list somewhere. :)
   
   If you had to modify the sshd2_config file, you'll have to HUP the
   sshd to make the change take effect.
   
       # kill -HUP `cat /var/run/sshd2_22.pid`
   
   Step 5. 
   
   You should be all set. 
   
   On Optimus, log in as the ClientUser and try this:
   
       ssh megatronUser@Server uptime
   
   You should get back the results of "uptime" run on the remote server. 
   
   The first time you run ssh to that particular server, you'll have to 
   answer "yes" when asked if you want to connect to the server. This is
   because the local ssh doesn't yet have the remote server's SSH public 
   key. This will only happen the first time. 
   
   Troubleshooting
   
   With SSH2, did you name the hostkey file appropriately? It should be 
   /etc/ssh2/knownhosts/HOSTNAME.ssh-dss.pub and HOSTNAME may need to be 
   the short hostname or the long hostname. 
   
   - Did you copy the hostkey properly? 
   - Did it get mangled when you copied it over? 
   - Check your spelling in the .shosts file.
   - Make sure the .shosts file is owned by the megatronUser? 
   - Run the server with the -v flag (for ssh2). This is a great way to see 
     if a hostkey file is missing, or if something is misconfigured.

2.4:

Q: How do I set up chrooted accounts (with restricted shell access, and
   only file transfer access) with sshd2?

A: First, you should make sure that the static binaries of
   ssh-dummy-shell and sftp-server2 got compiled with the rest. The
   binaries are named (creatively) ssh-dummy-shell.static and
   sftp-server2.static.
   
   Then, run 
     % ssh-chrootmgr <username> ...
   
   This copies the binaries to the user's bin-directory ($HOME/bin) 
   (and creates the bin directory, if necessary).
   
   The next step is to add the user to the server's configuration file
   (/etc/ssh2/sshd2_config, usually). Use ChRootUsers or ChRootGroups
   variable. [Note: As of ssh-2.4 the group doesn't have to be the
   primary group, supplementary groups can be used as well.]
   
   After this you should change the user's login shell in /etc/passwd,
   with vipw, for example (or whatever you use to manage the
   accounts). The new shell should be /bin/ssh-dummy-shell (which, from
   the chrooted users perspective, will be the one in $HOME/bin).
   
   After this, restart the daemon, or kill -HUP it.

   Note: make sure, that there is a line

      subsystem-sftp      sftp-server

   in sshd2_config. Otherwise the user won't be able to do anything.

   NOTE: This doesn't work with Solaris. Solaris doesn't support this 
   kind of static linking. You have to use the normal binaries and copy
   the needed libraries to the user's environment too. Unfortunately we
   don't have a tool for that (yet).


2.5:

Q: How do I set up PAM authentication with sshd2?

A: To set up PAM Authentication on the server:
   1. Install the source 
   2. Move the pamd.sshd2 file in the source distribution is installed 
   in /etc/pam.d and renamed sshd2

   3. For the server config (/etc/ssh2/sshd2_config), make sure you have 
   this authentication method defined in either AllowedAuthentications or 
   RequiredAuthentications:

	AllowedAuthentications	keyboard-interactive

   and the "pam" submethod
  
        AuthKbdInt.Required pam

   To set up the client to connect to servers with PAM authentication:
   For the client config (/etc/ssh2/ssh2_config), make sure you have
   this authentication method defined in AllowedAuthentications:

	AllowedAuthentications	keyboard-interactive

   Restart the server and connect.

   If you wish to allow backwards compatibility for older versions, you
   should add "pam-1@ssh.com" to either AllowedAuthentications or
   RequiredAuthentications (the latter only in the server).

	AllowedAuthentications	keyboard-interactive,pam-1@ssh.com
   
   Some caveats:
   If you decide to use /etc/pam.conf instead of the /etc/pam.d files, use the 
   contents of the pamd.sshd2 in the source directory and prepend each line 
   with "sshd2" and a space before each line. See your operating system manual 
   for more details.

   For example, this line in the /etc/pam.d/sshd2:

   auth       required     /lib/security/pam_pwdb.so shadow

   Would be this line in the /etc/pam.conf:

   sshd2 auth       required     /lib/security/pam_pwdb.so shadow


3. SSH2 Features
================

3.1:

Q: Is <insert feature here>, which is supported in ssh1 supported in
   ssh2? If not, when will it be implemented?

A: RhostsAuthentication:
	Won't be implemented. Would be against the draft (at least in spirit).

   UseRsh:
	Won't be implemented. (look above)

   PAM:
        As of 2.4.

   Kerberos & SecurID:
        As of 2.3 (Kerberos5) and 2.4 (SecurID).

   UseLogin:
	will be in a future version.


4. Troubleshooting
==================

4.1:

Q: When running sshd2 from inetd, it fails with a "Packet too long"
   error. What's wrong?

A: Make sure you run sshd2 as "sshd2 -i" when starting it via inetd
   (without any debug parameters). Also, don't compile in tcp_wrapper
   support in this case (--with-libwrap=no). In almost every case this
   error manifests, it is because sshd2's stdin and stdout (given by
   inetd) are the stream that sshd2 handles, and if any debug messages
   etc. are put to that stream, the protocol gets messed up.

4.2:

Q: When connecting to a host, where I know I have an account, ssh2
   says "Disconnected; authentication error (No further authentication 
   methods available.)." (for ssh-2.0.13 server), or
   doesn't let me in, even when I type the correct password (for newer 
   servers). What's wrong?

A: The server is probably trying to check that the hostname you gave
   it has a valid DNS record. This is not case with most dialups etc. In
   older ssh2-versions, the default /etc/sshd2_config file had a
   statement "RequireReverseMapping yes", when, in fact, it should
   default to "no". Ask your sysadmin to change this, and see if the
   situation improves. If you still have problems, consult your sysadmin
   about the situation.
