About
IfState is a python3 library to configure (linux) host interfaces in a declarative manner. It is a frontend for the kernel netlink protocol using pyroute2 and aims to be as powerful as the following commands:
- iproute2
- bridge
- ethtool
- sysctl for interface settings (
/proc/sys/net/ipv[46]/conf/$IFACE/
) - tc (experimental)
- wireguard
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 daemon 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.
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 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
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
configuring interface links
eth0 ok
eth0.10 add
LOOP ok
eth1 orphan
configuring ip addresses...
eth0.10 198.51.100.3/27
LOOP 192.0.2.3/32
LOOP 2001:db8::3/128
configuring routing table main...
198.51.100.128/25 add
It is possible to create a configuration template from the currently available interfaces using the ifstatecli show
command.