Configure your Linux network interfaces from YAML.

ypconfig is a Python tool that configures network interfaces on a Linux machine, according to a YAML config. ypconfig implements the test && commit || revert paradigm on Linux, making it ideal to run routers.

This tool is made possible by pyroute2 which enables us to communicate with Netlink.

ypconfig is available as a Debian package for Bookworm.

• GPG key: https://packagecloud.io/ypconfig/ypconfig/gpgkey
• Repository: deb https://packagecloud.io/ypconfig/ypconfig/debian bookworm main

Run:

pip3 install -r requirements-dev.txt
pre-commit install

ypconfig supports Python >= 3.11 and has been tested on Debian 12.

ypconfig reads a YAML file (defaults to /etc/ypconfig/ypconfig.yml) and tries to configure the system accordingly. The config file should contain an array of interfaces, where each interface has the following options:

• description: Your own description, usually read via snmpd.
• addresses: An array of addresses with the syntax 'ipAddress/prefixLength'.
• vaddresses: Optional: an array of addresses that can be assigned on this interface, e.g. via VRRP. ypconfig will not add or remove these addresses.
• adminstate: The state of the interface. Options: UP or DOWN. Default: UP.
• mtu: The MTU of the interface. Default: 1500.
• ratelimit: Either a single float-value where this value is the ratelimit in bit/s, or an in value and/or out value, to differentiate between incoming and outgoing ratelimits. Optionally, a unit can be added (KMG). [NOT YET IMPLEMENTED]
• slaves: An array with interfaces you want to bond into this interface.
• Optional type: The type of the interface:
  • default
  • bond
  • slave
  • vlan
  • loopback
• For vLAN interfaces, set the following options:
  • The value vlanid is the vLAN ID (integer).
  • The value parent is the name of the parent interface.
• For bond interfaces, set the following options:
  • bond-mode, the bond-mode you want to use. See this documentation for more information.
    • balance-rr
    • active-backup
    • balance-xor
    • broadcast
    • 802.3ad
    • balance-tlb
    • balance-alb
  • miimon: The MII link monitoring frequency in milliseconds. Default: 100.
  • lacp_rate: Only valid if mode is 802.3ad. Can be slow or fast. Default: slow.

There is a special 'interface' called routes. If the config file does not have a routes interface, ypconfig will not touch routes. If you do want ypconfig to handle routes, here's how:

routes:
  default:
  - 192.168.1.1
  - fd00::192:168:1:1
  172.16.0.0/24:
  - 192.168.2.1
  fd08::172:16:0:0/64
  - fd00::192:168:2:1

Although the routes use an array for nexthop, only one nexthop is currently supported.

When installing ypconfig, a config file will be created for you in /etc/ypconfig/ypconfig.yml. This config file will contain your currently configured interfaces. Note that this config file will not be generated when a file with the same name already exists. You can generate a config file at any time using ypconfig createconfig.

ypconfig ships with a systemd unit, ypconfig.service. This one-shot service takes care of configuring your interfaces (as specified in the config file) on boot.

You can commit at any time by running ypconfig commit. This will rollback if it doesn't receive your confirmation within 60 seconds. This behaviour can be overridden by running with the --confirm flag, but you should probably not do that as it will not rollback when you may need it to. Note that running --confirm with a faulty config file will not commit. You can check your config file using ypconfig configtest.

All ypconfig commands take the argument --cfg which allows you to use a custom config file.

This is a single, normal interface with no special options.

eth0:
  addresses:
  - 192.168.1.4/24
  - fd00::192:168:1:4/64
  adminstate: UP
  mtu: 1500
lo:
  addresses:
  - 127.0.0.1/8
  - ::1/128
  mtu: 65536

A vLAN interface on eth0.

eth0:
  adminstate: UP
  mtu: 1500
foobar:
  adminstate: UP
  addresses:
  - 192.168.1.4/24
  - fd00::192:168:1:4/64
  mtu: 1500
  vlanid: 200
  parent: eth0
lo:
  addresses:
  - 127.0.0.1/8
  - ::1/128
  mtu: 65536

Two interfaces: eth0 with jumbo frames, and eth1 with a ratelimit of 10 Mbit up and 100 Mbit down.

eth0:
  adminstate: UP
  mtu: 9000
  addresses:
  - 192.168.1.4/24
  - fd00::192:168:1:4/64
eth1:
  adminstate: UP
  mtu: 1500
  addresses:
  - 192.168.2.4/24
  - fd00::192:168:2:4/64
  ratelimit:
    up: 10M
    down: 100M
lo:
  addresses:
  - 127.0.0.1/8
  - ::1/128
  mtu: 65536

bond0:
  adminstate: UP
  mtu: 9000
  addresses:
  - 192.168.1.4/24
  - fd00::192:168:1:4/64
  slaves:
  - eth0
  - eth1

ypconfig was originally written by Mark Schouten mark@tuxis.nl at Tuxis. It was open-sourced in June 2017.