linkforge

README

Linkforge

Linkforge is a Go library for configuring Linux network interfaces. It combines rtnetlink-based link/address/route management with native Go DHCPv4 and DHCPv6 clients — no external commands (ip, dhclient, etc.) are executed.

Features

• Interface lifecycle: SetUp / SetDown with per-interface locking
• Static configuration: IPv4/IPv6 addresses + optional default route
• DHCPv4: Full DORA exchange, lease renewal (T1/T2), rebind, re-acquisition
• DHCPv6: Rapid Commit (Solicit/Reply), IA_NA address management, T1 renewal
• IPv6 RA: Router Solicitation, managed default route, and RDNSS discovery
• Thread-safe: Concurrent operations on different interfaces
• Context-aware: All blocking operations respect context cancellation
• No external dependencies: Pure Go; no ip, dhclient, ifconfig, etc.

Requirements

• Linux kernel (rtnetlink, AF_PACKET)
• Go 1.22+
• Capabilities: CAP_NET_ADMIN (link/addr/route), CAP_NET_RAW (DHCP)

Installation

go get github.com/bclswl0827/linkforge

Quick Start

package main

import (
    "context"
    "log"
    "net"

    "github.com/bclswl0827/linkforge"
)

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

    client, err := linkforge.New()
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    // Bring interface up
    if err := client.SetUp("eth0"); err != nil {
        log.Fatal(err)
    }

    // Static IP
    lease, err := client.Configure(ctx, linkforge.Config{
        Interface: "eth0",
        Mode:      linkforge.ModeStatic,
        Static: linkforge.StaticConfig{
            Address: &net.IPNet{IP: net.ParseIP("192.0.2.10"), Mask: net.CIDRMask(24, 32)},
            Gateway: net.ParseIP("192.0.2.1"),
        },
    })
    // lease is nil for static mode
}

API Overview

Type	Purpose
Client	Main entry point; owns rtnetlink handle and DHCP sessions
Config	High-level configuration request (static or DHCP)
Mode	ModeStatic or ModeDHCP
AddressFamily	FamilyIPv4 or FamilyIPv6
StaticConfig	Static address + optional gateway/metric
DHCPConfig	DHCP/RA timeout, retries, metric, optional DNS file
Lease	Result of DHCP configuration (address, gateway, DNS, times)

DHCP Behavior

• DHCPv4: Request → Renew at T1 → Rebind at T2 → Request (broadcast) on expiry
• DHCPv6: RapidSolicit plus Router Solicitation → retry Solicit on renewal failure
• Leases are applied via AddrReplace and RouteReplace (idempotent)
• RA default routes and RDNSS entries are refreshed and removed according to their advertised lifetimes
• DHCP and RA DNS servers are always returned in Lease.DNS
• DHCPConfig.WriteDNS optionally writes them to DNSPath (default /etc/resolv.conf)
• A managed DNS file is replaced completely; its original content is restored when the last owning session stops
• The selected RA router is returned in the DHCPv6 lease's Gateway

Documentation

Index

• type AddressFamily
• type Client
  • func New() (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Configure(ctx context.Context, cfg Config) (*Lease, error)
  • func (c *Client) Netlink() *netlink.Handle
  • func (c *Client) SetDown(name string) error
  • func (c *Client) SetUp(name string) error
  • func (c *Client) StopDHCP(name string) error
• type Config
• type DHCPConfig
• type Lease
• type Mode
• type StaticConfig

Types

type AddressFamily

type AddressFamily uint8

AddressFamily selects the address family used by DHCP.

const (
	FamilyIPv4 AddressFamily = iota
	FamilyIPv6
)

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client owns a rtnetlink handle and any DHCP sessions started through it. A Client is safe for concurrent use.

func New

func New() (*Client, error)

New creates a client with a dedicated rtnetlink handle.

func (*Client) Close

func (c *Client) Close() error

Close stops DHCP sessions, removes resources owned by those sessions, and closes the rtnetlink handle. Close is idempotent.

func (*Client) Configure

func (c *Client) Configure(ctx context.Context, cfg Config) (*Lease, error)

Configure applies a static address or starts a managed DHCP session. Configure does not automatically bring the interface up; call SetUp first. Applying a new configuration stops an existing DHCP session for the same interface and removes resources installed by that session.

func (*Client) Netlink

func (c *Client) Netlink() *netlink.Handle

Netlink returns the underlying handle so callers retain access to the full vishvananda/netlink API. The handle is owned by Client and must not be closed separately.

func (*Client) SetDown

func (c *Client) SetDown(name string) error

SetDown stops a DHCP session, removes its configured address and route, then brings the interface administratively down.

func (*Client) SetUp

func (c *Client) SetUp(name string) error

SetUp brings an interface administratively up.

func (*Client) StopDHCP

func (c *Client) StopDHCP(name string) error

StopDHCP stops and cleans up the DHCP session for an interface. It does not change the administrative state of the link. The caller must ensure that no other network manager changes the same interface concurrently.

type Config

type Config struct {
	Interface string
	Mode      Mode
	Static    StaticConfig
	DHCP      DHCPConfig
}

Config is the high-level interface configuration request.

type DHCPConfig

type DHCPConfig struct {
	Family    AddressFamily
	Timeout   time.Duration
	Retries   int
	Metric    int
	RATimeout time.Duration
	WriteDNS  bool
	DNSPath   string
}

DHCPConfig controls the DHCP exchange and the default route installed from the lease. FamilyIPv4 is the default. For DHCPv6, the default route and additional DNS servers are learned from Router Advertisements. A zero Timeout or Retries uses dependency defaults. A zero RATimeout uses ten seconds. If WriteDNS is true, DNSPath is replaced with the DNS servers from DHCP and RA; an empty DNSPath defaults to /etc/resolv.conf.

type Lease

type Lease struct {
	Family        AddressFamily
	Address       *net.IPNet
	Gateway       net.IP
	DNS           []net.IP
	Server        net.IP
	LeaseTime     time.Duration
	RenewalTime   time.Duration
	RebindingTime time.Duration
}

Lease is the part of a DHCP lease needed by a network configuration consumer. DNS is always reported to the caller and is only written to a resolver file when DHCPConfig.WriteDNS is true. For DHCPv6, Gateway and DNS can include information learned from IPv6 Router Advertisements.

type Mode

type Mode uint8

Mode selects how an interface receives its IP configuration.

const (
	ModeStatic Mode = iota
	ModeDHCP
)

type StaticConfig

type StaticConfig struct {
	Address *net.IPNet
	Gateway net.IP
	Metric  int
	// FlushAddresses removes existing addresses of the same family before
	// installing Address, preserving IPv6 link-local addresses. Removal is
	// not rolled back if configuration fails.
	FlushAddresses bool
}

StaticConfig describes the address and optional default route to install. The interface should have one configuration owner. Existing addresses are preserved unless FlushAddresses is true. Routes are not explicitly flushed, but a matching default route may be replaced.