244 lines
9.7 KiB
Markdown
244 lines
9.7 KiB
Markdown
# go-network-configurator
|
|
|
|
[](https://pkg.go.dev/github.com/grmrgecko/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.
|
|
|
|
```go
|
|
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
|
|
|
|
```go
|
|
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`:
|
|
|
|
```go
|
|
netconfig.SetLogger(myLogger) // anything with Printf/Println, e.g. *log.Logger
|
|
```
|
|
|
|
### Options
|
|
|
|
`NewConfigurator` accepts functional options:
|
|
|
|
```go
|
|
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
|
|
|
|
```go
|
|
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
|
|
|
|
```sh
|
|
go test ./...
|
|
```
|
|
|
|
Some tests exercise real kernel networking inside a throwaway network namespace
|
|
and are skipped unless run as root:
|
|
|
|
```sh
|
|
sudo go test ./...
|
|
```
|