Home | History | Annotate | Download | only in cygwin
      1 This package describes important Cygwin specific stuff concerning OpenSSH.
      2 
      3 The binary package is usually built for recent Cygwin versions and might
      4 not run on older versions.  Please check http://cygwin.com/ for information
      5 about current Cygwin releases.
      6 
      7 Build instructions are at the end of the file.
      8 
      9 ===========================================================================
     10 Important change since 3.7.1p2-2:
     11 
     12 The ssh-host-config file doesn't create the /etc/ssh_config and
     13 /etc/sshd_config files from builtin here-scripts anymore, but it uses
     14 skeleton files installed in /etc/defaults/etc.
     15 
     16 Also it now tries hard to create appropriate permissions on files.
     17 Same applies for ssh-user-config.
     18 
     19 After creating the sshd service with ssh-host-config, it's advisable to
     20 call ssh-user-config for all affected users, also already exising user
     21 configurations.  In the latter case, file and directory permissions are
     22 checked and changed, if requireed to match the host configuration.
     23 
     24 Important note for Windows 2003 Server users:
     25 ---------------------------------------------
     26 
     27 2003 Server has a funny new feature.  When starting services under SYSTEM
     28 account, these services have nearly all user rights which SYSTEM holds...
     29 except for the "Create a token object" right, which is needed to allow
     30 public key authentication :-(
     31 
     32 There's no way around this, except for creating a substitute account which
     33 has the appropriate privileges.  Basically, this account should be member
     34 of the administrators group, plus it should have the following user rights:
     35 
     36 	Create a token object
     37 	Logon as a service
     38 	Replace a process level token
     39 	Increase Quota
     40 
     41 The ssh-host-config script asks you, if it should create such an account,
     42 called "sshd_server".  If you say "no" here, you're on your own.  Please
     43 follow the instruction in ssh-host-config exactly if possible.  Note that
     44 ssh-user-config sets the permissions on 2003 Server machines dependent of
     45 whether a sshd_server account exists or not.
     46 ===========================================================================
     47 
     48 ===========================================================================
     49 Important change since 3.4p1-2:
     50 
     51 This version adds privilege separation as default setting, see
     52 /usr/doc/openssh/README.privsep.  According to that document the
     53 privsep feature requires a non-privileged account called 'sshd'.
     54 
     55 The new ssh-host-config file which is part of this version asks
     56 to create 'sshd' as local user if you want to use privilege
     57 separation.  If you confirm, it creates that NT user and adds
     58 the necessary entry to /etc/passwd.
     59 
     60 On 9x/Me systems the script just sets UsePrivilegeSeparation to "no"
     61 since that feature doesn't make any sense on a system which doesn't
     62 differ between privileged and unprivileged users.
     63 
     64 The new ssh-host-config script also adds the /var/empty directory
     65 needed by privilege separation.  When creating the /var/empty directory
     66 by yourself, please note that in contrast to the README.privsep document
     67 the owner sshould not be "root" but the user which is running sshd.  So,
     68 in the standard configuration this is SYSTEM.  The ssh-host-config script
     69 chowns /var/empty accordingly.
     70 ===========================================================================
     71 
     72 ===========================================================================
     73 Important change since 3.0.1p1-2:
     74 
     75 This version introduces the ability to register sshd as service on
     76 Windows 9x/Me systems.  This is done only when the options -D and/or
     77 -d are not given.
     78 ===========================================================================
     79 
     80 ===========================================================================
     81 Important change since 2.9p2:
     82 
     83 Since Cygwin is able to switch user context without password beginning
     84 with version 1.3.2, OpenSSH now allows to do so when it's running under
     85 a version >= 1.3.2. Keep in mind that `ntsec' has to be activated to
     86 allow that feature.
     87 ===========================================================================
     88 
     89 ===========================================================================
     90 Important change since 2.3.0p1:
     91 
     92 When using `ntea' or `ntsec' you now have to care for the ownership
     93 and permission bits of your host key files and your private key files.
     94 The host key files have to be owned by the NT account which starts
     95 sshd. The user key files have to be owned by the user. The permission
     96 bits of the private key files (host and user) have to be at least
     97 rw------- (0600)!
     98 
     99 Note that this is forced under `ntsec' only if the files are on a NTFS
    100 filesystem (which is recommended) due to the lack of any basic security
    101 features of the FAT/FAT32 filesystems.
    102 ===========================================================================
    103 
    104 If you are installing OpenSSH the first time, you can generate global config
    105 files and server keys by running
    106 
    107    /usr/bin/ssh-host-config
    108 
    109 Note that this binary archive doesn't contain default config files in /etc.
    110 That files are only created if ssh-host-config is started.
    111 
    112 If you are updating your installation you may run the above ssh-host-config
    113 as well to move your configuration files to the new location and to
    114 erase the files at the old location.
    115 
    116 To support testing and unattended installation ssh-host-config got
    117 some options:
    118 
    119 usage: ssh-host-config [OPTION]...
    120 Options:
    121     --debug  -d            Enable shell's debug output.
    122     --yes    -y            Answer all questions with "yes" automatically.
    123     --no     -n            Answer all questions with "no" automatically.
    124     --cygwin -c <options>  Use "options" as value for CYGWIN environment var.
    125     --port   -p <n>        sshd listens on port n.
    126     --pwd    -w <passwd>   Use "pwd" as password for user 'sshd_server'.
    127 
    128 Additionally ssh-host-config now asks if it should install sshd as a
    129 service when running under NT/W2K. This requires cygrunsrv installed.
    130 
    131 You can create the private and public keys for a user now by running
    132 
    133   /usr/bin/ssh-user-config
    134 
    135 under the users account.
    136 
    137 To support testing and unattended installation ssh-user-config got
    138 some options as well:
    139 
    140 usage: ssh-user-config [OPTION]...
    141 Options:
    142     --debug      -d        Enable shell's debug output.
    143     --yes        -y        Answer all questions with "yes" automatically.
    144     --no         -n        Answer all questions with "no" automatically.
    145     --passphrase -p word   Use "word" as passphrase automatically.
    146 
    147 Install sshd as daemon via cygrunsrv.exe (recommended on NT/W2K), via inetd
    148 (results in very slow deamon startup!) or from the command line (recommended
    149 on 9X/ME).
    150 
    151 If you start sshd as deamon via cygrunsrv.exe you MUST give the
    152 "-D" option to sshd. Otherwise the service can't get started at all.
    153 
    154 If starting via inetd, copy sshd to eg. /usr/sbin/in.sshd and add the
    155 following line to your inetd.conf file:
    156 
    157 ssh stream tcp nowait root /usr/sbin/in.sshd sshd -i
    158 
    159 Moreover you'll have to add the following line to your
    160 ${SYSTEMROOT}/system32/drivers/etc/services file:
    161 
    162    ssh         22/tcp          #SSH daemon
    163 
    164 Please note that OpenSSH does never use the value of $HOME to
    165 search for the users configuration files! It always uses the
    166 value of the pw_dir field in /etc/passwd as the home directory.
    167 If no home diretory is set in /etc/passwd, the root directory
    168 is used instead!
    169 
    170 You may use all features of the CYGWIN=ntsec setting the same
    171 way as they are used by Cygwin's login(1) port:
    172 
    173   The pw_gecos field may contain an additional field, that begins
    174   with (upper case!) "U-", followed by the domain and the username
    175   separated by a backslash.
    176   CAUTION: The SID _must_ remain the _last_ field in pw_gecos!
    177   BTW: The field separator in pw_gecos is the comma.
    178   The username in pw_name itself may be any nice name:
    179 
    180     domuser::1104:513:John Doe,U-domain\user,S-1-5-21-...
    181 
    182   Now you may use `domuser' as your login name with telnet!
    183   This is possible additionally for local users, if you don't like
    184   your NT login name ;-) You only have to leave out the domain:
    185 
    186     locuser::1104:513:John Doe,U-user,S-1-5-21-...
    187 
    188 Note that the CYGWIN=ntsec setting is required for public key authentication.
    189 
    190 SSH2 server and user keys are generated by the `ssh-*-config' scripts
    191 as well.
    192 
    193 If you want to build from source, the following options to
    194 configure are used for the Cygwin binary distribution:
    195 
    196 	--prefix=/usr \
    197 	--sysconfdir=/etc \
    198 	--libexecdir='${sbindir}' \
    199 	--localstatedir=/var \
    200 	--datadir='${prefix}/share' \
    201 	--mandir='${datadir}/man' \
    202 	--infodir='${datadir}/info'
    203 	--with-tcp-wrappers
    204 	--with-libedit
    205 
    206 If you want to create a Cygwin package, equivalent to the one
    207 in the Cygwin binary distribution, install like this:
    208 
    209 	mkdir /tmp/cygwin-ssh
    210 	cd ${builddir}
    211 	make install DESTDIR=/tmp/cygwin-ssh
    212 	cd ${srcdir}/contrib/cygwin
    213 	make cygwin-postinstall DESTDIR=/tmp/cygwin-ssh
    214 	cd /tmp/cygwin-ssh
    215 	find * \! -type d | tar cvjfT my-openssh.tar.bz2 -
    216 
    217 You must have installed the following packages to be able to build OpenSSH:
    218 
    219 - zlib
    220 - openssl-devel
    221 
    222 If you want to build with --with-tcp-wrappers, you also need the package
    223 
    224 - tcp_wrappers
    225 
    226 If you want to build with --with-libedit, you also need the package
    227 
    228 - libedit-devel
    229 
    230 Please send requests, error reports etc. to cygwin (a] cygwin.com.
    231 
    232 
    233 Have fun,
    234 
    235 Corinna Vinschen
    236 Cygwin Developer
    237 Red Hat Inc.
    238