Add an Interface

Once you have added a host to Pro Custodibus, you can add one or more WireGuard interfaces to the host.

What is a WireGuard Interface?

A virtual network interface that connects a host to a WireGuard network. From the perspective of a host, an interface is the local side of its connection to a network.

See the Terminology page for a fuller explanation.

Add Interface Page

Follow these steps to navigate to the Add Interface page for a host:

  1. Click the Hosts link in the app header.

  2. Find the host in the list, and click its name to view its main status page.

  3. Click the “plus” icon on the right side of the Interfaces panel.

State

Toggle the State button “Down” if you don’t want the agent to start up the interface after it is created; leave it “Up” to start the interface as soon as it is created.

Name

Enter the name the host will use to identify the interface, like “wg0”, in the Name field. This name must be less than 16 characters, and must consist of only ASCII letters, numbers, dot (“.”), dash (“-”), and lodash (“_”) characters. It also must be unique among any other network interface names used by the host.

This name can be changed later; but because it is used by the host to identify the interface, changing it may break other things on the host that have been configured to interact with the interface.

For macOS hosts, the Name must either be “utun”, or “utun” and a number, like “utun0”, “utun1”, etc. For OpenBSD hosts, the Name must either be “tun”, or “tun” and a number, like “tun0”, “tun1”, etc.

Description

Optionally enter a description for the interface, like “staging network for APAC”, in the Description field. This description will be displayed alongside the interface name in various places in the UI. There are no length or character restrictions, and you can change it without consequence later.

Peer

Select the peer identity by which remote hosts will know this interface, either by entering the name of a peer already added to Pro Custodibus in the Peer field, or by adding a new peer by clicking the New button next to the Peer field. This peer represents the interface’s own public key pair that it will use to authenticate itself to remote hosts (and corresponds to the “PrivateKey” setting in a wg-quick-style configuration file).

You can type part of a name in the Peer field to filter the displayed list of peers from which to choose. Use the up and down arrow keys to highlight a peer from the list, and use the tab or enter key to select the highlighted peer. If a peer is currently being used as the identity of another interface, the displayed list will indicate this (usually you don’t want to use the same peer identity for more than one interface).

If you click the New button next to the Peer field, an Add Peer dialog will appear, allowing you to register a new peer identity with Pro Custodibus. You can use then select this peer to use as the identity for the interface.

Port

Optionally enter a static UDP port on which the interface should listen, like “51820”, in the Port field. This is the port on which the interface’s encrypted tunnel will be established with its remote endpoints (and corresponds to the “ListenPort” setting in a wg-quick-style configuration file).

If you leave this field blank, every time the interface starts up, WireGuard will automatically choose a different free UDP port on which to listen.

Firewall Mark

Optionally enter a number with which to mark outgoing packets of this interface, like “0x7b”, in the Firewall Mark field (it corresponds to the “FwMark” setting in a wg-quick-style configuration file). Leave it blank unless you intend to set up custom firewall or routing rules on the host using this mark.

WireGuard does not support Firewall Mark on Android, iOS, macOS, or Windows hosts; leave it blank for them.

Addresses

Enter one or more source IP addresses to attach to the interface, like “10.0.0.1/24, fc00:0:0:1::/56”, in the Addresses field. Separate multiple addresses with commas, newlines, or other whitespace. This address or addresses should be unique among the local interfaces and remote hosts to which this interface can connect.

Most of the time you can omit netmasks (the “/24” part of “10.0.0.1/24”) when specifying IP addresses for the Addresses field. Unless you’re planning on setting up custom routing rules on the host, netmasks are usually only useful for WireGuard interface addresses if you attach more than one IP address of the same family (ie two or more IPv4 addresses, or two or more IPv6 addresses) to the same interface.

DNS Servers

Optionally enter the IP addresses of one or more DNS servers to use while the WireGuard interface is up, like “10.0.0.53, fc00:0:0:53::”, in the DNS Servers field. Separate multiple addresses with commas, newlines, or other whitespace.

Usually you’d use this setting only if you have a private DNS server that is accessible only through this WireGuard interface (it corresponds to the DNS servers portion of the “DNS” setting in a wg-quick-style configuration file).

On Linux hosts using system-resolved, you may have more success using “Post Up” and “Pre Down” scripts to adjust the host’s DNS settings through direct calls to resolvectl, rather than using the DNS Servers and Search Domains settings.

Search Domains

Optionally enter the search domains for which to query the above DNS Servers, like “wg.lan, corp”, in the DNS Servers field. Separate multiple addresses with commas, newlines, or other whitespace.

Usually you’d use this setting only in conjunction with the DNS Servers setting above for a private DNS server with a private domain name that is accessible only through this WireGuard interface (this setting corresponds to search domain portion of the “DNS” setting in a wg-quick-style configuration file).

MTU

Optionally enter a custom MTU value, like “1380”, in the MTU field. This is the maximum bytes of data that the OS should put in each packet it sends from local sockets to the interface (before WireGuard encrypts and wraps them in another set of packets). Usually you should omit this setting, and let WireGuard determine the best MTU to advertise automatically.

Table

Optionally enter a custom routing table number or name to which to add this interface’s routes, like “123”, in the Table field. Leave it blank or enter “auto” to use the host’s default routing table; enter “off” to prevent WireGuard from adding routes to any table.

WireGuard does not support the Table field on Android, iOS, or macOS hosts; leave it blank for them.

Pre Up Script

Optionally enter a list of commands to run before the interface starts up, like “sysctl -w net.ipv4.ip_forward=1”, in the Pre Up Script field. Enter each command on a separate line. Each command will be run as root in its own subshell. If a command fails (that is, exits with a non-zero exit code), the interface will not start up.

WireGuard does not support any of the script fields on Android, iOS, or macOS hosts; leave them blank.

Post Up Script

Optionally enter a list of commands to run after the interface starts up in the Post Up Script field. Enter each command on a separate line. Each command will be run as root in its own subshell. If a command fails (that is, exits with a non-zero exit code), the interface will shut down immediately, without running any pre- or post-down scripts.

Pre Down Script

Optionally enter a list of commands to run before the interface shuts down in the Pre Down Script field. Enter each command on a separate line. Each command will be run as root in its own subshell. If a command fails (that is, exits with a non-zero exit code), the interface will not shut down.

Pre Down Actions

Check the Save config checkbox to ovewrite the interface’s configuration file with the interface’s current state when it is shut down. This setting is usually not useful when using Pro Custodibus to manage the interface.

Post Down Script

Optionally enter a list of commands to run after the interface shuts down in the Post Down Script field. Enter each command on a separate line. Each command will be run as root in its own subshell. If a command fails (that is, exits with a non-zero exit code), it will have no effect on the interface shutting down.

Form Submit

Click the Add button to submit the form and queue the creation of the interface.

The next time the Pro Custodibus agent on the host pings the Pro Custodibus servers, the agent will receive the information about the new interface, and create it on the host.

Next Steps

Add an endpoint to the interface to allow it to connect to a remote peer.