var img = document.createElement('img'); img.src = "https://matomo.0l.de/piwik.php?idsite=5&rec=1&url=https://cunicu.li" + location.pathname; img.style = "border:0"; img.alt = "tracker"; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(img,s);
Skip to main content

Advanced Example

info

Please also have a look at the JSON Schema for a full reference of available options/

The following file contains a full-featured set of cunīcu's options.

You can find the file at:

/etc/cunicu.advanced.yaml
# SPDX-FileCopyrightText: 2023 Steffen Vogel <post@steffenvogel.de>
# SPDX-License-Identifier: Apache-2.0
# yaml-language-server: $schema=https://cunicu.li/schemas/config.yaml
---

# An interval at which cunīcu will periodically check for added,
# removed or modified WireGuard interfaces.
watch_interval: 1s

## Signaling backends
#
# These backends are used for exchanging control-plane messages
# between the peers.
# E.g. ICE candidates, Peer information
backends:
- grpc://signal.cunicu.li:443
# - grpc://localhost:8080?insecure=true&skip_verify=true


# RPC control socket settings
rpc:
  # Path to a Unix socket for management
  # and monitoring of the cunicu daemon.
  socket: /var/run/cunicu.sock

  # Start of cunīcu daemon will block until
  # its unblocked via the control socket.
  # Mostly useful for testing automation
  wait: false


# Logging configuration
log:
  # Show a banner during start of daemon
  banner: true

  # Use one of
  #  - auto    only colorize log output on TTYs
  #  - never   never colorize log output
  #  - always  always colorize log output
  color: auto

  # A path to a custom log file
  file: mylogfile.log

  # The standard log level
  level: info

  # Additional logging rules
  # Rule syntax:
  #
  #   RULE: LEVELS:NAMESPACES
  #
  #   LEVELS: LEVEL[,LEVELS]
  #   LEVEL: one of
  #    -  SEVERITY        for matching all levels with equal or higher severity
  #    - >SEVERITY        for matching all levels with higher severity
  #    - =SEVERITY        for matching all levels with equal severity
  #    - <SEVERITY        for matching all levels with lower severity
  #
  #   SEVERITY: one of
  #    - debug10..debug1
  #    - debug
  #    - info
  #    - warn
  #    - error
  #    - fatal
  #    - panic
  #
  #   NAMESPACES: NAMESPACE[,NAMESPACES]
  #   NAMESPACE: one of
  #    - namespace        should be exactly this namespace
  #    - *mat*ch*         should match
  #    - -NAMESPACE       should not match a namespace
  rules:
  - debug5:watcher,daemon
  - debug6:epdisc.*


#### Interface settings start here
# The following settings can be overwritten for each interface
# using the 'interfaces' settings (see below).
# The following settings will be used as default.

## WireGuard interface settings
#
# These settings configure WireGuard specific settings
# of the interface.

# A base64 private key generated by wg genkey.
# Will be automatically generated if not provided.
private_key: KLoqDLKgoqaUkwctTd+Ov3pfImOfadkkvTdPlXsuLWM=

# Create WireGuard interfaces using bundled wireguard-go
# user space implementation. This will be the default
# if there is no WireGuard kernel module present.
userspace: false

# A range constraint for an automatically assigned
# selected listen port.
# If the interface has no listen port specified, cunīcu
# will use the first available port from this range.
listen_port_range:
  min: 52820
  max: 65535

# A 16-bit port for listening. Optional;
# If not specified, first available port from listen_port_range
# will be used.
listen_port: 51825

# A 32-bit fwmark for outgoing packets which can be used
# for Netfilter or TC classification.
# If set to 0 or "off", this option is disabled.
# May be specified in hexadecimal by prepending "0x". Optional.
fwmark: 0x1000

# The remote WireGuard peers provided as a dictionary
# The keys of this dictionary are used as names for the peers
peers:  
  test:
    # A base64 public key calculated by wg pubkey from a private key,
    # and usually transmitted out of band
    # to the author of the configuration file.
    public_key: FlKHqqQQx+bTAq7+YhwEECwWRg2Ih7NQ48F/SeOYRH8=

    # A base64 pre-shared key generated by wg genpsk.
    # Optional, and may be omitted.
    # This option adds an additional layer of symmetric-key
    # cryptography to be mixed into the already existing
    # public-key cryptography, for post-quantum resistance.
    preshared_key: zu86NBVsWOU3cx4UKOQ6MgNj3gv8GXsV9ATzSemdqlI=

    # A pre-shared passphrase which is used to derive a preshared key.
    # cunīcu is using Argon2id as the key derivation function.
    preshared_key_passphrase: some-shared-passphrase

    # An endpoint IP or hostname, followed by a colon,
    # and then a port number. This endpoint will be updated
    # automatically to the most recent source IP address and
    # port of correctly authenticated packets from the peer.
    # If provided, no endpoint discovery will be performed.
    endpoint: vpn.example.com:51820

    # A time duration, between 1 and 65535s inclusive, of how
    # often to send an authenticated empty packet to the peer
    # for the purpose of keeping a stateful firewall or NAT mapping
    # valid persistently. For example, if the interface very rarely
    # sends traffic, but it might at anytime receive traffic from a
    # peer, and it is behind NAT, the interface might benefit from
    # having a persistent keepalive interval of 25 seconds.
    # If set to zero, this option is disabled.
    # By default or when unspecified, this option is off.
    # Most users will not need this. Optional.
    persistent_keepalive: 120s

    # A comma-separated list of IP (v4 or v6) addresses with
    # CIDR masks from which incoming traffic for this peer is
    # allowed and to which outgoing  traffic for this peer is directed.
    # The catch-all 0.0.0.0/0 may be specified for matching
    # all IPv4 addresses, and ::/0 may be specified for matching
    # all IPv6 addresses. May be specified multiple times.
    allowed_ips:
    - 192.168.5.0/24

## Basic interface settings
#

# The Maximum Transfer Unit of the WireGuard interface.
# If not specified, the MTU is automatically determined from
# the endpoint addresses or the system default route,
# which is usually a sane choice.
# However, to manually specify an MTU to override this
# automatic discovery, this value may be specified explicitly.
mtu: 1420

# A list of IP (v4 or v6) addresses (optionally with CIDR masks)
# to be assigned to the interface.
# May be specified multiple times.
addresses:
- 10.10.0.1/24

# A list of prefixes which cunicu uses to derive local addresses
# from the interfaces public key
prefixes:
- fc2f:9a4d::/32
- 10.237.0.0/16

# A list of IP (v4 or v6) addresses to be set as the interface's
# DNS servers, or non-IP hostnames to be set as the interface's
# DNS search domains.
# May be specified multiple times.
# Upon bringing the interface up, this runs `resolvconf -a tun.INTERFACE -m 0 -x`
# and upon bringing it down, this runs `resolvconf -d tun.INTERFACE`.
# If these particular invocations of resolvconf(8) are undesirable,
# custom hooks can be used instead.
dns:
- 1.1.1.1


## Config synchronization
#
# Synchronize local WireGuard interface configuration with wg(8) config-files.

# Enable config synchronization
sync_config: false

# Keep watching for changes in the configuration and apply them on-the-fly
watch_config: false

## Route Synchronization
#
# Synchronize the kernel routing table with WireGuard's AllowedIPs setting
# 
# It checks for routes in the kernel routing table which have a peers address
# as next-hop and adds those routes to the AllowedIPs setting of the respective peer.
#
# In reverse, also networks listed in a peers AllowedIPs setting will be installed as a
# kernel route with the peers address as the routes next-hop. 

# Enable route synchronization
sync_routes: true

# Kernel routing table which is used
# On Linux, see /etc/iproute2/rt_tables for table ids and names
routing_table: 254

# Keep watching the for changes in the kernel routing table via netlink multicast group.
watch_routes: true


## /etc/hosts synchronization
#
# Synchronizes the local /etc/hosts file with host names and addresses of connected peers. 

# Enable hosts file synchronization
sync_hosts: true

# The domain name which is appended to each of the peer host names
domain: wg-local


## Peer discovery
#
# Peer discovery finds new peers within the same community and adds them to the respective interface

# Enable/disable peer discovery
discover_peers: true

# The hostname which gets advertised to remote peers
hostname: my-node

# A passphrase shared among all peers of the same community
community: "some-common-password"

# Networks which are reachable via this peer and get advertised to remote peers
# These will be part of this interfaces AllowedIPs at the remote peers.
networks:
- 192.168.1.0/24
- 10.2.0.0/24

# A list of WireGuard public keys which are accepted peers
# If not configured, all peers will be accepted.
whitelist:
- coNsGPwVPdpahc8U+dbbWGzTAdCd6+1BvPIYg10wDCI=

# A list if WireGuard public keys which are rejected as peers
blacklist:
- AOZzBaNsoV7P8vo0D5UmuIJUQ7AjMbHbGt2EA8eAuEc=


## Endpoint discovery
#
# Endpoint discovery uses Interactive Connectivity Establishment (ICE) as used by WebRTC to
# gather a list of candidate endpoints and performs connectivity checks to find a suitable
# endpoint address which can be used by WireGuard

# Enable/disable endpoint discovery
discover_endpoints: true

# Interactive Connectivity Establishment (ICE) parameters
ice:
  # A list of STUN and TURN servers used by ICE.
  urls:
  # Community provided STUN/TURN servers
  - grpc://relay.cunicu.li

  # Public STUN servers
  - stun:stun3.l.google.com:19302
  - stun:relay.webwormhole.io
  - stun:stun.sipgate.net
  - stun:stun.ekiga.net
  - stun:stun.services.mozilla.com

  # Caution: OpenRelay servers are located in Ontario, Canada.
  # Beware of the latency!
  # See also: https://www.metered.ca/tools/openrelay/
  # - turn:openrelayproject:openrelayproject@openrelay.metered.ca:80
  # - turn:openrelayproject:openrelayproject@openrelay.metered.ca:443
  # - turn:openrelayproject:openrelayproject@openrelay.metered.ca:443?transport=tcp

  # Credentials for STUN/TURN servers configured above.
  username: ""
  password: ""

  # Allow connections to STUNS/TURNS servers for which we can not validate TLS certificates.
  insecure_skip_verify: false

  # Limit available network and candidate types.
  # network_types: [udp4, udp6, tcp4, tcp6]
  # candidate_types: [host, srflx, prflx, relay]

  # A glob(7) pattern to match interfaces against which are used to gather ICE candidates (e.g. \"eth[0-9]\").
  interface_filter: "*"

  # Lite agents do not perform connectivity check and only provide host candidates.
  lite: false

  # Enable local Multicast DNS discovery.
  mdns: false

  # Sets the max amount of binding requests the agent will send over a candidate pair for validation or nomination.
  # If after the the configured number, the candidate is yet to answer a binding request or a nomination we set the pair as failed.
  max_binding_requests: 7

  # SetNAT1To1IPs sets a list of external IP addresses of 1:1 (D)NAT and a candidate type for which the external IP address is used.
  # This is useful when you are host a server using Pion on an AWS EC2 instance which has a private address, behind a 1:1 DNAT with a public IP (e.g. Elastic IP).
  # In this case, you can give the public IP address so that Pion will use the public IP address in its candidate instead of the private IP address.
  # nat_1to1_ips:
  # - 10.10.2.3

  # Limit the port range used by ICE
  port_range:
      # Minimum port for allocation policy for ICE sockets (range: 0-65535)
      min: 49152

      # Maximum port for allocation policy for ICE sockets (range: 0-65535)
      max: 65535

  # Interval at which the agent performs candidate checks in the connecting phase
  check_interval: 200ms
    
  # Time until an Agent transitions disconnected.
  # If the duration is 0, the ICE Agent will never go to disconnected
  disconnected_timeout: 5s

  # Time until an Agent transitions to failed after disconnected
  # If the duration is 0, we will never go to failed.
  failed_timeout: 5s

  # Time to wait before ICE restart
  restart_timeout: 5s

  # Interval between STUN keepalives (should be less then connection timeout above).
  # Af the interval is 0, we never send keepalive packets
  keepalive_interval: 2s


## Hook callbacks
#
# Hook callback can be used to invoke subprocesses
# or web-hooks on certain events within cunīcu.
hooks:

  # An 'exec' hook spawn a subprocess for each event.
  - type: exec
    command: ../../scripts/hook.sh
  
    # Prepend additional arguments
    args: []
  
    # Pass JSON object via Stdin to command
    stdin: true
  
    # Set environment variables for invocation
    env:
      COLOR: "1"
  
  # A 'web' hook performs HTTP requests for each event.
  - type: web
  
    # URL of the webhook endpoint
    url: https://my-webhook-endpoint.com/api/v1/webhook
    
    # HTTP method of the request
    method: POST
  
    # Additional HTTP headers which are used for the requests
    headers:
      User-Agent: ahoi
      Authorization: Bearer XXXXXX


## Interface specific settings / overwrites.
#
# Most of the top-level settings of this configuration file can be customized
# for specific interfaces.
# 
# The keys of the 'interfaces' dictionary are glob(7) patterns which will be
# matched against the interface names.
# Settings are overlayed in the order in which the keys are provided in the
# interface map.
#
# Keys which are not a glob(8) pattern, will be created as new interfaces if
# they do not exist already in the system.
interfaces:
  # A simple interface specific setting
  # cunicu will set the private key of interface 'wg0' to the provided value.
  wg0:
    discover_endpoints: false

  # No settings are overwritten. But since this is not a glob pattern,
  # A new interface named 'wg1' will be created if it does not exist yet.
  # The same applies to the previous interface 'wg0'
  wg1: {}

  # Create a new interface using the wireguard-go user-space implementation.
  wg2:
    userspace: true

  # This pattern configuration will be applied to all interfaces which match the pattern.
  # This rule will not create any new interfaces.
  wg-work-*:
    community: "mysecret-pass" 
    
    ice:
      urls:
      - turn:mysecret.turn-server.com

  # Multiple patterns are supported and evaluated in the order they a defined in the configuration file.
  # 
  wg-work-external-*:
    ice:
      network_types: [ udp6 ]