Server Setup

How To Set Up a New Server

Mole is a client-server architecture. The server binary is separate from the client. In principle, the server binary is a HTTP server with some specific functionality built in.

Create a User

The mole server should run as a specific, non-privileged user. For this guide, we'll assume you create a new user called mole with the home directory /home/mole.

Install the Server Binary

Download the latest molesrv-all.tar.gz from the Releases page. It contains server binaries for Linux and Mac OS X; take the one matching your architecture and OS and move it to /usr/local/bin/molesrv. Make sure it's executable and not owned by the mole user.

Initialize the Store Directory

Mole stores tunnel definitions, certificate and auxiliary files in a specific directory structure. To create this structure and generate certificates, run molesrv with the -init-store option. It must be run as the mole user.

# sudo -Hu mole molesrv -init-store
2013/12/07 13:11:17 OK: Initialized store directory /home/mole/mole-store

By default, the mole server will keep all it's data in the ~/mole-store directory, although this is configurable.

Start the Server

Test the server by starting it manually.

# sudo -Hu mole molesrv
2013/12/07 13:12:31 mole server 4.0.7
<nothing more>

At this point it is running and listening on the default port 9443. You can now use the mole client to talk to the server from this or another computer. The first step is to "register" with the server, which basically means that the client saves the hostname, port and certificate data of the server for future use.

$ mole register localhost
+--[ mole ]-------+
|                 |
| +               |
|= + E            |
|.= +     o .     |
|o.  + . S o      |
|.. . o o .       |
|  o.+o.          |
|   B*.o          |
|  .oBB.          |
+-----------------+
79:89:B2:B0:78:DE:32:5A:BE:C6:2D:AD:BC:00:86:85:33:79:FC:4C
ok Registered with "localhost". Consider running 'mole install' to see what
  extra packages, such as VPN providers, are available.

If the register works, your server is running OK. At this point you probably want to set it up to start automatically and run in the background. I recommend using daemontools. This is also where you want to set any options for the server. The following is an example run script, setting some non-default options and using logger to get log output into syslog.

$ cat /etc/service/molesrv/run 
#!/bin/sh

cd /opt/mole
export HOME=/opt/mole
exec setuidgid mole molesrv-linux-amd64 \
	-store-dir /opt/mole \
	-audit-intv 168h \
	-canonical-hostname mole.example.com \
	-auth=ldap \
	-ldap-host sso.example.com \
	-ldap-bind uid=%s,cn=users,cn=accounts,dc=int,dc=prnw,dc=net \
	2>&1 | logger -t molesrv

Configuration Options

Running molesrv with the -help flag shows all available options and their default values.

$ ./molesrv -help
Usage:
  molesrv [options]

Options:
  -audit-file=audit.log       Audit file (relative to store directory)
  -audit-intv=24h0m0s         Audit file creation interval
  -auth=none                  Authentication backend
  -canonical-hostname=        Server hostname to advertise as canonical
  -cert-file=cert.pem         Certificate file (relative to store directory)
  -init-store                 Initialize store directory and certificates
  -key-file=key.pem           Key file (relative to store directory)
  -ldap-bind=uid=%s,cn=users  (for -auth=ldap) LDAP bind template
  -ldap-host=localhost        (for -auth=ldap) LDAP host
  -ldap-port=389              (for -auth=ldap) LDAP port
  -listen=:9443               HTTPS listen address
  -no-git                     Do not treat the store as a git repository
  -no-write                   Disallow writable client operations (push, rm, etc)
  -store-dir=~/mole-store     Mole store directory
  -ticket-file=               Ticket key file. Leave blank to autogenerate key on startup.
  -version=4.0.7              Version string to advertise

For options that take file names, these are always relative to the store directory. The store directory itself can be an absolute path or begin with ~/ to be relative to the current user's home directory.

• -audit-file=audit.log Sets the base file name for the audit log. The actual filename will have a timestamp in epoch seconds appended to it. The audit log describes all server operations performed, tagged with the originating IP and authentication user, if any.

• audit-intv=24h0m0s Sets how often a new audit log file is created. Old files are not removed automatically, so some form of cleanup script might need to be used in the long term.

• -auth=none Selects the authentication backend to use for authentication users. The currently implemented backends are none (no user authentication; anyone who can connect to the server can perform all operations) and ldap (users are challenged for a user name and password which is checked against an LDAP server).

• -canonical-hostname= Sets the hostname that the server advertises to the client when responding to requests. If blank (the default) no hostname is advertised. The client side behavior is that if the server returns a hostname that differs from what is locally configured (i.e. what the client registered with), the client will update it's configuration to point to the new hostname. This can be used to gently point clients towards a new server, or to prepare for moving to a new name, etc.

• -cert-file=cert.pem Sets the name of the certificate file (created by -init-store).

• -init-store Initializes the store directory and creates certificates. Necessary to set up a new server. Note that if this is run on an existing installation, the certificates will be overwritten and existing clients will no longer accept the server as genuine.

• -key-file=key.pem Sets the name of key file (created by -init-store).

• -ldap-bind=uid=%s,cn=users (for -auth=ldap) LDAP bind template

• -ldap-host=localhost (for -auth=ldap) LDAP host

• -ldap-port=389 (for -auth=ldap) LDAP port

• -listen=:9443 Sets address that the server listens on, ip:port format. Blank IP means to listen on all addresses. The default port is 9443, which is what the client will attempt to connect to unless configured otherwise.

• -no-git Disable use of git for managing the store directory. When git is enabled, which is the default, the data directory inside the store directory contains a git repository. All changes performed by users, such as pushed or deleted tunnel configurations, are followed by a commit to this repository. Mole itself does nothing further with the git information, but it can be used by an administrator to undo incorrect edits, resurrect deleted tunnels, etc.

• -no-write Disable all write operations by clients, turning the server into read only mode. Can be used for maintenance, or running a non-authenticated server with a fixed set of tunnel definitions, etc.

• -store-dir=~/mole-store Sets the store directory where the mole server keeps it's data.

• -ticket-file= Sets the ticket key file name. Absolute path, not relative to the store directory. The ticket key is used to generate client tickets when using something other than the none authentication backend. This key is crucial for the server security; if compromised, an attacker could generate a valid ticket and access the server without authentication. When blank, as is the default, the key is generated on server startup and kept in memory only (not on disk). This is the safest mode of operation but means that clients will need to reauthenticate if the server restarts, because their tickets are now invalid. If this is undesirable, set this to the path of a file containing at least 32 bytes of random data. That data will be used as the key. The file should obviously be protected from reading by anyone other than the mole user.

• -version=4.0.7 Set the version string to advertise (also shows the compiled molesrv version). Only for informational purposes, it doesn't affect client operations. Leaving it at the default is recommended.