VNS3 VPN Client tools

One of VNS3’s functions is to operate as a VPN concentrator, providing a management interface for your business’s VPN users and your infrastructures overlay network. Here we provide a few tools for operating client connections:

  1. Client SDK and CLI - python library and cli for managing client
  2. Desktop Apps for managing your VNS3 connections

Note, currently only wireguard is supported by the CN VPN Client SDK/CLI and GUI

Client API SDK and CLI

The Cohesive VPN Client library provides a client API for managing client VPN connections. You can find the code here: https://github.com/cohesive/cohesive-wg-utils.

Latest version is 0.1.1 Build c541652. Released 2022-11-16.

Installation

There are a few ways to get started with the client:

Install the library via pip.

Latest package: https://cohesive-networks.s3.amazonaws.com/extras/cnvpnclient/cnvpnclient-0.1.1.c541652.tar.gz

$ pip install https://cohesive-networks.s3.amazonaws.com/extras/cnvpnclient/cnvpnclient-0.1.1.c541652.tar.gz
# the cnvpn executable will be installed in your pythons bin folder. To ensure it is in your path, see below for options.
$ cnvpn --help

The cnvpn will be installed in your python’s bin folder. For example, if your python is installed @ /Users/myusername/Library/Python/3.8/, cnvpn will be located at /Users/myusername/Library/Python/3.8/bin/cnvpn. If you are using virtualenv or venv to manage your python installations, it will be located in your env/bin directory.

Adding cnvpn to your path

You can add cnvpn to your path on Mac or Linux by linking to a directory that is in your path. For example:

ln -s /Users/myusername/Library/Python/3.8/bin/cnvpn /usr/local/bin/cnvpn

You could also .. yada yada. ben to finish.

Bundled CLIs - these zip folders each contain a cnvpn or cnvpn.exe executable with one or both of Python and Wireguard included.

PlatformVersionBundledDownload
Mac M10.1.1py3 + wgDownload
Mac M10.1.1py3Download
Mac Intel0.1.1py3 + wgDownload
Mac Intel0.1.1py3Download
Linux0.1.1py3 + wgTBA
Linux0.1.1py3TBA
Windows0.1.1py3 + wgDownload
Windows0.1.1py3Download

Note: Mac M1 builds only support Monterey (MacOS 12) and later. Mac Intel builds support Big Sur and later. Windows client currently supports windows 10.

You can review the versions of bundled dependencies with cnvpn inspect.

CLI

The CLI provides common management functions: start, stop, list etc.

usage: cnvpn [-h|--help] [--log-level LOG_LEVEL] [-c/-cp clientpack.conf] [-n name] action

Command line interface for VNS3 VPN Client

positional arguments:
  action                API object action to execute
  action_args           Pass argument to action (can be csv)

optional arguments:
  -h, --help            show this help message and exit
  -c CLIENTPACK, -cp CLIENTPACK, --clientpack CLIENTPACK
                        Clientpack file
  -n NAME, --name NAME  Connection name
  -t CONN_TYPE, --type CONN_TYPE
                        Connection type. Defaults to wg-cohesive. Options: ['wg-native', 'wg-cohesive']
  -f, --tail            Tail logs for logs func
  -l LINES, --lines LINES
                        Number of log lines to show
  --log-level LOG_LEVEL
  --names [NAMES]       filter by clientpack names
  --verbose             Show verbose output

Actions:
# start with create new data files (if new name) and start connection
$ cnvpn start [all] -cp/--clientpack clientpack.conf -n/--name [connection name] (--type [type str])
# save will save connection data files but not start/stop connection
$ cnvpn save -cp/--clientpack clientpack.conf -n/--name [connection name] (--type [type str])
$ cnvpn stop [all] -n/--name [connection name]
$ cnvpn delete [connection name]
$ cnvpn show [connection name]
$ cnvpn list [--names [name1] [name2]]
$ cnvpn logs -n/--name [name] [-f/--tail] [-l/--lines (integer)]
# Review version and env
$ cnvpn inspect

Environment variables:
[Required]
CNVPN_WG_DIR=/path/to/wireguard/ OR 'local' - Where to store wireguard confs. such as wg installation dir. If local, will store local to data directory.
[Optional]
CNVPN_DATA_DIR=/my/data - Where to store connection data. Default: [User home]/.cohesive (~/.cohesive) .
CNVPN_WG_PATH=/path/to/wg - Path to 'wg' executable. Default: wg (assumes in path)
CNVPN_WG_QUICK_PATH=/path/to/wg-quick - Path to 'wg-quick' executable. Default: wg-quick (assumes in path)
CNVPN_AUTO_DISCOVER_INTERFACE=(False/True) - calculate next available wg interface. e.g. 100_64_0_1.conf => wg2
CNVPN_ALLOW_CUSTOM_INTERFACE=(False/True) - allow custom interface name parsed from clientpack file name. e.g. test.conf => test
CNVPN_LOG_LEVEL=(ERROR/WARN/INFO/DEBUG) - default INFO

END of HELP.

Python Lib

The python library provides a python interface for writing your own client code. The main interface is in api.py:

from cnvpnclient import api, config


env_overrides = {}
env = config.read_env(**env_overrides)
cnvpn = api.Api(env)

current_connections = cnvpn.list_connections()

## All functions exposed by Api
# list_connections
# get_connection
# run_connection # blocking!
# start_connection
# stop_connection
# delete_connection
# save_connection
# inspect
# start_all_connections
# stop_all_connections

## helpers
# get_next_interface
# parse_clientpack
# validate_clientpack

Desktop Apps

The VPN Client app provides a simple interface for managing your VPN connections.

Latest version is 0.1.1 Build 50e9431. Released 2022-11-16.

CN VPN Client GUI

Download

PlatformVersionBundledDownload
Mac M10.1.1py3 + wgDownload
Mac Intel0.1.1py3 + wgDownload
Linux0.1.1py3 + wgTBA
Windows0.1.1py3 + wgDownload

Note: Mac M1 builds only support Monterey (MacOS 12) and later. Mac Intel builds support Big Sur and later. Windows client currently supports windows 10.

App functionality

Creating a new connection

Todo

Reviewing connection logs

  1. From connection Actions dropdown, select Details
  2. Click Logs button at the bottom of the window
  3. Logs are copy and pastable. Be sure to hold down your click when dragging to highlight the log section to copy

Stopping/Starting/Deleting a Connection

These actions are available from the Actions dropdown.

Mac Edition

The dmg file above includes two files:

  • a pkg installer file. This installs the App to /Applications. It also installs a background process to /Library/LaunchDaemons
  • an uninstall script called uninstall. To uninstall the application AND the background process, double click the uninstall file to run it

Logs

  • App log @ $HOME/Library/Logs/CohesiveNetVPN/app.log
  • App background process log @ /var/log/cohesivenet-spool-stdout.log
  • App background process error log @ /var/log/cohesivenet-spool-stderr.log
  • App background process unprocessed tasks @ /var/spool/cohesivenet/
  • App background process processed tasks @ /tmp/cohesivenet/

Uninstall

The downloadable files above include an uninstall script for uninstalling the CohesiveNet VPN Client App. Simply double click on this script from your Finder app to run.

Windows Edition

Logs

  • App log @ $HOME/AppData/Local/Cohesive/Logs/app.log
  • Connection logs @ $HOME/AppData/Local/Cohesive/Logs/[connection name].log

Windows Gotchas

  • If there is an issue with a wireguard clientpack, sometimes the wireguard service will provide no feedback. This can result in your connection flipping between “Connected” and “Connecting” and “Disconnected”. We will be updating the client shortly to show an error when this is the case. Currently this behavior will be reviewable from the logs.

App Known Issues

  • the Disconnect after X minutes of inactivity doesnt currently work
  • on the logs page under connection details the title isnt centered
  • on exit, the app stops all connections and this can cause the apple wheel spinning. Should improve UX here.
  • launch app at login doesnt work for mac or windows