README
1See http://www.openssh.com/txt/release-6.6 for the release notes.
2
3- A Japanese translation of this document and of the OpenSSH FAQ is
4- available at http://www.unixuser.org/~haruyama/security/openssh/index.html
5- Thanks to HARUYAMA Seigo <haruyama@unixuser.org>
6
7This is the port of OpenBSD's excellent OpenSSH[0] to Linux and other
8Unices.
9
10OpenSSH is based on the last free version of Tatu Ylonen's sample
11implementation with all patent-encumbered algorithms removed (to
12external libraries), all known security bugs fixed, new features
13reintroduced and many other clean-ups. OpenSSH has been created by
14Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo de Raadt,
15and Dug Song. It has a homepage at http://www.openssh.com/
16
17This port consists of the re-introduction of autoconf support, PAM
18support, EGD[1]/PRNGD[2] support and replacements for OpenBSD library
19functions that are (regrettably) absent from other unices. This port
20has been best tested on AIX, Cygwin, HP-UX, Linux, MacOS/X,
21NetBSD, OpenBSD, OpenServer, Solaris, Unicos, and UnixWare.
22
23This version actively tracks changes in the OpenBSD CVS repository.
24
25The PAM support is now more functional than the popular packages of
26commercial ssh-1.2.x. It checks "account" and "session" modules for
27all logins, not just when using password authentication.
28
29OpenSSH depends on Zlib[3], OpenSSL[4] and optionally PAM[5].
30
31There is now several mailing lists for this port of OpenSSH. Please
32refer to http://www.openssh.com/list.html for details on how to join.
33
34Please send bug reports and patches to the mailing list
35openssh-unix-dev@mindrot.org. The list is open to posting by
36unsubscribed users.Code contribution are welcomed, but please follow the
37OpenBSD style guidelines[6].
38
39Please refer to the INSTALL document for information on how to install
40OpenSSH on your system. There are a number of differences between this
41port of OpenSSH and F-Secure SSH 1.x, please refer to the OpenSSH FAQ[7]
42for details and general tips.
43
44Damien Miller <djm@mindrot.org>
45
46Miscellania -
47
48This version of OpenSSH is based upon code retrieved from the OpenBSD
49CVS repository which in turn was based on the last free sample
50implementation released by Tatu Ylonen.
51
52References -
53
54[0] http://www.openssh.com/faq.html
55[1] http://www.lothar.com/tech/crypto/
56[2] http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html
57[3] http://www.gzip.org/zlib/
58[4] http://www.openssl.org/
59[5] http://www.openpam.org
60 http://www.kernel.org/pub/linux/libs/pam/
61 (PAM also is standard on Solaris and HP-UX 11)
62[6] http://www.openbsd.org/cgi-bin/man.cgi?query=style&sektion=9
63[7] http://www.openssh.com/faq.html
64
65$Id: README,v 1.86 2014/02/27 23:03:53 djm Exp $
66
README.dns
1How to verify host keys using OpenSSH and DNS
2---------------------------------------------
3
4OpenSSH contains support for verifying host keys using DNS as described in
5draft-ietf-secsh-dns-05.txt. The document contains very brief instructions
6on how to use this feature. Configuring DNS is out of the scope of this
7document.
8
9
10(1) Server: Generate and publish the DNS RR
11
12To create a DNS resource record (RR) containing a fingerprint of the
13public host key, use the following command:
14
15 ssh-keygen -r hostname -f keyfile -g
16
17where "hostname" is your fully qualified hostname and "keyfile" is the
18file containing the public host key file. If you have multiple keys,
19you should generate one RR for each key.
20
21In the example above, ssh-keygen will print the fingerprint in a
22generic DNS RR format parsable by most modern name server
23implementations. If your nameserver has support for the SSHFP RR
24you can omit the -g flag and ssh-keygen will print a standard SSHFP RR.
25
26To publish the fingerprint using the DNS you must add the generated RR
27to your DNS zone file and sign your zone.
28
29
30(2) Client: Enable ssh to verify host keys using DNS
31
32To enable the ssh client to verify host keys using DNS, you have to
33add the following option to the ssh configuration file
34($HOME/.ssh/config or /etc/ssh/ssh_config):
35
36 VerifyHostKeyDNS yes
37
38Upon connection the client will try to look up the fingerprint RR
39using DNS. If the fingerprint received from the DNS server matches
40the remote host key, the user will be notified.
41
42
43 Jakob Schlyter
44 Wesley Griffin
45
46
47$OpenBSD: README.dns,v 1.2 2003/10/14 19:43:23 jakob Exp $
48
README.hpn
1Notes:
2
3NONE CIPHER:
4 To use the NONE option you must have the NoneEnabled switch set on the server
5 and you MUST have *both* NoneEnabled and NoneSwitch set to yes on the client.
6 The NONE feature works with ALL ssh subsystems (as far as we can tell)
7 as long as there is no tty allocated.
8 If a user uses the -T switch to prevent a tty being created the NONE cipher
9 will be disabled.
10
11
12PERFORMANCE:
13 The performance increase will only be as good as the network and TCP stack
14 tuning on the reciever side of the connection allows. As a rule of thumb a
15 user will need at least 10Mb/s connection with a 100ms RTT to see a doubling
16 of performance.
17 The HPN-SSH home page http://www.psc.edu/networking/projects/hpn-ssh
18 describes this in greater detail.
19
20
21BUFFER SIZES:
22- if HPN is disabled the receive buffer size will be set to the OpenSSH default
23 of 64K.
24
25- if a HPN system connects to a non-HPN system the receive buffer will
26 be set to the HPNBufferSize value. The default is 2MB but user adjustable.
27
28- If a HPN to HPN connection is established a number of different things might
29 happen based on the user options and conditions.
30
31 Conditions: HPNBufferSize NOT Set, TCPRcvBufPoll enabled, TCPRcvBuf NOT Set
32 Result: HPN Buffer Size = up to 64MB
33 This is the default state. The HPN buffer size will grow to a maximum of
34 64MB as the TCP receive buffer grows. The maximum HPN Buffer size of 64MB
35 is geared towards 10GigE transcontinental connections.
36
37 Conditions: HPNBufferSize NOT Set, TCPRcvBufPoll disabled, TCPRcvBuf NOT Set
38 Result: HPN Buffer Size = TCP receive buffer value.
39 Users on non-autotuning systesm should disable TCPRcvBufPoll in the
40 ssh_cofig and sshd_config
41
42 Conditions: HPNBufferSize SET, TCPRcvBufPoll disabled, TCPRcvBuf NOT Set
43 Result: HPN Buffer Size = minmum of TCP receive buffer and HPNBufferSize.
44 This would be the system defined TCP receive buffer (RWIN).
45
46 Conditions: HPNBufferSize SET, TCPRcvBufPoll disabled, TCPRcvBuf SET
47 Result: HPN Buffer Size = minmum of TCPRcvBuf and HPNBufferSize.
48 Generally there is no need to set both.
49
50 Conditions: HPNBufferSize SET, TCPRcvBufPoll enabled, TCPRcvBuf NOT Set
51 Result: HPN Buffer Size = grows to HPNBufferSize
52 The buffer will grow up to the maximum size specified here.
53
54 Conditions: HPNBufferSize SET, TCPRcvBufPoll enabled, TCPRcvBuf SET
55 Result: HPN Buffer Size = minmum of TCPRcvBuf and HPNBufferSize.
56 Generally there is no need to set both of these, especially on autotuning
57 systems. However, if the users wishes to override the autotuning this would
58 be one way to do it.
59
60 Conditions: HPNBufferSize NOT Set, TCPRcvBufPoll enabled, TCPRcvBuf SET
61 Result: HPN Buffer Size = TCPRcvBuf.
62 This will override autotuning and set the TCP recieve buffer to the user
63 defined value.
64
65
66HPN SPECIFIC CONFIGURATION OPTIONS:
67
68- HPNDisabled=[yes/no] client/server
69 In some situations, such as transfers on a local area network, the impact
70 of the HPN code produces a net decrease in performance. In these cases it is
71 helpful to disable the HPN functionality. By default HPNDisabled is set to no.
72
73- HPNBufferSize=[int]KB client/server
74 This is the default buffer size the HPN functionality uses when interacting
75 with non-HPN SSH installations. Conceptually this is similar to the TcpRcvBuf
76 option as applied to the internal SSH flow control. This value can range from
77 1KB to 64MB (1-65536). Use of oversized or undersized buffers can cause
78 performance problems depending on the roud trip time of the network path.
79 The default size of this buffer is 2MB.
80
81- TcpRcvBufPoll=[yes/no] client/server
82 Enable or disable the polling of the TCP receive buffer through the life
83 of the connection. You would want to make sure that this option is enabled
84 for systems making use of autotuning kernels (linux 2.4.24+, 2.6, MS Vista,
85 FreeBSD 7.x and later). Default is yes.
86
87- TcpRcvBuf=[int]KB client
88 Set the TCP socket receive buffer to n Kilobytes. It can be set up to the
89 maximum socket size allowed by the system. This is useful in situations where
90 the TCP receive window is set low but the maximum buffer size is set higher
91 (as is typical). This works on a per TCP connection basis. You can also use
92 this to artifically limit the transfer rate of the connection. In these cases
93 the throughput will be no more than n/RTT. The minimum buffer size is 1KB.
94 Default is the current system wide TCP receive buffer size.
95
96- NoneEnabled=[yes/no] client/server
97 Enable or disable the use of the None cipher. Care must always be used when
98 enabling this as it will allow users to send data in the clear. However, it
99 is important to note that authentication information remains encrypted even
100 if this option is enabled. Set to no by default.
101
102- NoneSwitch=[yes/no] client
103 Switch the encryption cipher being used to the None cipher after
104 authentication takes place. NoneEnabled must be enabled on both the client
105 and server side of the connection. When the connection switches to the NONE
106 cipher a warning is sent to STDERR. The connection attempt will fail with an
107 error if a client requests a NoneSwitch from the server that does not
108 explicitly have NoneEnabled set to yes.
109 Note: The NONE cipher cannot be used in interactive (shell) sessions and it
110 will fail silently. Set to no by default.
111
112
113CREDITS:
114
115 This patch was conceived, designed, and led by Chris Rapier (rapier@psc.edu)
116 The majority of the actual coding for versions up to HPN12v1 was performed
117 by Michael Stevens (mstevens@andrew.cmu.edu).
118 The MT-AES-CTR cipher was implemented by Ben Bennet (ben@psc.edu).
119 This work was financed, in part, by Cisco System, Inc., the National Library
120 of Medicine, and the National Science Foundation.
121
README.platform
1This file contains notes about OpenSSH on specific platforms.
2
3AIX
4---
5As of OpenSSH 3.8p1, sshd will now honour an accounts password expiry
6settings, where previously it did not. Because of this, it's possible for
7sites that have used OpenSSH's sshd exclusively to have accounts which
8have passwords expired longer than the inactive time (ie the "Weeks between
9password EXPIRATION and LOCKOUT" setting in SMIT or the maxexpired
10chuser attribute).
11
12Accounts in this state must have their passwords reset manually by the
13administrator. As a precaution, it is recommended that the administrative
14passwords be reset before upgrading from OpenSSH <3.8.
15
16As of OpenSSH 4.0, configure will attempt to detect if your version
17and maintenance level of AIX has a working getaddrinfo, and will use it
18if found. This will enable IPv6 support. If for some reason configure
19gets it wrong, or if you want to build binaries to work on earlier MLs
20than the build host then you can add "-DBROKEN_GETADDRINFO" to CFLAGS
21to force the previous IPv4-only behaviour.
22
23IPv6 known to work: 5.1ML7 5.2ML2 5.2ML5
24IPv6 known broken: 4.3.3ML11 5.1ML4
25
26If you wish to use dynamic libraries that aren't in the normal system
27locations (eg IBM's OpenSSL and zlib packages) then you will need to
28define the environment variable blibpath before running configure, eg
29
30blibpath=/lib:/usr/lib:/opt/freeware/lib ./configure \
31 --with-ssl-dir=/opt/freeware --with-zlib=/opt/freeware
32
33If sshd is built with the WITH_AIXAUTHENTICATE option (which is enabled
34by default) then sshd checks that users are permitted via the
35loginrestrictions() function, in particular that the user has the
36"rlogin" attribute set. This check is not done for the root account,
37instead the PermitRootLogin setting in sshd_config is used.
38
39
40Cygwin
41------
42To build on Cygwin, OpenSSH requires the following packages:
43gcc, gcc-mingw-core, mingw-runtime, binutils, make, openssl,
44openssl-devel, zlib, minres, minires-devel.
45
46
47Darwin and MacOS X
48------------------
49Darwin does not provide a tun(4) driver required for OpenSSH-based
50virtual private networks. The BSD manpage still exists, but the driver
51has been removed in recent releases of Darwin and MacOS X.
52
53Nevertheless, tunnel support is known to work with Darwin 8 and
54MacOS X 10.4 in Point-to-Point (Layer 3) and Ethernet (Layer 2) mode
55using a third party driver. More information is available at:
56 http://www-user.rhrk.uni-kl.de/~nissler/tuntap/
57
58
59Linux
60-----
61
62Some Linux distributions (including Red Hat/Fedora/CentOS) include
63headers and library links in the -devel RPMs rather than the main
64binary RPMs. If you get an error about headers, or complaining about a
65missing prerequisite then you may need to install the equivalent
66development packages. On Redhat based distros these may be openssl-devel,
67zlib-devel and pam-devel, on Debian based distros these may be
68libssl-dev, libz-dev and libpam-dev.
69
70
71Solaris
72-------
73If you enable BSM auditing on Solaris, you need to update audit_event(4)
74for praudit(1m) to give sensible output. The following line needs to be
75added to /etc/security/audit_event:
76
77 32800:AUE_openssh:OpenSSH login:lo
78
79The BSM audit event range available for third party TCB applications is
8032768 - 65535. Event number 32800 has been choosen for AUE_openssh.
81There is no official registry of 3rd party event numbers, so if this
82number is already in use on your system, you may change it at build time
83by configure'ing --with-cflags=-DAUE_openssh=32801 then rebuilding.
84
85
86Platforms using PAM
87-------------------
88As of OpenSSH 4.3p1, sshd will no longer check /etc/nologin itself when
89PAM is enabled. To maintain existing behaviour, pam_nologin should be
90added to sshd's session stack which will prevent users from starting shell
91sessions. Alternatively, pam_nologin can be added to either the auth or
92account stacks which will prevent authentication entirely, but will still
93return the output from pam_nologin to the client.
94
95
96$Id: README.platform,v 1.10 2009/08/28 23:14:48 dtucker Exp $
97
README.privsep
1Privilege separation, or privsep, is method in OpenSSH by which
2operations that require root privilege are performed by a separate
3privileged monitor process. Its purpose is to prevent privilege
4escalation by containing corruption to an unprivileged process.
5More information is available at:
6 http://www.citi.umich.edu/u/provos/ssh/privsep.html
7
8Privilege separation is now enabled by default; see the
9UsePrivilegeSeparation option in sshd_config(5).
10
11On systems which lack mmap or anonymous (MAP_ANON) memory mapping,
12compression must be disabled in order for privilege separation to
13function.
14
15When privsep is enabled, during the pre-authentication phase sshd will
16chroot(2) to "/var/empty" and change its privileges to the "sshd" user
17and its primary group. sshd is a pseudo-account that should not be
18used by other daemons, and must be locked and should contain a
19"nologin" or invalid shell.
20
21You should do something like the following to prepare the privsep
22preauth environment:
23
24 # mkdir /var/empty
25 # chown root:sys /var/empty
26 # chmod 755 /var/empty
27 # groupadd sshd
28 # useradd -g sshd -c 'sshd privsep' -d /var/empty -s /bin/false sshd
29
30/var/empty should not contain any files.
31
32configure supports the following options to change the default
33privsep user and chroot directory:
34
35 --with-privsep-path=xxx Path for privilege separation chroot
36 --with-privsep-user=user Specify non-privileged user for privilege separation
37
38Privsep requires operating system support for file descriptor passing.
39Compression will be disabled on systems without a working mmap MAP_ANON.
40
41PAM-enabled OpenSSH is known to function with privsep on AIX, FreeBSD,
42HP-UX (including Trusted Mode), Linux, NetBSD and Solaris.
43
44On Cygwin, Tru64 Unix, OpenServer, and Unicos only the pre-authentication
45part of privsep is supported. Post-authentication privsep is disabled
46automatically (so you won't see the additional process mentioned below).
47
48Note that for a normal interactive login with a shell, enabling privsep
49will require 1 additional process per login session.
50
51Given the following process listing (from HP-UX):
52
53 UID PID PPID C STIME TTY TIME COMMAND
54 root 1005 1 0 10:45:17 ? 0:08 /opt/openssh/sbin/sshd -u0
55 root 6917 1005 0 15:19:16 ? 0:00 sshd: stevesk [priv]
56 stevesk 6919 6917 0 15:19:17 ? 0:03 sshd: stevesk@2
57 stevesk 6921 6919 0 15:19:17 pts/2 0:00 -bash
58
59process 1005 is the sshd process listening for new connections.
60process 6917 is the privileged monitor process, 6919 is the user owned
61sshd process and 6921 is the shell process.
62
63$Id: README.privsep,v 1.16 2005/06/04 23:21:41 djm Exp $
64
README.tun
1How to use OpenSSH-based virtual private networks
2-------------------------------------------------
3
4OpenSSH contains support for VPN tunneling using the tun(4) network
5tunnel pseudo-device which is available on most platforms, either for
6layer 2 or 3 traffic.
7
8The following brief instructions on how to use this feature use
9a network configuration specific to the OpenBSD operating system.
10
11(1) Server: Enable support for SSH tunneling
12
13To enable the ssh server to accept tunnel requests from the client, you
14have to add the following option to the ssh server configuration file
15(/etc/ssh/sshd_config):
16
17 PermitTunnel yes
18
19Restart the server or send the hangup signal (SIGHUP) to let the server
20reread it's configuration.
21
22(2) Server: Restrict client access and assign the tunnel
23
24The OpenSSH server simply uses the file /root/.ssh/authorized_keys to
25restrict the client to connect to a specified tunnel and to
26automatically start the related interface configuration command. These
27settings are optional but recommended:
28
29 tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... reyk@openbsd.org
30
31(3) Client: Configure the local network tunnel interface
32
33Use the hostname.if(5) interface-specific configuration file to set up
34the network tunnel configuration with OpenBSD. For example, use the
35following configuration in /etc/hostname.tun0 to set up the layer 3
36tunnel on the client:
37
38 inet 192.168.5.1 255.255.255.252 192.168.5.2
39
40OpenBSD also supports layer 2 tunneling over the tun device by adding
41the link0 flag:
42
43 inet 192.168.1.78 255.255.255.0 192.168.1.255 link0
44
45Layer 2 tunnels can be used in combination with an Ethernet bridge(4)
46interface, like the following example for /etc/bridgename.bridge0:
47
48 add tun0
49 add sis0
50 up
51
52(4) Client: Configure the OpenSSH client
53
54To establish tunnel forwarding for connections to a specified
55remote host by default, use the following ssh client configuration for
56the privileged user (in /root/.ssh/config):
57
58 Host sshgateway
59 Tunnel yes
60 TunnelDevice 0:any
61 PermitLocalCommand yes
62 LocalCommand sh /etc/netstart tun0
63
64A more complicated configuration is possible to establish a tunnel to
65a remote host which is not directly accessible by the client.
66The following example describes a client configuration to connect to
67the remote host over two ssh hops in between. It uses the OpenSSH
68ProxyCommand in combination with the nc(1) program to forward the final
69ssh tunnel destination over multiple ssh sessions.
70
71 Host access.somewhere.net
72 User puffy
73 Host dmzgw
74 User puffy
75 ProxyCommand ssh access.somewhere.net nc dmzgw 22
76 Host sshgateway
77 Tunnel Ethernet
78 TunnelDevice 0:any
79 PermitLocalCommand yes
80 LocalCommand sh /etc/netstart tun0
81 ProxyCommand ssh dmzgw nc sshgateway 22
82
83The following network plan illustrates the previous configuration in
84combination with layer 2 tunneling and Ethernet bridging.
85
86+--------+ ( ) +----------------------+
87| Client |------( Internet )-----| access.somewhere.net |
88+--------+ ( ) +----------------------+
89 : 192.168.1.78 |
90 :............................. +-------+
91 Forwarded ssh connection : | dmzgw |
92 Layer 2 tunnel : +-------+
93 : |
94 : |
95 : +------------+
96 :......| sshgateway |
97 | +------------+
98--- real connection Bridge -> | +----------+
99... "virtual connection" [ X ]--------| somehost |
100[X] switch +----------+
101 192.168.1.25
102
103(5) Client: Connect to the server and establish the tunnel
104
105Finally connect to the OpenSSH server to establish the tunnel by using
106the following command:
107
108 ssh sshgateway
109
110It is also possible to tell the client to fork into the background after
111the connection has been successfully established:
112
113 ssh -f sshgateway true
114
115Without the ssh configuration done in step (4), it is also possible
116to use the following command lines:
117
118 ssh -fw 0:1 sshgateway true
119 ifconfig tun0 192.168.5.1 192.168.5.2 netmask 255.255.255.252
120
121Using OpenSSH tunnel forwarding is a simple way to establish secure
122and ad hoc virtual private networks. Possible fields of application
123could be wireless networks or administrative VPN tunnels.
124
125Nevertheless, ssh tunneling requires some packet header overhead and
126runs on top of TCP. It is still suggested to use the IP Security
127Protocol (IPSec) for robust and permanent VPN connections and to
128interconnect corporate networks.
129
130 Reyk Floeter
131
132$OpenBSD: README.tun,v 1.4 2006/03/28 00:12:31 deraadt Exp $
133