git ssb

1
# I'm just not gonna write troff :-)
2
3
=head1 NAME
4
5
 sslh - ssl/ssh multiplexer
6
7
=head1 SYNOPSIS
8
9
sslh [ B<-t> I<num> ] [B<-p> I<listening address> [B<-p> I<listening address> ...] [B<--ssl> I<target address for SSL>] [B<--ssh> I<target address for SSH>] [B<--openvpn> I<target address for OpenVPN>] [B<-u> I<username>] [B<-P> I<pidfile>] [-v] [-i] [-V] [-f] [-n]
10
11
=head1 DESCRIPTION
12
13
B<sslh> accepts HTTPS, SSH, OpenVPN, tinc and XMPP connections
14
on the same port. This makes it possible to connect to any
15
of these servers on port 443 (e.g. from inside a corporate
16
firewall, which almost never block port 443) while still
17
serving HTTPS on that port. 
18
19
20
The idea is to have B<sslh> listen to the external 443 port,
21
accept the incoming connections, work out what type of
22
connection it is, and then fordward to the appropriate
23
server.
24
25
=head2 Protocol detection
26
27
The protocol detection is made based on the first bytes sent
28
by the client: SSH connections start by identifying each
29
other's versions using clear text "SSH-2.0" strings (or
30
equivalent version strings). This is defined in RFC4253,
31
4.2. Meanwhile, OpenVPN clients start with 0x00 0x0D 0x38,
32
tinc clients start with "0 ", and XMPP client start with a
33
packet containing "jabber".
34
35
Additionally, two kind of SSH clients exist: the client
36
waits for the server to send its version string ("Shy"
37
client, which is the case of OpenSSH and Putty), or the
38
client sends its version first ("Bold" client, which is the
39
case of Bitvise Tunnelier and ConnectBot). 
40
41
B<sslh> waits for some time for the incoming connection to
42
send data. If it stays quiet after the timeout period, it is
43
assumed to be a shy SSH client, and is connected to the SSH
44
server. Otherwise, B<sslh> reads the first packet the client
45
provides, and connects it to the SSH server if it starts
46
with "SSH-", or connects it to the SSL server otherwise.
47
48
=head2 Libwrap support
49
50
One drawback of B<sslh> is that the B<ssh> and B<httpd>
51
servers do not see the original IP address of the client
52
anymore, as the connection is forwarded through B<sslh>.
53
B<sslh> provides enough logging to circumvent that problem.
54
However it is common to limit access to B<ssh> using
55
B<libwrap> or B<tcpd>. For this reason, B<sslh> can be
56
compiled to check SSH accesses against SSH access lists as
57
defined in F</etc/hosts.allow> and F</etc/hosts.deny>.
58
59
=head1 OPTIONS
60
61
=over 4
62
63
=item B<-t> I<num>, B<--timeout> I<num>
64
65
Timeout before a connection is considered to be SSH. Default
66
is 2s.
67
68
=item B<-p> I<listening address>, B<--listen> I<listening address>
69
70
Interface and port on which to listen, e.g. I<foobar:443>,
71
where I<foobar> is the name of an interface (typically the
72
IP address on which the Internet connection ends up).
73
74
This can be specified several times to bind B<sslh> to
75
several addresses.
76
77
=item B<--ssl> I<target address>
78
79
Interface and port on which to forward SSL connection,
80
typically I<localhost:443>.
81
82
Note that you can set B<sslh> to listen on I<ext_ip:443> and
83
B<httpd> to listen on I<localhost:443>: this allows clients
84
inside your network to just connect directly to B<httpd>.
85
86
=item B<--ssh> I<target address>
87
88
Interface and port on which to forward SSH connections,
89
typically I<localhost:22>.
90
91
=item B<--openvpn> I<target address>
92
93
Interface and port on which to forward OpenVPN connections,
94
typically I<localhost:1194>.
95
96
=item B<--xmpp> I<target address>
97
98
Interface and port on which to forward XMPP connections,
99
typically I<localhost:5222>.
100
101
=item B<--tinc> I<target address>
102
103
Interface and port on which to forward tinc connections,
104
typically I<localhost:655>.
105
106
This is experimental. If you use this feature, please report
107
the results (even if it works!)
108
109
=item B<-v>, B<--verbose>
110
111
Increase verboseness.
112
113
=item B<-n>, B<--numeric>
114
115
Do not attempt to resolve hostnames: logs will contain IP
116
addresses. This is mostly useful if the system's DNS is slow
117
and running the I<sslh-select> variant, as DNS requests will
118
hang all connections.
119
120
=item B<-V>
121
122
Prints B<sslh> version.
123
124
=item B<-u> I<username>, B<--user> I<username>
125
126
Requires to run under the specified username. Defaults to
127
I<nobody> (which is not perfect -- ideally B<sslh> should
128
run under its own UID).
129
130
=item B<-P> I<pidfile>, B<--pid-file> I<pidfile>
131
132
Specifies the file in which to write the PID of the main
133
server. Defaults to I</var/run/sslh.pid>.
134
135
=item B<-i>, B<--inetd>
136
137
Runs as an I<inetd> server. Options B<-P> (PID file), B<-p>
138
(listen address), B<-u> (user) are ignored.
139
140
=item B<-f>, B<--foreground>
141
142
Runs in foreground. The server will not fork and will remain connected
143
to the terminal. Messages normally sent to B<syslog> will also be sent
144
to I<stderr>.
145
146
=back
147
148
=head1 FILES
149
150
=over 4
151
152
=item F</etc/init.d/sslh>
153
154
Start-up script. The standard actions B<start>, B<stop> and
155
B<restart> are supported.
156
157
=item F</etc/default/sslh>
158
159
Server configuration. These are environment variables
160
loaded by the start-up script and passed to B<sslh> as
161
command-line arguments. Refer to the OPTIONS section for a
162
detailed explanation of the variables used by B<sslh>.
163
164
=back
165
166
=head1 SEE ALSO
167
168
Last version available from
169
L<http://www.rutschle.net/tech/sslh>, and can be tracked
170
from L<http://freshmeat.net/projects/sslh/>.
171
172
=head1 AUTHOR
173
174
Written by Yves Rutschle
175