go-network-configurator/README.md

go-network-configurator

A Go library for inspecting and changing a host's IP addresses and static routes at runtime and persisting those changes to whatever on-disk network configuration backend the system actually uses — so the change survives a reboot.

It is designed for hosting environments where an automated system needs to add, swap, or remove IPs on a server without knowing in advance whether that server is running netplan, systemd-networkd, NetworkManager, RHEL network-scripts, ifupdown, or cloud-init — and without leaving a control panel (cPanel, Plesk, InterWorx) out of sync.

import "github.com/grmrgecko/go-network-configurator"

How it works

A single Configurator applies every change in two layers:

1. Runtime — the live kernel state is changed immediately (via netlink on Linux, the IP Helper API on Windows). Address and gateway changes are verified against an internet-reachability test and rolled back automatically if connectivity is lost.
2. Persistence — the same change is written to every detected configuration backend so it survives a reboot, and registered control panels are told to re-read the system's IPs.

Backends are auto-detected at construction time. A host running both netplan and cloud-init, for example, has both files kept in sync; a failure writing one backend is logged but does not abort the others.

Supported backends

Network configuration (persistence)

Backend	Detection
netplan	netplan binary on PATH
cloud-init	cloud-init network config present
NetworkManager	NetworkManager.service active
systemd-networkd	systemd-networkd.service active
RHEL network-scripts	network.service active (config dir on legacy hosts)
ifupdown	/etc/network/interfaces

Control panels

Panel	Detection
cPanel	/usr/local/cpanel/bin/whmapi1
Plesk	/usr/sbin/plesk
InterWorx	/usr/bin/nodeworx

Detection of the service-managed backends (NetworkManager, systemd-networkd, and RHEL network-scripts) uses systemd over D-Bus, with a fallback for legacy systems that lack a usable systemd D-Bus interface (Ubuntu 14.04 Upstart, CentOS 5/6). On that fallback path network-scripts is detected by the presence of its /etc/sysconfig/network-scripts directory.

Platforms

• Linux — full support (all backends and panels above).
• Windows — runtime changes via the IP Helper API, persisted to cloud-init, with Plesk panel support.

API

type Configurator interface {
    // Enumerate interfaces with their addresses, gateways, static routes,
    // DNS servers, and search domains.
    GetInterfaces(ctx context.Context) ([]*Interface, error)

    // Add an IP address (optionally setting/replacing the default gateway).
    AddAddress(ctx context.Context, iface string, addr *net.IPNet, gateway net.IP) error

    // Promote an address already on the interface to be the primary of its family.
    SetPrimaryAddress(ctx context.Context, iface string, addr *net.IPNet) error

    // Remove an IP address.
    RemoveAddress(ctx context.Context, iface string, addr *net.IPNet) error

    // Add or remove a static route.
    AddRoute(ctx context.Context, iface string, dst *net.IPNet, gateway net.IP, metric int) error
    RemoveRoute(ctx context.Context, iface string, dst *net.IPNet, gateway net.IP) error

    // Set the DNS servers and search domains for an interface.
    SetDNS(ctx context.Context, iface string, servers []net.IP, searchDomains []string) error
}

// Construct the configurator for the current OS, auto-detecting backends.
// Behaviour is tuned with Option values (see Options below).
func NewConfigurator(opts ...Option) (Configurator, error)

// Resolve an interface by name, or by the special "public-internet" /
// "public-internet-6" selectors.
func FindInterfaceByName(name string, ifaces []*Interface) *Interface

Every operation takes a context.Context. The slow steps — the ICMP probe of a new gateway and the internet-reachability test — honour cancellation and deadlines, so a caller can bound how long a change may block.

DNS

SetDNS applies an interface's resolvers and search domains to the live resolver so they take effect immediately, and persists them through whichever network management backends are detected on the host so they survive a reboot.

Logging

The package uses a single, package-wide logger for non-fatal diagnostics from backends and control panels. It defaults to the logrus standard logger. Replace it with SetLogger before constructing any Configurator:

netconfig.SetLogger(myLogger) // anything with Printf/Println, e.g. *log.Logger

Options

NewConfigurator accepts functional options:

c, err := netconfig.NewConfigurator(
    netconfig.WithTestAddress("http://my-canary/health"), // connectivity-test URL
    netconfig.WithConnectivityCheck(false),                // skip the post-change probe + rollback
    netconfig.WithSkipConnectivityCheck(),                 // same as WithConnectivityCheck(false)
    netconfig.WithConnectivityTimeout(5 * time.Second),    // HTTP reachability timeout
    netconfig.WithPingCount(3),                            // ICMP probes per ping test
    netconfig.WithPingTimeout(10 * time.Second),           // overall ping-run timeout
    netconfig.WithBackupRetention(10),                     // .bak.* copies kept per config file (0 = keep all)
    netconfig.WithAllowPrimaryRemoval(true),               // let RemoveAddress remove the primary IP
    netconfig.WithSkipPanels(true),                        // skip all panel interaction (add/primary/remove)
)

WithConnectivityCheck(false) (or the convenience WithSkipConnectivityCheck()) is useful on hosts with no outbound internet access, where the default reachability test would always fail and roll changes back. WithConnectivityTimeout, WithPingCount, and WithPingTimeout tune the probes used after gateway changes. WithBackupRetention limits how many .bak.<timestamp> copies each backend keeps per original config file; the oldest backups beyond this number are pruned on every save.

WithAllowPrimaryRemoval(true) overrides the default refusal to remove an address that is the primary of its family. The intended safe flow is to call SetPrimaryAddress on another address first and then remove the old one; enable the override only when you are deliberately tearing down the current primary.

WithSkipPanels(true) skips all control-panel interaction: AddAddress, SetPrimaryAddress, and RemoveAddress do not tell cPanel, Plesk, or InterWorx to reload, set the main IP, or release an IP. Only the running system and the network-manager configuration files are changed.

FindInterfaceByName accepts two well-known selectors in addition to a literal interface name:

• "public-internet" — the interface that carries the IPv4 default gateway.
• "public-internet-6" — the interface that carries the IPv6 default gateway.

Usage

package main

import (
    "context"
    "log"
    "net"

    netconfig "github.com/grmrgecko/go-network-configurator"
)

func main() {
    ctx := context.Background()

    c, err := netconfig.NewConfigurator()
    if err != nil {
        log.Fatal(err)
    }

    ifaces, err := c.GetInterfaces(ctx)
    if err != nil {
        log.Fatal(err)
    }
    iface := netconfig.FindInterfaceByName(netconfig.Public, ifaces)
    if iface == nil {
        log.Fatal("no public interface found")
    }

    // Swap the primary IP without dropping connectivity:
    // add a new address, switch the system over to it, then remove the old one.
    _, newIP, _ := net.ParseCIDR("203.0.113.20/24")
    _, oldIP, _ := net.ParseCIDR("203.0.113.10/24")

    if err := c.AddAddress(ctx, iface.Name, newIP, nil); err != nil {
        log.Fatal(err)
    }
    if err := c.SetPrimaryAddress(ctx, iface.Name, newIP); err != nil {
        log.Fatal(err)
    }
    if err := c.RemoveAddress(ctx, iface.Name, oldIP); err != nil {
        log.Fatal(err)
    }
}

The primary address is the first address listed on an interface. SetPrimaryAddress reorders an interface's addresses so the chosen IP is first within its family, both in the running kernel and in the written configuration. The address must already be present on the interface (compose it with AddAddress); IPv4 and IPv6 each have their own primary.

Safety

Operations that can break connectivity are guarded:

• Adding an IP that already answers ping is refused.
• After an address/gateway change, an internet-reachability test runs; if it fails, the previous runtime state (addresses and default route) is restored and the operation returns an error.
• Removing an address that is the only route to the default gateway is refused.
• Removing the primary address of its family is refused by default (use WithAllowPrimaryRemoval(true) to override). The safe flow is to promote another address with SetPrimaryAddress first, then remove the old one.

Most operations require elevated privileges (root on Linux, Administrator on Windows) to modify network state.

Development

go test ./...

Some tests exercise real kernel networking inside a throwaway network namespace and are skipped unless run as root:

sudo go test ./...