VPN Services (GNU Guix Reference Manual)

10.8.21 VPN Services

The (gnu services vpn) module provides services related to virtual private networks (VPNs).

Bitmask

Scheme Variable: bitmask-service-type: A service type for the Bitmask VPN client. It makes the client available in the system and loads its polkit policy. Please note that the client expects an active polkit-agent, which is either run by your desktop-environment or should be run manually.

OpenVPN

It provides a client service for your machine to connect to a VPN, and a server service for your machine to host a VPN.

Scheme Procedure: openvpn-client-service [#:config (openvpn-client-configuration)]: Return a service that runs openvpn, a VPN daemon, as a client.

Scheme Procedure: openvpn-server-service [#:config (openvpn-server-configuration)]

Return a service that runs openvpn, a VPN daemon, as a server.

Both can be run simultaneously.

Available openvpn-client-configuration fields are:

openvpn-client-configuration parameter: package openvpn: The OpenVPN package.

openvpn-client-configuration parameter: string pid-file

The OpenVPN pid file.

Defaults to ‘"/var/run/openvpn/openvpn.pid"’.

openvpn-client-configuration parameter: proto proto

The protocol (UDP or TCP) used to open a channel between clients and servers.

Defaults to ‘udp’.

openvpn-client-configuration parameter: dev dev

The device type used to represent the VPN connection.

Defaults to ‘tun’.

If you do not have some of these files (eg. you use a username and password), you can disable any of the following three fields by setting it to 'disabled.

openvpn-client-configuration parameter: maybe-string ca

The certificate authority to check connections against.

Defaults to ‘"/etc/openvpn/ca.crt"’.

openvpn-client-configuration parameter: maybe-string cert

The certificate of the machine the daemon is running on. It should be signed by the authority given in ca.

Defaults to ‘"/etc/openvpn/client.crt"’.

openvpn-client-configuration parameter: maybe-string key

The key of the machine the daemon is running on. It must be the key whose certificate is cert.

Defaults to ‘"/etc/openvpn/client.key"’.

openvpn-client-configuration parameter: boolean comp-lzo?

Whether to use the lzo compression algorithm.

Defaults to ‘#t’.

openvpn-client-configuration parameter: boolean persist-key?

Don’t re-read key files across SIGUSR1 or –ping-restart.

Defaults to ‘#t’.

openvpn-client-configuration parameter: boolean persist-tun?

Don’t close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 or –ping-restart restarts.

Defaults to ‘#t’.

openvpn-client-configuration parameter: boolean fast-io?

(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to poll/epoll/select prior to the write operation.

Defaults to ‘#f’.

openvpn-client-configuration parameter: number verbosity

Verbosity level.

Defaults to ‘3’.

openvpn-client-configuration parameter: tls-auth-client tls-auth

Add an additional layer of HMAC authentication on top of the TLS control channel to protect against DoS attacks.

Defaults to ‘#f’.

openvpn-client-configuration parameter: maybe-string auth-user-pass

Authenticate with server using username/password. The option is a file containing username/password on 2 lines. Do not use a file-like object as it would be added to the store and readable by any user.

Defaults to ‘'disabled’.

openvpn-client-configuration parameter: key-usage verify-key-usage?

Whether to check the server certificate has server usage extension.

Defaults to ‘#t’.

openvpn-client-configuration parameter: bind bind?

Bind to a specific local port number.

Defaults to ‘#f’.

openvpn-client-configuration parameter: resolv-retry resolv-retry?

Retry resolving server address.

Defaults to ‘#t’.

openvpn-client-configuration parameter: openvpn-remote-list remote

A list of remote servers to connect to.

Defaults to ‘()’.

Available openvpn-remote-configuration fields are:

openvpn-remote-configuration parameter: string name

Server name.

Defaults to ‘"my-server"’.

openvpn-remote-configuration parameter: number port

Port number the server listens to.

Defaults to ‘1194’.

Available openvpn-server-configuration fields are:

openvpn-server-configuration parameter: package openvpn: The OpenVPN package.

openvpn-server-configuration parameter: string pid-file

The OpenVPN pid file.

Defaults to ‘"/var/run/openvpn/openvpn.pid"’.

openvpn-server-configuration parameter: proto proto

The protocol (UDP or TCP) used to open a channel between clients and servers.

Defaults to ‘udp’.

openvpn-server-configuration parameter: dev dev

The device type used to represent the VPN connection.

Defaults to ‘tun’.

If you do not have some of these files (eg. you use a username and password), you can disable any of the following three fields by setting it to 'disabled.

openvpn-server-configuration parameter: maybe-string ca

The certificate authority to check connections against.

Defaults to ‘"/etc/openvpn/ca.crt"’.

openvpn-server-configuration parameter: maybe-string cert

The certificate of the machine the daemon is running on. It should be signed by the authority given in ca.

Defaults to ‘"/etc/openvpn/client.crt"’.

openvpn-server-configuration parameter: maybe-string key

The key of the machine the daemon is running on. It must be the key whose certificate is cert.

Defaults to ‘"/etc/openvpn/client.key"’.

openvpn-server-configuration parameter: boolean comp-lzo?

Whether to use the lzo compression algorithm.

Defaults to ‘#t’.

openvpn-server-configuration parameter: boolean persist-key?

Don’t re-read key files across SIGUSR1 or –ping-restart.

Defaults to ‘#t’.

openvpn-server-configuration parameter: boolean persist-tun?

Don’t close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 or –ping-restart restarts.

Defaults to ‘#t’.

openvpn-server-configuration parameter: boolean fast-io?

(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to poll/epoll/select prior to the write operation.

Defaults to ‘#f’.

openvpn-server-configuration parameter: number verbosity

Verbosity level.

Defaults to ‘3’.

openvpn-server-configuration parameter: tls-auth-server tls-auth

Add an additional layer of HMAC authentication on top of the TLS control channel to protect against DoS attacks.

Defaults to ‘#f’.

openvpn-server-configuration parameter: number port

Specifies the port number on which the server listens.

Defaults to ‘1194’.

openvpn-server-configuration parameter: ip-mask server

An ip and mask specifying the subnet inside the virtual network.

Defaults to ‘"10.8.0.0 255.255.255.0"’.

openvpn-server-configuration parameter: cidr6 server-ipv6

A CIDR notation specifying the IPv6 subnet inside the virtual network.

Defaults to ‘#f’.

openvpn-server-configuration parameter: string dh

The Diffie-Hellman parameters file.

Defaults to ‘"/etc/openvpn/dh2048.pem"’.

openvpn-server-configuration parameter: string ifconfig-pool-persist

The file that records client IPs.

Defaults to ‘"/etc/openvpn/ipp.txt"’.

openvpn-server-configuration parameter: gateway redirect-gateway?

When true, the server will act as a gateway for its clients.

Defaults to ‘#f’.

openvpn-server-configuration parameter: boolean client-to-client?

When true, clients are allowed to talk to each other inside the VPN.

Defaults to ‘#f’.

openvpn-server-configuration parameter: keepalive keepalive: Causes ping-like messages to be sent back and forth over the link so that each side knows when the other side has gone down. keepalive requires a pair. The first element is the period of the ping sending, and the second element is the timeout before considering the other side down.

openvpn-server-configuration parameter: number max-clients

The maximum number of clients.

Defaults to ‘100’.

openvpn-server-configuration parameter: string status

The status file. This file shows a small report on current connection. It is truncated and rewritten every minute.

Defaults to ‘"/var/run/openvpn/status"’.

openvpn-server-configuration parameter: openvpn-ccd-list client-config-dir

The list of configuration for some clients.

Defaults to ‘()’.

Available openvpn-ccd-configuration fields are:

openvpn-ccd-configuration parameter: string name

Client name.

Defaults to ‘"client"’.

openvpn-ccd-configuration parameter: ip-mask iroute

Client own network

Defaults to ‘#f’.

openvpn-ccd-configuration parameter: ip-mask ifconfig-push

Client VPN IP.

Defaults to ‘#f’.

strongSwan

Currently, the strongSwan service only provides legacy-style configuration with ipsec.conf and ipsec.secrets files.

Scheme Variable: strongswan-service-type

A service type for configuring strongSwan for IPsec VPN (Virtual Private Networking). Its value must be a strongswan-configuration record as in this example:

(service strongswan-service-type
         (strongswan-configuration
          (ipsec-conf "/etc/ipsec.conf")
          (ipsec-secrets "/etc/ipsec.secrets")))

Data Type: strongswan-configuration

Data type representing the configuration of the StrongSwan service.

strongswan: The strongSwan package to use for this service.
ipsec-conf (default: #f): The file name of your ipsec.conf. If not #f, then this and ipsec-secrets must both be strings.
ipsec-secrets (default #f): The file name of your ipsec.secrets. If not #f, then this and ipsec-conf must both be strings.

Wireguard

Scheme Variable: wireguard-service-type

A service type for a Wireguard tunnel interface. Its value must be a wireguard-configuration record as in this example:

(service wireguard-service-type
         (wireguard-configuration
          (peers
           (list
            (wireguard-peer
             (name "my-peer")
             (endpoint "my.wireguard.com:51820")
             (public-key "hzpKg9X1yqu1axN6iJp0mWf6BZGo8m1wteKwtTmDGF4=")
             (allowed-ips '("10.0.0.2/32")))))))

Data Type: wireguard-configuration

Data type representing the configuration of the Wireguard service.

wireguard: The wireguard package to use for this service.
interface (default: "wg0"): The interface name for the VPN.
addresses (default: '("10.0.0.1/32")): The IP addresses to be assigned to the above interface.
port (default: 51820): The port on which to listen for incoming connections.
private-key (default: "/etc/wireguard/private.key"): The private key file for the interface. It is automatically generated if the file does not exist.
peers (default: '()): The authorized peers on this interface. This is a list of wireguard-peer records.

Data Type: wireguard-peer

Data type representing a Wireguard peer attached to a given interface.

name: The peer name.
endpoint (default: #f): The optional endpoint for the peer, such as "demo.wireguard.com:51820".
public-key: The peer public-key represented as a base64 string.
allowed-ips: A list of IP addresses from which incoming traffic for this peer is allowed and to which incoming traffic for this peer is directed.
keep-alive (default: #f): An optional time interval in seconds. A packet will be sent to the server endpoint once per time interval. This helps receiving incoming connections from this peer when you are behind a NAT or a firewall.