About
IfState is a python3 utility to configure the Linux network stack in a declarative manner. It is a frontend for the kernel’s netlink protocol based on pyroute2 and aims to be as powerful as the following commands:
- bridge
- ethtool
- iproute2
- address
- link
- neighbour
- netns
- route
- rule
- vrf
- sysctl for network config (
/proc/sys/net/ipv[46]/conf/$IFACE/
) - tc
- wireguard
- xdp-tools
It was written for interface configuration on lightweight software defined linux routers without using any additional network management daemon like Network-Manager or systemd-networkd. Can be used with deployment and automation tools like ansible since it’s declarative and operates idempotent.
When IfState was born there where already other projects for declarative interface configuration. Sadly they require network management daemons and lack support for many virtual link types:
- NMState - A Declarative API for Host Network Management
- Netplan - The network configuration abstraction renderer
IfState can be used as a base for dynamic routing daemons like:
It is possible to skip different settings (addresses, routes, …) in IfState completely if a routing daemon (FRR, Quagga) does handle it.
IfState has full support for Linux netns namespaces. This allows to build firewalls and routers with hard multi-client capability without much effort. Alpine Linux is one of the few (the only?) Linux distributions with native netns support for daemons.
Presentations
The following recordings of public talks about IfState are available online:
- Declarative network configuration with ifstate at AlpineConf 2021 (in English)
- Deklarative Netzwerkkonfiguration mit IfState at Chemnitzer Linux-Tage 2023 (in German)
Installation
IfState is available in the following linux distributions:
Alternatively you could use pip3 to install IfState:
pip3 install ifstate
This will also install all python dependencies if not already statisfied.
Usage
Be aware that using the ifstatecli
command will by default shutdown and remove any interfaces which are not declared in the configuration. It ships with a build-in ignore list for some well-known interfaces which should not handled by IfState (i.e. docker0
, veth
, …).
Example configuration:
interfaces:
- name: eth0
addresses: []
link:
kind: physical
- name: eth0.10
addresses:
- 198.51.100.3/27
link:
kind: vlan
link: eth0
vlan_id: 10
- name: LOOP
addresses:
- 192.0.2.3
- 2001:db8::3
link:
kind: dummy
routing:
routes:
- to: 198.51.100.128/25
via: 198.51.100.1
Run the ifstatecli
command:
# ifstatecli -c test.yml apply
cleanup orphan interfaces…
eth1 orphan
configure interfaces…
lo
link ok
addresses = 127.0.0.1/8
addresses = ::1/128
eth0
link ok
eth0.10
link add
addresses + 198.51.100.3/27
LOOP
link ok
addresses = 192.0.2.3/32
addresses = 2001:db8::3/128
configure routing…
main + 198.51.100.128/25
It is possible to create a configuration template from the currently available interfaces using the ifstatecli show
command.