Configuration

Cyberhive Connect has several configuration options to tune its behaviour to your needs. On Unix-like systems, these are set via environment variables.

The following options are available:

CONNECT_APPLY_DNS_SEARCH_SUFFIX

When set to true, the default, the TAN DNS suffix will be added to the search list on systems running systemd-resolved. If set to false the DNS suffix will not be added and on restarting the client, any existing setting will be removed.

Note

When Connect is registered with a new Organisation or uninstalled, the DNS search suffix is not removed from the settings. To manually remove it, delete the file /etc/systemd/resolved.conf.d/10-connectdomains.conf.

CONNECT_AUTH_TOKEN

When set, this token will be sent in requests to the Control Service to serve as authentication, which is useful mostly during registration when interactive authentication is not an option.

The token is linked to a user. This user must be specified in CONNECT_USERNAME.

Following registration, a signing key will have been generated. For authentication, the signing key is given preference over the authentication token, as the signature-based authentication works with PQ-resistant signatures, rather than a static key string.

When using CONNECT_AUTH_TOKEN, a secure connection must be used (https, ideally protected with KEMTLS or similar) to avoid leaking credentials. It is strongly recommended to only use the authentication token for registration.

CONNECT_AUTO_LISTEN_PORT

When set to true, the default, the listening port will be automatically set to an available, unused port. When set to false, the value provided by CONNECT_LISTEN_PORT will be used.

CONNECT_INJECTION_PORT

When in UDP injection mode (defined by CONNECT_INTERFACE_PATH), defines the port Connect uses to listen for (UDP-encapsulated) injected packets for the VPN.

CONNECT_INTERFACE_PATH

Overrides the tunnel interface path. For operating systems that use file-system based device paths, this permits pointing Connect to a different tunnel device, e.g. /dev/net/your_preferred_tun.

The interface path can also be set to 127.0.0.1:{port}, which enables UDP injection mode. In this mode, unencrypted network packets can be read/written on the socket (encapsulated in UDP packets), and Connect takes care of the encryption. {port} defines the port that an external application uses to listen for packets from the VPN (see also CONNECT_INJECTION_PORT which defines the port that Connect uses to listen for packets going to the VPN).

CONNECT_INTERFACE_PREFIX

Provides the prefix to be used as interface name. Optional.

CONNECT_KEY_DIR

Specify the directory where any keys such as SSH keys, signing keys, and preshared keys are stored. The default is $HOME/.config/cyberhive-connect for Unix-like systems.

CONNECT_LISTEN_PORT

Specify a listening port to use.

CONNECT_MTU

Specify the MTU to use inside the VPN tunnel. A good value is 80 bytes less than the MTU of your network interface. When not specified, Connect assumes a default of 1420. It is strongly advised to keep the MTU of your network interface at 1456 or higher.

CONNECT_RESOLVE

This provides name resolution for hosts that DNS doesn't know about. Formatted as hostname:ip[,hostname:ip]. This is similar to a hosts file, but limited in scope to services that Connect needs to function. Typically either not set, or limited to the IP address of the Control Service.

CONNECT_SERVER

Server URL to use when none is given on the command line. Should be in the format https://servername.domain:port (port number optional).

CONNECT_STUN

Setting this to "local" will make clients use their local IP addresses rather than public IP addresses. Use this for "local vpn", where all vpn clients run on the same LAN. Specify {ip}:{port} to force the client to advertise itself to the Control Service as being accessible on a given IP address and port number without performing STUN calls. In this mode, manual gateway configuration may be required.

CONNECT_TEMP_DIR

Specify the directory to be used as temporary directory.

CONNECT_USERNAME

user@domain style username to be used.

CONNECT_OVERRIDE_HOSTNAME

Format

Endpoint hostnames can contain only letters, numbers, and hyphens and must be 63 characters or less in length. Valid hostnames look like desktop-pc, DESKTOP-PC, or DesktopPC.

Invalid hostnames look like desktop_pc, DESKTOP PC, desktop--pc, or -DesktopPC.

Hostnames are also case-insensitive unique within an Organisation. For example, desktop-pc, Desktop-PC, and DESKTOP-PC are identical in Connect.

Each Endpoint within the Organisation must have a unique name. Set this if you wish to use a hostname that differs from the actual hostname of your machine, which Connect uses by default.

If your machine's actual hostname contains disallowed characters - such as spaces, underscores, or brackets - these will be automatically removed to conform to Connect's required hostname format.