README
¶
Command tlstun implements basic VPN over TLS (both client and server).
Client part is expected to be run locally and used by local services as a
socks5 proxy. Client establishes TLS session to the server running on some
remote host that performs outgoing requests on behalf of requests made to
the client.
Client and server authenticate each other with certificates which can be
created with openssl or https://github.com/artyom/gencert
Usage example
Generate server and client side certificates, they can be signed by the same
CA and saved using PEM encoding into a single file. Certificate keys should
also be saved as a separate PEM-encoded files. With gencert tool from
https://github.com/artyom/gencert this can be done as:
gencert -hosts my.domain.tld
This produces five files in the current directory: client certificate + key
pair, another pair for the server and a certificate authority certificate.
Note that my.domain.tld should point to the host you plan running server
part of tlstun.
Now configure tlstun to run on the server that could be reached at
my.domain.tld like this:
tlstun server -addr=:9000 -ca=ca.pem \
-cert=server-cert.pem -key=server-key.pem
The client part is expected to be running locally (on a laptop/workstation,
etc.):
tlstun client -addr=127.0.0.1:1080 -ca=ca.pem \
-cert=client-cert.pem -key=client-key.pem \
my.domain.tld:9000
Client is now listening on localhost port 1080 and local software can be
configured to use this endpoint as a socks5 proxy.
Client may be configured to work with multiple servers:
tlstun client -addr=127.0.0.1:1080 -ca=ca.pem \
-cert=client-cert.pem -key=client-key.pem \
my.domain.tld:9000 other.domain.tld:9000
By default client will periodically evaluate all endpoints and prefer one
which replies first. This check may be disabled with -no-check flag.
Instead of listing endpoints directly, client may discover them from SRV DNS
records. If -discover=domain.tld flag is set, client ignores any endpoints
given on the command line and instead looks up SRV record
_tlstun._tcp.domain.tld, which must follow standard format to specify
host/port pairs.
HTTPS compatible mode
Server may be configured to automatically issue certificate from ACME
provider (currently is's Let's Encrypt). For this to work, server must be
exposed over port 443 and it also doubles as an https endpoint. By default
it replies with 404 Not Found, but can optionally be configured to serve
static files from file system directory:
tlstun server -addr=:443 -ca=ca.pem -acme \
-acme-domain=domain.tld -acme-email=you@domain.tld \
-acme-cache=/var/cache/acme \
-httproot=/var/www/domain.tld
Server may also be run with -dns-tls flag, which enables resolving via
DNS-over-TLS providers (currently Cloudflare and Quad9).
Documentation
¶
Overview ¶
Command tlstun implements basic VPN over TLS (both client and server).
Client part is expected to be run locally and used by local services as a socks5 proxy. Client establishes TLS session to the server running on some remote host that performs outgoing requests on behalf of requests made to the client.
Client and server authenticate each other with certificates which can be created with openssl or https://github.com/artyom/gencert
Usage example ¶
Generate server and client side certificates, they can be signed by the same CA and saved using PEM encoding into a single file. Certificate keys should also be saved as a separate PEM-encoded files. With gencert tool from https://github.com/artyom/gencert this can be done as:
gencert -hosts my.domain.tld
This produces five files in the current directory: client certificate + key pair, another pair for the server and a certificate authority certificate. Note that my.domain.tld should point to the host you plan running server part of tlstun.
Now configure tlstun to run on the server that could be reached at my.domain.tld like this:
tlstun server -addr=:9000 -ca=ca.pem \ -cert=server-cert.pem -key=server-key.pem
The client part is expected to be running locally (on a laptop/workstation, etc.):
tlstun client -addr=127.0.0.1:1080 -ca=ca.pem \ -cert=client-cert.pem -key=client-key.pem \ my.domain.tld:9000
Client is now listening on localhost port 1080 and local software can be configured to use this endpoint as a socks5 proxy.
Client may be configured to work with multiple servers:
tlstun client -addr=127.0.0.1:1080 -ca=ca.pem \ -cert=client-cert.pem -key=client-key.pem \ my.domain.tld:9000 other.domain.tld:9000
By default client will periodically evaluate all endpoints and prefer one which replies first. This check may be disabled with -no-check flag.
Instead of listing endpoints directly, client may discover them from SRV DNS records. If -discover=domain.tld flag is set, client ignores any endpoints given on the command line and instead looks up SRV record _tlstun._tcp.domain.tld, which must follow standard format to specify host/port pairs.
HTTPS compatible mode ¶
Server may be configured to automatically issue certificate from ACME provider (currently is's Let's Encrypt). For this to work, server must be exposed over port 443 and it also doubles as an https endpoint. By default it replies with 404 Not Found, but can optionally be configured to serve static files from file system directory:
tlstun server -addr=:443 -ca=ca.pem -acme \ -acme-domain=domain.tld -acme-email=you@domain.tld \ -acme-cache=/var/cache/acme \ -httproot=/var/www/domain.tld
Server may also be run with -dns-tls flag, which enables resolving via DNS-over-TLS providers (currently Cloudflare, Quad9, LibreDNS).
Source Files