Installation

Alpine Linux

IfState is available in the community repository since Alpine Linux 3.13.

To enable eXpress Data Path (XDP) support you need to install libbpf.

You need to install py3-pygments to enable syntax highlighting in ifstate's interactive python shell.

Debian GNU/Linux

IfState is not available in the Debian repository, yet. Packages are provided for Debian trixie and bookworm in the RouterKit package registry hosted at Codeberg:

put the following repository key at /etc/apt/keyrings/routerkit.asc:

add a new repository source file /etc/apt/sources.list.d/routerkit.list with the following content:

Debian GNU/Linux 13 (trixie)Debian GNU/Linux 12 (bookworm)

deb [signed-by=/etc/apt/keyrings/routerkit.asc] https://codeberg.org/api/packages/routerkit/debian trixie stable

deb [signed-by=/etc/apt/keyrings/routerkit.asc] https://codeberg.org/api/packages/routerkit/debian bookworm stable

install ifstate via apt:
```
# apt update
# apt install ifstate
```

Configuration required

Installing ifstate will remove the ifupdown package (or one of its replacements). If no sensible ifstate configuration is provided the host will not have a working network setup when it is rebooted the next time!

NixOS

Downstream Nixpkgs

IfState is available in Nixpkgs repository since NixOS 25.11.

See NixOS Search for all available options.

Additionally this module also supports IfState to be used in the initrd to accomplish features like remote disk decryption using ssh.

Example Configuration

{
  networking.ifstate = {
    enable = true;
    settings = {
      interfaces.eth0 = {
        addresses = [ "2001:0db8::10/64" ];
        link = {
          state = "up";
          kind = "physical";
        };
        identify.perm_address = "2e:28:00:60:c2:1b";
      };
      routing.routes = [
        { to = "::/0"; via = "2001:0db8::1"; }
      ];
    };
  };
}

Example initrd Configuration

{ config, ... }:

{
  boot.initrd = {
    # systemd stage two is required for IfState in initrd
    system.enable = true;

    network = {
      enable = true;

      ifstate = {
        enable = true;
        # copy non-initrd ifstate configuration
        # NOTE: ifstate in initrd disables some features by default
        #       in order to redurce disk usage in /boot
        #       see `boot.initrd.network.ifstate.package` for details.
        settings = config.networking.ifstate.settings;
      };

      # example ssh configuration
      # See https://wiki.nixos.org/wiki/Remote_disk_unlocking for details
      # after connecting to ssh execute `systemctl default`
      ssh = {
        enable = true;
        hostKeys = [ /etc/ssh/ssh_initrd_host_ed25519_key ];
        authorizedKeys = [ "ssh-ed25519 AAAA..." ];  
      };
    };
  };
}

Using IfState as a flake

This repository can also be used as a flake input:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-25.05";
    ifstate = {
      url = "git+https://codeberg.org/routerkit/ifstate";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { nixpkgs, ifstate, ... }: {
    nixosConfigurations = {
      hostname = nixpkgs.lib.nixosSystem {
        modules = [
          ifstate.nixosModules.default
        ];
      };
    };
  };
}

The supported options are identical, but may contain new features ahead of schedule.

For a full list of available options see the options reference.

Manually

Prerequisites

IfState depends on Python3 and the following python packages:

pyroute2 - Python Netlink library
PyYAML - YAML parser and emitter for Python
jsonschema - An implementation of JSON Schema validation for Python (recommended)
Pygments - Python syntax highlighter (optional)

IfState uses python ctypes to configure XDP. You need to have libbp.so.1 available to configure XDP.

PyPI

IfState is available at Python Package Index. Use pip3 for installation:

pip3 install ifstate

This will also install all dependencies if not already satisfied. The optional dependencies can be installed via pip's extra feature:

pip3 install ifstate[shell]