Lokinet Exit Provider Guide

Author: Jeff (majestrate)


This document will guide you in the process of setting up an authenticated exit provider on lokinet. This document is written for the target audience of people who know how to run a commercial VPN.

Architectual overview

The high level "bird's eye view" of the architecture of an exit provider is hub and spoke. Multiple Lokinet clients provide exit connectivity and all phone home to an auth server over a ZMQ socket. The auth server will tell a lokinet exit provider if a loki address + auth code pair is valid at the current time. This pair is sent when a lokinet exit user establishes a new flow (convtag) with the exit, this happens on a regular interval.

Auth Server Setup

Requirements for the auth server:

  • cmake
  • python3
  • c++17 compiler
  • lokimq


First off, if you haven't already, add the lokinet apt repository:

    sudo curl -so /etc/apt/trusted.gpg.d/loki.gpg https://deb.loki.network/pub.gpg
    echo "deb https://deb.loki.network $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/loki.list
    sudo apt update

On ubuntu you can install the dependencies via:

    sudo apt install python3-dev cmake git build-essential liblokimq-dev

Clone the repository for the auth server and build it.

    git clone --recursive https://github.com/loki-project/loki-pylokimq -b stable pylokimq
    cd pylokimq
    python3 setup.py build

Install the built python module:

    sudo python3 setup.py install

You can run a test version of the auth server using:

    python3 -m lokinet.auth --bind tcp:// --cmd /bin/true 

The --bind flag tells where to bind the zmq socket, it also takes ipc:///path/to/auth.socket to bind to a unix socket.

The --cmd flag is a path to a script or executable that is used for the actual logic of the authentication, the script is passed two arguments: clientaddress.loki and base64_encoded_auth_code, the script should return exit code 0 on auth success or non-zero on auth failure.

An example implementation of this script could be the following shell script:

#!/usr/bin/env bash
grep $(sha256sum <<<"$2" | cut -d' ' -f1) /etc/loki/auth-codes.txt

with this example script an auth code can be generated and added via:

    sha256sum <<<"$(base64 -e 'code goes here')" | cut -d' ' -f1 >> /etc/loki/auth-codes.txt

NOTE: operators are advised to not use this example implementation.

Lokinet Configuration

The suggested configuration for lokinet exits are as such:



post setup for exit (as root) given eth0 is used to get to the internet:

    echo 1 > /proc/sys/net/ipv4/ip_forward
    iptables -t nat -A POSTROUTING -s -o eth0 -j MASQUERADE