git ssb

Files: 63a83cf0416ab89720b15a4a649786812b630b79 / sslh.pod

7331 bytesRaw

1 # I'm just not gonna write troff :-)
2 
3 =head1 NAME
4 
5  sslh - protocol demultiplexer
6 
7 =head1 SYNOPSIS
8 
9 sslh [B<-F> I<config file>] [ B<-t> I<num> ] [B<--transparent>] [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<--anyprot> I<default target address>] [B<--on-timeout> I<protocol name>] [B<-u> I<username>] [B<-P> I<pidfile>] [-v] [-i] [-V] [-f] [-n]
10 
11 =head1 DESCRIPTION
12 
13 B<sslh> accepts connections on specified ports, and forwards
14 them further based on tests performed on the first data
15 packet sent by the remote client.
16 
17 Probes for HTTP, SSL, SSH, OpenVPN, tinc, XMPP are
18 implemented, and any other protocol that can be tested using
19 a regular expression, can be recognised. A typical use case
20 is to allow serving several services on port 443 (e.g. to
21 connect to ssh from inside a corporate firewall, which
22 almost never block port 443) while still serving HTTPS on
23 that port. 
24 
25 Hence B<sslh> acts as a protocol demultiplexer, or a
26 switchboard. Its name comes from its original function to
27 serve SSH and HTTPS on the same port.
28 
29 =head2 Libwrap support
30 
31 One drawback of B<sslh> is that the servers do not see the
32 original IP address of the client anymore, as the connection
33 is forwarded through B<sslh>.
34 
35 For this reason, B<sslh> can be compiled with B<libwrap> to
36 check accesses defined in F</etc/hosts.allow> and
37 F</etc/hosts.deny>.  Libwrap services can be defined using
38 the configuration file.
39 
40 =head2 Configuration file
41 
42 A configuration file can be supplied to B<sslh>. Command
43 line arguments override file settings. B<sslh> uses
44 B<libconfig> to parse the configuration file, so the general
45 file format is indicated in
46 L<http://www.hyperrealm.com/libconfig/libconfig_manual.html>.
47 Please refer to the example configuration file provided with
48 B<sslh> for the specific format (Options have the same names
49 as on the command line, except for the list of listen ports
50 and the list of protocols).
51 
52 The configuration file makes it possible to specify
53 protocols using regular expressions: a list of regular
54 expressions is given as the I<regex_patterns> parameter, and if the
55 first packet received from the client matches any of these
56 expressions, B<sslh> connects to that protocol.
57 
58 =head2 Probing protocols
59 
60 When receiving an incoming connection, B<sslh> will read the
61 first bytes sent be the connecting client. It will then
62 probe for the protocol in the order specified on the command
63 line (or the configuration file). Therefore B<--anyprot>
64 should alway be used last, as it always succeeds and further
65 protocols will never be tried.
66 
67 If no data is sent by the client, B<sslh> will eventually
68 time out and connect to the protocol specified with
69 B<--on-timeout>, or I<ssh> if none is specified.
70 
71 =head2 Logging
72 
73 As a security/authorization program, B<sslh> logs to the
74 LOG_AUTH facility, with priority LOG_INFO for normal
75 connections and LOG_ERR for failures.
76 
77 =head1 OPTIONS
78 
79 =over 4
80 
81 =item B<-F> I<filename>, B<--config> I<filename>
82 
83 Uses I<filename> has configuration file. If other
84 command-line options are specified, they will override the
85 configuration file's settings.
86 
87 =item B<-t> I<num>, B<--timeout> I<num>
88 
89 Timeout before forwarding the connection to the timeout
90 protocol (which should usually be SSH). Default is 2s.
91 
92 =item B<--on-timeout> I<protocol name>
93 
94 Name of the protocol to connect to after the timeout period
95 is over. Default is 'ssh'.
96 
97 =item B<--transparent>
98 
99 Makes B<sslh> behave as a transparent proxy, i.e. the
100 receiving service sees the original client's IP address.
101 This works on Linux only and involves B<iptables> settings.
102 Refer to the README for more information.
103 
104 =item B<-p> I<listening address>, B<--listen> I<listening address>
105 
106 Interface and port on which to listen, e.g. I<foobar:443>,
107 where I<foobar> is the name of an interface (typically the
108 IP address on which the Internet connection ends up).
109 
110 This can be specified several times to bind B<sslh> to
111 several addresses.
112 
113 =item B<--ssl> I<target address>
114 
115 =item B<--tls> I<target address>
116 
117 Interface and port on which to forward SSL connection,
118 typically I<localhost:443>.
119 
120 Note that you can set B<sslh> to listen on I<ext_ip:443> and
121 B<httpd> to listen on I<localhost:443>: this allows clients
122 inside your network to just connect directly to B<httpd>.
123 
124 Also, B<sslh> probes for SSLv3 (or TLSv1) handshake and will
125 reject connections from clients requesting SSLv2. This is
126 compliant to RFC6176 which prohibits the usage of SSLv2. If
127 you wish to accept SSLv2, use B<--default> instead.
128 
129 =item B<--ssh> I<target address>
130 
131 Interface and port on which to forward SSH connections,
132 typically I<localhost:22>.
133 
134 =item B<--openvpn> I<target address>
135 
136 Interface and port on which to forward OpenVPN connections,
137 typically I<localhost:1194>.
138 
139 =item B<--xmpp> I<target address>
140 
141 Interface and port on which to forward XMPP connections,
142 typically I<localhost:5222>.
143 
144 =item B<--http> I<target address>
145 
146 Interface and port on which to forward HTTP connections,
147 typically I<localhost:80>.
148 
149 =item B<--tinc> I<target address>
150 
151 Interface and port on which to forward tinc connections,
152 typically I<localhost:655>.
153 
154 This is experimental. If you use this feature, please report
155 the results (even if it works!)
156 
157 =item B<--anyprot> I<target address>
158 
159 Interface and port on which to forward if no other protocol
160 has been found. Because B<sslh> tries protocols in the order
161 specified on the command line, this should be specified
162 last. If no default is specified, B<sslh> will forward
163 unknown protocols to the first protocol specified.
164 
165 =item B<-v>, B<--verbose>
166 
167 Increase verboseness.
168 
169 =item B<-n>, B<--numeric>
170 
171 Do not attempt to resolve hostnames: logs will contain IP
172 addresses. This is mostly useful if the system's DNS is slow
173 and running the I<sslh-select> variant, as DNS requests will
174 hang all connections.
175 
176 =item B<-V>
177 
178 Prints B<sslh> version.
179 
180 =item B<-u> I<username>, B<--user> I<username>
181 
182 Requires to run under the specified username. 
183 
184 =item B<-P> I<pidfile>, B<--pidfile> I<pidfile>
185 
186 Specifies a file in which to write the PID of the main
187 server.
188 
189 =item B<-i>, B<--inetd>
190 
191 Runs as an I<inetd> server. Options B<-P> (PID file), B<-p>
192 (listen address), B<-u> (user) are ignored.
193 
194 =item B<-f>, B<--foreground>
195 
196 Runs in foreground. The server will not fork and will remain connected
197 to the terminal. Messages normally sent to B<syslog> will also be sent
198 to I<stderr>.
199 
200 =item B<--background>
201 
202 Runs in background. This overrides B<foreground> if set in
203 the configuration file (or on the command line, but there is
204 no point setting both on the command line unless you have a
205 personality disorder).
206 
207 =back
208 
209 =head1 FILES
210 
211 =over 4
212 
213 =item F</etc/init.d/sslh>
214 
215 Start-up script. The standard actions B<start>, B<stop> and
216 B<restart> are supported.
217 
218 =item F</etc/default/sslh>
219 
220 Server configuration. These are environment variables
221 loaded by the start-up script and passed to B<sslh> as
222 command-line arguments. Refer to the OPTIONS section for a
223 detailed explanation of the variables used by B<sslh>.
224 
225 =back
226 
227 =head1 SEE ALSO
228 
229 Last version available from
230 L<http://www.rutschle.net/tech/sslh>, and can be tracked
231 from L<http://freecode.com/projects/sslh>.
232 
233 =head1 AUTHOR
234 
235 Written by Yves Rutschle
236

Built with git-ssb-web

cel / sslh

Tree: 63a83cf0416ab89720b15a4a649786812b630b79

Files: 63a83cf0416ab89720b15a4a649786812b630b79 / sslh.pod

1	# I'm just not gonna write troff :-)
2
3	=head1 NAME
4
5	sslh - protocol demultiplexer
6
7	=head1 SYNOPSIS
8
9	sslh [B<-F> I<config file>] [ B<-t> I<num> ] [B<--transparent>] [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<--anyprot> I<default target address>] [B<--on-timeout> I<protocol name>] [B<-u> I<username>] [B<-P> I<pidfile>] [-v] [-i] [-V] [-f] [-n]
10
11	=head1 DESCRIPTION
12
13	B<sslh> accepts connections on specified ports, and forwards
14	them further based on tests performed on the first data
15	packet sent by the remote client.
16
17	Probes for HTTP, SSL, SSH, OpenVPN, tinc, XMPP are
18	implemented, and any other protocol that can be tested using
19	a regular expression, can be recognised. A typical use case
20	is to allow serving several services on port 443 (e.g. to
21	connect to ssh from inside a corporate firewall, which
22	almost never block port 443) while still serving HTTPS on
23	that port.
24
25	Hence B<sslh> acts as a protocol demultiplexer, or a
26	switchboard. Its name comes from its original function to
27	serve SSH and HTTPS on the same port.
28
29	=head2 Libwrap support
30
31	One drawback of B<sslh> is that the servers do not see the
32	original IP address of the client anymore, as the connection
33	is forwarded through B<sslh>.
34
35	For this reason, B<sslh> can be compiled with B<libwrap> to
36	check accesses defined in F</etc/hosts.allow> and
37	F</etc/hosts.deny>. Libwrap services can be defined using
38	the configuration file.
39
40	=head2 Configuration file
41
42	A configuration file can be supplied to B<sslh>. Command
43	line arguments override file settings. B<sslh> uses
44	B<libconfig> to parse the configuration file, so the general
45	file format is indicated in
46	L<http://www.hyperrealm.com/libconfig/libconfig_manual.html>.
47	Please refer to the example configuration file provided with
48	B<sslh> for the specific format (Options have the same names
49	as on the command line, except for the list of listen ports
50	and the list of protocols).
51
52	The configuration file makes it possible to specify
53	protocols using regular expressions: a list of regular
54	expressions is given as the I<regex_patterns> parameter, and if the
55	first packet received from the client matches any of these
56	expressions, B<sslh> connects to that protocol.
57
58	=head2 Probing protocols
59
60	When receiving an incoming connection, B<sslh> will read the
61	first bytes sent be the connecting client. It will then
62	probe for the protocol in the order specified on the command
63	line (or the configuration file). Therefore B<--anyprot>
64	should alway be used last, as it always succeeds and further
65	protocols will never be tried.
66
67	If no data is sent by the client, B<sslh> will eventually
68	time out and connect to the protocol specified with
69	B<--on-timeout>, or I<ssh> if none is specified.
70
71	=head2 Logging
72
73	As a security/authorization program, B<sslh> logs to the
74	LOG_AUTH facility, with priority LOG_INFO for normal
75	connections and LOG_ERR for failures.
76
77	=head1 OPTIONS
78
79	=over 4
80
81	=item B<-F> I<filename>, B<--config> I<filename>
82
83	Uses I<filename> has configuration file. If other
84	command-line options are specified, they will override the
85	configuration file's settings.
86
87	=item B<-t> I<num>, B<--timeout> I<num>
88
89	Timeout before forwarding the connection to the timeout
90	protocol (which should usually be SSH). Default is 2s.
91
92	=item B<--on-timeout> I<protocol name>
93
94	Name of the protocol to connect to after the timeout period
95	is over. Default is 'ssh'.
96
97	=item B<--transparent>
98
99	Makes B<sslh> behave as a transparent proxy, i.e. the
100	receiving service sees the original client's IP address.
101	This works on Linux only and involves B<iptables> settings.
102	Refer to the README for more information.
103
104	=item B<-p> I<listening address>, B<--listen> I<listening address>
105
106	Interface and port on which to listen, e.g. I<foobar:443>,
107	where I<foobar> is the name of an interface (typically the
108	IP address on which the Internet connection ends up).
109
110	This can be specified several times to bind B<sslh> to
111	several addresses.
112
113	=item B<--ssl> I<target address>
114
115	=item B<--tls> I<target address>
116
117	Interface and port on which to forward SSL connection,
118	typically I<localhost:443>.
119
120	Note that you can set B<sslh> to listen on I<ext_ip:443> and
121	B<httpd> to listen on I<localhost:443>: this allows clients
122	inside your network to just connect directly to B<httpd>.
123
124	Also, B<sslh> probes for SSLv3 (or TLSv1) handshake and will
125	reject connections from clients requesting SSLv2. This is
126	compliant to RFC6176 which prohibits the usage of SSLv2. If
127	you wish to accept SSLv2, use B<--default> instead.
128
129	=item B<--ssh> I<target address>
130
131	Interface and port on which to forward SSH connections,
132	typically I<localhost:22>.
133
134	=item B<--openvpn> I<target address>
135
136	Interface and port on which to forward OpenVPN connections,
137	typically I<localhost:1194>.
138
139	=item B<--xmpp> I<target address>
140
141	Interface and port on which to forward XMPP connections,
142	typically I<localhost:5222>.
143
144	=item B<--http> I<target address>
145
146	Interface and port on which to forward HTTP connections,
147	typically I<localhost:80>.
148
149	=item B<--tinc> I<target address>
150
151	Interface and port on which to forward tinc connections,
152	typically I<localhost:655>.
153
154	This is experimental. If you use this feature, please report
155	the results (even if it works!)
156
157	=item B<--anyprot> I<target address>
158
159	Interface and port on which to forward if no other protocol
160	has been found. Because B<sslh> tries protocols in the order
161	specified on the command line, this should be specified
162	last. If no default is specified, B<sslh> will forward
163	unknown protocols to the first protocol specified.
164
165	=item B<-v>, B<--verbose>
166
167	Increase verboseness.
168
169	=item B<-n>, B<--numeric>
170
171	Do not attempt to resolve hostnames: logs will contain IP
172	addresses. This is mostly useful if the system's DNS is slow
173	and running the I<sslh-select> variant, as DNS requests will
174	hang all connections.
175
176	=item B<-V>
177
178	Prints B<sslh> version.
179
180	=item B<-u> I<username>, B<--user> I<username>
181
182	Requires to run under the specified username.
183
184	=item B<-P> I<pidfile>, B<--pidfile> I<pidfile>
185
186	Specifies a file in which to write the PID of the main
187	server.
188
189	=item B<-i>, B<--inetd>
190
191	Runs as an I<inetd> server. Options B<-P> (PID file), B<-p>
192	(listen address), B<-u> (user) are ignored.
193
194	=item B<-f>, B<--foreground>
195
196	Runs in foreground. The server will not fork and will remain connected
197	to the terminal. Messages normally sent to B<syslog> will also be sent
198	to I<stderr>.
199
200	=item B<--background>
201
202	Runs in background. This overrides B<foreground> if set in
203	the configuration file (or on the command line, but there is
204	no point setting both on the command line unless you have a
205	personality disorder).
206
207	=back
208
209	=head1 FILES
210
211	=over 4
212
213	=item F</etc/init.d/sslh>
214
215	Start-up script. The standard actions B<start>, B<stop> and
216	B<restart> are supported.
217
218	=item F</etc/default/sslh>
219
220	Server configuration. These are environment variables
221	loaded by the start-up script and passed to B<sslh> as
222	command-line arguments. Refer to the OPTIONS section for a
223	detailed explanation of the variables used by B<sslh>.
224
225	=back
226
227	=head1 SEE ALSO
228
229	Last version available from
230	L<http://www.rutschle.net/tech/sslh>, and can be tracked
231	from L<http://freecode.com/projects/sslh>.
232
233	=head1 AUTHOR
234
235	Written by Yves Rutschle
236

cel / sslh

Tree: 63a83cf0416ab89720b15a4a649786812b630b79 shsmasterv1.9v1.8v1.7v1.6v1.5v1.3v1.2v1.18v1.17v1.16v1.15v1.14v1.13v1.12v1.11v1.10v1.1v1.0 <input type="submit" value="Go"/>

Files: 63a83cf0416ab89720b15a4a649786812b630b79 / sslh.pod

Tree: 63a83cf0416ab89720b15a4a649786812b630b79