Skip to content

Documentation

Declarative network stack configuration

IfState will (re)configure the hosts network stack configuration to match the desired configuration. As a result unspecified interfaces or ip addresses are automatically shutdown or removed. IfState reaches the desired network configuration from any previous state. Simular to ansible only those parts of the network stack that are referenced in the configuration file are taken into account.

Usage

On Alpine Linux IfState can be installed via apk and is packaged with a init script. IfState provides the CLI command ifstatecli as an interface.

Configuration file

IfState uses a YAML configuration file which needs to comply with the IfState Configuration Schema. The default filename of the config file is /etc/ifstate/ifstate.yaml.

This is a basic example configuration for a single interface and a default route:

# yaml-language-server: $schema=https://ifstate.net/schema/2.0/ifstate.conf.schema.json

## configure ifstate's behavoir (optional)
# parameters
#   cshaper: …   # "cake shaper" templates
#   defaults: …  # default/implicit interface settings
#   hooks: …     # define external hooks for external interface configuration
#   ignore: …    # ignore settings of existing ifaces, IP addresses, …

## load and pin bpf programs (optional)
# bpf: …

## configure network related global sysctl settings (optional)
# sysctl: …

## interface configuration block (required)
interfaces:
  eno1:
    addresses:
    - 192.0.2.254/24
    link:
      state: up
      kind: physical
    identify:
      parent_dev_name: 0000:00:1f.6
      parent_dev_bus_name: pci

## routing settings (optional)
routing:
  routes:
  - to: 0.0.0.0/0
    via: 192.0.2.1

## configuration for netns namespaces (optional)
# namespaces: …

Settings of the configuration file:

The JSON schema of the configuration file is available in the JSON Schema Store (as ifstate.conf). Most modern editors and IDEs have native support for JSON Schema Store.

Adding the following line to the configuration file instructs editors and IDEs using the YAML Language Server to load the IfState schema automatically. The schema is versioned and available for the latest major and major.minor releases:

# yaml-language-server: $schema=https://ifstate.net/schema/2/ifstate.conf.schema.json

# yaml-language-server: $schema=https://ifstate.net/schema/2.0/ifstate.conf.schema.json

VRRP actions & Keepalived

IfState can be combined with Keepalived as a notify script. The vrrp option for interface and routing settings allows to reconfigure parts of the network stack depending on the state of a VRRP instance or group. This allows to move complex network configuration out of Keepalived while still using it for VRRP.