git ssb

1
===== sslh -- A ssl/ssh multiplexer. =====
2
3
Sslh accepts connections on specified ports, and forwards
4
them further based on tests performed on the first data
5
packet sent by the remote client.
6
7
Probes for HTTP, SSL, SSH, OpenVPN, tinc, XMPP are
8
implemented, and any other protocol that can be tested using
9
a regular expression, can be recognised. A typical use case
10
is to allow serving several services on port 443 (e.g. to
11
connect to ssh from inside a corporate firewall, which
12
almost never block port 443) while still serving HTTPS on
13
that port. 
14
15
Hence sslh acts as a protocol demultiplexer, or a
16
switchboard. Its name comes from its original function to
17
serve SSH and HTTPS on the same port.
18
19
==== Compile and install ====
20
21
sslh uses libconfig (http://www.hyperrealm.com/libconfig/)
22
and libwrap.
23
24
For Debian, these are contained in packages libwrap0-dev and
25
libconfig8-dev.  
26
27
For OpenSUSE, these are contained in packages libconfig9 and
28
libconfig-dev in repository
29
http://download.opensuse.org/repositories/multimedia:/libs/openSUSE_12.1/
30
31
For Fedora, this package should work:
32
https://admin.fedoraproject.org/pkgdb/acls/name/libconfig
33
(feedback from Fedorans appreciated).
34
35
If you can't find libconfig, or just don't want a
36
configuration file, set 'USELIBCONFIG=' in the Makefile.
37
38
After this, the Makefile should work:
39
40
make install
41
42
There are a couple of configuration options at the beginning
43
of the Makefile: 
44
45
    USELIBWRAP compiles support for host access control (see
46
    hosts_access(3)), you will need libwrap headers and
47
    library to compile (libwrap0-dev in Debian).
48
49
    USELIBCONFIG compiles support for the configuration
50
    file. You will need libconfig headers to compile
51
    (libconfig8-dev in Debian).
52
53
The Makefile produces two different executables: sslh-fork
54
and sslh-select. 
55
56
sslh-fork forks a new process for each incoming connection.
57
It is well-tested and very reliable, but incurs the overhead
58
of many processes.  sslh-select uses only one thread, which
59
monitors all connections at once. It is more recent and less
60
tested, but only incurs a 16 byte overhead per connection.
61
Also, if it stops, you'll lose all connections, which means
62
you can't upgrade it remotely.
63
64
If you are going to use sslh for a "small" setup (less than
65
a dozen ssh connections and a low-traffic https server) then
66
sslh-fork is probably more suited for you. If you are going
67
to use sslh on a "medium" setup (a few thousand ssh
68
connections, and another few thousand ssl connections),
69
sslh-select will be better. If you have a very large site
70
(tens of thousands of connections), you'll need a vapourware
71
version that would use libevent or something like that.
72
73
74
To install:
75
76
make
77
cp sslh-fork /usr/local/sbin/sslh
78
cp scripts/etc.default.sslh /etc/default/sslh
79
80
For Debian:
81
cp scripts/etc.init.d.sslh /etc/init.d/sslh
82
For CentOS:
83
cp scripts/etc.rc.d.init.d.sslh /etc/rc.d/init.d/sslh
84
85
and probably create links in /etc/rc<x>.d so that the server
86
start automatically at boot-up, e.g. under Debian:
87
update-rc.d sslh defaults
88
89
90
91
==== Configuration ====
92
93
You can edit settings in /etc/default/sslh:
94
95
LISTEN=ifname:443
96
SSH=localhost:22
97
SSL=localhost:443
98
99
A good scheme is to use the external name of the machine in
100
$LISTEN, and bind httpd to localhost:443 (instead of all
101
binding to all interfaces): that way, https connections
102
coming from inside your network don't need to go through
103
sslh, and sslh is only there as a frontal for connections
104
coming from the internet.
105
106
Note that 'external name' in this context refers to the
107
actual IP address of the machine as seen from your network,
108
i.e. that that is not 127.0.0.1 in the output of
109
ifconfig(8).
110
111
==== Libwrap support ====
112
113
Sslh can optionnaly perform libwrap checks for the sshd
114
service: because the connection to sshd will be coming
115
locally from sslh, sshd cannot determine the IP of the
116
client.
117
118
==== OpenVPN support ====
119
120
OpenVPN clients connecting to OpenVPN running with
121
-port-share reportedly take more than one second between
122
the time the TCP connexion is established and the time they
123
send the first data packet. This results in sslh with
124
default settings timing out and assuming an SSH connexion.
125
To support OpenVPN connexions reliably, it is necessary to
126
increase sslh's timeout to 5 seconds.
127
128
Instead of using OpenVPN's port sharing, it is more reliable
129
to use sslh's -o option to get sslh to do the port sharing.
130
131
==== Using proxytunnel with sslh ====
132
133
If you are connecting through a proxy that checks that the
134
outgoing connection really is SSL and rejects SSH, you can
135
encapsulate all your traffic in SSL using proxytunnel (this
136
should work with corkscrew as well). On the server side you
137
receive the traffic with stunnel to decapsulate SSL, then
138
pipe through sslh to switch HTTP on one side and SSL on the
139
other.
140
141
In that case, you end up with something like this:
142
143
ssh -> proxytunnel -e --------ssh/ssl------> stunnel ---ssh---> sslh --> sshd
144
145
Web browser --------http/ssl------> stunnel ---http---> sslh --> http:80
146
147
Configuration goes like this:
148
149
On the server side, using stunnel3:
150
stunnel -f -p mycert.pem  -d thelonious:443 -l /usr/local/sbin/sslh -- sslh -i  --http localhost:80 --ssh localhost:22
151
152
stunnel options: -f for foreground/debugging, -p specifies
153
the key + certificate, -d specifies which interface and port
154
we're listening to for incoming connexions, -l summons sslh
155
in inetd mode.
156
157
sslh options: -i for inetd mode, --http to forward http
158
connexions to port 80, and SSH connexions to port 22.
159
160
==== IP_TPROXY support ====
161
162
There is a netfilter patch that adds an option to the Linux
163
TCP/IP stack to allow a program to set the source address
164
of an IP packet that it sends. This could let sslh set the
165
address of packets to that of the actual client, so that
166
sshd would see and log the IP address of the client, making
167
sslh transparent.
168
169
This is not, and won't be, implemented in sslh for the
170
following reasons (in increasing order of importance):
171
172
  * It's not vital: the real connecting IP address can be
173
    found in logs. Little gain.
174
  * It's Linux only: it means increased complexity for no
175
    gain to some users.
176
  * It's a patch: it means it'd only be useful to Linux
177
    users who compile their own kernel.
178
  * Only root can use the feature: that's a definite no-no.
179
    Sslh should not, must not, will never run as root.
180
181
This isn't to mean that it won't eventually get implemented,
182
when/if the feature finds its way into the main kernel and
183
it becomes usuable by non-root processes.
184
185
186
==== Comments? Questions? ====
187
188
You can subscribe to the sslh mailing list here:
189
http://rutschle.net/cgi-bin/mailman/listinfo/sslh
190
191
This mailing list should be used for discussion, feature
192
requests, and will be the prefered channel for
193
announcements.
194
195