git ssb

0+

cel / sslh



Tree: 9bcb2cdd7a920ebc78b59d0b5797d678424aa93a

Files: 9bcb2cdd7a920ebc78b59d0b5797d678424aa93a / sslh.pod

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

Built with git-ssb-web