The current state of ClueVPN is rapidly changing, so this readme may well be out of date. Currently, it's just an overview.

ClueVPN requires that a single port, both TCP and UDP, be forwarded to each node. The default is 3406. UDP is used for all the data transmissions. TCP is used for negotiation of encryption keys and other parameters, and in the future, for other functions as well.

• A DSA public and private key. The public key is shared globally over the ClueVPN network. The private key should only be configured on a single node (the node that will be used to generate the BNL).
• An SSL CA certificate, and certificates/keys signed by the CA for each node. The certificate common names should be the node names of each node, as specified in the BNL.
• A BNL (Bootstrap Node List) shared globally across the network. This is signed by the DSA private key, and verified using the DSA public key. The BNL contains a list of nodes in the network, their global addresses, their internal subnets, and a few other bits of information.
• A config file (described below)

The BNL contains a list of nodes and paramters. Each node is assigned a numeric ID, starting from 1. They do not need to be sequential, but the numbers should be kept low, as an array is created indexed by the IDs. In the future, the IDs will be automatically generated by a more friendly BNL generation utility. For example, a 5 node network could have nodes 1,2,5,6,8. This will waste a little bit of memory, but not much. However, giving them IDs of 1,2,3,4,10000 would waste a ton of memory. So, keep them close to 0.

The program bnlutil can be used to create and modify BNLs. It requires a configuration file with the "bnlprivkey" directive to run. The command line options are:

• -c: Specify the configuration directory.
• -b: Specify an alternative location for the BNL (other than the default in the configuration directory).
• -t: Specify an alternative timestamp to use for modified/created BNLs. The timestamp is a number (a UNIX timestamp). If this option is not used, the current time is used as a timestamp.

After the command line options, a subcommand and options are given. The subcommands are:

• print
• new
• add <Name> [ID=<ID>] [IPv4=<IPv4Address>] [IPv6=<IPv6Address>] [Port=<Port>] [PreferIPv6] [Subnet=<Subnet1>] [Subnet=<Subnet2>] ...
• modify <Name> [IPv4=[IPv4Address]] [IPv6=[IPv6Address]] [Port=[Port]] [PreferIPv4] [PreferIPv6]
• addsubnet <Name> <Subnet>
• delsubnet <Name> <Subnet>
• remove <Name>

Each Subnet: /

The BNL itself is stored in a binary file with a signature. However, it can be generated from a comma-separated-value file using the csv2bnl utility. The format of each line in the CSV file is:

<NodeName>,<NodeID>,<NodeIPv4Address>,<NodeIPv6Address>,<NodePort>,<IPv6IsPreferred>,<NumberOfInternalSubnets>,<Subnet1>,<Subnet2>,...

• is a string - usually the hostname of the node. It must match the common name in the SSL certificate for that node.
• is the numeric ID for the node, as described above.
• is the external IPv4 address of the node. If the node is IPv6-only, this should be specified as 0.0.0.0
• is the external IPv6 address of the node. If the node is IPv4-only, this should be specified as ::
• is the port of the node. We recommend using the standard, 3406.
• is a boolean value, specified as either 0 or 1. If this is 0, then IPv4 is the preferred way to contact the node. If this is 1, then IPv6 is the preferred way to contact the node.
• is the number of internal subnets that are routed to this node.

After the number of subnets, each subnet is specified. The format of each subnet is: :/

• is either 4 or 6, depending on if it's an IPv4 or IPv6 subnet.
• is the network address of the subnet.
• is the CIDR mask for the subnet.

An example line for a BNL CSV file is:

testnode.cluenet.org,5,99.100.101.102,::,3406,0,2,4:10.156.10.0/24,10.156.11.0/24

After you create the BNL CSV file, you need to convert it into the binary BNL file using the csv2bnl utility. Before you can do that, you need to create a config file in the current directory that includes the bnlprivkey directive. After you have the config file in the current directory, named cluevpn.conf, run the command:

$ ./csv2bnl < bnl.csv > bnl.bnl

It will automatically create and sign the BNL for you.

The config file should be called cluevpn.conf in the ClueVPN directory. It follows the following format (with comments to explain each directive):

# Hostname of this host - must match its cert CN
name=testnode.cluenet.org
# The interface name on the machine
devname=cluevpn
# The SSL cert for this host
cert=/etc/cluevpn/testnode.cluenet.org-cluevpn.cert
# The SSL key for this host
privkey=/etc/cluevpn/testnode.cluenet.org-cluevpn.key
# The CA certificate for the network
cacert=/etc/cluevpn/cacert.pem
# The ID for this host - must match the ID in the BNL for this host.  This directive is optional - if not given, the ID is discovered from the BNL.
id=5
# The port to listen on - must match the port for this host in the BNL.  Default is 3406
port=3406
# Whether or not to disable IPv6
disableipv6=false
# Whether or not to locally prefer IPv6 for external communication
preferipv6=false
# If you'd like to make sure that each cert has a certain OU, specify it here
restrictouname=ClueVPN
# The DSA public key for the network
bnlpubkey=dsa_pub.pem
# The DSA private key for the network - only one host should have this - the host signing the BNL
bnlprivkey=dsa_priv.pem
# The debug level as specified on the command line - the command line overrides this
loglevel=3
# The log method (stderr, file, or syslog)
logmethod=syslog
# If the log method is file, the log file
# logfile=/var/log/cluevpn.log
# The command to execute after cluevpn finishes initializing
upcmd=ifconfig $TUNDEV 10.156.10.1 netmask 255.255.0.0 up
# The command to run for each subnet the VPN can reach
# subnetupcmd=/etc/cluevpn/initsubnet.sh
# The command to run for each locally assigned subnet the VPN can reach
# mysubnetupcmd=/etc/cluevpn/initmysubnet.sh
# A space-separated list of encryption algorithms, key lengths, and preference values.
# Currently, only the aescbc algorithm is supported.
# In the space-separated list of supported algorithms, each item has three fields separated by colons.
# The first field is the algorithm (there can only be one of each algorithm), the second is the key length in bits to use for the algorithm, and the third is the preference value
# The preference value is used in negotiation to help choose which algorithm to use.  The algorithm with the highest total preference value from both sides is used
cryptalgos=aescbc:128:20
# A space separated list of compression algorithms.  The two supported algorithms currently are "zlib" and "none"
# It's in the same format as the cryptalgos directive, but instead of the key length, it's the compression level (1-9)
compalgos=none:0:5 zlib:6:2

• -c <Directory> - This specifies the cluevpn root directory. The cluevpn conf file should be here, as well as the bnl.bnl file. All paths in cluevpn conf are relative to this directory. The default is /etc/cluevpn/
• -d <LogLevel> - The higher this number is, the less information is logged. Values are (the default is 4):
  • 1: Debug
  • 2: Info
  • 3: Notice
  • 4: Warning
  • 5: Error
  • 6: Critical error
  • 7: No logs
• -p <PIDFile> - Causes the daemon to write a file containing its PID after forking.
• -f - Run in the foreground

• TUNDEV: The name of the tun device.

• SUBADDRTYPE: Either INET or INET6 for IPv4 or IPv6 subnets.
• SUBADDR: The network address of the subnet.
• SUBCIDR: The CIDR mask of the subnet.
• SUBNET: Same as ${SUBADDR}/${SUBCIDR}
• NODEID: The ID of the node the subnet belongs to.
• NODE: The name of the node the subnet belongs to.

$ openssl dsaparam -out dsaparam.pem 2048
$ openssl gendsa -out bnlkey-priv.pem dsaparam.pem
$ openssl dsa -in bnlkey-priv.pem -out bnlkey-pub.pem -pubout

• Run cluevpn just by running the binary. I recommend running it in debug mode the first time (-d 1)
• Cluevpn needs to be run as root to create the tun device
• A file called nodeinfo.cni will be created in the working directory. Among other thing, it stores a cache of the BNL and negotiations. If you want to force renegotiation for some reason, shut down the daemon, remove the nodeinfo.cni file, and restart it.
• The first packet that is sent to a node before negotiation is complete may be lost.