Jump to content
Not connected, Your IP: 216.73.216.195
AirVPN
Suite

AirVPN Suite for Linux

AirVPN's free and open source OpenVPN 3 and WireGuard suite based on AirVPN's OpenVPN 3 library fork

Version 2.2.0 - Release date 15 October 2026

Main features:

  • Bluetit: lightweight D-Bus controlled system daemon providing full connectivity to AirVPN servers as well as generic OpenVPN and WireGuard servers. OpenVPN support is implemented by using AirVPN's OpenVPN 3 library fork whereas WireGuard support is ensured through the high-performance built-in Linux kernel module. VPN Traffic splitting feature to channel internet traffic inside (encrypted) and outside (clear) the VPN tunnel

  • Goldcrest: Bluetit client, allowing full integration with AirVPN servers, users, keys, profiles as well as generic OpenVPN and WireGuard servers

  • Hummingbird: lightweight and standalone client for generic OpenVPN and WireGuard server connection, for both Linux and macOS (please refer to README-hummingbird.md for more specific information)

  • Cuckoo: traffic split tool

  • Airsu: Switch user tool allowing graphical applications to properly use traffic splitting

  • Linux x86-64, armv7l and arm64 (Raspberry) support

  • AirVPN's exclusive per application traffic splitting system through Bluetit

  • Full integration with systemd, SysVStyle-init and chkconfig

  • No heavy framework required, no GUI

  • Tiny RAM footprint

  • Lightning fast

  • Based on OpenVPN 3 library fork by AirVPN with tons of critical bug fixes from the main branch, new cipher support and never-seen-before features

  • ChaCha20-Poly1305 cipher support on both Control and Data Channel providing great performance boost on ARM, Raspberry PI and any Linux-based platform not supporting AES-NI. Note: ChaCha20 support for Android has already been implemented in our free and open source Eddie Android edition

  • Robust leak prevention through Network Lock based either on iptables, nftables or pf through automatic detection

  • Proper handling of DNS push by VPN servers, working with resolv.conf as well as with any operational mode of systemd-resolved

  • Word completion (auto completion) support for bash and zsh

Contents

Introduction

AirVPN Suite is a collection of applications providing VPN connectivity both to AirVPN servers and to generic OpenVPN and WireGuard servers. The Suite offers two different operational methods to connect to a VPN server, according to the system in use. The Suite is made of five applications: Bluetit, Goldcrest, Hummingbird, Cuckoo and Airsu. It should be noted that full integration and functionality with the AirVPN infrastructure and servers are primarily provided by Bluetit and Goldcrest, whereas Hummingbird is a standalone program to connect to any OpenVPN or WireGuard server, including AirVPN's. AirVPN users are of course advised to install and use Bluetit and Goldcrest on their computers to have full access to, and functionality with, the AirVPN server infrastructure and to get a better security model provided by the specific client/server architecture of these two components.

Hummingbird, while it can be used to connect to any AirVPN server, is to be considered a standalone and portable tool for connecting to any OpenVPN or WireGuard server by providing a valid OpenVPN or WireGuard config file.

AirVPN Suite provides the following components:

  • Bluetit: D-Bus controlled system daemon with OpenVPN and WireGuard connectivity
  • Goldcrest: Command line client for Bluetit
  • Hummingbird: Standalone command line OpenVPN and WireGuard client
  • Cuckoo: Traffic split tool, running applications outside the VPN tunnel
  • Airsu: Switch user tool for running graphical applications with Cuckoo

All the components of AirVPN Suite are based on OpenVPN 3 AirVPN version 3.12 and embeddable WireGuard library 1.0.

Installing AirVPN Suite for Linux

AirVPN Suite is distributed both in binary and source code forms. Both the binary version and the complete source code are available in the official gitlab repository. For more information, feedback and latest news, please refer to AirVPN forum and related threads.

Requirements

The AirVPN Suite supports both systemd and SysVStyle-init Linux distributions on the x86-64, ARM32 and ARM64 architectures.

AirVPN Suite runs on the following architectures and systems:

Linux with OpenSSL 3.x

  • x86-64 (64 bit), ARM 32 or ARM 64 bit CPU
  • OpenSSL 3.x
  • tar
  • sha512sum (optional)
  • ldd (optional)

Linux with OpenSSL 1.1.1 series (legacy)

  • x86-64 (64 bit), ARM 32 or ARM 64 bit CPU
  • OpenSSL 1.1.1 series (any release from 1.1.1 to 1.1.1w)
  • tar
  • sha512sum (optional)
  • ldd (optional)

Each component of the suite requires specific dependencies to be properly installed, configured and running on your system. It is very likely most of the dependencies are already available and properly configured on your system as they are part of any modern Linux distribution. In case a specific dependency is not already available on your system, you need to install it by using each distribution's specific tool for installing packages. Each component requires the following dependencies to be available and installed on your system:

Bluetit

  • D-Bus
  • libxml2
  • libssl (OpenSSL 3.x, OpenSSL 1.1.1 series for legacy installation)

Goldcrest

  • D-Bus

Hummingbird

  • libssl (OpenSSL 3.x, OpenSSL 1.1.1 series for legacy installation)

Before installing the suite, you need to download the distribution package and checksum file for your specific system and in particular:

Install AirVPN Suite

AirVPN Suite comes with an installation Bourne shell script (sh) which tries to determine your system type and environment to properly run the correct installation procedure. In particular, AirVPN Suite can be used both in systemd and SysVStyle-init systems and the installation script takes care of both environments and properly configures the system.

The installation script can also create a proper user and group to let the Goldcrest client communicate with and use the Bluetit daemon. Specifically, the Bluetit daemon can be operated and used only by users belonging to the group airvpn. The installation script will prompt for both airvpn user and group to be created and, of course, it is up to the superuser to properly manage user and group creation. The creation of both airvpn user and group is optional, however the superuser is advised to add at least one user to the group airvpn to use and communicate with Bluetit daemon.

The superuser is of course granted the use and management of all AirVPN Suite components. Please note the installation script needs root privileges.

To install AirVPN Suite, please do the following steps:

  • Download AirVPN Suite tarball according to your system and to the links provided above.

  • [optional] Download the corresponding checksum file according to the links provided above. This file is needed to check the integrity of the above tar archive. It is not mandatory but it is strongly advised to download this file and check the tar archive integrity

  • Open a terminal window and log in as root by issuing the command su -l. In case your system does not allow root login (such as Ubuntu) you can use sudo or enable root login.

  • [optional] Check the integrity of the tar archive by issuing this command: sha512sum --check <checksum_file.sha512>

  • [optional] Make sure the command responds with <package_name>: OK

  • Change your current directory to a convenient place, such as your home directory. This can be done by issuing the command cd ~

  • Extract the tar archive by issuing this command in your terminal window: tar xvf <package_name>

  • A new directory will be created: AirVPN-Suite

  • Move into this new directory with command cd AirVPN-Suite

  • [optional] Check dynamic library availability. Issue the ldd command for each program of the suite:

    • ldd bin/bluetit

    • ldd bin/goldcrest

    • ldd bin/hummingbird

    Make sure all the required dynamic libraries are available. No line of the output must contain "not found"

  • AirVPN Suite is now ready to be installed

  • Make sure to log in as root either by opening a root terminal or by issuing the command su -l

  • Run the installation script: sh ./install.sh

  • In case your system does not permit root login, you can run the installation script with sudo sh ./install.sh. The user issuing this command must be in the "sudoers" list.

  • The script will configure your system according to the init style in use (systemd or SysVStyle-init) and will copy the programs in their specific locations:

    • bluetit will be copied to /sbin

    • goldcrest, hummingbird, cuckoo and airsu will be copied to /usr/local/bin or /usr/bin or /bin according to directory availability and in this specific order. Please note Hummingbird needs root privileges to run. Your user must therefore be included in your system's "sudoers" (depending on specific Linux distribution)

  • Depending on your system, the script will ask you whether you want the Bluetit daemon to start at boot, therefore making it always available to clients for connecting to any OpenVPN or WireGuard server, including AirVPN functionality and connectivity.

    • systemd If you want Bluetit to be started at boot, you need to answer "yes" to both "Do you want to enable bluetit.service unit?" and "Do you want to start Bluetit service now?"

    • SysVStyle-init If you want Bluetit to be started at boot, you need to answer "yes" to "Do you want to start bluetit at boot?". Please note the SysVStyle-init Bluetit script can also be used with chkconfig and the installation script will use it in case it is available on your system.

  • Bluetit daemon is accessible and used only by users belonging to the group airvpn or by root. In this regard, the installation script will ask whether it should create, in case it is not already defined on your system, the user airvpn. Creating such a user is not mandatory; it is however the responsibility of root to properly create and manage users and the airvpn group in order to comply with Bluetit policy.

  • The installation script will also ask whether the group airvpn should be created in case it is not already defined on your system. In case you do not want the script to create the group airvpn, be advised root must however create it and add to this group all the users allowed to run goldcrest and to interact with Bluetit daemon. In the scenario of a standard installation, only users belonging to the group airvpn are allowed to use and access Bluetit. The system administrator can of course change this behavior by changing and properly setting the policy of both D-Bus and Bluetit, under his or her own responsibility. To set or change D-Bus and Bluetit policy, please refer to the specific section below.

  • By default, the installation script will add the airvpn user to the airvpn group.

  • AirVPN Suite is now ready to be used.

Note about Hummingbird and SELinux

The user is always and strongly advised to use Bluetit daemon and to control it by using one of its clients, such as Goldcrest. In case you want to run Hummingbird from a systemd unit at boot time on a system with SELinux, please note that SELinux will prevent nft from being called by Hummingbird, because access to stdin is forbidden by the default policy. In this specific case, Hummingbird will be unable to enforce Network Lock rules via nft and you need to create a specific SELinux exception in order to do that.

Note on Checksum Files

We strongly suggest that you check the integrity of the distribution tar.gz file to make sure you are installing the suite created and fully supported by AirVPN. Please read CHECKSUM.md for more information and to get the checksum codes created and guaranteed by AirVPN.

AirVPN Bluetit daemon

AirVPN Bluetit daemon is the core component of the suite providing full support to connectivity and functionality with AirVPN server architecture and infrastructure. It also provides three levels of security and access control by allowing the superuser to define specific policies within Bluetit.

Bluetit also provides full connectivity with any generic OpenVPN or WireGuard server by using a working OpenVPN profile or configuration file. OpenVPN connectivity is implemented with OpenVPN 3 AirVPN library forked from the master project and actively maintained by AirVPN developers.

Bluetit is a daemon designed and developed with the aim of providing a lightweight system service with a low impact on the overall consumption of system resources. The daemon is accessed through a D-Bus interface exposing specific methods that give full support to VPN connections and AirVPN functionality, including - but not limited to - quick automatic connection to the best AirVPN server for any specific location, as well as connection to any specific AirVPN server.

It also allows the connection to any generic OpenVPN or WireGuard server by means of profile or configuration files. This means Bluetit can also be used with any OpenVPN or WireGuard infrastructure and is not limited to AirVPN's. As a matter of fact, AirVPN support and functionality can be disabled by the superuser, therefore turning Bluetit into a generic OpenVPN or WireGuard component.

Bluetit configuration

Bluetit allows the superuser to configure the functionality of the daemon, including specific access and use policies, in three different levels and each controlling a specific behavior as well as restricting the connections to particular servers. Bluetit control and access are provided through these three methods, which are covered in detail in the related sections below.

  • System user policy: access to the daemon can be granted only to specific users or groups

  • D-Bus policy both for daemon and client. This allows a "fine grained" access control by allowing or denying specific users or groups

  • Bluetit run control file

AirVPN Bluetit uses a set of files to control its behavior and, in particular, to ensure full support for all AirVPN functions and services. The configuration files used by Bluetit are stored in /etc/airvpn and this folder is created by the installation script, in case it does not exist. This directory also stores the bluetit.lock file (actually, a PID file) controlling the execution of the daemon. Please note the installation script sets /etc/airvpn and all the files it contains to mode 0660, that is rw-rw----, owned by root. This means only root can read, write and access the content of this directory.

Run control file

Bluetit daemon can be controlled by specific settings defined in the run control file bluetit.rc stored in /etc/airvpn. This file defines specific rules and settings to control the functionality of the daemon, in particular what services and functions are allowed, limited or denied by the superuser.

AirVPN Suite comes with a bluetit.rc template defining only the options needed to ensure AirVPN support, therefore allowing AirVPN connectivity "out of the box".

The run control file provides for the following options and types. The options defined as "list" can be used multiple times within bluetit.rc and each entry can have as a value either a string (with no quotes) or a list of strings in the form of value1,value2,value3,....

  • bootserver: (list) URL of AirVPN bootstrap server. To enable AirVPN support there must be at least one bootserver defined.

  • rsaexponent: (string) RSA exponent of AirVPN public key. This option must be set to enable AirVPN support.

  • rsamodulus: (string) RSA modulus of AirVPN public key. This option must be set to enable AirVPN support.

  • airconnectatboot: (string) Define whether Bluetit should connect to an AirVPN server at boot or startup time. Allowed values: off, quick, server, country. Default: off

  • networklockpersist: (string) Define the network lock method to be used for the whole Bluetit session. When turned on, traffic is allowed to and from the network only in case Bluetit is connected to a VPN. You should therefore consider activating this directive carefully in case Bluetit is started at boot time. In this specific case, you should be aware no traffic will be permitted soon after Bluetit startup and this will affect all services and processes subsequently started and requiring network access. Also consider this directive takes priority over the networklock directive, which will therefore be ignored. Network lock is an exclusive AirVPN feature to prevent data leakage in case of accidental disconnection by keeping the network traffic in a locked state. Network locking is done by a specific set of firewall rules allowing traffic to and from the connected server only. Allowed values: on (automatic), iptables, nftables, pf or off. The "on" value automatically detects the firewall system in use. Default: off

  • airusername: (string) Valid AirVPN username to be used for AirVPN connection at boot or startup time. Default: empty

  • airpassword: (string) Password associated with the airusername to be used for AirVPN connection at boot or startup time. Important: the password is stored in this directive and in the .rc file in plain text. You should consider this even though bluetit.rc, by default, can be read by the root user only. Default: empty

  • airvpntype: (string) VPN type to be used for AirVPN connections. Allowed values: wireguard, openvpn. Default: wireguard

  • airkey: (string) Name of AirVPN key associated with airusername. It must be an existing key, previously defined in the Client Area of the AirVPN website. Please note this value is case sensitive and it must be therefore exactly entered the way it has been defined in the Client Area. In case no key is provided, automatic connection will use the first key defined for airusername. Default: empty

  • airserver: (string) Name of AirVPN server to be used for boot connection by means of airconnectatboot directive. In this specific case, airconnectatboot must be set to server. Default: empty

  • aircountry: (string) Name of AirVPN country to be used for boot connection by means of airconnectatboot directive. In this specific case, airconnectatboot must be set to country. When this mode is enabled, AirVPN connection will be established with the best performing server of the specified country. Default: empty

  • airproto: (string) Protocol to be used for automatic boot connection. Allowed values: udp, tcp. Default: udp

  • airport: (integer) Port number to be used for automatic boot connection. Default: 443 for OpenVPN, 1637 for WireGuard

  • aircipher: (string) Cipher algorithm name to be used for automatic boot connection. Default: empty

  • airipv6: (on/off) Enable or disable IPv6 for automatic boot connection. Default: off

  • air4to6: (on/off) Enable or disable IPv4 over IPv6 tunnel for AirVPN connections. When set to on, it implicitly sets airipv6 to on in case airipv6 is not explicitly set. Default: IPv6 status of system

  • air6to4: (on/off) Enable or disable IPv6 over IPv4 tunnel for AirVPN connections. When set to on, it implicitly sets airipv6 to off in case airipv6 is not explicitly set. Default: IPv6 status of system

  • manifestupdateinterval: (integer) Interval between AirVPN manifest updates in minutes. Please note this value sets the initial or default interval time only and it may be overridden in case AirVPN manifest dictates a different interval. Default: 15

  • airwhiteserverlist: (list) Name of AirVPN servers allowed and available for connection. In case this option is defined, the clients can connect only to the specified AirVPN servers. Default: empty

  • airblackserverlist: (list) Name of AirVPN servers explicitly forbidden and denied for connection. In case this option is defined, the clients cannot connect to the specified AirVPN servers in any way. Default: empty

  • airwhitecountrylist: (list) Define the countries allowed and available for connection. In case this option is defined, the clients can connect only to AirVPN servers located in the specified countries. Countries must be specified with their corresponding ISO code. Default: empty

  • airblackcountrylist: (list) Define the countries explicitly forbidden and denied for connection. In case this option is defined, the clients cannot connect to any AirVPN server located in the specified countries. Countries must be specified with their corresponding ISO code. Default: empty

  • forbidquickhomecountry: (on/off) Never allow quick connection to connect to servers in the country where your computer is located, including those specified in the white list (option airwhiteserverlist). For security reasons, AirVPN strongly advises setting this option to on. Default: on

  • allowuservpnprofiles: (on/off) Allow Bluetit's clients (therefore, users) to provide custom VPN profiles. Default: off

  • country: (string) ISO code of the country where your computer is located (home country). In case this option is not used, Bluetit will determine the home country by contacting AirVPN's ipleak.net site through a secure connection. The home country is needed to let the AirVPN quick (automatic) connection properly choose the best server location, therefore ensuring the best traffic performance. Default: empty

    Important note for users connecting from Russian Federation: Because of the vast extension of the Russian Federation, covering a wide range of longitudes, please be aware that this country has been divided into two areas. Specifically, use R1 in case your system is located in the Western area of Russian Federation, R2 in case it is located in the Eastern area. For your reference, the division point is exactly located at 103.851959 decimal longitude. This is essential for the best server determination in case of AirVPN quick (automatic) connection. In fact, users located in the Western area of the Russian Federation (R1) are preferably connected to European AirVPN servers, whereas those in the Eastern area (R2) are connected to Asian AirVPN servers. This ensures the best performance for the whole Russian Federation. In case you set this option to RU, connection will be established with the best European AirVPN server.

  • remote: (list) Define the OpenVPN servers allowed for connection. Values can be either valid IP addresses or host names. This option also affects AirVPN connectivity: it will allow connection only to AirVPN servers whose IP addresses are defined in this option. Default: empty

  • proto: (list) Define the protocols allowed and available for connection for both AirVPN and OpenVPN servers. Allowed values are udp and tcp. Default: empty

  • port: (list) Define the port numbers allowed and available for connection for both AirVPN and generic VPN servers. Default: empty

  • tunpersist: (on/off) Enable or disable tunnel persistence. In case it is enabled the tun device is kept active in case of VPN connection loss or pause. This usually prevents traffic leaks during reconnection or accidental disconnection. Default: on

  • cipher: (list) Define the cipher algorithms allowed for connection for both AirVPN and OpenVPN servers. Default: empty

  • mtu: (integer) MTU value for WireGuard VPN interface. Allowed range is from 1280 to 1440. Default: 1320

  • maxconnretries: (integer) Define the maximum number of retries for VPN connections, specifically direct connection to AirVPN servers, connection at boot to an AirVPN server and to a generic OpenVPN profile. It does not apply to AirVPN quick connection which is tried just once. In case of failed connection, the next attempts will be tried after a 5-second pause. Default: 10

  • tcpqueuelimit: (integer) Define the maximum number of queued TCP output packets. In case this value is too small, it is very likely the queue becomes frequently full, therefore leading to data loss. This is particularly true for high speed connections. Default: 8192

  • networklock: (string) Define the network lock method to be used during the connection. This directive is ignored in case networklockpersist directive is set. Network lock is an exclusive AirVPN feature to prevent data leakage in case of accidental disconnection by keeping the network traffic in a locked state. Network locking is done by a specific set of firewall rules allowing traffic to and from the connected server only. Allowed values: on (automatic), iptables, nftables, pf or off. The "on" value automatically detects the firewall system in use. Default: on

  • networkcheck: (on/gateway/airvpn/off) Network check mode at startup. This check forces Bluetit to wait for a valid network connection before startup and availability to clients. In gateway mode, Bluetit waits for a valid network gateway to be available before continuing startup. In airvpn mode, which can also be considered an internet availability test, Bluetit waits until a valid and usable internet connection is available, that is until a connection to the AirVPN server infrastructure succeeds. In this specific case, be aware Bluetit actually sends connection requests to AirVPN servers and, therefore, it actually sends and receives unencrypted data packets to and from the external network. Default: on, corresponding to gateway mode.

  • allowprivatenetwork: (yes/no) Control how the local and private network traffic can pass through the Network Lock. When disabled, only VPN traffic is allowed through the Network Lock. When enabled, local and private network traffic, as well as VPN traffic, is allowed to pass through the Network Lock. Default: yes

  • allowping: (string) Control how ICMP echo-request and echo-reply messages (ping) should be treated by the Network Lock. When disabled, ping, both input and output, is blocked by the Network Lock. When enabled, ping messages, both input and output, are allowed to pass through the Network Lock. Allowed values: on, off, input or output. Default: output

  • allowipv6ndp: (yes/no) Control how IPv6 ICMP NDP messages (Neighbor Discovery Protocol) should be treated by the Network Lock. When disabled, NDP, both input and output, are blocked by the Network Lock. When enabled, NDP messages, both input and output, are allowed to pass through the Network Lock. Allowed values: on, off. Default: yes

  • ignorednspush: (yes/no) Define whether Bluetit should ignore the DNS setting pushed by the server or not. In case DNS push is ignored, connection will use current system DNS configuration. Default: no

  • timeout: (integer) OpenVPN connection timeout in seconds. Default: 0 (retry indefinitely)

  • compress: (string) Compression mode. Allowed values: yes - allow compression on both uplink and downlink; asym - allow compression on downlink only; no - support compression stubs only. Default: no

  • tlsversionmin: (string) Minimum TLS version override. Allowed values: disabled - don't specify a minimum; default - use TLS version defined in profile; tls_1_0 - use TLS 1.0 minimum; tls_1_1 - use TLS 1.1 minimum; tls_1_2 - use TLS 1.2 minimum. Default: default

  • proxyhost: (string) Proxy IP address or URL. Default: empty

  • proxyport: (integer) Proxy port number. Default: empty

  • proxyusername: (string) Proxy user name. Default: empty

  • proxypassword: (string) Proxy user password. Default: empty

  • proxybasic: (yes/no) Allow HTTP basic auth for proxy connection. Default: no

  • allowtrafficsplitting: (on/off) Enable or disable traffic splitting (unencrypted and out of the tunnel traffic). Default: off

  • trafficsplitnamespace: (string) Name of Linux network namespace dedicated to traffic splitting. Default: aircuckoo

  • trafficsplitinterface: (string) Name of the physical network interface to be used for traffic splitting. All the unencrypted and out of the tunnel data will pass through the specified network device/interface. In case this directive is not specified, Bluetit will automatically use the main network interface of the system, that is the one connected to the default gateway. Default: unspecified

  • trafficsplitnamespaceinterface: (string) Name of the virtual network interface to be associated with the Linux network namespace dedicated to traffic splitting. Default: ckveth0

  • trafficsplitipv4: (IPv4 address|auto) IPv4 address of the virtual network interface used for traffic splitting. In case it is set to 'auto', Bluetit will try to automatically assign an unused IPv4 address belonging to the system's host sub-network (/24). Default: auto

  • trafficsplitipv6: (IPv6 address|auto) IPv6 address of the virtual network interface used for traffic splitting. In case it is set to 'auto', Bluetit will try to automatically assign an unused IPv6 address belonging to the system's host sub-network (/64). Default: auto

  • trafficsplitfirewall: (on/off) Enable or disable the firewall in Linux network namespace dedicated to traffic splitting. The firewall is set up with a minimal rule set for a very basic security model. Default: off

User policy

Bluetit user policy is provided by means of two separate levels: system user policy and D-Bus configuration, the latter providing a fine grained control over both groups and users. Bluetit can in fact be accessed only through its D-Bus interface exposing methods for controlling both AirVPN functionality and VPN connectivity. Clients and users can therefore use Bluetit only in case a specific and proper D-Bus policy has been defined for them.

The default policy provided by the default configuration files found in the standard distribution package (that is the one directly distributed by AirVPN only) permits Bluetit access only to users belonging to the system group airvpn. This restriction is essentially defined by the D-Bus policy.

By using D-Bus configuration mechanism, the superuser can change this default policy, including granting or denying access to specific users and groups, under his or her own responsibility.

System user policy is controlled by the usual system commands (e.g. useradd, usermod and groupadd) whereas D-Bus configuration files are stored in /etc/dbus-1/system.d and controlled by these specific files:

  • org.airvpn.server.conf: D-Bus policy for Bluetit daemon (server)

  • org.airvpn.client.conf: D-Bus policy for all clients

By changing the content of these files, the superuser can change and define Bluetit access policy according to the specific need of the environment and system. In case one of these files is changed, as well as when a user or group is changed or added, please remember to reload the D-Bus configuration to make the changes effective. (systemd: "systemctl reload dbus.service" - SysVStyle-init: "/etc/init.d/dbus reload")

Bluetit default connection values

Bluetit uses specific default values applied to any VPN connection unless otherwise specified either by the client (e.g. goldcrest) or by the run control file bluetit.rc.

These default values are always applied regardless of the VPN connection type, either to any AirVPN server or generic server connected via a custom OpenVPN configuration file. In this latter case, you should consider that some of the directives of the OpenVPN configuration file will always be overridden by Bluetit default values, unless they are explicitly set with the corresponding Bluetit options through a client (e.g. goldcrest command line options).

The following values are used as default for these specific connection parameters:

  • proto: UDP
  • port: 443 for OpenVPN, 1637 for WireGuard
  • TLS mode: Crypt (only for AirVPN connections)
  • cipher: Server. This means the choice of the cipher algorithm is determined by the connected server configuration.

Controlling Bluetit daemon

Running and stopping Bluetit daemon depends on the system in use. Although Bluetit can be run by directly invoking it from a terminal or shell (e.g. entering /sbin/bluetit) it is advised to control it by using either systemd tools or SysVStyle-init script. Please note Bluetit daemon requires root privileges to run.

When Bluetit starts, it creates the "lock" file bluetit.lock in /etc/airvpn. This file is actually a PID file and is also used to check whether Bluetit is running or has ended abnormally. In case you are sure Bluetit is not running, you can delete this file to let Bluetit start again.

Bluetit daemon uses the following system signals to control specific actions. You can send a signal to Bluetit by using the kill command from a terminal.

  • SIGTERM, SIGINT, SIGPIPE and SIGHUP: Stop and terminate Bluetit daemon. In case Bluetit is connected to a server, the connection will be terminated. No VPN connectivity is therefore available and no client will be able to use it.

  • SIGUSR1: This is actually a toggle signal to be used to both pause and resume VPN connection. In case Bluetit is connected to a VPN server, the connection is paused, whereas in case it is paused, VPN connection will be resumed. When the VPN connection is paused, the tunnel device status is controlled according to tunpersist option. Also consider that pausing and resuming a connection is allowed only in case TUN persistence is enabled.

  • SIGUSR2: Reconnect (restart) the current VPN connection. Reconnecting a connection is allowed only in case TUN persistence is enabled.

systemd

In a systemd controlled system, Bluetit can be controlled by using the systemctl tool and with the usual options. The systemd unit name controlling Bluetit is bluetit.service. Below are described the relevant commands to be used for controlling Bluetit daemon.

  • systemctl enable bluetit.service: Enable Bluetit to run at boot time. This makes Bluetit available and running whenever you turn your system on or restart it.

  • systemctl disable bluetit.service: Disable Bluetit run at boot time. In case you want to use Bluetit, you need to explicitly start it with the command below.

  • systemctl start bluetit.service: Start Bluetit daemon for the current session.

  • systemctl stop bluetit.service: Stop Bluetit daemon. In case Bluetit is connected to a server, the connection will be terminated. No VPN connectivity is therefore available and no client will be able to use it.

  • systemctl restart bluetit.service: Restart Bluetit daemon. In case Bluetit is connected to a server, the connection will be terminated and will not be resumed.

  • systemctl status bluetit.service: Show the running status of Bluetit daemon.

SysVStyle-init

In a SysVStyle-init system, Bluetit can be controlled by using the bluetit script found in /etc/init.d. The script is compatible with chkconfig and, by default, the installation script will configure Bluetit daemon to start at run levels 3 and 5 only. By default, start priority is assigned to 90 whereas stop priority is 60. Below are listed the relevant commands to control Bluetit daemon in a SysVStyle-init system.

  • /etc/init.d/bluetit start: Start Bluetit daemon for the current session.

  • /etc/init.d/bluetit stop: Stop Bluetit daemon. In case Bluetit is connected to a server, the connection will be terminated. No VPN connectivity is therefore available and no client will be able to use it.

  • /etc/init.d/bluetit restart: Restart Bluetit daemon. In case Bluetit is connected to a server, the connection will be terminated and will not be resumed.

  • /etc/init.d/bluetit status: Show the running status of Bluetit daemon.

Logging

The whole activity of Bluetit daemon is logged to the system log, that is to syslog, including requests from clients, errors and information messages which may be useful to the superuser to better understand the daemon activity.

All log messages sent to syslog are tagged as bluetit and can be therefore filtered according to this key. Not all log messages are sent to the client, therefore in case of critical errors or to better understand the cause of errors, the superuser should rely on syslog messages rather than on client messages. System relevant messages, as well as internal and sensitive information are sent to the syslog only, whereas only user-related messages, including error messages relevant to user activity, are sent to the client.

Bluetit log can be browsed according to the standard tools and logging facilities in use on each specific system or Linux distribution.

Automatic connection at boot or startup time

Bluetit can start an automatic connection to any AirVPN server at boot time or startup time. To use this feature, Bluetit needs to be started either via systemd or SysVStyle-init scripting facilities, depending on your system.

Automatic connection at boot or startup time can be performed in the same ways allowed for any standard AirVPN connection. To enable automatic connection at boot or startup time, you need to properly configure bluetit.rc file by using the directives implemented for this specific purpose, in particular airusername, airpassword and airconnectatboot, which make the minimum setting required for automatic connection at startup.

Bluetit provides for the following automatic connection modes, to be specified in the airconnectatboot directive:

quick: Start a quick connection by selecting the best performing server at the moment of connection and according to your home country

server: Start a connection to a specific AirVPN server. This mode requires the directive airserver to be properly assigned to a valid, existing and available AirVPN server

country: Start a connection to the best performing AirVPN server at the moment of connection of a specific AirVPN country. This mode requires the directive aircountry to be properly assigned to a valid and existing AirVPN country

Please note, in case airconnectatboot is set to server or country, the directives airserver or aircountry must be set accordingly. Also note, the automatic boot or startup connection requires the user's credentials to be properly specified in airusername and airpassword. Moreover, the connection can also be further personalized with any other directive controlling a VPN connection, as well as a specific AirVPN key associated with the user. The connection key must be specified with the airkey directive. Please note this directive is case sensitive, the key name must therefore be exactly entered the way it has been defined in the Client Area of the AirVPN website. In case no airkey is provided, automatic boot connection will use the first key associated with the user in the Client Area.

The automatic connection at boot or startup time can also be optionally started with a specific protocol and port. In this case, the directives airproto and airport must be set to the desired values.

When started, the automatic connection can be controlled by using Goldcrest client. For this specific purpose, in fact, the client provides three options to be used to stop (disconnect), pause or resume the connection. Please note that pausing or resuming a connection works only in case the connection has been started with tun persistence mode enabled.

Please note that in case you want to control Bluetit automatic connection with the commands below, no other Bluetit client must be running.

Stop the current connection

$ goldcrest --disconnect

Pause the current VPN connection

$ goldcrest --pause

Resume the current VPN connection

$ goldcrest --resume

Goldcrest client

Goldcrest is the command line Bluetit client allowing full functionality and control for both generic VPN and AirVPN servers. To use Goldcrest, the user must belong to the group airvpn which is optionally created by the installation script. For your convenience, the installation script can create the airvpn user specifically meant to be used for this purpose. The system administrator can of course add any other user to the group airvpn to grant other users the use of Bluetit daemon through the Goldcrest client. In this regard, please refer to the Bluetit configuration sections above.

Goldcrest can be controlled by invoking it with command line options as well as configuring it by properly editing its configuration file as described below. Below are listed all the command line options supported by Goldcrest:

Goldcrest - AirVPN Bluetit Client 2.2.0 - 15 October 2026

usage: ./goldcrest [options] [config-file]

--help, -h : Show the help page
--version, -v : Show version info
--bluetit-status : Show Bluetit status and exit
--bluetit-stats : Show Bluetit connection statistics and exit
--air-connect, -O : Start AirVPN connection
--air-server, -S : AirVPN server name <pattern>
--air-country, -Z : AirVPN country or continent <pattern|country ISO code|continent code>
--air-vpn-type, -f : VPN type for AirVPN connection <wireguard|openvpn>
--air-tls-mode, -T : TLS mode for AirVPN connection <auto|auth|crypt>
--air-ipv6, -V : IPv6 mode for AirVPN connection <on|off>
--air-4to6, -n : Enable IPv4 over IPv6 tunnel for AirVPN connection <on|off>
--air-6to4, -B : Enable IPv6 over IPv4 tunnel for AirVPN connection <on|off>
--air-user, -U : AirVPN user name
--air-password, -P : AirVPN user password
--air-key, -F : AirVPN user key <name>
--air-key-list, -K : AirVPN user key list
--air-key-load, -Q : Load (use) AirVPN user key from local file <file_name>
--air-user-info : Show information about an AirVPN user
--air-save, -W : Save an AirVPN server, country profile or user key to local file <file_name>
--air-info, -I : AirVPN info (requires --air-server or --air-country)
--air-list, -L : AirVPN server or country list <pattern>
--air-sort : Ascending order sort criterion for AirVPN server list <name|location|score|load|users|bandwidth|maxbandwidth> Default name (requires --air-list and --air-server)
--air-rsort : Descending order sort criterion for AirVPN server list <name|location|score|load|users|bandwidth|maxbandwidth> (requires --air-list and --air-server)
--air-limit : AirVPN server or country list items limit <number> (requires --air-list)
--air-white-server-list, -G : AirVPN white server list <list>
--air-black-server-list, -M : AirVPN black server list <list>
--air-white-country-list, -J : AirVPN white country list <list>
--air-black-country-list, -X : AirVPN black country list <list>
--air-bootserver-info : List AirVPN boot server information and ranking
--async : Enable asynchronous connection for --air-connect option and user VPN profiles
--cipher, -C : Encrypt packets with specific cipher algorithm <alg>
--list-data-ciphers, -D : List supported data ciphers
--server, -s : Server override
--proto, -p : Protocol override <udp|tcp>
--port, -R : Port override
--tcp-queue-limit, -l : Size of TCP packet queue <1-65535> default 8192
--allowuaf, -6 : Allow unused address families <yes|no|default>
--mtu, -r : WireGuard MTU
--network-lock, -N : Network filter and lock mode <on|iptables|nftables|pf|off> Default on
--network-lock (async), -N : Network filter and lock mode (asynchronous mode) <on|off|noprivate>
--allow-private-network : Allow private IPv4 and IPv6 network classes to pass to and from the network filter. Default on
--allow-ping : Allow ping to pass to and from the network filter. <on|off|input|output> Default output
--allow-ipv6ndp : Allow IPv6 NDP to pass to and from the network filter. <on|off> Default on
--ignore-dns-push, -i : Ignore DNS push request and use system DNS settings
--timeout, -t : Connection timeout <seconds>
--compress, -c : Compression mode <yes|no|asym>
--pk-password, -z : Private key password
--tvm-override, -m : tls-version-min override <disabled|default|tls_1_x>
--tcprof-override, -o : tls-cert-profile override <legacy|preferred|...>
--proxy-host, -y : HTTP proxy hostname/IP
--proxy-port, -q : HTTP proxy port
--proxy-username, -u : HTTP proxy username
--proxy-password, -w : HTTP proxy password
--proxy-basic, -b : Allow HTTP basic auth
--alt-proxy, -A : Enable alternative proxy module
--no-cert, -x : Disable client certificate
--def-keydir, -k : Default key direction <bi|0|1>
--ssl-debug : SSL debug level
--auto-sess, -a : Request autologin session
--auth-retry, -Y : Retry connection on auth failure
--persist-tun, -j : Keep TUN interface open across reconnections
--peer-info, -e : Peer information key/value list in the form K1=V1,K2=V2,...
--gremlin, -g : Gremlin information <send_delay_ms|recv_delay_ms|send_drop_prob|recv_drop_prob>
--epki-ca : Simulate external PKI certificate supporting intermediate/root certificates
--epki-cert : Simulate external PKI certificate
--epki-key : Simulate external PKI private key
--gui-version, -E : Set custom gui version <text>
--recover-network, -H : Recover network settings after a crash or unexpected exit
--remove-wireguard-device : Remove any existing WireGuard tunnel device after a crash or unexpected exit
--disconnect : Disconnect the VPN session, including Bluetit boot connection
--pause : Pause the VPN connection, including Bluetit boot connection
--resume : Resume a paused VPN connection, including Bluetit boot connection
--reconnect : Reconnect the VPN connection, including Bluetit boot connection

Open Source Project by AirVPN (https://airvpn.org)

Linux and macOS design, development and coding by ProMIND

Special thanks to the AirVPN community for the valuable help,
support, suggestions and testing.

All the above options beginning with --air are specifically meant to be used with AirVPN server and infrastructure, having no effect when connecting to a generic OpenVPN or WireGuard server by using a config file. This is also true when Goldcrest is used for connecting to an AirVPN server with a config file either created and saved with Goldcrest or generated with the Config Generator available on the AirVPN website.

The remaining options can affect connectivity of both AirVPN and generic OpenVPN/WireGuard servers, therefore allowing the user to override either the connection directives of the optional config file or the default parameters of both Goldcrest and Bluetit. In this regard, Bluetit configuration and options cannot be overridden in any way by Goldcrest and, in this sense, Bluetit configuration sets the connectivity limit for all clients and what can be done when connecting to any VPN server, either being an OpenVPN or AirVPN one.

Goldcrest configuration

The configuration of Goldcrest is meant to set a specific group of default options to be used at each connection, both to a generic OpenVPN and AirVPN server. The values specified in the configuration file can be overridden by command line options and, in this sense, command line options always take precedence over the configuration file.

The configuration file location changes according to each specific system and, in particular, whether the home directory complies with freedesktop.org's XDG standard layout (X Desktop Group) and whether the .config directory is available in the user's home directory.

In case .config directory is available, Goldcrest configuration file is stored in ~/.config/goldcrest.rc otherwise it is always found in ~/.goldcrest.rc. In the latter case, please note the . (dot) at the beginning of the file name, actually making it a "hidden file".

When Goldcrest is run for the first time, it will create a template configuration file in case it is not found in the user's home directory. The options available in the configuration file have the same names as the command line options. In this regard, you should note the double dash -- must not be used in the configuration file and not all the command line options can be used in the configuration file.

The configuration file provides for the following options and types. The options defined as "list" can be used multiple times within the configuration file and each entry can have as a value either a string (with no quotes) or a list of strings in the form of value1,value2,value3,....

  • air-server: (string) Default AirVPN server to be used in any AirVPN connection. Default: empty

  • air-tls-mode: (auto/auth/crypt) Default TLS mode for AirVPN connections. Default: empty

  • air-ipv6: (on/off) Enable or disable IPv6 for AirVPN connections. Default: off

  • air-4to6: (on/off) Enable or disable IPv4 over IPv6 tunnel for AirVPN connection. When set to on, it implicitly sets air-ipv6 to on. Default: IPv6 status of system

  • air-6to4: (on/off) Enable or disable IPv6 over IPv4 tunnel for AirVPN connection. When set to on, it implicitly sets air-ipv6 to off. Default: IPv6 status of system

  • air-user: (string) Default AirVPN username. Default: empty

  • air-password: (string) Default AirVPN username password. Please note the password is written in this file in plain text, therefore it is visible to anyone reading the configuration file. For security reasons, the user is advised to not store the user password in the configuration file and to enter it at each use. For more information on AirVPN user access, please see below. Default: empty

  • air-key: (string) Default AirVPN user key to be used for all AirVPN operations and as defined in the "client area" on the AirVPN website. Default: empty

  • air-white-server-list: (list) Name of AirVPN servers allowed and available for connection. In case this option is defined, Goldcrest can connect only to the specified AirVPN servers. Please note the list is not an override to Bluetit's white and black server list policy. In case a server defined in this list is not allowed by Bluetit's policy (either on server or country basis) the server is ignored. Default: empty

  • air-black-server-list: (list) Name of AirVPN servers explicitly forbidden and denied for connection. In case this option is defined, Goldcrest cannot connect to the specified AirVPN servers in any way. Default: empty

  • air-white-country-list: (list) Define the countries allowed and available for connection in Goldcrest. In case this option is defined, Goldcrest can connect only to AirVPN servers located in the specified countries. Countries must be specified with their corresponding ISO code. Please note the list is not an override to Bluetit's white or black country list policy. In case a country defined in this list is not allowed by Bluetit's policy, the country is ignored. Default: empty

  • air-black-country-list: (list) Define the countries explicitly forbidden and denied for connection in Goldcrest. In case this option is defined, Goldcrest cannot connect to any AirVPN server located in the specified countries. Countries must be specified with their corresponding ISO code. Default: empty

  • cipher: (string) Default cipher algorithm name for all VPN connections. Default: empty

  • proto: (udp/tcp) Default protocol for all VPN connections. Default: empty

  • server: (string) Default server IP address or URL to be used for generic OpenVPN connection. Default: empty

  • port: (number) Default port number for all VPN connections. Default: empty

  • tcp-queue-limit: (integer) Define the maximum number of queued TCP output packets. In case this value is too small, it is very likely the queue becomes frequently full, therefore leading to data loss. This is particularly true for high speed connections. Default: 8192

  • network-lock: (string) Define the network lock method to be used during the connection. Network lock is an exclusive AirVPN feature to prevent data leakage in case of accidental disconnection by keeping the network traffic in a locked state. Network locking is done by a specific set of firewall rules allowing traffic to and from the connected server only. Allowed values: on (automatic), iptables, nftables, pf or off. The on value automatically detects the firewall system in use. Default: on

  • allow-private-network: (yes/no) Control how the local and private network traffic can pass through the Network Lock. When disabled, only VPN traffic is allowed through the Network Lock. When enabled, local and private network traffic, as well as VPN traffic, is allowed to pass through the Network Lock. Default: yes

  • allow-ping: (string) Control how ICMP echo-request and echo-reply messages (ping) should be treated by the Network Lock. When disabled, ping, both input and output, is blocked by the Network Lock. When enabled, ping messages, both input and output, are allowed to pass through the Network Lock. Allowed values: on, off, input or output. Default: output

  • allow-ipv6ndp: (yes/no) Control how IPv6 ICMP NDP messages (Neighbor Discovery Protocol) should be treated by the Network Lock. When disabled, NDP, both input and output, are blocked by the Network Lock. When enabled, NDP messages, both input and output, are allowed to pass through the Network Lock. Default: yes

  • ignore-dns-push: (yes/no) Define whether the connection process should ignore the DNS setting pushed by the server or not. In case DNS push is ignored, connection will use current system DNS configuration. Default: no

  • allowuaf: (yes/no/default) Allow unused address families. Default: default

  • timeout: (integer) Connection timeout in seconds. Default: 0 (retry indefinitely)

  • compress: (string) Compression mode. Allowed values: yes - allow compression on both uplink and downlink; asym - allow compression on downlink only; no - support compression stubs only. Default: no

  • proxy-host: (string) Proxy IP address or URL. Default: empty

  • proxy-port: (integer) Proxy port number. Default: empty

  • proxy-username: (string) Proxy user name. Default: empty

  • proxy-password: (string) Proxy user password. Default: empty

  • proxy-basic: (yes/no) Allow HTTP basic auth for proxy connection. Default: no

  • alt-proxy: (yes/no) enable alternative proxy module. Default: no

  • persist-tun: (on/off) Enable or disable tunnel persistence. In case it is enabled the tun device is kept active in case of VPN connection loss or pause. This usually prevents traffic leaks during reconnection or accidental disconnection. Default: on

  • mtu: (integer) MTU value for WireGuard VPN interface. Allowed range is from 1280 to 1440. Default: empty (use Bluetit setting)

  • async: (on/off) Enable or disable asynchronous VPN connection. Default: off

  • conn-stat-interval: (integer) Interval time in seconds for connection statistics logging. When set to 0, connection statistics logging is disabled. Default: 60 seconds

Note on AirVPN username and password

When accessing AirVPN user functions or connecting to a server, Goldcrest requires a valid AirVPN username and password to properly login to AirVPN infrastructure. In particular, whenever Goldcrest is used with the options --air-connect, --air-key, --air-key-list, --air-save and --air-key-load, it is mandatory to provide AirVPN credentials, that is a valid username and password.

There are many ways to provide AirVPN credentials to Goldcrest and specifically:

  • Configuration file (options air-user and air-password)

  • Command line options (--air-user and --air-password)

  • Keyboard input

Please note command line options have the highest priority, therefore, in case credentials are stored in the configuration file and Goldcrest is run with command line options --air-user or --air-password, this will explicitly override the value defined in the configuration file.

In case the credentials, or one of them (username or password), are not provided either in the configuration file or in the command line options, Goldcrest will ask the user to enter them with the keyboard. In this specific case, username will be echoed to the output while it is being typed, whereas the password will not be echoed on the terminal for obvious security reasons.

In case AirVPN credentials are stored in the configuration file, please be aware of the fact they are stored in plain text, therefore perfectly readable by anyone having access to the configuration file. For this reason, to ensure the best safeguarding of AirVPN credentials, it is advised to always enter them from the keyboard when Goldcrest asks the user to do so.

Controlling Goldcrest client

Goldcrest uses the following system signals to control specific actions. You can send a signal to Goldcrest by using the kill command from a terminal.

  • SIGTERM, SIGINT, SIGPIPE, SIGHUP: Disconnect the active VPN connection

  • SIGUSR1: This is actually a toggle signal to be used to both pause and resume VPN connection. In case Goldcrest is connected to a VPN server, the connection is paused, whereas in case it is paused, VPN connection will be resumed. When the VPN connection is paused, the tunnel device status is controlled according to --persist-tun option. Also consider that pausing and resuming a connection is allowed only in case TUN persistence is enabled.

  • SIGUSR2: Reconnect (restart) the current VPN connection. Reconnecting a connection is allowed only in case TUN persistence is enabled.

Using Goldcrest with AirVPN Servers

Goldcrest provides full functionality with AirVPN infrastructure to registered and active users. The client allows the user to both start and stop a connection to any AirVPN server as well as fetching information about the user, user key, servers and countries.

The user can therefore arbitrarily start a VPN connection to a specific AirVPN server and with specific connection parameters - such as protocol, cipher algorithm and port - as well as starting a quick (automatic) connection by letting Bluetit choose the best server to ensure the best traffic performance.

Below are some examples of how to use Goldcrest with AirVPN. Some of them require the user to provide valid AirVPN credentials by using the methods described above.

List AirVPN servers

List all AirVPN servers whose name, country or location contain the pattern "co"

$ goldcrest --air-list --air-server co

List all AirVPN servers located in Germany

$ goldcrest --air-list --air-server germany

or

$ goldcrest --air-list --air-server de

List all AirVPN servers

$ goldcrest --air-list --air-server all

List all AirVPN servers sorted by score

$ goldcrest --air-list --air-server earth --air-sort score

List the first 5 best AirVPN servers in Europe

$ goldcrest --air-list --air-server europe --air-sort score --air-limit 5

List AirVPN servers in America sorted by traffic load

$ goldcrest --air-list --air-server america --air-sort load

List AirVPN countries

List all AirVPN countries whose name or ISO code contain the pattern "se"

$ goldcrest --air-list --air-country SE

List a specific AirVPN country

$ goldcrest --air-list --air-country Sweden

List all AirVPN countries

$ goldcrest --air-list --air-country all

List the first 10 AirVPN countries alphabetically

$ goldcrest --air-list --air-country all --air-limit 10

Request information about a specific AirVPN server

$ goldcrest --air-info --air-server diadema

Request information about a specific AirVPN country

$ goldcrest --air-info --air-country japan

or

$ goldcrest --air-info --air-country nl

Request information about a specific AirVPN continent

$ goldcrest --air-info --air-country europe

or

$ goldcrest --air-info --air-country eur

Continent codes and names are defined as follows:

Code Name
---- ----------------
AFR Africa
AME America
ASI Asia
EARTH Earth
EUR Europe
NAM North America
OCE Oceania
SAM South America

Please note the statistics returned by --air-info and --air-list options, when used with --air-country, include the available and active AirVPN servers only. This may differ from what is shown on the server page of the AirVPN website, where all the servers making up the whole network are considered, regardless of their operational status.

List user keys

$ goldcrest --air-key-list

Save user key to a local file

$ goldcrest --air-save mykey.asc --air-key my_key

Generate and save an OpenVPN config file for an AirVPN server

$ goldcrest --air-save comae.ovpn --air-server comae --air-vpn-type openvpn

Generate an OpenVPN config file for a specific user key

$ goldcrest --air-save comae.ovpn --air-server comae --air-key my_key

Generate and save a WireGuard config file for an AirVPN server

$ goldcrest --air-save luhman.conf --air-server luhman --air-vpn-type wireguard

Generate and save an OpenVPN config file for an AirVPN country

$ goldcrest --air-save usa.ovpn --air-country US --air-vpn-type openvpn

$ goldcrest --air-save spain.ovpn --air-country spain --air-vpn-type openvpn

Generate an OpenVPN config file for a specific user key

$ goldcrest --air-save belgium.ovpn --air-country belgium --air-key my_key

Generate and save a WireGuard config file for an AirVPN country

$ goldcrest --air-save sweden.conf --air-country SE --air-vpn-type wireguard

$ goldcrest --air-save germany.conf --air-country germany --air-vpn-type wireguard

Start a quick (automatic) connection to AirVPN

$ goldcrest --air-connect

Start a quick connection with a specific key

$ goldcrest --air-connect --air-key my_key

Start a quick connection with a specific protocol and port

$ goldcrest --air-connect --proto tcp --port 80

Start a quick connection with a specific cipher algorithm

$ goldcrest --air-connect --cipher CHACHA20-POLY1305

Start a quick WireGuard connection

$ goldcrest --air-connect --air-vpn-type wireguard

Start a quick OpenVPN connection

$ goldcrest --air-connect --air-vpn-type openvpn

Start an asynchronous quick (automatic) connection to AirVPN

$ goldcrest --air-connect --async

Start a connection to a specific AirVPN server

$ goldcrest --air-connect --air-server orion

Start a connection with a specific key

$ goldcrest --air-connect --air-server mebsuta --air-key my_key

Start a connection with a specific protocol and port

$ goldcrest --air-connect --air-server luhman --proto udp --port 443

Start a connection with a specific cipher algorithm

$ goldcrest --air-connect --air-server comae --cipher AES-128-GCM

Start a connection to a specific AirVPN country

$ goldcrest --air-connect --air-country canada

Start a connection with a specific key

$ goldcrest --air-connect --air-country ukraine --air-key my_key

Start a connection with a specific protocol and port

$ goldcrest --air-connect --air-country ch --proto udp --port 443

Start a connection with a specific cipher algorithm

$ goldcrest --air-connect --air-country spain --cipher AES-256-GCM

Stop a connection

Type CTRL+C in the terminal window where Goldcrest is running. The client will ask Bluetit daemon to initiate the disconnection process and to restore your original network settings according to your options.

Using Goldcrest with Generic VPN servers

Goldcrest can also be used to connect to any generic OpenVPN or WireGuard server by providing a valid config file or profile. When connecting to a generic VPN server, that is by providing a VPN config file, all the AirVPN options --air-* will be ignored and have no effect. The profile type is automatically recognized by Goldcrest, which will start the corresponding VPN connection accordingly.

To connect to a generic OpenVPN server, you need to provide the config file name at the end of command line options. For example

goldcrest server.ovpn

will start a connection to the OpenVPN server defined in the server.ovpn config file. This mode can also be used to connect to an AirVPN server defined in a config file generated and saved either with Goldcrest (e.g. goldcrest --air-save airvpn-orion-server.ovpn --air-server orion) or created with the config generator available in the client area of AirVPN website.

The same applies to WireGuard servers and in case a valid WireGuard config file is passed to Goldcrest.

The user can override the values defined in the config file by using command line options. For example to override cipher, port and protocol:

goldcrest --cipher CHACHA20-POLY1305 --port 443 --proto tcp server.ovpn

When used in this mode, Goldcrest becomes equivalent to Hummingbird in functionality, however ensuring a better security model offered by Bluetit daemon. You should in fact consider that, while Goldcrest can be used by any user of the system authorized by root and by Bluetit policy, Hummingbird needs root privileges to run.

For this reason, it is always advised and recommended to use Goldcrest and Bluetit on any computer or system whenever possible. In this regard, Hummingbird is meant to be a standalone client and mainly used for specific and special purposes, such as portable systems and special conditions.

Controlling the Network Lock in Asynchronous Mode

In case Bluetit is connected to a VPN server in asynchronous mode (that is started at boot time or connected with Goldcrest by using the --async option) the Network Lock can be controlled by Goldcrest by using the --network-lock option. Please note this is a special use of this option and when intended to control the Network Lock in asynchronous mode, it must be the only option specified in the command line.

In this specific case, the Network Lock can be enabled and disabled only in case Bluetit is not connected to a VPN server and in any case according to Bluetit policy. Also note that in case the persistent Network Lock is enabled by Bluetit policy, the operation is rejected.

When the --network-lock option is intended to be used in this specific case, it permits three parameters only: on, off and noprivate. The noprivate parameter enables the Network Lock with the exemption of the private network. Please note private network exemption is allowed according to Bluetit policy and, in case it cannot be exempted, the command will be rejected.

$ goldcrest --network-lock on

Enables the network lock

$ goldcrest --network-lock off

Disables the network lock

$ goldcrest --network-lock noprivate

Enables the network lock with private network exemption

Traffic Splitting

Bluetit supports and implements a traffic splitting facility by using a dedicated network namespace, therefore completely separating the VPN and encrypted traffic from the unencrypted and "out of the tunnel" traffic. The VPN traffic is carried in the default (main) namespace, therefore ensuring that all system data and traffic are encrypted and tunneled into the VPN by default.

Any optional unencrypted data or clear network traffic must be explicitly requested by an authorized user having the right to run Cuckoo - the AirVPN traffic split manager and tool - and granted by the system administrator.

AirVPN Traffic splitting is implemented by using a separate and independent network namespace, directly communicating with the system's default gateway through a virtual interface associated with a physical network interface available in the system. This ensures a true separation of traffic between tunneled and encrypted VPN data from the unencrypted and clear data to be channeled out of the VPN tunnel. The unencrypted traffic generated within the traffic splitting network namespace will never pass through the default (main) namespace - which is under the VPN control - including, and most importantly, DNS requests.

To generate unencrypted and out of the tunnel traffic, any application software having this need must be run inside the traffic split namespace. To do so, the application must be run by using the dedicated traffic split tool cuckoo. This tool can be used by users belonging to the airvpn group only and it cannot be used by root or any user belonging to the root group.

AirVPN's traffic splitting is enabled and controlled by Bluetit by means of run control directives. To properly set and use the traffic split feature, please refer to Bluetit run control file.

AirVPN's traffic splitting is designed to minimize any further configuration from the system administrator. To enable traffic splitting, the administrator simply needs to set allowtrafficsplitting directive to "on" and Bluetit will configure the traffic split namespace with the default options as explained above. When needed, the system administrator can finely tune the traffic splitting service by using the dedicated directives in Bluetit run control file.

AirVPN's traffic splitting offers a remarkable security bonus in terms of isolation as well as avoiding the dangerous DNS leaks typical of cgroups-based traffic splitting solutions. Bluetit traffic splitting facility uses a dedicated namespace associated with the primary network adapter and using its dedicated and exclusive IP address.

This solution, although ensuring a solid encapsulation of the "out of the tunnel and unencrypted traffic", however poses a limitation in a specific case. In its default settings, Bluetit will automatically assign an IP address belonging to the private subnet in which it is connected to. This is, by the way, the most common condition for the majority of users, who usually have their devices connected to a home or office network and reaching the internet through a NAT or router.

In case the system is not behind a NAT or router (this is usually the condition for ISP, corporate or institutional entities) the administrator will need to manually assign a specific public IP address to the network namespace dedicated to traffic splitting. In this specific case, to manually set a public IP address, the system administrator can use the directives trafficsplitipv4 and/or trafficsplitipv6 in Bluetit run control file.

The system administrator is warned to keep this limitation in mind especially in case the AirVPN Suite is run with per application traffic splitting on a dedicated or virtual server in some datacenter, as most of the time these are not behind any NAT or router.

The traffic split network namespace uses its own routing, network channels, DNS and firewall. It will not interfere or communicate in any way with the main namespace where the VPN is running and using its own encrypted tunnel. As for DNS, the traffic split network namespace will use default system DNS settings. In case the administrator wishes to use a specific and dedicated configuration for the traffic split network namespace, he or she can easily set the desired environment by using the dedicated Linux command for network namespaces, ip netns.

Using the Traffic Split Tool Cuckoo

Any application whose network traffic is meant to be channeled in plain and outside the encrypted VPN traffic, must be run by using cuckoo, the AirVPN traffic split tool and manager.

By using Cuckoo it is possible to run applications inside Bluetit's traffic split network namespace, therefore channelling the application's network traffic data outside the VPN tunnel. For security and system administration reasons, Cuckoo is designed and meant to be used by any regular user belonging to the airvpn group. Moreover, for the very same reasons, cuckoo cannot be used by the root user and users belonging to the root group.

Cuckoo switches to the traffic split network namespace and then launches the specified application inside it. Programs started with cuckoo are regular Linux processes and, as such, can be managed (that is stopped, interrupted, paused, terminated and killed) by using the usual process control tools, such as kill. The programs started by cuckoo run as the user who started cuckoo.

To properly switch to the traffic split network namespace, cuckoo requires root privileges, which are dropped immediately after successfully switching to the traffic split network namespace. This means that, to properly run and work, cuckoo is granted special permissions and ownership, as follows:

Owner: root

Group: airvpn

Permissions: -r-sr-x--- (owner can read and execute with setuid; group can read and execute; others have no access)

Please note, for safety and security reasons, cuckoo performs a "sanity check" at startup and refuses to work in case these settings are different from the above or have been tampered with. Also please note the "setuid" bit is essential to let cuckoo properly switch to the traffic split network namespace, a procedure which in Linux can be performed by the root user only. Again, after having switched to the traffic split network namespace, root privileges are dropped for all intents and purposes, therefore after that, cuckoo is running with the permissions of the user who effectively called it. By no means will the specified application be run as root or with root privileges.

Below are listed all the command line options supported by Cuckoo:

Cuckoo - AirVPN Traffic Splitting Manager 2.2.0 - 15 October 2026

usage: cuckoo <options...>

--help, -h : Show the help page
--version, -v : Show version info
--run, -r : Run application "<application_name|application_path [application_options...]>" (please note the mandatory use of double quotes)
--inject, -i : Inject predefined options to preset applications (default)
--no-inject, -j : Do not inject predefined options to preset application
--list-preset-apps, -l : List preset applications and predefined inject options
--namespace, -n : Traffic split network namespace <name> (default: aircuckoo)

Open Source Project by AirVPN (https://airvpn.org)

Linux and macOS design, development and coding by ProMIND

Special thanks to the AirVPN community for the valuable help,
support, suggestions and testing.

Below are some examples of how to use Cuckoo.

List preset applications

$ cuckoo --list-preset-apps

Run an application inside the traffic split "out of the VPN tunnel" network namespace

$ cuckoo --run my_application

Please note cuckoo will find my_application in the user's $PATH. In case my_application is not in the current $PATH, the application must be specified with its complete path.

Run an application with options

$ cuckoo --run "my_application -o1 --long-option --assign-option=XYZ"

Please note the use of double quotes after the --run option.

Run an application in a specific network namespace

$ cuckoo --namespace my_namespace --run my_application

Run an application without injecting predefined options

$ cuckoo --no-inject --run my_application

Note on GUI Software and Web Browsers

Because of the specific Linux architecture and namespaces, some applications may need to properly specify the graphical environment to start and use the currently selected display server, such as X.Org (X11) and Wayland. Cuckoo can automatically do this by "injecting" predefined options to some preset applications, in particular those based on the chromium engines, most of them being web browsers. To see the list of predefined applications, please use --list-preset-apps option.

When running an application with cuckoo, the user should make sure to effectively start a new instance. This is usually guaranteed when starting an application from the command line (such as running it with cuckoo), whereas it may not happen when starting an application from the desktop environment (such as GNOME or KDE), that is by clicking on its icon or selecting it from the application menu, depending on the environment settings or architecture.

The user is therefore invited to effectively check for this specific condition since cuckoo has no way to change or determine how the application is started, except when this can be controlled by using the application's options, when available.

In case of web browsers, the user can check whether it is running inside or outside the VPN tunnel by visiting AirVPN's website and service ipleak.net. In case an AirVPN server is shown (the same Bluetit is connected to) the traffic is channeled into the encrypted VPN tunnel. This is usually the case of single instance web browsers which usually channel their traffic to and from the network namespace in which the initial instance has been started, even though any subsequent instances are effectively assigned to the real user who started the new instance.

Running an application outside of the VPN tunnel by using cuckoo may not work properly or at all, in case the application has been packaged in a format meant to run the binary in a so-called "container". The same may also apply to Docker and sandboxed applications, according to what has been set and provided by the running environment. Because of the limitations of such cases, the application may not work in AirVPN network namespace as expected, it may fail to start or work improperly. In these cases cuckoo will seem to get stuck while it is indeed waiting for the application to finish. In such cases, the process can be terminated by sending CTRL+C or SIGTERM to cuckoo.

AirVPN Switch User Tool Airsu

Running an application in a graphical environment - such as X.Org (X11) and Wayland - requires the user to have a properly set local environment, in particular specific environment variables, as well as access to the required sockets or cookies.

This is usually done at the moment of graphical login, such as the welcome screen shown by the display manager, while it may not be properly set in case the user has logged in by using the system tool su.

In this specific case - and depending on the Linux distribution or system administrator settings - the user will probably not be allowed to access the graphical environment and any GUI application will not start.

AirVPN's airsu is used for this specific purpose and sets and enables the user environment for the current windowing system - X.Org (X11) or Wayland - therefore allowing access to GUI applications, in particular when run through cuckoo.

In this regard, the user and system administrator should keep in mind that airsu does that by partially copying and replicating the environment of the caller user to the switched one, including granting access to some of the caller's environment files essential for GUI software. For this specific reason and, of course, for safety and security reasons, airsu cannot be used by root user or any user belonging to the root group.

Airsu can also set the necessary environment for D-Bus infrastructure, something that will likely be mandatory for most Linux applications.

Please note airsu requires bash and this is the shell explicitly requested in the script's shebang.

Below is the help output for airsu:

AirVPN Suite switch user version 1.3.0 - 15 June 2026

airsu [user] [options]

Options:

-d, --dbus Launch and set D-Bus environment (default)
-n, --no-dbus Do not launch and set D-Bus environment
-h, --help This help screen
-v, --version Show version

Change the effective user ID and group ID to that of <user> and properly
set the environment in order to allow application execution by using cuckoo,
in particular graphical ones. If <user> is not given, airvpn is assumed.

Please note the environment for the switched user is replicated from that of
the calling user.

Use 'cuckoo' to run applications with network traffic outside the VPN tunnel

Note: in case the user who has logged in to the graphical environment belongs to the airvpn group, airsu is not required.

A typical traffic splitting session for a generic AirVPN user can therefore be started and used like the below example:

$ airsu Password: $ cuckoo --run my_gui_application

Please note the default user for airsu is airvpn.

Running the Hummingbird Client

Hummingbird is the standalone AirVPN client allowing the user to connect to any generic OpenVPN or WireGuard server by providing a valid OpenVPN or WireGuard configuration file.

To use Hummingbird, you need root privileges. Run hummingbird and display its help to become familiar with its options. From your terminal window issue this command:

sudo ./hummingbird --help

After having entered your password, hummingbird responds with:

Hummingbird - WireGuard/OpenVPN3 Client 2.2.0 - 15 October 2026

OpenVPN core 3.12 AirVPN (20260514) linux x86_64 64-bit
Copyright (C) 2012- OpenVPN Inc. All rights reserved.
OpenSSL 3.5.4 30 Sep 2025
AirVPN WireGuard Client 2.0.0 Linux x86_64 64-bit

usage: hummingbird [options] <config-file>

--help, -h : Show this help page
--version, -v : Show version info
--eval, -e : Evaluate profile only (standalone)
--username, -u : Username
--password, -p : Password
--response, -r : Static response
--dc, -D : Dynamic challenge/response cookie
--cipher, -C : Encrypt packets with specific cipher algorithm <alg>
--list-data-ciphers : List supported data ciphers
--proto, -P : Protocol override <udp|tcp>
--server, -s : Server override
--port, -R : Port override
--tcp-queue-limit, -l : Size of TCP packet queue <1..65535> default 8192
--mtu : WireGuard MTU
--network-lock, -N : Network filter and lock mode <on|iptables|nftables|pf|off> default on
--allow-private-network : Allow private IPv4 and IPv6 network classes to pass to and from the network filter. <on|off> default on
--allow-ping : Allow Ping to pass to and from the network filter. <on|off|input|output> default output
--allow-ipv6ndp : Allow IPv6 NDP to pass to and from the network filter. <on|off> default on
--gui-version, -E : Set custom gui version <text>
--ignore-dns-push, -i : Ignore DNS push request and use system DNS settings
--allowuaf, -6 : Allow unused address families <yes|no|default>
--timeout, -t : Timeout <seconds>
--compress, -c : Compression mode <yes|no|asym>
--pk-password, -z : Private key password
--tvm-override, -M : Tls-version-min override <disabled|default|tls_1_x>
--tcprof-override, -X : Tls-cert-profile override <legacy|preferred|etc.>
--proxy-host, -y : HTTP proxy hostname/IP
--proxy-port, -q : HTTP proxy port
--proxy-username, -U : HTTP proxy username
--proxy-password, -W : HTTP proxy password
--proxy-basic, -b : Allow HTTP basic auth
--alt-proxy, -A : Enable alternative proxy module
--cache-password, -H : Cache password
--no-cert, -x : Disable client certificate
--def-keydir, -k : Default key direction <bi|0|1>
--ssl-debug : SSL debug level
--auto-sess, -a : Request autologin session
--auth-retry, -Y : Retry connection on auth failure
--persist-tun, -j : Keep TUN interface open across reconnects
--peer-info, -I : Peer info key/value list in the form K1=V1,K2=V2,...
--gremlin, -G : Gremlin info <send_delay_ms|recv_delay_ms|send_drop_prob|recv_drop_prob>
--epki-ca : Simulate external PKI cert supporting intermediate/root certs
--epki-cert : Simulate external PKI cert
--epki-key : Simulate external PKI private key
--recover-network : Recover network settings after a crash or unexpected exit
--remove-wireguard-device : Remove any existing WireGuard tunnel device after a crash or unexpected exit

Open Source Project by AirVPN (https://airvpn.org)

Linux and macOS design, development and coding by ProMIND

Special thanks to the AirVPN community for the valuable help,
support, suggestions and testing.

Hummingbird needs a valid OpenVPN or WireGuard profile in order to connect to a server. You can create a VPN profile by using the config generator available on the AirVPN website in your account's Client Area

Start a VPN connection

Hummingbird can start both OpenVPN and WireGuard connections by providing a proper configuration file or profile. The profile type is automatically recognized by Hummingbird, which will start the corresponding VPN connection accordingly.

Start an OpenVPN connection

sudo ./hummingbird your_openvpn_file.ovpn

Start a WireGuard connection

sudo ./hummingbird your_wireguard_file.conf

Stop a connection

Type CTRL+C in the terminal window where Hummingbird is running. The client will initiate the disconnection process and will restore your original network settings according to your options.

Start a connection with a specific cipher

sudo ./hummingbird --cipher CHACHA20-POLY1305 your_openvpn_file.ovpn

Please note: in order to properly work, the server you are connecting to must support the cipher specified with the --cipher option.

Disable the network filter and lock

sudo ./hummingbird --network-lock off your_openvpn_file.ovpn

Ignore the DNS servers pushed by the VPN server

sudo ./hummingbird --ignore-dns-push your_openvpn_file.ovpn

Please note: the above options can be combined together according to their use and function.

Controlling Hummingbird

Hummingbird uses the following system signals to control specific actions. You can send a signal to Hummingbird by using the kill command from a terminal.

  • SIGTERM, SIGINT, SIGPIPE, SIGHUP : Disconnect the active VPN connection

  • SIGUSR1: This is actually a toggle signal to be used to both pause and resume VPN connection. In case Hummingbird is connected to a VPN server, the connection is paused, whereas in case it is paused, VPN connection will be resumed. When the VPN connection is paused, the tunnel device status is controlled according to --persist-tun option. Also consider that pausing and resuming a connection is allowed only in case TUN persistence is enabled.

  • SIGUSR2: Reconnect (restart) the current VPN connection. Reconnecting a connection is allowed only in case TUN persistence is enabled.

Note on macOS and UDP

Because of some architectural specifications and implementation in macOS, in particular in case of high speed traffic - a condition becoming more and more common in modern internet technology and infrastructure - Hummingbird may warn the user about shortage of buffer space, specifically when connected with the UDP protocol.

This condition is signaled by Hummingbird with the below messages in the log:

UDP send exception: send: No buffer space available
ERROR: NETWORK_SEND_ERROR

This error is caused by the maximum size set in macOS for network sockets, a value usually small and unsuited for modern high speed networks, specifically in case the VPN is connected with the UDP protocol. The solution to this problem consists of increasing the maximum allowed size for socket buffers and, in case the problem persists, to increase the number of mbuf clusters.

In this regard, it should be considered that each mbuf cluster in macOS has a fixed size of 2 KB and the maximum socket buffer size cannot be greater than 1/16 of the total memory allocated by the system for mbuf clusters.

For example, in case the number of mbuf clusters is set to 32768 (this is likely to be the default value in most macOS systems), the total memory allocated for this purpose is 32768 * 2 KB, therefore 64 MB. The maximum socket buffer size is hence set to 1/16 of 64 MB, therefore 4 MB.

To find out the current values set on your system, you can use the following commands. Please note, you need to be root to manipulate these settings according to the commands provided below.

sysctl -a kern.ipc.nmbclusters

and

sysctl -a kern.ipc.maxsockbuf

to respectively get the current values set for the number of mbuf clusters and the maximum socket buffer size.

In case the current number of mbuf clusters set on your system allows it, you can change the maximum socket buffer size by issuing the following command:

sysctl -w kern.ipc.maxsockbuf=<size_in_bytes>

For example, to set the maximum socket buffer size to 16 MB, this can be done with the below command:

sysctl -w kern.ipc.maxsockbuf=16777216

The above value is accepted by the system only in case the number of mbuf clusters is equal to or greater than 131072 (131072 * 2 KB = 268435456 = 256 MB)

Important note: by using sysctl command as described above, the value is set for the current session only and it is not permanent. This means when the machine is restarted or powered on, the above values will be reset to their respective default values and according to the macOS version in use. To make these changes permanent and properly set up at system start-up, please refer to the procedures provided for the specific macOS version in use.

In case the current kern.ipc.nmbclusters value is not enough to properly increase kern.ipc.maxsockbuf, you can permanently change the value of ncl boot argument by issuing this command:

nvram boot-args="ncl=<number_of_mbuf_clusters>"

Please remember each mbuf cluster equates to 2 KB of RAM, therefore in case you want to set the size of memory used for mbuf clusters to 256 MB, therefore allowing a maximum value for kern.ipc.maxsockbuf of 16 MB, you can multiply this value (in bytes) by 16, then divide it by 2048 (2 KB in bytes), therefore yielding the number of mbuf clusters.

16777216 * 16 = 268435456 (256 MB)

268435456 / 2048 = 131072

to make this value permanent you then need to issue the command:

nvram boot-args="ncl=131072"

then restart your system:

shutdown -r now

Upon reboot you are now allowed to set kern.ipc.maxsockbuf to 16 MB.

Network Filter and Lock

AirVPN Suite network filter and lock natively uses iptables, iptables-legacy, nftables and pf to provide a "best effort leak prevention". Bluetit and Hummingbird will automatically detect and use the infrastructure available on your system.

The --network-lock option (networklock in the Bluetit configuration file) defaults to on: in this case the firewall installed on your system is automatically detected, using this priority: iptables-legacy, iptables, nftables and finally pf. To force a specific firewall, specify its name in the same option, for example --network-lock nftables. Please note the firewall must be properly installed on your system.

Also note in case both iptables and iptables-legacy are installed on your system, iptables-legacy will be used.

Note on nftables: nftables rules created and issued by AirVPN Suite follow the specification and behavior of nftables version 0.9. In case you detect nftables errors or it seems to not be working properly, please check nftables installed on your system and make sure it is compatible with 0.9 specifications.

Please note: Linux services firewalld and ufw may interfere with the AirVPN Suite's network filter and lock and you are strongly advised not to issue any firewall-related command while the VPN connection is active.

Using Network Filter and Lock with Bluetit

The Network Filter and Lock in Bluetit can strongly affect the whole network traffic of your system, in particular in case it is going to be enabled in persistent mode. When turned on at boot time with the networklockpersist directive in Bluetit configuration file, traffic is allowed to and from the external network (i.e. any non-local subnet) only in case Bluetit is connected to a VPN. Local network traffic is however allowed regardless of the Network Filter and Lock status or whether the system is connected to a VPN or not. You should therefore consider activating this directive carefully in case Bluetit is started at boot time. In this specific case, you should be aware no traffic will be permitted soon after Bluetit startup and this will affect all services and processes subsequently started and requiring external network access. Also consider networklockpersist directive takes priority over networklock directive which will be therefore ignored.

You should also consider that enabling the Network Filter and Lock at boot time will forbid any external network traffic and this also includes Bluetit in case it is not connected to a VPN. This restriction also applies to AirVPN Manifest update and the initial query to AirVPN's ipleak.net to determine the system's real country.

In these specific cases, be aware AirVPN Manifest update is suspended until a new connection to an AirVPN server is started, whereas, as for system country detection, you need to explicitly set it with the country directive in Bluetit run control file. In case no country is defined in Bluetit run control file and the Network Filter and Lock is enabled at boot, AirVPN quick connection will consider the whole AirVPN server infrastructure and will connect to the "best worldwide server" at that specific time. This means quick connection will not consider the specific area in which your system is located and will connect to a server which could be too far away or not the best for your local and specific geographic condition.

In case the Network Filter and Lock is started in persistent mode, that is enabled at Bluetit startup, be aware it will stay enabled as long as Bluetit is running and no direct procedure or command is provided to disable it or turn it off. However, the system administrator root can of course change the firewall rules set by Bluetit - therefore directly affecting the Network Filter and Lock

  • by using the specific system tools to operate the firewall. In this specific case you should be aware Bluetit will re-enable the Network Filter and Lock after the VPN is disconnected and will override any firewall rule or specification set by root meanwhile.

Note on firewalld

In case the firewalld service is running and it is set to own nftables tables, this will strongly interfere with Bluetit, in particular, with system netfilter restore at disconnection.

In its default settings, firewalld is the owner of its nftables tables and, by default, will interfere with any application when trying to interact with nftables tables created and owned by firewalld. This condition will make nftables issue an error at the moment of tables modification, including tables restore, as in the case of Bluetit. In this specific case, Bluetit will also fail to restore the system network settings, therefore causing a "dirty" network status.

In case firewalld is set to be the owner of nftables tables, Bluetit will issue a warning in the system log, therefore inviting the system administrator to change this setting.

To change firewalld settings to let Bluetit work properly and to proficiently interact with the system, you need to edit firewalld's configuration file /etc/firewalld/firewalld.conf, set the option NftablesTableOwner to "no" and then restart both firewalld and Bluetit. Please note, by default, NftablesTableOwner is set to yes, so, in case you do not see this line in the configuration file, you explicitly need to add it and set NftablesTableOwner=no.

DNS Management in Linux

AirVPN Suite currently supports both resolv.conf and systemd-resolved service. It is also aware of NetworkManager, in case it is running. While any of the AirVPN Suite components are running, you are strongly advised not to issue any systemd-resolved related command (such as resolvectl) or change the resolv.conf file to make sure the system properly uses DNS pushed by the VPN server. Please note: DNS system settings are not changed in case the client has been started with --ignore-dns-push (ignorednspush in Bluetit configuration file). In this specific case, the connection will use your system DNS.

Furthermore, please note that if your network interfaces are managed by NetworkManager, DNS settings might be changed under peculiar circumstances during a VPN connection, even when DNS push had been previously accepted.

Recover Your Network Settings

In case Bluetit or Hummingbird crash or are killed by the user (e.g. kill -9 `pidof hummingbird` ) as well as in case of system reboot while the connection is active, the system may keep and use some or all of the network settings determined by the previous session, therefore your network connection might not work as expected, every connection might be refused and the system might seem to be "network locked". To restore and recover your system network, you can use the client (Goldcrest or Hummingbird) with the --recover-network option.

goldcrest --recover-network

or

sudo hummingbird --recover-network

Please note in case of crash or unexpected exit, when you subsequently run Goldcrest or Hummingbird you will be warned about the unexpected exit and required to run it again with the --recover-network option. They will also refuse to start any connection until the network has been properly restored and recovered.

Special Note for Bluetit

In case Bluetit has ended abnormally, it may happen that DNS and firewall rules still reflect the last connected VPN server and network connectivity is not available. In other words, no traffic is allowed to and from the system. In such a specific case, you need to do the following to recover your system network connectivity.

  • Log in as root

  • In case the file bluetit.lock is present in /etc/airvpn, check whether Bluetit is running (e.g. ps aux | grep bluetit)

  • In case Bluetit is not running, delete the lock file (e.g. rm /etc/airvpn/bluetit.lock) and start Bluetit

  • Use a Bluetit client, such as goldcrest, with the --recover-network option (e.g. goldcrest --recover-network)

  • Bluetit will try to recover network connectivity by restoring the system configuration

Building AirVPN Suite from Sources

To build Bluetit, Goldcrest, Cuckoo and Hummingbird from sources, you need the following dependencies:

Clone AirVPN-Suite repository into your computer:

git clone https://gitlab.com/AirVPN/AirVPN-Suite

Move into the project's directory:

cd AirVPN-Suite

Build Linux Dynamic Binaries

Edit build-bluetit.sh, build-goldcrest.sh, build-cuckoo.sh and build-hummingbird.sh scripts and set INC_DIR, OPENVPN3 and ASIO variables according to your system configuration

Run the build shell script:

  • Bluetit: sh build-bluetit.sh

  • Goldcrest: sh build-goldcrest.sh

  • Cuckoo: sh build-cuckoo.sh

  • Hummingbird: sh build-hummingbird.sh

The scripts will compile their corresponding binary component in the current directory.

Build Linux Static Binaries

Edit build-bluetit-static.sh, build-goldcrest-static.sh, build-cuckoo-static.sh and build-hummingbird-static.sh scripts and set INC_DIR, OPENVPN3 and ASIO variables according to your system configuration. Also set STATIC_LIB_DIR and SSL_LIB_DIR according to your system architecture.

Run the build shell script:

  • Bluetit: sh build-bluetit-static.sh

  • Goldcrest: sh build-goldcrest-static.sh

  • Cuckoo: sh build-cuckoo-static.sh

  • Hummingbird: sh build-hummingbird-static.sh

The scripts will create their corresponding static binary components according to your system and will also create the associated distribution compressed tarball file in the current directory. To install the binary on your system, please refer to the installation instructions provided above.

AirVPN Suite, with its components Bluetit, Goldcrest, Hummingbird, Cuckoo and Airsu, is an open source project by AirVPN

Linux and macOS design, development and coding by ProMIND

Special thanks to the AirVPN community for the valuable help, support, suggestions and testing.

OpenVPN is Copyright (C) 2012-2025 OpenVPN Inc. All rights reserved.

AirVPN Suite and its components are released and licensed under the GNU General Public License Version 3 (GPLv3)

×
×
  • Create New...