VPN Services (GNU Guix Reference Manual)

12.9.23 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.

Data Type: openvpn-client-configuration

Available openvpn-client-configuration fields are:

openvpn (default: openvpn) (type: file-like)

The OpenVPN package.

pid-file (default: "/var/run/openvpn/openvpn.pid") (type: string)

The OpenVPN pid file.

proto (default: udp) (type: proto)

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

dev (default: tun) (type: dev)

The device type used to represent the VPN connection.

ca (default: "/etc/openvpn/ca.crt") (type: maybe-string)

The certificate authority to check connections against.

cert (default: "/etc/openvpn/client.crt") (type: maybe-string)

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

key (default: "/etc/openvpn/client.key") (type: maybe-string)

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

comp-lzo? (default: #t) (type: boolean)

Whether to use the lzo compression algorithm.

persist-key? (default: #t) (type: boolean)

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

persist-tun? (default: #t) (type: boolean)

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

fast-io? (default: #f) (type: boolean)

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

verbosity (default: 3) (type: number)

Verbosity level.

tls-auth (default: #f) (type: tls-auth-client)

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

auth-user-pass (type: maybe-string)

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.

verify-key-usage? (default: #t) (type: key-usage)

Whether to check the server certificate has server usage extension.

bind? (default: #f) (type: bind)

Bind to a specific local port number.

resolv-retry? (default: #t) (type: resolv-retry)

Retry resolving server address.

remote (default: ()) (type: openvpn-remote-list)

A list of remote servers to connect to.

Data Type: openvpn-remote-configuration

Available openvpn-remote-configuration fields are:

name (default: "my-server") (type: string): Server name.
port (default: 1194) (type: number): Port number the server listens to.

Data Type: openvpn-server-configuration

Available openvpn-server-configuration fields are:

openvpn (default: openvpn) (type: file-like): The OpenVPN package.
pid-file (default: "/var/run/openvpn/openvpn.pid") (type: string): The OpenVPN pid file.
proto (default: udp) (type: proto): The protocol (UDP or TCP) used to open a channel between clients and servers.
dev (default: tun) (type: dev): The device type used to represent the VPN connection.
ca (default: "/etc/openvpn/ca.crt") (type: maybe-string): The certificate authority to check connections against.
cert (default: "/etc/openvpn/client.crt") (type: maybe-string): The certificate of the machine the daemon is running on. It should be signed by the authority given in ca.
key (default: "/etc/openvpn/client.key") (type: maybe-string): The key of the machine the daemon is running on. It must be the key whose certificate is cert.
comp-lzo? (default: #t) (type: boolean): Whether to use the lzo compression algorithm.
persist-key? (default: #t) (type: boolean): Don’t re-read key files across SIGUSR1 or –ping-restart.
persist-tun? (default: #t) (type: boolean): Don’t close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 or –ping-restart restarts.
fast-io? (default: #f) (type: boolean): (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to poll/epoll/select prior to the write operation.
verbosity (default: 3) (type: number): Verbosity level.
tls-auth (default: #f) (type: tls-auth-server): Add an additional layer of HMAC authentication on top of the TLS control channel to protect against DoS attacks.
port (default: 1194) (type: number): Specifies the port number on which the server listens.
server (default: "10.8.0.0 255.255.255.0") (type: ip-mask): An ip and mask specifying the subnet inside the virtual network.
server-ipv6 (default: #f) (type: cidr6): A CIDR notation specifying the IPv6 subnet inside the virtual network.
dh (default: "/etc/openvpn/dh2048.pem") (type: string): The Diffie-Hellman parameters file.
ifconfig-pool-persist (default: "/etc/openvpn/ipp.txt") (type: string): The file that records client IPs.
redirect-gateway? (default: #f) (type: gateway): When true, the server will act as a gateway for its clients.
client-to-client? (default: #f) (type: boolean): When true, clients are allowed to talk to each other inside the VPN.
keepalive (default: (10 120)) (type: 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.
max-clients (default: 100) (type: number): The maximum number of clients.
status (default: "/var/run/openvpn/status") (type: string): The status file. This file shows a small report on current connection. It is truncated and rewritten every minute.
client-config-dir (default: ()) (type: openvpn-ccd-list): The list of configuration for some clients.

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.
dns (default: #f): The DNS server(s) to announce to VPN clients via DHCP.
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.
pre-up (default: '()): The script commands to be run before setting up the interface.
post-up (default: '()): The script commands to be run after setting up the interface.
pre-down (default: '()): The script commands to be run before tearing down the interface.
post-down (default: '()): The script commands to be run after tearing down the interface.
table (default: "auto"): The routing table to which routes are added, as a string. There are two special values: "off" that disables the creation of routes altogether, and "auto" (the default) that adds routes to the default table and enables special handling of default routes.

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.