Home About Blog Contact Software

Previous Next All

ttunnel Tutorial

By J. David Lee on 2014-12-03.


ttunnel provides encrypted tunnels with simplified certificate handling, authentication, and client revocation. Because ttunnel is written in Go it benefits from Go's TLS library which has forward secrecy by default. It's a simple alternative to stunnel.

Example Usage

In this post we'll use ttunnel to tunnel a MySQL connection from a server to a client. The example server's address is


and the client's is


The MySQL server is listening locally on port 3306.



Binaries for ttunnel are available on GitHub. The binaries linked here were compiled on a 64-bit Linux system. We'll install the binaries in /usr/local/bin:

cd /usr/local/bin

wget $ADDR/ttunnel-init-server
wget $ADDR/ttunnel-server
wget $ADDR/ttunnel-add-client

We'll need to make the files executable:

chmod +x ttunnel-*


Before we can run the server, we'll need to generate a self-signed certificate. This is done using the ttunnel-init-server program. ttunnel-init-server takes two arguments: the server's public address, and the key size in bits.

ttunnel-init-server server.crumpington.com 2048


We run the server by calling ttunnel-server with a single argument giving the address and port to listen on.

ttunnel-server :2022

In this case we're listening on port 2022 on all available interfaces. We'll leave this command running in a terminal so we can connect to the server later.

Adding a Client

In order for the client to connect to the server, we need to create two configuration files: one for the server and one for the client. These file are created by calling ttunnel-add-client:

ttunnel-add-client              \
    client-server-mysql         \
    server.crumpington.com:2022 \
    localhost:3306              \

ttunnel-add-client takes four arguments:

  1. The filename for the configuration.
  2. The server's public address and port.
  3. The address to forward incoming traffic to.
  4. The local port for the client to listen on.

The configuration filename must be unique on both the client and the server. When a client attempts to connect to the server, it sends the configuration file name followed by a password for authentication. If configuration file doesn't exist or the password is incorrect, the connection is dropped.


ttunnel-add-client as called above creates a configuration file for the server in ~/.ttunnel/clients/client-server-mysql.json. If this file is deleted, the client will no longer be able to connect.



Download the client binary from GitHub:

cd /usr/local/bin

wget $ADDR/ttunnel-client

and make the file executable:

chmod +x ttunnel-client

Copy the Configuration File

We copy the client's configuration file that we created on the server to the client:

mkdir ~/.ttunnel
mkdir ~/.ttunnel/tunnels

cd ~/.ttunnel/tunnels

scp $ADDR/client-server-mysql.json .


ttunnel-client client-server-mysql

In another terminal, on the client, connect to the MySQL server on the tunneled port:

mysql --host --user=root -p

On the server you should see the connection logged to stderr:

2014/11/21 19:35:10 Forwarding traffic for client client-server-mysql.

General Notes

In order to run ttunnel at boot as a service, I'd recommend something like Supervisor. I think it's also advisable to run both the client and server under unprivileged users.

A Note on Security

I wrote this software over the course of a few days, and it hasn't been audited or even looked at by anyone else, as far as I know. If you'd like to use the code, I'd recommend taking a few minutes to review the source to check for obvious errors. If you have or would like to review the source code, please don't hesitate to get in touch with me using the link below.

The Author

J. David Lee is a programmer turned physicist turned programmer and the proprietor of Crumpington Consulting. If you feel that his expertise could benefit you or your organization, don't hesitate to get in touch.