From 2d3b6c4abd1ef4339a403bca47b5b3a195787d4a Mon Sep 17 00:00:00 2001 From: Yves Rutschle Date: Sun, 9 Feb 2014 20:50:03 +0100 Subject: [PATCH] fix Markdown documentation for libcap --- README | 229 ------------------------------------------------------ README.md | 16 ++-- 2 files changed, 8 insertions(+), 237 deletions(-) delete mode 100644 README diff --git a/README b/README deleted file mode 100644 index cb2f588..0000000 --- a/README +++ /dev/null @@ -1,229 +0,0 @@ -===== sslh -- A ssl/ssh multiplexer. ===== - -Sslh accepts connections on specified ports, and forwards -them further based on tests performed on the first data -packet sent by the remote client. - -Probes for HTTP, SSL, SSH, OpenVPN, tinc, XMPP are -implemented, and any other protocol that can be tested using -a regular expression, can be recognised. A typical use case -is to allow serving several services on port 443 (e.g. to -connect to ssh from inside a corporate firewall, which -almost never block port 443) while still serving HTTPS on -that port. - -Hence sslh acts as a protocol demultiplexer, or a -switchboard. Its name comes from its original function to -serve SSH and HTTPS on the same port. - -==== Compile and install ==== - -sslh uses libconfig (http://www.hyperrealm.com/libconfig/) -and libwrap. - -For Debian, these are contained in packages libwrap0-dev and -libconfig8-dev. - -For OpenSUSE, these are contained in packages libconfig9 and -libconfig-dev in repository -http://download.opensuse.org/repositories/multimedia:/libs/openSUSE_12.1/ - -For Fedora, you'll need packages libconfig and -libconfig-devel: -yum install libconfig libconfig-devel - -If you can't find libconfig, or just don't want a -configuration file, set 'USELIBCONFIG=' in the Makefile. - -After this, the Makefile should work: - -make install - -There are a couple of configuration options at the beginning -of the Makefile: - - USELIBWRAP compiles support for host access control (see - hosts_access(3)), you will need libwrap headers and - library to compile (libwrap0-dev in Debian). - - USELIBCONFIG compiles support for the configuration - file. You will need libconfig headers to compile - (libconfig8-dev in Debian). - -The Makefile produces two different executables: sslh-fork -and sslh-select. - -sslh-fork forks a new process for each incoming connection. -It is well-tested and very reliable, but incurs the overhead -of many processes. sslh-select uses only one thread, which -monitors all connections at once. It is more recent and less -tested, but only incurs a 16 byte overhead per connection. -Also, if it stops, you'll lose all connections, which means -you can't upgrade it remotely. - -If you are going to use sslh for a "small" setup (less than -a dozen ssh connections and a low-traffic https server) then -sslh-fork is probably more suited for you. If you are going -to use sslh on a "medium" setup (a few thousand ssh -connections, and another few thousand ssl connections), -sslh-select will be better. If you have a very large site -(tens of thousands of connections), you'll need a vapourware -version that would use libevent or something like that. - - -To install: - -make -cp sslh-fork /usr/local/sbin/sslh -cp scripts/etc.default.sslh /etc/default/sslh - -For Debian: -cp scripts/etc.init.d.sslh /etc/init.d/sslh -For CentOS: -cp scripts/etc.rc.d.init.d.sslh /etc/rc.d/init.d/sslh - -and probably create links in /etc/rc.d so that the server -start automatically at boot-up, e.g. under Debian: -update-rc.d sslh defaults - - - -==== Configuration ==== - -You can edit settings in /etc/default/sslh: - -LISTEN=ifname:443 -SSH=localhost:22 -SSL=localhost:443 - -A good scheme is to use the external name of the machine in -$LISTEN, and bind httpd to localhost:443 (instead of all -binding to all interfaces): that way, https connections -coming from inside your network don't need to go through -sslh, and sslh is only there as a frontal for connections -coming from the internet. - -Note that 'external name' in this context refers to the -actual IP address of the machine as seen from your network, -i.e. that that is not 127.0.0.1 in the output of -ifconfig(8). - -==== Libwrap support ==== - -Sslh can optionnaly perform libwrap checks for the sshd -service: because the connection to sshd will be coming -locally from sslh, sshd cannot determine the IP of the -client. - -==== OpenVPN support ==== - -OpenVPN clients connecting to OpenVPN running with --port-share reportedly take more than one second between -the time the TCP connexion is established and the time they -send the first data packet. This results in sslh with -default settings timing out and assuming an SSH connexion. -To support OpenVPN connexions reliably, it is necessary to -increase sslh's timeout to 5 seconds. - -Instead of using OpenVPN's port sharing, it is more reliable -to use sslh's -o option to get sslh to do the port sharing. - -==== Using proxytunnel with sslh ==== - -If you are connecting through a proxy that checks that the -outgoing connection really is SSL and rejects SSH, you can -encapsulate all your traffic in SSL using proxytunnel (this -should work with corkscrew as well). On the server side you -receive the traffic with stunnel to decapsulate SSL, then -pipe through sslh to switch HTTP on one side and SSL on the -other. - -In that case, you end up with something like this: - -ssh -> proxytunnel -e --------ssh/ssl------> stunnel ---ssh---> sslh --> sshd - -Web browser --------http/ssl------> stunnel ---http---> sslh --> http:80 - -Configuration goes like this: - -On the server side, using stunnel3: -stunnel -f -p mycert.pem -d thelonious:443 -l /usr/local/sbin/sslh -- sslh -i --http localhost:80 --ssh localhost:22 - -stunnel options: -f for foreground/debugging, -p specifies -the key + certificate, -d specifies which interface and port -we're listening to for incoming connexions, -l summons sslh -in inetd mode. - -sslh options: -i for inetd mode, --http to forward http -connexions to port 80, and SSH connexions to port 22. - -==== capabilities support ==== - -On Linux (only?), you can compile sslh with USELIBCAP=1 to -make use of POSIX capabilities; this will save the required -capabilities needed for transparent proxying for unprivileged -processes. - -Alternatively, you may use filesystem capabilities instead -of starting sslh as root and asking it to drop privileges. -You will need CAP_NET_BIND_SERVICE for listening on port 443 -and CAP_NET_ADMIN for transparent proxying (see -capabilities(7)). - -You can use the setcap(8) utility to give these capabilities -to the executable: - -# setcap cap_net_bind_service,cap_net_admin+pe sslh-select - -Then you can run sslh-select as an unpriviledged user, e.g.: - -$ sslh-select -p myname:443 --ssh localhost:22 --ssl localhost:443 - -Caveat: CAP_NET_ADMIN does give sslh too many rights, e.g. -configuring the interface. If you're not going to use -transparent proxying, just don't use it (or use the libcap method). - -==== Transparent proxy support ==== - -On Linux (only?) you can use the --transparent option to -request transparent proying. This means services behind sslh -(Apache, sshd and so on) will see the external IP and ports -as if the external world connected directly to them. This -simplifies IP-based access control (or makes it possible at -all). - -sslh needs extended rights to perform this: you'll need to -give it cap_net_admin capabilities manually or enable libcap -support (see appropriate chapter). - -The firewalling tables also need to be adjusted as follow -(example to connect to https on 4443 -- adapt to your needs -(I don't think it is possible to have httpd listen to 443 in -this scheme -- let me know if you manage that))): - -# iptables -t mangle -N SSLH -# iptables -t mangle -A OUTPUT --protocol tcp --out-interface eth0 --sport 22 --jump SSLH -# iptables -t mangle -A OUTPUT --protocol tcp --out-interface eth0 --sport 4443 --jump SSLH -# iptables -t mangle -A SSLH --jump MARK --set-mark 0x1 -# iptables -t mangle -A SSLH --jump ACCEPT -# ip rule add fwmark 0x1 lookup 100 -# ip route add local 0.0.0.0/0 dev lo table 100 - -This will only work if sslh does not use any loopback -addresses (no 127.0.0.1 or localhost), you'll need to use -explicit IP addresses (or names): - -sslh --listen 192.168.0.1:443 --ssh 192.168.0.1:22 --ssl 192.168.0.1:4443 - -This will not work: -sslh --listen 192.168.0.1:443 --ssh 127.0.0.1:22 --ssl 127.0.0.1:4443 - -==== Comments? Questions? ==== - -You can subscribe to the sslh mailing list here: -http://rutschle.net/cgi-bin/mailman/listinfo/sslh - -This mailing list should be used for discussion, feature -requests, and will be the prefered channel for -announcements. - diff --git a/README.md b/README.md index 938c2f1..daef2e6 100644 --- a/README.md +++ b/README.md @@ -189,27 +189,27 @@ Configuration goes like this on the server side, using `stunnel3`: Capabilities support -------------------- -On Linux (only?), you can compile sslh with USELIBCAP=1 to +On Linux (only?), you can compile sslh with `USELIBCAP=1` to make use of POSIX capabilities; this will save the required capabilities needed for transparent proxying for unprivileged processes. Alternatively, you may use filesystem capabilities instead of starting sslh as root and asking it to drop privileges. -You will need CAP_NET_BIND_SERVICE for listening on port 443 -and CAP_NET_ADMIN for transparent proxying (see -capabilities(7)). +You will need `CAP_NET_BIND_SERVICE` for listening on port 443 +and `CAP_NET_ADMIN` for transparent proxying (see +`capabilities(7)`). -You can use the setcap(8) utility to give these capabilities +You can use the `setcap(8)` utility to give these capabilities to the executable: -# setcap cap_net_bind_service,cap_net_admin+pe sslh-select + # setcap cap_net_bind_service,cap_net_admin+pe sslh-select Then you can run sslh-select as an unpriviledged user, e.g.: -$ sslh-select -p myname:443 --ssh localhost:22 --ssl localhost:443 + $ sslh-select -p myname:443 --ssh localhost:22 --ssl localhost:443 -Caveat: CAP_NET_ADMIN does give sslh too many rights, e.g. +Caveat: `CAP_NET_ADMIN` does give sslh too many rights, e.g. configuring the interface. If you're not going to use transparent proxying, just don't use it (or use the libcap method).