openssh/contrib/cygwin/README

   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     --port       -p <n>    sshd listens on port n.
 125
 126 Additionally ssh-host-config now asks if it should install sshd as a
 127 service when running under NT/W2K. This requires cygrunsrv installed.
 128
 129 You can create the private and public keys for a user now by running
 130
 131   /usr/bin/ssh-user-config
 132
 133 under the users account.
 134
 135 To support testing and unattended installation ssh-user-config got
 136 some options as well:
 137
 138 usage: ssh-user-config [OPTION]...
 139 Options:
 140     --debug      -d        Enable shell's debug output.
 141     --yes        -y        Answer all questions with "yes" automatically.
 142     --no         -n        Answer all questions with "no" automatically.
 143     --passphrase -p word   Use "word" as passphrase automatically.
 144
 145 Install sshd as daemon via cygrunsrv.exe (recommended on NT/W2K), via inetd
 146 (results in very slow deamon startup!) or from the command line (recommended
 147 on 9X/ME).
 148
 149 If you start sshd as deamon via cygrunsrv.exe you MUST give the
 150 "-D" option to sshd. Otherwise the service can't get started at all.
 151
 152 If starting via inetd, copy sshd to eg. /usr/sbin/in.sshd and add the
 153 following line to your inetd.conf file:
 154
 155 ssh stream tcp nowait root /usr/sbin/in.sshd sshd -i
 156
 157 Moreover you'll have to add the following line to your
 158 ${SYSTEMROOT}/system32/drivers/etc/services file:
 159
 160    ssh         22/tcp          #SSH daemon
 161
 162 Please note that OpenSSH does never use the value of $HOME to
 163 search for the users configuration files! It always uses the
 164 value of the pw_dir field in /etc/passwd as the home directory.
 165 If no home diretory is set in /etc/passwd, the root directory
 166 is used instead!
 167
 168 You may use all features of the CYGWIN=ntsec setting the same
 169 way as they are used by Cygwin's login(1) port:
 170
 171   The pw_gecos field may contain an additional field, that begins
 172   with (upper case!) "U-", followed by the domain and the username
 173   separated by a backslash.
 174   CAUTION: The SID _must_ remain the _last_ field in pw_gecos!
 175   BTW: The field separator in pw_gecos is the comma.
 176   The username in pw_name itself may be any nice name:
 177
 178     domuser::1104:513:John Doe,U-domain\user,S-1-5-21-...
 179
 180   Now you may use `domuser' as your login name with telnet!
 181   This is possible additionally for local users, if you don't like
 182   your NT login name ;-) You only have to leave out the domain:
 183
 184     locuser::1104:513:John Doe,U-user,S-1-5-21-...
 185
 186 Note that the CYGWIN=ntsec setting is required for public key authentication.
 187
 188 SSH2 server and user keys are generated by the `ssh-*-config' scripts
 189 as well.
 190
 191 If you want to build from source, the following options to
 192 configure are used for the Cygwin binary distribution:
 193
 194         --prefix=/usr \
 195         --sysconfdir=/etc \
 196         --libexecdir='$(sbindir)' \
 197         --localstatedir=/var \
 198         --datadir='$(prefix)/share' \
 199         --mandir='$(datadir)/man' \
 200         --with-tcp-wrappers
 201
 202 If you want to create a Cygwin package, equivalent to the one
 203 in the Cygwin binary distribution, install like this:
 204
 205         mkdir /tmp/cygwin-ssh
 206         cd $(builddir)
 207         make install DESTDIR=/tmp/cygwin-ssh
 208         cd $(srcdir)/contrib/cygwin
 209         make cygwin-postinstall DESTDIR=/tmp/cygwin-ssh
 210         cd /tmp/cygwin-ssh
 211         find * \! -type d | tar cvjfT my-openssh.tar.bz2 -
 212
 213 You must have installed the zlib and openssl-devel packages to be able to
 214 build OpenSSH!
 215
 216 Please send requests, error reports etc. to cygwin@cygwin.com.
 217
 218 Have fun,
 219
 220 Corinna Vinschen
 221 Cygwin Developer
 222 Red Hat Inc.