summaryrefslogtreecommitdiff
path: root/debian/README.Debian
diff options
context:
space:
mode:
Diffstat (limited to 'debian/README.Debian')
-rw-r--r--debian/README.Debian295
1 files changed, 295 insertions, 0 deletions
diff --git a/debian/README.Debian b/debian/README.Debian
new file mode 100644
index 000000000..dbe6c2958
--- /dev/null
+++ b/debian/README.Debian
@@ -0,0 +1,295 @@
1OpenSSH for Debian
2------------------
3
4UPGRADE ISSUES
5==============
6
7PermitRootLogin
8---------------
9
10As of 1:6.6p1-1, new installations will be set to "PermitRootLogin
11without-password" (or the synonymous "PermitRootLogin prohibit-password" as
12of 1:7.1p1-1). This disables password authentication for root, foiling
13password dictionary attacks on the root user. Some sites may wish to use
14the stronger "PermitRootLogin forced-commands-only" or "PermitRootLogin no",
15but note that "PermitRootLogin no" will break setups that SSH to root with a
16forced command to take full-system backups. You can use PermitRootLogin in
17a Match block if you want finer-grained control here.
18
19For many years Debian's OpenSSH packaging used "PermitRootLogin yes", in
20line with upstream. To avoid breaking local setups, this is still true for
21installations upgraded from before 1:6.6p1-1. If you wish to change this,
22you should edit /etc/ssh/sshd_config, change it manually, and run "service
23ssh restart" as root.
24
25Disabling PermitRootLogin means that an attacker possessing credentials for
26the root account (any credentials in the case of "yes", or private key
27material in the case of "prohibit-password") must compromise a normal user
28account rather than being able to SSH directly to root. Be careful to avoid
29a false illusion of security if you change this setting; any account you
30escalate to root from should be considered equivalent to root for the
31purposes of security against external attack. You might for example disable
32it if you know you will only ever log in as root from the physical console.
33
34Since the root account does not generally have non-password credentials
35unless you explicitly install an SSH public key in its
36~/.ssh/authorized_keys, which you presumably only do if you want to SSH to
37it, "prohibit-password" should be a reasonable default for most sites.
38
39As of OpenSSH 7.0, this is the upstream default.
40
41For further discussion, see:
42
43 https://bugs.debian.org/298138
44 https://bugzilla.mindrot.org/show_bug.cgi?id=2164
45
46X11 Forwarding
47--------------
48
49ssh's default for ForwardX11 has been changed to ``no'' because it has
50been pointed out that logging into remote systems administered by
51untrusted people is likely to open you up to X11 attacks, so you
52should have to actively decide that you trust the remote machine's
53root, before enabling X11. I strongly recommend that you do this on a
54machine-by-machine basis, rather than just enabling it in the default
55host settings.
56
57In order for X11 forwarding to work, you need to install xauth on the
58server. In Debian this is in the xbase-clients package.
59
60As of OpenSSH 3.1, the remote $DISPLAY uses localhost by default to reduce
61the security risks of X11 forwarding. Look up X11UseLocalhost in
62sshd_config(8) if this is a problem.
63
64OpenSSH 3.8 invented ForwardX11Trusted, which when set to no causes the
65ssh client to create an untrusted X cookie so that attacks on the
66forwarded X11 connection can't become attacks on X clients on the remote
67machine. However, this has some problems in implementation - notably a
68very short timeout of the untrusted cookie - breaks large numbers of
69existing setups, and generally seems immature. The Debian package
70therefore sets the default for this option to "yes" (in ssh itself,
71rather than in ssh_config).
72
73Fallback to RSH
74---------------
75
76The default for this setting has been changed from Yes to No, for
77security reasons, and to stop the delay attempting to rsh to machines
78that don't offer the service. Simply switch it back on in either
79/etc/ssh/ssh_config or ~/.ssh/config for those machines that you need
80it for.
81
82Setgid ssh-agent and environment variables
83------------------------------------------
84
85As of version 1:3.5p1-1, ssh-agent is installed setgid to prevent ptrace()
86attacks retrieving private key material. This has the side-effect of causing
87glibc to remove certain environment variables which might have security
88implications for set-id programs, including LD_PRELOAD, LD_LIBRARY_PATH, and
89TMPDIR.
90
91If you need to set any of these environment variables, you will need to do
92so in the program exec()ed by ssh-agent. This may involve creating a small
93wrapper script.
94
95Symlink Hostname invocation
96---------------------------
97
98This version of ssh no longer includes support for invoking ssh with the
99hostname as the name of the file run. People wanting this support should
100use the ssh-argv0 script.
101
102=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
103
104OTHER ISSUES
105============
106
107Authorization Forwarding
108------------------------
109
110Similarly, root on a remote server could make use of your ssh-agent
111(while you're logged into their machine) to obtain access to machines
112which trust your keys. This feature is therefore disabled by default.
113You should only re-enable it for those hosts (in your ~/.ssh/config or
114/etc/ssh/ssh_config) where you are confident that the remote machine
115is not a threat.
116
117Problems logging in with RSA authentication
118-------------------------------------------
119
120If you have trouble logging in with RSA authentication then the
121problem is probably caused by the fact that you have your home
122directory writable by group, as well as user (this is the default on
123Debian systems).
124
125Depending upon other settings on your system (i.e. other users being
126in your group) this could open a security hole, so you will need to
127make your home directory writable only by yourself. Run this command,
128as yourself:
129
130 chmod g-w ~/
131
132to remove group write permissions. If you use ssh-copy-id to install your
133keys, it does this for you.
134
135-L option of ssh nonfree
136------------------------
137
138non-free ssh supported the usage of the option -L to use a non privileged
139port for scp. This option will not be supported by scp from openssh.
140
141Please use instead scp -o "UsePrivilegedPort=no" as documented in the
142manpage to scp itself.
143
144Problem logging in because of TCP-Wrappers
145------------------------------------------
146
147ssh is compiled with support for tcp-wrappers. So if you can no longer
148log into your system, please check that /etc/hosts.allow and /etc/hosts.deny
149are configured so that ssh is not blocked.
150
151Kerberos support
152----------------
153
154ssh is now compiled with Kerberos support. Unfortunately, privilege
155separation is incompatible with parts of Kerberos support for protocol 2;
156you may need to run kinit after logging in.
157
158Interoperability between scp and the ssh.com SSH server
159-------------------------------------------------------
160
161In version 2 and greater of the commercial SSH server produced by SSH
162Communications Security, scp was changed to use SFTP (SSH2's file transfer
163protocol) instead of the traditional rcp-over-ssh, thereby breaking
164compatibility. The OpenSSH developers regard this as a bug in the ssh.com
165server, and do not currently intend to change OpenSSH's scp to match.
166
167Workarounds for this problem are to install scp1 on the server (scp2 will
168fall back to it), to use sftp, or to use some other transfer mechanism such
169as rsync-over-ssh or tar-over-ssh.
170
171Running sshd from inittab
172-------------------------
173
174Some people find it useful to run the sshd server from inittab, to make sure
175that it always stays running. To do this, stop sshd ('service ssh stop'),
176add the following line to /etc/inittab, and run 'telinit q':
177
178 ss:2345:respawn:/usr/sbin/sshd -D
179
180If you do this, note that you will need to stop sshd being started in the
181normal way ('update-rc.d ssh disable') and that you will need to restart
182this sshd manually on upgrades.
183
184Per-connection sshd instances with systemd
185------------------------------------------
186
187If you want to reconfigure systemd to listen on port 22 itself and launch an
188instance of sshd for each connection (inetd-style socket activation), then
189you can run:
190
191 systemctl stop ssh.service
192 systemctl start ssh.socket
193
194To make this permanent:
195
196 systemctl disable ssh.service
197 systemctl enable ssh.socket
198
199This may be appropriate in environments where minimal footprint is critical
200(e.g. cloud guests). Be aware that this bypasses MaxStartups, and systemd's
201MaxConnections cannot quite replace this as it cannot distinguish between
202authenticated and unauthenticated connections; see
203https://bugzilla.redhat.com/show_bug.cgi?id=963268 for more discussion.
204
205The provided ssh.socket unit file sets ListenStream=22. If you need to have
206it listen on a different address or port, then you will need to do this as
207follows (modifying ListenStream to match your requirements):
208
209 mkdir -p /etc/systemd/system/ssh.socket.d
210 cat >/etc/systemd/system/ssh.socket.d/listen.conf <<EOF
211 [Socket]
212 ListenStream=2222
213 EOF
214 systemctl daemon-reload
215
216See systemd.socket(5) for details.
217
218Terminating SSH sessions cleanly on shutdown/reboot with systemd
219----------------------------------------------------------------
220
221If you have libpam-systemd >= 230 installed (following openssh-server's
222Recommends) and "UsePAM yes" in sshd_config (the default configuration
223shipped by this package), then SSH sessions will be terminated cleanly when
224the server is shut down or rebooted.
225
226If either of these conditions does not hold, then you may find that SSH
227sessions hang silently when the server is shut down or rebooted. If you do
228not want to use PAM or configure it properly for whatever reason, then you
229can instead copy
230/usr/share/doc/openssh-server/examples/ssh-session-cleanup.service to
231/etc/systemd/system/ and run "systemctl enable ssh-session-cleanup.service".
232
233Non-systemd users may find /usr/lib/openssh/ssh-session-cleanup helpful if
234they have a similar problem, although at present there is no system
235integration for this for anything other than systemd.
236
237SSH protocol 1 server support removed
238-------------------------------------
239
240sshd(8) no longer supports the old SSH protocol 1, so all the configuration
241options related to it are now deprecated and should be removed from
242/etc/ssh/sshd_config. These are:
243
244 KeyRegenerationInterval
245 RSAAuthentication
246 RhostsRSAAuthentication
247 ServerKeyBits
248
249The Protocol option is also no longer needed, although it is silently
250ignored rather than deprecated.
251
252if-up hook removed
253------------------
254
255openssh-server previously shipped an if-up hook that restarted sshd when a
256network interface came up. This generally caused more problems than it
257solved: for instance, it means that sshd stops listening briefly while being
258restarted, which can cause problems in some environments, particularly
259automated tests.
260
261The only known situation where the if-up hook was useful was when
262sshd_config was changed to add ListenAddress entries for particular IP
263addresses, overriding the default of listening on all addresses, and the
264system is one that often roams between networks. In such a situation, it is
265better to remove ListenAddress entries from sshd_config (restoring it to the
266default behaviour) and instead use firewall rules to restrict incoming SSH
267connections to only the desired interfaces or addresses.
268
269For further discussion, see:
270
271 https://bugs.launchpad.net/bugs/1674330
272
273IPQoS defaults reverted to pre-7.8 values
274-----------------------------------------
275
276OpenSSH 7.8 changed the default IPQoS settings to use DSCP AF21 for
277interactive traffic and CS1 for bulk. This caused some problems with other
278software ("iptables -m tos" and VMware), so Debian's OpenSSH reverts this
279change for the time being.
280
281This is *temporary*, and we expect to come back into sync with upstream
282OpenSSH once those other issues have been fixed. If you want to restore the
283upstream default, add this to ssh_config and sshd_config:
284
285 IPQoS af21 cs1
286
287For further discussion, see:
288
289 https://bugs.debian.org/923879
290 https://bugs.debian.org/926229
291 https://bugs.launchpad.net/1822370
292
293--
294Matthew Vernon <matthew@debian.org>
295Colin Watson <cjwatson@debian.org>