Metadata-Version: 2.4
Name: cnvpnclient
Version: 1.2.3
Summary: Cohesive Networks VPN Client SDK/CLI
Home-page: https://github.com/cohesive/cohesive-wg-utils
Author: Cohesive Networks, Inc.
Author-email: solutions@cohesive.net
License: MIT
Keywords: Cohesive Networks VPN,Cohesive Networks,Secops,SDN,Software Defined Networking,Networkops,networking,SASE,Openapi
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Networking :: Firewalls
Classifier: Topic :: System :: Networking :: VPN
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.5.0
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests==2.32.3
Requires-Dist: requests-toolbelt==1.0.0
Requires-Dist: PyYAML==6.0.2
Requires-Dist: psutil==6.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Cohesive VPN Client SDK and CLI

## cnvpnclient library
The code has been reorganized into modules

- `api.py` - main python interface for interacting with VPN clients. view, create, start, stop, and delete connections.
- `client.py` - main functions for running the cohesive vpn process
- `config.py` - module for capturing config from env and defining default constants
- `files.py` - utils for interacting with local files as app datastore
- `logutil.py` - utils for logging
- `version.py` - current package version

## API

```
from cnvpnclient import api as vpn

# main functions

# Stop connection with name and clientpack
vpn.start_connection
# Stop connection by name
vpn.stop_connection
# List all connections (stored in files in data/ directory)
vpn.list_connections
# Delete connection
vpn.delete_connection

# This is a blocking method that will start the vpn client. Typically
# you will call start_connection to manage the connection
vpn.run_connection
```

## Configuration
The lib/cli configuration is defined and read from env by `config.py`:

**LibConfig** class

This contains constants that won't change related to the file naming conventions and local file system storage locations for state and logs

**EnvConfig** class

This contains configuration values that can be overriden by enviornment variables. The environment variables should have the prefix `CNVPN_`. The configuration values are

```
[Required]
WG_DIR - path to directory to store clientpack conf files in. OR use "local" for local to data dir. Common use would be to point at the standard install directory for your platform, e.g. /etc/wireguard/
[Optional]
DATA_DIR=/my/data - Where to store connection data. Default: [User home]/.cohesive (~/.cohesive)
WG_AUTH: default auth. oidc
AUTO_DISCOVER_INTERFACE: (True/False) default: False. If true, start_connection will calculate the next available interface for a clientpack
ALLOW_CUSTOM_INTERFACE: (True/False) default: False. If true, allow a non-wgX name for
the interface, as taken from the clientpack name. e.g. mycustominterface.conf
POLLING_INTERVAL: how often to poll for new routes. default 30
LOGIN_RETRY_INTERVAL: how often to poll for login success if auth enabled. default 3.
LOG_LEVEL: default INFO
```

**Note on clientpack discovery**

If the clientpack passed is not a path to a clientpack but is instead the name of the file in the configured WG_DIR, then that clientpack will be used (provided it is not already taken by another client).

Examples:
```
$ export CNVPN_WG_DIR=/etc/wireguard/
$ ls /etc/wireguard
wg1.conf
$ cnvpn start --clientpack wg1 --name tunnel1
```

**Note on interface configuration and discovery logic**

There are 3 different ways to configure how cnvpnclient determines the interface:

1. The name of the clientpack file. e.g. wg1.conf 
2. If `CNVPN_ALLOW_CUSTOM_INTERFACE` is True, use custom name from clientpack name. e.g. customint.conf
3. If `CNVPN_AUTO_DISCOVER_INTERFACE` is True, then even if there are conflicts from 1 or 2, calculate the next available wireguard standard interface, ie. wg[integer], e.g. wg3

Examples:
```
CNVPN_ALLOW_CUSTOM_INTERFACE=False CNVPN_AUTO_DISCOVER_INTERFACE=False cnvpn start -n test -cp 100_64_0_1.conf
Result: Invalid interface 100_64_0_1

CNVPN_ALLOW_CUSTOM_INTERFACE=True CNVPN_AUTO_DISCOVER_INTERFACE=False cnvpn start -n test -cp 100_64_0_1.conf
Result: Tries to create interface with name 100_64_0_1. If taken, it fails.

CNVPN_ALLOW_CUSTOM_INTERFACE=False CNVPN_AUTO_DISCOVER_INTERFACE=True cnvpn start -n test -cp 100_64_0_1.conf
Result: Calculates next wireguard interface. e.g. wg1, wg2 etc.

# wg0 is taken
CNVPN_ALLOW_CUSTOM_INTERFACE=False CNVPN_AUTO_DISCOVER_INTERFACE=True cnvpn start -n test -cp wg0.conf
Result: Calculates next wireguard interface. e.g. wg1

# test is taken
CNVPN_ALLOW_CUSTOM_INTERFACE=True CNVPN_AUTO_DISCOVER_INTERFACE=True cnvpn start -n test -cp test.conf
Result: Calculates next wireguard interface because interface "test" is taken. e.g. wg3
```

## CLI

```
# show help
$bin/cnvpn --help
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

optional arguments:
  -h, --help            show this help message and exit
  -c CLIENTPACK, -cp CLIENTPACK, --clientpack CLIENTPACK
                        Clientpack file
  -n NAME, --name NAME  Connection name
  --log-level LOG_LEVEL
  --names NAMES [NAMES ...]
                        filter by clientpack names
  --details             Show full details of connections
  --verbose             Show verbose output

Examples:
$ bin/cnvpn start -cp/--clientpack clientpack.conf -n/--name [connection name]
$ bin/cnvpn stop -n/--name [connection name]
$ bin/cnvpn delete -n/--name [connection name]
$ bin/cnvpn show-connection -n/--name [connection name]
$ bin/cnvpn list-connections [-n/--names [name1] [name2]]

Environment variables:
CNVPN_WG_DIR=/path/to/wireguard/ OR 'local' - Where to store wireguard confs. If local, will store in local data directory.
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
CNVPN_WINDOWS_WIREGUARD_EXE=/path/to/wireguard.exe. default='C:\Program Files\WireGuard\wireguard.exe'
```

## Local data storage
The lib will store data in a `./data` directory:


### Main state file

**connection state files**: `data/connection.[name_of_connection]`

### Other Connection data
These files are pointed at in the state file. e.g. `routes_file: /path/to/data/routes.[name]`

**connection route files**: `data/routes.[name_of_connection]`

state file key: `routes_file`

**connection log files with rotation**: `data/logs/connection.[name_of_connection].log`

state file key: `log_file`
