SSH 3.2.5 README
================

       Timo J. Rinne <[email protected]>
       Sami Lehtinen <[email protected]>
       January 15, 2003.

  See the file LICENSE for licensing terms.

  What is Secure Shell?
  ---------------------

  Secure Shell is a program to log into another computer over a
  network, to execute commands in a remote machine, and to move files
  from one machine to another.  It provides strong authentication and
  secure communications over insecure channels.  It is intended as a
  replacement for rlogin, rsh, rcp, and rdist.

  Important note
  --------------

  Read the NEWS file to find about any incompatible changes with
  previous versions. Usually these concern the configuration files. If you
  have already installed an earlier version of ssh2, you
  should definitely be aware of these issues. Read it now.

  What has changed since SSH1?
  ----------------------------

     - SSH has been 98% rewritten.

     - SSH now supports other key-exchange methods besides double-
       encrypting RSA key exchange. The current distribution comes with
       Diffie-Hellman key exchange.

     - SSH now has support for DSA and other public key algorithms
       besides RSA.

     - The protocol is more secure.

     - The protocol complies with the upcoming 'secsh' internet standard.

     - SSH now supports "subsystems", platform-independent modules that
       implement particular functions such as file transfers.

     - SSH now has built-in SOCKS support.

     - A new feature has been added: sftp, the secure file transfer
       protocol.


  Feedback
  --------

     You can report bugs via a Web form at

     http://www.ssh.com/support/contact/bug-report-shell.mpl

     Feature requests can also be submitted via

     http://www.ssh.com/support/contact/feature-request-shell.mpl

     Be sure to check the FAQ (included in the distribution) and
     KNOWN BUGS (see below) first! See also online documentation
     and FAQ at http://www.ssh.com/support/ssh/.

  Commercial Inquiries
  -------------------

     To purchase a commercial license, please visit our online store at
     http://www.ssh.com/company/sales/store/

     Also commercial evaluation versions with PKI support are available
     at http://www.ssh.com/support/downloads/

     For any queries concerning commercial company-wide use (such as
     availability and other ssh.com products), please submit an inquiry
     to our sales at http://www.ssh.com/company/sales/


SSH2 Binaries
=============

     ssh2            The SSH2 client.

     sshd2           The SSH2 daemon.

     sftp2           The SFTP client (needs ssh2). Type "?" in the
                     command line for help.

     sftp-server2    The SFTP server (executed by sshd2).

     scp2            The SCP client.

     ssh-keygen2     The utility for generating keys. Use -h for help.

     ssh-add2        Add identities to the authentication agent.

     ssh-agent2      The authentication agent.

     ssh-askpass2    X11 utility for querying passwords.

     ssh-signer2     A small program that signs "hostbased" authentication
                     packets. Executed by ssh2, and for proper function,
                     must be suid root. (This is done by 'make install'.)

     ssh-probe2      Program to probe a given network for ssh2
                     servers. See ssh-probe(1) and sshd2_config(5)
                     for MaxBroadcastsPerSecond.

     ssh-dummy-shell Can be used as a restricted shell when only file
                     transfer or tcp forwarding functionality is desired.

     ssh-certenroll2 A certificate enrollment client (only in
                     commercial distribution)

     sshd-check-conf A configuration checker utility for use with
                     sshd2

Installation
============

  1. uncompress the distribution
  ------------------------------

     % zcat ssh-3.x.y.tar.gz | tar xvf -

     or

     % tar zxvf ssh-3.x.y.tar.gz

     or

     % gunzip -c ssh-3.x.y.tar.gz | tar zvf -

     This should create a subdirectory ssh-3.x.y.

     % cd ssh-3.x.y


  2. compile ssh2
  ---------------

     Read the NOTES-section found in the end of this file.

     % ./configure
     % make

     If this fails, find and fix the problem. Report it
     via a Web form at

     http://www.ssh.com/support/contact/bug-report-shell.mpl

     Then try again. :-) Please see the section REPORTING BUGS
     for more information before submitting a bug report.

  3. run the install script
  -------------------------

     Get a root shell and change to the ssh-3.x.y directory.

     # make install

     This should set everything up and create the host key.

     The old files are moved to *.old files. If you don't want them
     around, goto apps/ssh and run

     # make clean-up-old

     which will delete them.

     NOTE: This host key has relatively little entropy. We'll have
           to actually stir in more randomness to create strong
           keys (this is a problem, if your system doesn't have
           /dev/random). If your system doesn't have /dev/random, you
           might want to generate a couple of keys with ssh-keygen,
           and after that install a new hostkey. We'll fix this later.


  4. configure sshd2
  ------------------

     Set up the following files:


ssh2 files
===========

     Public keys have a .pub suffix, private keys have no suffix.
     For example:

        id_dsa_1024_a        A 1024-bit DSA private key
        id_dsa_1024_a.pub    The corresponding public key

     There is no "known_hosts", as in ssh1. The host keys are stored
     in separate files in ~/.ssh2/hostkeys .


  ~/.ssh2/hostkeys/key_xxxx_yyyy.pub
  -----------------------------

     This would be the public host key of the ssh2 daemon running in
     port xxxx of the host yyyy.


  /etc/ssh2/hostkey.pub  and  /etc/ssh2/hostkey
  -----------------------------------------

     Public and private hostkeys for sshd2. Created by "make install".
     If this is not created by "make install" or you need to recreate
     your host keypair, run

     # rm /etc/ssh2/hostkey*
     # ssh-keygen2 -P /etc/ssh2/hostkey


  ~/.ssh2/identification
  ----------------------

     Lists the private keys that are offered to the server in public-key
     user authentication.

        # identification
        IdKey  id_dsa_1024_a

     This means that the private key in the file ~/.ssh2/id_dsa_1024_a
     is used for public key authentication. Use CertKey instead of IdKey
     if certificates are used (only in commercial distribution).


  ~/.ssh2/authorization
  ---------------------

     Lists the public keys that are accepted for authentication on
     this host.

        # authorization
        Key     id_dsa_1024_a.pub

     This means that anyone who holds the matching private key to the
     public key in the file $USER/.ssh2/id_dsa_1024_a.pub can log in
     as $USER.


  /etc/ssh2/sshd2_config
  --------------------

     The server configuration file, copied here by "make install".
     See the man page for details.

     The line:

        subsystem-sftp                  sftp-server

     means that when the subsystem "sftp" is requested, the
     command "sftp-server" is started. For example, if our sshd2_config
     reads:

        subsystem-quux                  echo "fim fam foo"

     the command "ssh2 host -s quux" would simply print the text
     "fim fam foo".


  ~/.ssh2/ssh2_config
  -------------------

      The client configuration file. See the global client config file
      ssh2_config in /etc/ssh2.


  ~/.ssh2/knownhosts/xxxxyyyy.pub
  -------------------------------

     These are the public host keys of the hosts that a user wants to
     log from using host based authentication (equivalent with SSH1's
     RhostsRSAAuthentication).

     Also, a user has to set up her/his ~/.shosts (which only SSH uses)
     or ~/.rhosts file (insecure, as it is also used by the r*-commands).
     If the username is the same in both hosts, it is adequate to put
     the public hostkey to /etc/ssh2/knownhosts and add the host's name to
     /etc/shosts.equiv (or /etc/hosts.equiv).

     xxxx denotes the hostname (FQDN) and yyyy the public key algorithm
     of the key.

     For example, zappa.foo.fi's hostkey algorithm is ssh-dss. The
     hostkey would be named

         zappa.foo.fi.ssh-dss.pub

     in the knownhosts directory.

     Possible values for publickey-algorithms are "ssh-dss" and
     "ssh-rsa" (without the quotes).


  /etc/ssh2/knownhosts/xxxxyyyy.pub
  ---------------------------------

     As above, but system-wide. These can be overridden by the user
     by putting a file with the same name to her/his ~/.ssh2/knownhosts
     directory.


  /etc/hosts.equiv and /etc/shosts.equiv
  --------------------------------------

     Used to check whether authentication from host is allowed using
     host based authentication. In its simplest form, the file contains
     host names, one per line.

     For more information, see 'man sshd2'.


  ~/.rhosts and ~/.shosts
  -----------------------

     This file contains host-username-pairs, separated by spaces, one
     per line. The given user from the specified host is allowed to
     log in without a password.

     For more information, see 'man ssh2' and 'man sshd2'.


Platforms
=========

       Officially supported platforms are listed on the product pages
       at http://www.ssh.com/products/security/ for example for SSH
       Secure Shell for Servers the list is available at

       http://www.ssh.com/products/security/secureshellserver/platforms.html


NOTES ON INSTALLATION AND USE
=============================

       * As of ssh-2.2.0, configuration file format and parameters
         for ssh2 and sshd2 are documented in ssh2_config(5) and
         sshd2_config(5), respectively. The split was done to make the
         man-pages more readable.

       * For detailed info on how to set up chrooted accounts, see
         the FAQ (included in this distribution).

       * If your system doesn't support non-blocking connect, or
         has a broken version of it, run ./configure with
         --enable-blocking-connect .

       * If you get errors when compiling assembler files, configure
         with --disable-asm and recompile.

       * compatibility with SSH1 works correctly ONLY IF your SSH1 version
         is 1.2.26 or better (1.2.33 is the latest). So be sure you have
         that!

       * If your Sun boots during a connect to sshd2, do the following:
         Fetch the latest patches from Sun, generate a new host key with
         the patched version, and try again. (Also, you might want to try
         --enable-blocking-connect etc.)

       * If configure complains 'configure: error: configuring with X
         but xauth not found - aborting', try

               ./configure --without-x

         or, add path of xauth to your PATH before running
         configure. You can find xauth's location like this:

               find / -name xauth

       * Use 'ssh-keygen -P' to create keys without passphrases
         (for use with rsync etc).

       * Configure option --disable-crypt-asm no longer exists
         (use --disable-asm instead).

       * If your sftp2 complains something like this: "Need basic
         cursor movement capability, using vt100", then no library
         containing tgetent() function was found when you ran
         ./configure . If you have a Linux system, then that is
         probably because you don't have either termcap-devel or
         ncurses-devel packages installed. If you want to get rid of
         the message, and/or to use some more exotic terminals
         capabilities, you should install either package. (A good
         place to look for those is your distribution's web-page.)

       * If you have trouble using X forwarding (X client application
         can't connect using the forwarded channel), verify that your X
         server's security policy isn't causing it. You can also try
         "ssh -X" (which will make ssh2 treat all X client applications
         as trusted (in the X11 SECURITY extension sense)), but this
         overrides the X servers security policy. If that fails, and
         you still can't use X forwarding, try configuring with
         --without-x11-security, which will cause ssh2 to behave as it
         used to (using xauth). The latter is the least secure way of
         using X forwarding.

KNOWN BUGS
==========

       * Assembler-optimizations don't compile on BSDI. Configure
         with --disable-asm. (as of 2.3.0, this is autodetected)

       * static building of sftp-server and ssh-dummy-shell is
         EXPERIMENTAL. If you use the static binaries, please try
         them before real use. (as of 3.2.0, static binaries are not
         needed in order to chroot sftp users, see FAQ)

REPORTING BUGS
==============

  Submit your bug reports using the web-form at

     http://www.ssh.com/support/contact/bug-report-shell.mpl

  When reporting bugs, follow the directions in the web form. Please
  attach at least the following information:

       a) your system type (preferably by running config.guess which
          is in the root of ssh2 sourcedir, and running the command
               % uname -a
               ).
       b) compiler and version number (e.g. gcc 2.95.2).

       c) detailed description of the bug

       d) how to repeat it

       e) config.log, which is left to the root of ssh2 sourcedir
          after running configure.

       f) possibly even make.log, if you've encountered a problem
          with compilation. You can do this by running the following
          sequence:

               % script make.log
               % make
                 [.... lots of output ...]
               % exit

          If your system doesn't have script, use shell redirects etc.
          For example, in Bourne shell-variants:

               % make > make.log 2>&1

                 or

               % make |& tee make.log

          Note that you need to redirect also stderr (2) to stdout (1).
          We need those warnings and errors to appear in the log too.

       g) Version number of the Secure Shell release (e.g. 3.0.0) that
          you're using.

REMEMBER
========

* Latest news about ssh can be found at

   http://www.ssh.org/


LEGAL ISSUES
============

See the file LICENSE for licensing and distribution conditions.
THERE IS NO WARRANTY FOR THIS PROGRAM.

In some countries, particularly Russia, Iraq, Pakistan, and France,
it may be illegal to use any encryption at all without a special permit.

This software may be freely imported into the United States; however,
the United States Government may consider re-exporting it a criminal
offense. Thus, if you are outside the US, please retrieve this
software from outside the US.

Note that any information and cryptographic algorithms used in this
software are publicly available on the Internet and at any major
bookstore, scientific library, or patent office worldwide.

SSH, SSH2 and Secure Shell are registered trademarks or trademarks
of SSH Communications Security.


THANKS
======
..to everyone who contributed to SSH2. If you feel that your name
should be in this list, please mail to [email protected]. The following names
are in no particular order.

       Dug Song
       Andreas Ley
       Troy Barbee
       Simon Burge
       Luigi Pugnetti
       Youki Kadobayashi
       Georgi Kuzmanov
       Hirotaka Yamamoto
       Martin Buchholz
       John David Anglin
       David Mansfield
       Goran Gajic
       Niko Tyni
       Eugene Krainov
       William C. Ray
       Andrew Libby
       Alexander Savelyev
       Aldo Ramos
       Sigurdur Asgeirsson
       Cedomir Igaly
       Jeremy Buhler
       Per Allansson
       Andre Cornelis van Veen
       Tom Woodburn
       Brian A May
       Horst von Brand
       John Riddoch
       Neil W Rickert
       Marina Buitrago
       Ian Duplisse
       Jeff P. Van Dyke
       Thorsten Schlichting
       Roger Cornelius
       Markus Gyger
       Gregor Mosheh
       Mike Brudenell
       Klaus Gottschalk
       Stephen Harpster
       Tan-Sheng Li
       Tim Rice
       Carl Nobile
       Andy Polyakov
       Robbert Heederik
       Mats Andersson
       Richard E. Silverman
       Bernd Porr
       Markus Germeier
       Doug Neuhauser
       Greg A. Woods
       Ric Anderson
       Andrew G. Morgan
       G. Lehnert
       Valdis Kletnieks
       Joseph Galbraith
       Roland Mainz
       Binesh Bannerjee
       Logan Gabriel
       Jo"rg Schilling
       Andrew Schultz

.. and everyone else who submitted bug reports, feature-requests and
patches.

/EOF/