Nipart

https://nispor.github.io/nipart/

Nipart is a network management tool written in Rust providing descriptive API for network management.

Nipart can work in common daemon-client mode, or one-shot daemon-free mode.

The nipartd daemon provides complex network management features, such as DHCP, conditional network up/down.

The npt client by default, send request to daemon for querying and applying network changes. With npt apply <YAML> --no-daemon, it bypass daemon and apply network changes directly to Linux kernel or related daemon(e.g. OVS).

Example YAML connecting to a WIFI network(works both in daemon and no-daemon mode):

---
version: 1
routes:
  config:
  - destination: 0.0.0.0/0
    next-hop-interface: wlan0
    next-hop-address: 192.0.2.1
    metric: 100
interfaces:
- name: wlan0
  type: wifi-phy
  wifi:
    ssid: Test-WIFI
    password: 12345678
  ipv4:
    enabled: true
    dhcp: false
    address:
    - ip: 192.0.2.99
      prefix-length: 24

Installation

Build from source

cargo build --release
sudo systemctl stop nipart || true
sudo cp -fv target/release/nipartd /usr/bin/
sudo cp -fv target/release/npt /usr/bin/
sudo cp -fv packaging/nipart.service /etc/systemd/system/
sudo cp -fv packaging/nipart-wait-online.service /etc/systemd/system/
sudo systemctl enable nipart.service
sudo systemctl enable nipart-wait-online.service
sudo systemctl start nipart.service

Install from Archlinux AUR

TODO: Upload to AUR

Install from Fedora COPR

TODO: Upload to COPR

Usage

Show current network state

# daemon mode
sudo npt show
# no-daemon mode
sudo npt show -n

Show saved config of daemon

sudo npt show -s

Show running status of certain interface

sudo npt show wlan0

Scan WIFI networks

sudo npt wifi scan

Connect to WIFI

# This command will ask you to input your wifi password
sudo npt wifi connect <SSID>

Features

Nipart Base Interface support

Nipart Base Interface support

All interface types supported by Nipart support this YAML structure:

---
version: 1
interfaces:
- name: eth1
  type: veth
  iface-index: 8
  state: up
  link-state: up
  controller: bond0
  mac-address: CE:67:51:EC:E2:6A
  permanent-mac-address: CE:67:51:EC:E2:6A
  mtu: 1500
  min-mtu: 68
  max-mtu: 65535
  ipv4:
    enabled: false
  ipv6:
    enabled: false

`name` – Interface name

The kernel name of interface

`type` – Interface type

The type of interface, e.g. veth, bond, bridge, etc.

`iface-index` - Interface index

The kernel index of the interface. Query only property.

`state` - Interface state

The management state of the interface:

up: the interface is administratively up
down: the interface is administratively down
absent: apply only property, request nipart to delete this interface or restore physical interface to kernel default state
ignore: Not managed by nipart
up-ignore: Interface is administratively up but not managed by nipart
down-ignore: Interface is administratively down but not managed by nipart

`link-state` – Link state

Query only property. Interface carrier state:

up: the interface has carrier
down: the interface does not have carrier
dormant: the interface is dormant, e.g. a wireless interface in power saving mode
lower-layer-down: the interface is down due to lower layer failure, e.g. a physical interface is down
testing: the interface is in testing mode

`controller` - Controller interface

The kernel interface name of the controller interface.

When applying, setting this property to empty string means detach from its current controller. When applying, setting this property to a non-empty string means attach to the controller interface.

`mac-address` - MAC address

The current MAC address of the interface.

When applying, setting this property to empty string means restore the permanent MAC address. When applying, setting this property to a non-empty string means set the MAC address.

`permanent-mac-address` - Permanent MAC address

Query only property. The permanent MAC address of the interface

`mtu` - MTU

MTU of the interface

`min-mtu` - Minimum MTU

Query only property. The minimum MTU supported by the interface

`max-mtu` - Maximum MTU

Query only property. The maximum MTU supported by the interface

`ipv4` and `ipv6` - IP configuration

Please check IP configuration for details.

IP Address

IP Address

Example YAML of static IP address configuration:

version: 1
interfaces:
- name: eth1
  type: veth
  state: up
  ipv4:
    enabled: true
    dhcp: false
    address:
    - ip: 192.0.2.252
      prefix-length: 24
    - ip: 192.0.2.251
      prefix-length: 24
  ipv6:
    enabled: true
    dhcp: false
    autoconf: false
    address:
    - ip: 2001:db8:1::1
      prefix-length: 64
    - ip: 2001:db8:2::1
      prefix-length: 64

`enabled` – Enable IP stack

When set to false, the IP stack will be disabled for the interface. This means that the interface will not be able to send or receive IP packets.

`dhcp` – Enable DHCP

When set to true, the interface will attempt to obtain an IP address via DHCP. This is only applicable if enabled is set to true.

NOTE: DHCPv6 cannot set IPv6 route. Use autoconf to obtain IPv6 address and route via IPv6 Route Advertisement instead.

`address` – IP address configuration

The address field is a list of IP address configurations for the interface.

Each entry in the list should contain the following fields:

ip: The IP address to assign to the interface.
prefix-length: The prefix length (subnet mask) for the IP address.
valid-life-time: (Optional) The valid lifetime of the IP address in seconds. If not specified, the IP address will be considered as static IP and valid indefinitely.
preferred-life-time: (Optional) The preferred lifetime of the IP address in seconds. If not specified, the IP address will be considered as static IP and preferred indefinitely.

`autoconf` – Enable IPv6 autoconfiguration

When set to true, the interface will attempt to obtain an IPv6 address via IPv6 Route Advertisement. This is only applicable if enabled is set to true.

No Daemon mode

When passing with --no-daemon option in npt apply <YAML_FILE>, npt command will not contact nipartd daemon but apply the configuration directly to kernel or related daemon(e.g. OpenvSwitch daemon).

Limitations:

Cannot renew DHCP lease. When you request DHCP in desired YAML file, npt will request DHCP lease and apply DHCP lease IP addresses with preferred-life-time and valid-life-time allowing kernel to purge the IP after lease expired. Hence you need to run np apply <YAML_FILE> --no-daemon on a regular basis to renew DHCP lease.
Does not support conditional interface up down because we don’t have daemon to monitor link carrier state and trigger interface up/down conditionally. Use daemon mode instead.

WIFI

WIFI

WIFI configuration in Nipart uses two interface types:

wifi-phy: A kernel wifi physical interface (e.g. wlan0). Used for current state (query results) or when the physical interface name is known ahead of time.
wifi-cfg: A psuedo/userspace-only interface that holds the desired wifi connection configuration. It has no kernel index and lives only in the Nipart desired state. You can optionally bind it to a specific wifi-phy via base-iface, or leave it unbound (meaning “any available wifi-phy”).

Example YAML for WIFI configuration with static IP:

version: 1
routes:
  config:
  - destination: 0.0.0.0/0
    next-hop-interface: wlan0
    next-hop-address: 172.17.2.1
    metric: 100
interfaces:
- name: wlan0
  type: wifi-phy
  state: up
  mtu: 1492
  ipv4:
    enabled: true
    dhcp: false
    address:
    - ip: 172.17.2.6
      prefix-length: 24
  wifi:
    ssid: SweatHome5G
    bssid: D0:21:F9:49:B3:52
    password: <_hidden_>

`ssid` – SSID

The SSID (Service Set Identifier) of the wifi network to connect to.

`state` – Wifi state

Query only property. The current connection state of the wifi link:

disconnected: BSS disconnected
scanning: Scanning for SSID
connecting: SSID found, trying to associate and authenticate with a BSS/SSID
completed: Data connection is fully configured and operational
unknown: State could not be determined

`bssid` – BSSID

The BSSID (Basic Service Set Identifier) of the access point. When set, Nipart will only connect to the specified AP. If omitted, any AP broadcasting the SSID may be used.

`password` – Password

The password or pre-shared key for authentication. This field is replaced with <_hidden_> when querying current state.

`base-iface` – Base interface

The kernel name of the wifi physical interface to bind this configuration to. If set, the wifi connection is restricted to that specific interface.

When using wifi-phy type, this field defaults to the interface name itself. When using wifi-cfg type with base-iface: <name>, the config binds to that physical interface. When undefined (unbound), the config applies to any eligible wifi-phy interface.

`auth-types` – Authentication types

Query only property. It contains the current authentication type. When showing wifi scan results, it contains the authentication types supported by the AP. Ignored when applying.

Supported authentication types:

OPEN – No authentication (open network)
WEP – WEP (deprecated)
WPA1 – WPA 1 (deprecated)
WPS – WPS (deprecated)
WPA2-PSK – WPA 2 Pre-shared Key
EAP – WPA 2/3 EAP / Enterprise (including OSEN)
WPA3-PSK – WPA 3 Pre-shared Key using SAE
WPA3-OPEN – WPA 3 open network using OWE
FILS – IEEE 802.11ai Fast Initial Link Setup
DPP – Device Provisioning Protocol (Easy Connect)

`generation` – Wifi generation

Query only property. The wifi generation, e.g. 6 for WiFi 6.

`frequency-mhz` – Frequency

Query only property. The wifi frequency in MHz.

`rx-bitrate-mb` – Receive bitrate

Query only property. The receive bitrate in 1 Mb/s.

`tx-bitrate-mb` – Transmit bitrate

Query only property. The transmit bitrate in 1 Mb/s.

`signal-dbm` – Signal level

Query only property. The signal strength in dBm.

`signal-percent` – Signal percentage

Query only property. The signal strength as a percentage (0-100).

Route

Route

Example YAML of route configuration:

version: 1
routes:
  config:
  - destination: 0.0.0.0/0
    next-hop-interface: eth1
    next-hop-address: 192.0.2.1
    metric: 100
    table-id: 254
  - destination: 0.0.0.0/0
    next-hop-interface: eth1
    next-hop-address: 192.0.2.2
    metric: 100
    weight: 2
  - destination: 2001:db8::/64
    next-hop-interface: eth1
    next-hop-address: 2001:db8::1
  - destination: 10.0.0.0/24
    next-hop-interface: eth1
    next-hop-address: 192.0.2.254
  - state: absent
    next-hop-interface: eth1

`running` – Current kernel routes

Query only property. Contains the currently active routes from kernel, filtered to routes with universe or link scope and only from these protocols: boot, static, ra, dhcp, mrouted, keepalived, babel.

Ignored when applying.

`config` – Desired static routes

The desired static routes. Contains routes from universe or link scope, and only from protocols boot and static.

When applying, None means preserve current routes. This property is not overriding but adding specified routes to existing routes. To delete a route entry, set state to absent. Any property of an absent RouteEntry set to None means wildcard matching. For example, this will remove all routes next hop to interface eth1:

routes:
  config:
  - next-hop-interface: eth1
    state: absent

To change a route entry, you need to delete the old one and add the new one (can be in single transaction).

`state` – Route state

Used only for deleting routes when applying:

absent: Mark a route entry to be removed. Properties set to None act as wildcards for matching which routes to delete.
ignore: Mark a route as not managed by nipart.

`destination` – Route destination network

The destination network of the route in CIDR notation, e.g. 0.0.0.0/0 for default gateway or 10.0.0.0/24.

Mandatory for every non-absent route.

0.0.0.0/8 and its subnet cannot be used as the route destination for unicast route. Use 0.0.0.0/0 for default gateway instead.

`next-hop-interface` – Next hop interface

The interface name of the next hop, e.g. eth1.

Mandatory for every non-absent unicast route. Not required for routes with route type Blackhole, Unreachable, or Prohibit.

`next-hop-address` – Next hop IP address

The IP address of the next hop router, e.g. 192.0.2.1.

Optional. When set to empty string for absent route, it will only delete routes without a next-hop-address.

`metric` – Route metric

The route metric (priority). Default is backend-defined. Lower metric is preferred.

`table-id` – Route table ID

The routing table ID. Default is 254 (main routing table). Set to 0 to use backend default.

`weight` – ECMP route weight

The weight for Equal-Cost Multi-Path (ECMP) routing. Valid range is 1 to 256.

When multiple route entries share the same destination and metric but have different next-hop-address, they form ECMP routes. Kernel distributes traffic across them proportionally to the weight.

IPv6 ECMP route with weight is not supported yet.

`route-type` – Route type

The type of route:

blackhole: Packets matching this route are silently discarded.
unreachable: Packets matching this route generate an ICMP unreachable message.
prohibit: Packets matching this route generate an ICMP administratively prohibited message.

A route without route-type is a unicast route (default).

A non-unicast route cannot have a next-hop-interface (except lo) or next-hop-address.

`source` – Source address

The preferred source address for packets routed via this route. Specifies which local IP address should be used as the source for outgoing packets matching this route.

`cwnd` – Congestion window clamp

The congestion window clamp size in bytes. Cannot be set to 0.

`initcwnd` – Initial congestion window

The initial congestion window size in bytes (TCP initcwnd).

`initrwnd` – Initial receive window

The initial receive window size in bytes (TCP initrwnd).

`mtu` – Route MTU

The MTU of the route in bytes. Cannot be set to 0.

`quickack` – Quick ACK

When set to true, disables delayed TCP acknowledgments for connections using this route.

`advmss` – Advertised MSS

The Maximum Segment Size (MSS) to advertise for TCP connections using this route. Cannot be set to 0.

Conditional Network Up/Down
- Example: Carrier-based up/down
- Example: Start VPN when not in home WIFI

Conditional Network Up/Down

For conditionally bringing an interface up/down, the trigger section is used for daemon mode only.

The trigger takes these values:

never: Never do auto action to bring interface up/down.
always: Always bring interface up/down regardless of carrier.
carrier: Bring interface up if carrier is up, otherwise bring interface down.
wifi: <SSID>: Bring interface up if specified SSID is connected, otherwise disconnect.
wifi-not: <SSID>: Bring interface down if specified SSID is connected, otherwise connect.

Example: Carrier-based up/down

interfaces:
- name: enp7s0
  type: ethernet
  state: up
  trigger: carrier
  ipv4:
    enabled: true
    dhcp: false
    address:
    - ip: 192.0.2.251
      prefix-length: 32
  ipv6:
    enabled: false

Example: Start VPN when not in home WIFI

routes:
  config:
  - destination: 203.0.113.0/24
    next-hop-interface: wg0
    next-hop-address: 198.51.100.1
    metric: 100
    table-id: 25
interfaces:
- name: wg0
  type: wireguard
  state: up
  ipv4:
    enabled: true
    dhcp: false
    address:
    - ip: 198.51.100.9
      prefix-length: 24
  trigger:
    wifi-not: HomeWifi
  wireguard:
    public-key: JKossUAjywXuJ2YVcaeD6PaHs+afPmIthDuqEVlspwA=
    private-key: 6LTHiAM4vgKEgi5vm30f/EBIEWFDmySkTc9EWCcIqEs=
    listen-port: 51820
    peers:
    - endpoint: 192.0.2.0:51820
      public-key: 8bdQrVLqiw3ZoHCucNh1YfH0iCWuyStniRr8t7H24Fk=
      persistent-keepalive: 0
      allowed-ips:
      - ip: 0.0.0.0
        prefix-length: 0

Wait Online

Wait Online

npt wait-online waits for nipartd to configure the network and reach an online state. Used by nipart-wait-online.service for systemd network-online.target.

Configuration

wait-online:
  timeout-sec: 30
  conditions:
  - gateway4
  - gateway6

wait-online does not use partial updating - if defined, it overrides any previous configuration. To keep existing settings, use the previously saved config.

Behavior

When all conditions are met, the daemon considers the network online and npt wait-online exits with code 0.
On timeout, npt wait-online exits with code 124 (matching /usr/bin/timeout).
Once the daemon reaches the online state, it stops tracking subsequent network changes and does not re-check whether the conditions are still met.

Valid Conditions

Condition	Description
`saved-config-applied`	All saved configs applied (excl. conditional act.)
`gateway`	IPv4 or IPv6 gateway added
`gateway4`	IPv4 gateway added
`gateway6`	IPv6 gateway added

Vlan

Vlan

Example YAML of VLAN interface configuration:

version: 1
interfaces:
- name: eth1.101
  type: vlan
  state: up
  vlan:
    base-iface: eth1
    id: 101
    protocol: 802.1q
    registration-protocol: none
    reorder-headers: true
    loose-binding: false
    bridge-binding: false
    ingress-qos-map:
    - from: 3
      to: 1
    egress-qos-map:
    - from: 1
      to: 3

`base-iface` – Base interface

The physical or parent interface name on which the VLAN is created, e.g. eth1.

Mandatory when creating a new VLAN interface. When applying changes to an existing VLAN, leaving this unset preserves the current base interface.

`id` – VLAN ID

The VLAN identifier. Valid range is 0 to 4094.

Mandatory when creating a new VLAN interface. When applying changes to an existing VLAN, leaving this unset preserves the current ID.

`protocol` – VLAN protocol

The VLAN encapsulation protocol:

802.1q: Standard IEEE 802.1Q VLAN tagging (default).
802.1ad: Provider Bridging (Q-in-Q) IEEE 802.1ad.

Defaults to 802.1q if not defined.

`registration-protocol` – VLAN registration protocol

The registration protocol used for VLAN pruning:

gvrp: GARP VLAN Registration Protocol.
mvrp: Multiple VLAN Registration Protocol.
none: No registration protocol (default).

`reorder-headers` – Reorder output packet headers

When set to true, the VLAN device will reorder the output packet headers to move the VLAN tag before any hardware-specific headers. Defaults to true.

`loose-binding` – Loose binding

When set to true, the VLAN device operates in loose binding mode, where the VLAN device state is not strictly tied to the master device’s operating state.

`bridge-binding` – Bridge binding

When set to true, the VLAN device link state tracks the state of bridge ports that are members of the VLAN.

`ingress-qos-map` – Ingress QoS mapping

Maps VLAN header PCP (Priority Code Point) values to Linux internal packet priority for incoming packets. Each entry maps from (VLAN PCP value) to to (Linux priority).

The maximum priority value is 7 according to 802.1Q-2018 PCP field definition.

`egress-qos-map` – Egress QoS mapping

Maps Linux internal packet priority to VLAN header PCP values for outgoing packets. Each entry maps from (Linux priority) to to (VLAN PCP value).

The maximum priority value is 7 according to 802.1Q-2018 PCP field definition.

Bond

Bond

Example YAML of bond interface configuration:

version: 1
interfaces:
- name: bond0
  type: bond
  state: up
  bond:
    mode: 802.3ad
    options:
      miimon: 100
      updelay: 0
      downdelay: 0
      use_carrier: true
      lacp_rate: slow
      lacp_active: true
      xmit_hash_policy: layer3+4
      ad_select: stable
      ad_actor_sys_prio: 65535
      ad_user_port_key: 0
      min_links: 0
      lp_interval: 1
      packets_per_slave: 1
      resend_igmp: 1
      all_slaves_active: dropped
      arp_interval: 0
      arp_ip_target: 192.0.2.1,192.0.2.2
      arp_all_targets: any
      arp_validate: none
      arp_missed_max: 3
      fail_over_mac: none
      primary: eth1
      primary_reselect: always
      num_grat_arp: 1
      num_unsol_na: 1
      peer_notif_delay: 0
      tlb_dynamic_lb: true
      ns_ip6_target:
      - "2001:db8::1"
    ports:
    - name: eth1
      priority: 0
      queue-id: 0
    - name: eth2
      priority: 0
      queue-id: 0

`mode` – Bond mode

The bonding mode. Mandatory when creating a new bond interface. Supports numeric aliases for deserialization:

balance-rr (0): Round-robin – transmit packets in sequential order.
active-backup (1): Active-backup – one port is active, standby takes over on failure.
balance-xor (2): XOR – transmit based on XOR of MAC addresses.
broadcast (3): Broadcast – transmits all packets on all ports.
802.3ad (4, alias lacp): IEEE 802.3ad dynamic link aggregation.
balance-tlb (5): Adaptive transmit load balancing.
balance-alb (6): Adaptive load balancing (TLB + receive load balancing).

`options` – Bond options

Kernel bond options. Please refer to kernel documentation for details.

`miimon` – MII link monitoring interval

Interval in milliseconds for MII link monitoring. Default is 0 (disabled). Cannot be used together with arp_interval.

`updelay` – Up delay

Delay in milliseconds before enabling a port after link up detection. Default is 0.

`downdelay` – Down delay

Delay in milliseconds before disabling a port after link loss detection. Default is 0.

`use_carrier` – Use carrier

Whether to use MII/ETHTOOL ioctl or netif_carrier_ok() for link detection. Default is true.

`arp_interval` – ARP monitoring interval

Interval in milliseconds for ARP monitoring. Default is 0 (disabled). Cannot be used together with miimon. Invalid for 802.3ad, balance-tlb, and balance-alb modes.

`arp_ip_target` – ARP target IPs

Comma-separated IPv4 addresses used as ARP monitoring targets. Only valid when arp_interval is greater than 0.

`arp_all_targets` – ARP all targets

Specifies how many arp_ip_target must be reachable for a port to be considered up:

any (0): Any single target is reachable.
all (1): All targets must be reachable.

Only affects active-backup mode with arp_validate enabled.

`arp_validate` – ARP validation

Specifies ARP probe and reply validation for link monitoring:

none (0): No validation.
active (1): Validate only on the active port.
backup (2): Validate only on backup ports.
all (3): Validate on all ports.
filter (4): Filter non-ARP traffic on all ports.
filter_active (5): Filter on all ports, validate on active port.
filter_backup (6): Filter on all ports, validate on backup ports.

`arp_missed_max` – ARP missed max

Maximum number of ARP monitoring misses before considering a link down.

`fail_over_mac` – Fail over MAC

Specifies MAC address handling in active-backup mode:

none (0): All ports share the same MAC address.
active (1): Bond MAC follows the active port’s MAC.
follow (2): Ports are programmed with bond MAC only on failover.

When fail_over_mac is set to active with active-backup mode, the desired MAC address is ignored as it is determined by the active port.

`primary` – Primary port

The port name to use as the primary port (preferred active port) in active-backup, balance-tlb, and balance-alb modes.

`primary_reselect` – Primary reselect policy

Specifies when the primary port becomes active again:

always (0): Primary becomes active whenever it comes back up.
better (1): Only if primary has better speed/duplex than current active.
failure (2): Only if current active port fails.

`lacp_rate` – LACP rate

LACP PDU rate in 802.3ad mode:

slow (0): Transmit LACPDUs every 30 seconds.
fast (1): Transmit LACPDUs every 1 second.

Only valid in 802.3ad mode.

`lacp_active` – LACP active

When set to true, LACPDUs are transmitted regardless of the partner state. When false, LACPDUs are only transmitted in response to received LACPDUs. Only valid in 802.3ad mode.

`xmit_hash_policy` – Transmit hash policy

Transmit hash policy for balance-xor, 802.3ad, and balance-tlb modes:

layer2 (0): Hash based on MAC addresses.
layer3+4 (1): Hash based on IP and port.
layer2+3 (2): Hash based on MAC and IP.
encap2+3 (3): Encapsulated layer 2+3 for tunnel interfaces.
encap3+4 (4): Encapsulated layer 3+4 for tunnel interfaces.
vlan+srcmac (5): Hash based on VLAN tag and source MAC.

`ad_select` – 802.3ad aggregation selection

Aggregation selection logic for 802.3ad mode:

stable (0): Use the stable aggregator.
bandwidth (1): Select aggregator with highest bandwidth.
count (2): Select aggregator with most ports.

`ad_actor_sys_prio` – Actor system priority

The 802.3ad actor system priority. Used in LACP negotiation.

`ad_actor_system` – Actor system MAC

The 802.3ad actor system MAC address. Cannot be a multicast address (prefix 01:00:5E).

`ad_user_port_key` – User port key

The 802.3ad user-defined port key.

`all_slaves_active` – All slaves active

Also deserializable as all_ports_active. Specifies handling of duplicate frames on inactive ports:

dropped (0): Drop duplicate frames.
delivered (1): Deliver duplicate frames.

`min_links` – Minimum links

Minimum number of ports that must be active before the bond is considered up.

`lp_interval` – LACP PDU interval

The number of seconds between LACP PDU transmissions.

`packets_per_slave` – Packets per slave

Also deserializable as packets_per_port. Number of packets to transmit on a port before switching to the next in balance-rr mode.

`resend_igmp` – Resend IGMP

Number of IGMP membership reports to be sent after a failover.

`num_grat_arp` – Gratuitous ARP count

Number of gratuitous ARP packets to send after a failover. Must be equal to num_unsol_na if both are defined.

`num_unsol_na` – Unsolicited NA count

Number of unsolicited IPv6 Neighbor Advertisements to send after a failover. Same meaning in kernel as num_grat_arp.

`peer_notif_delay` – Peer notification delay

Delay in milliseconds between gratuitous ARP/NA notifications after a failover.

`tlb_dynamic_lb` – TLB dynamic load balancing

Enables dynamic load balancing in balance-tlb mode. When true, the bond rebalances traffic periodically.

`ns_ip6_target` – IPv6 neighbor solicitation targets

List of IPv6 addresses used as neighbor solicitation targets for IPv6 link monitoring. Only valid when arp_interval is greater than 0.

`ports` – Bond ports

List of port configurations for the bond. When applying, if defined, it will override the current port list.

Each port entry supports:

`name` – Port name

The interface name of the bond port. Mandatory.

`priority` – Port priority

Port priority for failover. Only valid in active-backup, balance-tlb, and balance-alb modes.

`queue-id` – Port queue ID

The queue ID assigned to this port. Multiple ports sharing the same queue ID is not supported by the Linux kernel.

Linux Bridge

Linux Bridge

Example YAML of Linux bridge interface configuration:

version: 1
interfaces:
- name: br0
  type: linux-bridge
  state: up
  bridge:
    options:
      group-addr: 01:80:C2:00:00:00
      group-fwd-mask: 0
      hash-max: 4096
      mac-ageing-time: 300
      multicast-last-member-count: 2
      multicast-last-member-interval: 100
      multicast-membership-interval: 26000
      multicast-querier: false
      multicast-querier-interval: 25500
      multicast-query-interval: 12500
      multicast-query-response-interval: 1000
      multicast-query-use-ifaddr: false
      multicast-router: auto
      multicast-snooping: true
      multicast-startup-query-count: 2
      multicast-startup-query-interval: 3125
      stp:
        enabled: true
        forward-delay: 15
        hello-time: 2
        max-age: 20
        priority: 32768
      vlan-protocol: 802.1q
      vlan-default-pvid: 1
    ports:
    - name: eth1
      stp-hairpin-mode: false
      stp-path-cost: 100
      stp-priority: 32
    - name: eth2
      stp-hairpin-mode: false
      stp-path-cost: 100
      stp-priority: 32

`options` – Bridge options

Linux bridge kernel options. When applying, existing options are merged into desired.

`group-addr` – Multicast group address

The multicast MAC address used by the bridge. Default is 01:80:C2:00:00:00.

`group-fwd-mask` – Group forward mask

Also configurable as group-forward-mask (deprecated alias). Defines the mask for forwarding link-local frames. Setting a bit enables forwarding of frames with the corresponding destination MAC address.

`hash-max` – Hash table maximum

The maximum size of the multicast hash table.

`mac-ageing-time` – MAC ageing time

The MAC address ageing time in seconds. Controls how long a learned MAC address is kept in the forwarding database without being refreshed.

`multicast-last-member-count` – Last member query count

The number of queries sent after receiving a leave message.

`multicast-last-member-interval` – Last member query interval

The interval in milliseconds between last member query transmissions.

`multicast-membership-interval` – Membership interval

The interval in milliseconds after which a multicast membership expires.

`multicast-querier` – Multicast querier

When set to true, the bridge can act as a multicast querier.

`multicast-querier-interval` – Querier interval

The interval in milliseconds between querier transmissions.

`multicast-query-interval` – Query interval

The interval in milliseconds between general multicast queries.

`multicast-query-response-interval` – Query response interval

The maximum response time in milliseconds for multicast queries.

`multicast-query-use-ifaddr` – Query use interface address

When set to true, the bridge uses its own IP address as the source of multicast queries.

`multicast-router` – Multicast router type

The multicast router type:

auto (1): The bridge automatically detects multicast routers.
disabled (0): Multicast router functionality is disabled.
enabled (2): The bridge acts as a multicast router.

`multicast-snooping` – Multicast snooping

When set to true, the bridge performs IGMP/MLD snooping to reduce multicast traffic.

`multicast-startup-query-count` – Startup query count

The number of queries sent when the bridge starts.

`multicast-startup-query-interval` – Startup query interval

The interval in milliseconds between startup queries.

`stp` – Spanning Tree Protocol

STP options for the bridge.

`enabled` – STP enabled

Enables or disables Spanning Tree Protocol on the bridge. When disabled, the remaining STP options are discarded during apply.

`forward-delay` – Forward delay

The forwarding delay in seconds. Valid range is 2 to 30.

`hello-time` – Hello time

The interval in seconds between STP hello BPDU transmissions. Valid range is 1 to 10.

`max-age` – Maximum age

The maximum age of STP information in seconds. Valid range is 6 to 40.

`priority` – Bridge priority

The STP bridge priority. Lower priority increases the chance of becoming the root bridge.

`vlan-protocol` – VLAN protocol

The VLAN encapsulation protocol used by the bridge:

802.1q: Standard IEEE 802.1Q VLAN tagging (default).
802.1ad: Provider Bridging (Q-in-Q) IEEE 802.1ad.

`vlan-default-pvid` – Default PVID

The default Port VLAN ID (PVID) assigned to ports. Default is 1. Cannot be changed to a value other than 1 unless VLAN filtering is enabled.

`ports` – Bridge ports

List of bridge port configurations. When applying, the desired port list will override the current port list.

`name` – Port name

The kernel interface name of the bridge port. Mandatory.

`stp-hairpin-mode` – Hairpin mode

When set to true, traffic may be sent back out of the port on which it was received.

`stp-path-cost` – STP path cost

The STP path cost of the port. Used in root port and designated port selection.

`stp-priority` – STP priority

The STP port priority. An unsigned 8-bit value (0 to 255). Lower priority increases the chance of becoming the designated port.

`vlan` – Port VLAN filtering

VLAN filtering configuration specific to this port. If not defined, the current VLAN filtering is preserved for the port.

`vlan` – Bridge VLAN filtering

The VLAN filtering configuration for the bridge itself. Setting to vlan: {} will remove all VLANs.

`mode` – VLAN mode

The bridge VLAN filtering mode:

access: Single untagged VLAN (access port).
trunk: Tagged VLANs (trunk port).

Defaults to access if not defined.

`tag` – Native VLAN tag

The VLAN tag for the native VLAN. In access mode, this is the access VLAN. In trunk mode, requires enable-native to be true.

`enable-native` – Enable native VLAN

When set to true, the tag VLAN is treated as the native untagged VLAN on a trunk port. Cannot be set in access mode.

`trunk-tags` – Trunk tags

List of allowed VLANs on a trunk port. Each entry is either a single VLAN ID or a range:

trunk-tags:
- id: 100
- id-range:
    min: 200
    max: 300

Overlapping trunk tags are not allowed.

OpenvSwitch Bridge

OpenvSwitch Bridge

Example YAML of OVS bridge configuration:

version: 1
interfaces:
- name: br0
  type: ovs-bridge
  state: up
  bridge:
    ports:
    - name: eth1
    - name: eth2
- name: br0
  type: ovs-interface
  state: up
  controller: br0
  ipv4:
    enabled: false
  ipv6:
    enabled: false
- name: eth1
  type: ovs-interface
  state: up
  controller: br0
- name: eth2
  type: ovs-interface
  state: up
  controller: br0

OVS bridge consists of three parts: the ovs-bridge interface itself, one ovs-interface for the bridge internal interface, and ovs-interface entries for each port.

`bridge`

The OVS bridge configuration.

`ports` – Bridge ports

List of port names attached to the bridge. Each port entry contains:

`name` – Port name

The interface name of the port attached to this OVS bridge. The corresponding interface should be defined with type: ovs-interface and controller: <bridge-name>.

Port interfaces

Ports are defined as separate interfaces with type: ovs-interface and controller set to the OVS bridge name. They inherit all base interface properties including IP configuration.

OVS internal interface

The bridge itself typically has one ovs-interface with the same name as the bridge, serving as the bridge’s internal interface with IP configuration.

Limitations

OVS Bond is not supported yet.
OVS patch and dpdk interface types are not supported yet.

Wireguard

Wireguard

Example YAML of WireGuard interface configuration:

version: 1
interfaces:
- name: wg0
  type: wireguard
  state: up
  wireguard:
    private-key: xH4dTz3dN3LzP2gE2kR8pA7sV9cF0bN1mQ5wY6uJ8k=
    listen-port: 51820
    fwmark: 0
    peers:
    - endpoint: 192.0.2.1:51820
      public-key: r3V5cF0bN1mQ5wY6uJ8k=xH4dTz3dN3LzP2gE2kR8pA7sV9=
      preshared-key: p7sV9cF0bN1mQ5wY6uJ8k=xH4dTz3dN3LzP2gE2kR8pA=
      persistent-keepalive: 25
      allowed-ips:
      - ip: 10.0.0.0
        prefix-length: 24
      - ip: 192.168.0.0
        prefix-length: 16

ip: The IP address.
prefix-length: The prefix length (CIDR mask).

Keyboard shortcuts

Nipart Document