debian/README.Debian

   1 OpenSSH for Debian
   2 ------------------
   3
   4 Although this package is widely referred to as OpenSSH, it is actually
   5 a branch of an early version of ssh which has been tidied up by the
   6 OpenBSD folks.
   7
   8 It has been decided that this version should have the privilege of
   9 carrying the ``ssh'' name in Debian, since it is the only version of
  10 ssh that is going to make it into Debian proper, being the only one
  11 that complies with the Debian Free Software Guidelines.
  12
  13 If you were expecting to get the non-free version of ssh (1.2.27 or
  14 whatever) when you installed this package, then you're out of luck, as
  15 Debian don't ship it.
  16
  17 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  18
  19 BUILD ISSUES
  20 ============
  21
  22 To build the openssh package for woody, set DEB_BUILD_SSH_WOODY=1 in
  23 your environment. This is necessary due to non-backward-compatible
  24 changes in PAM support.
  25
  26 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  27
  28 UPGRADE ISSUES
  29 ==============
  30
  31 Privilege Separation
  32 --------------------
  33
  34 As of 3.3, openssh has employed privilege separation to reduce the
  35 quantity of code that runs as root, thereby reducing the impact of
  36 some security holes in sshd. This now also works properly with PAM.
  37
  38 Privilege separation is turned on by default, so, if you decide you
  39 want it turned off, you need to add "UsePrivilegeSeparation no" to
  40 /etc/ssh/sshd_config.
  41
  42 PermitRootLogin set to yes
  43 --------------------------
  44
  45 This is now the default setting (in line with upstream), and people
  46 who asked for an automatically-generated configuration file when
  47 upgrading from potato (or on a new install) will have this setting in
  48 their /etc/ssh/sshd_config file.
  49
  50 Should you wish to change this setting, edit /etc/ssh/sshd_config, and
  51 change:
  52 PermitRootLogin yes
  53 to:
  54 PermitRootLogin no
  55
  56 Having PermitRootLogin set to yes means that an attacker that knows
  57 the root password can ssh in directly (without having to go via a user
  58 account). If you set it to no, then they must compromise a normal user
  59 account. In the vast majority of cases, this does not give added
  60 security; remember that any account you su to root from is equivalent
  61 to root - compromising this account gives an attacker access to root
  62 easily. If you only ever log in as root from the physical console,
  63 then you probably want to set this value to no.
  64
  65 As an aside, PermitRootLogin can also be set to "without-password" or
  66 "forced-commands-only" - see sshd(8) for more details.
  67
  68 DO NOT FILE BUG REPORTS SAYING YOU THINK THIS DEFAULT IS INCORRECT!
  69
  70 The argument above is somewhat condensed; I have had this discussion
  71 at great length with many people. If you think the default is
  72 incorrect, and feel strongly enough to want to argue about it, then
  73 send email to debian-ssh@lists.debian.org. I will close bug reports
  74 claiming the default is incorrect.
  75
  76 SSH now uses protocol 2 by default
  77 ----------------------------------
  78
  79 This means all your keyfiles you used for protocol version 1 need to
  80 be re-generated. The server keys are done automatically, but for RSA
  81 authentication, please read the ssh-keygen manpage.
  82
  83 If you have an automatically generated configuration file, and decide
  84 at a later stage that you do want to support protocol version 1 (not
  85 recommended, but note that the ssh client shipped with Debian potato
  86 only supported protocol version 1), then you need to do the following:
  87
  88 Change /etc/ssh/sshd_config such that:
  89 Protocol 2
  90 becomes:
  91 Protocol 2,1
  92 Also add the line:
  93 HostKey /etc/ssh/ssh_host_key
  94
  95 If you do not already have an RSA1 host key in /etc/ssh/ssh_host_key,
  96 you will need to generate one. To do so, run this command as root:
  97
  98   ssh-keygen -f /etc/ssh/ssh_host_key -N '' -t rsa1
  99
 100 As of openssh-server 1:4.1p1-2, the option to support protocol version 1
 101 is no longer available via debconf. You must edit the configuration file
 102 instead.
 103
 104 X11 Forwarding
 105 --------------
 106
 107 ssh's default for ForwardX11 has been changed to ``no'' because it has
 108 been pointed out that logging into remote systems administered by
 109 untrusted people is likely to open you up to X11 attacks, so you
 110 should have to actively decide that you trust the remote machine's
 111 root, before enabling X11.  I strongly recommend that you do this on a
 112 machine-by-machine basis, rather than just enabling it in the default
 113 host settings.
 114
 115 In order for X11 forwarding to work, you need to install xauth on the
 116 server. In Debian this is in the xbase-clients package.
 117
 118 As of OpenSSH 3.1, the remote $DISPLAY uses localhost by default to reduce
 119 the security risks of X11 forwarding. Look up X11UseLocalhost in
 120 sshd_config(8) if this is a problem.
 121
 122 OpenSSH 3.8 invented ForwardX11Trusted, which when set to no causes the
 123 ssh client to create an untrusted X cookie so that attacks on the
 124 forwarded X11 connection can't become attacks on X clients on the remote
 125 machine. However, this has some problems in implementation - notably a
 126 very short timeout of the untrusted cookie - breaks large numbers of
 127 existing setups, and generally seems immature. The Debian package
 128 therefore sets the default for this option to "yes" (in ssh itself,
 129 rather than in ssh_config).
 130
 131 Fallback to RSH
 132 ---------------
 133
 134 The default for this setting has been changed from Yes to No, for
 135 security reasons, and to stop the delay attempting to rsh to machines
 136 that don't offer the service.  Simply switch it back on in either
 137 /etc/ssh/ssh_config or ~/.ssh/config for those machines that you need
 138 it for.
 139
 140 Setgid ssh-agent and environment variables
 141 ------------------------------------------
 142
 143 As of version 1:3.5p1-1, ssh-agent is installed setgid to prevent ptrace()
 144 attacks retrieving private key material. This has the side-effect of causing
 145 glibc to remove certain environment variables which might have security
 146 implications for set-id programs, including LD_PRELOAD, LD_LIBRARY_PATH, and
 147 TMPDIR.
 148
 149 If you need to set any of these environment variables, you will need to do
 150 so in the program exec()ed by ssh-agent. This may involve creating a small
 151 wrapper script.
 152
 153 Symlink Hostname invocation
 154 ---------------------------
 155
 156 This version of ssh no longer includes support for invoking ssh with the
 157 hostname as the name of the file run.  People wanting this support should
 158 use the ssh-argv0 script.
 159
 160 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 161
 162 OTHER ISSUES
 163 ============
 164
 165 /usr/bin/ssh not SUID
 166 ---------------------
 167
 168 Due to Debian bug #164325, RhostsRSAAuthentication can only be used if ssh
 169 is SUID.  Until this is fixed, if that is a problem, use:
 170
 171    dpkg-statoverride
 172
 173 or if that's also missing, use this:
 174
 175    chown root.root /usr/bin/ssh
 176    chmod 04755 /usr/bin/ssh
 177
 178 Authorization Forwarding
 179 ------------------------
 180
 181 Similarly, root on a remote server could make use of your ssh-agent
 182 (while you're logged into their machine) to obtain access to machines
 183 which trust your keys.  This feature is therefore disabled by default.
 184 You should only re-enable it for those hosts (in your ~/.ssh/config or
 185 /etc/ssh/ssh_config) where you are confident that the remote machine
 186 is not a threat.
 187
 188 Problems logging in with RSA authentication
 189 -------------------------------------------
 190
 191 If you have trouble logging in with RSA authentication then the
 192 problem is probably caused by the fact that you have your home
 193 directory writable by group, as well as user (this is the default on
 194 Debian systems).
 195
 196 Depending upon other settings on your system (i.e. other users being
 197 in your group) this could open a security hole, so you will need to
 198 make your home directory writable only by yourself.  Run this command,
 199 as yourself:
 200
 201   chmod g-w ~/
 202
 203 to remove group write permissions.  If you use ssh-copy-id to install your
 204 keys, it does this for you.
 205
 206 -L option of ssh nonfree
 207 ------------------------
 208
 209 non-free ssh supported the usage of the option -L to use a non privileged
 210 port for scp. This option will not be supported by scp from openssh.
 211
 212 Please use instead scp -o "UsePrivilegedPort=no" as documented in the
 213 manpage to scp itself.
 214
 215 Problem logging in because of TCP-Wrappers
 216 ------------------------------------------
 217
 218 ssh is compiled with support for tcp-wrappers. So if you can no longer
 219 log into your system, please check that /etc/hosts.allow and /etc/hosts.deny
 220 are configured so that ssh is not blocked.
 221
 222 Kerberos support
 223 ----------------
 224
 225 ssh is now compiled with Kerberos support. Unfortunately, privilege
 226 separation is incompatible with Kerberos support for SSH protocol 1 and
 227 parts of the support for protocol 2; you may need to run kinit after logging
 228 in.
 229
 230 Interoperability between scp and the ssh.com SSH server
 231 -------------------------------------------------------
 232
 233 In version 2 and greater of the commercial SSH server produced by SSH
 234 Communications Security, scp was changed to use SFTP (SSH2's file transfer
 235 protocol) instead of the traditional rcp-over-ssh, thereby breaking
 236 compatibility. The OpenSSH developers regard this as a bug in the ssh.com
 237 server, and do not currently intend to change OpenSSH's scp to match.
 238
 239 Workarounds for this problem are to install scp1 on the server (scp2 will
 240 fall back to it), to use sftp, or to use some other transfer mechanism such
 241 as rsync-over-ssh or tar-over-ssh.
 242
 243 Running sshd from inittab
 244 -------------------------
 245
 246 Some people find it useful to run the sshd server from inittab, to make sure
 247 that it always stays running. To do this, stop sshd ('/etc/init.d/ssh
 248 stop'), add the following line to /etc/inittab, and run 'telinit q':
 249
 250   ss:2345:respawn:/usr/sbin/sshd -D
 251
 252 If you do this, note that you will need to stop sshd being started in the
 253 normal way ('rm -f /etc/rc[2345].d/S16ssh') and that you will need to
 254 restart this sshd manually on upgrades.
 255
 256 --
 257 Matthew Vernon
 258 <matthew@debian.org>
 259 and
 260 Colin Watson
 261 <cjwatson@debian.org>