Go Library - txeh

txeh provides a Go library for programmatic /etc/hosts file management. It was originally built to support kubefwd for Kubernetes service forwarding.

Installation

go get github.com/txn2/txeh

Loading the Hosts File

System default

hosts, err := txeh.NewHostsDefault()
if err != nil {
    log.Fatal(err)
}

Custom paths

hosts, err := txeh.NewHosts(&txeh.HostsConfig{
    ReadFilePath:  "/custom/path/hosts",
    WriteFilePath: "/custom/path/hosts",
})

From a string (in-memory)

raw := "127.0.0.1 localhost\n::1 localhost\n"
hosts, err := txeh.NewHosts(&txeh.HostsConfig{
    RawText: &raw,
})

When RawText is set, Save() returns an error since there is no file path. Use RenderHostsFile() or SaveAs() instead.

Adding Hosts

// Single hostname
hosts.AddHost("127.0.0.1", "myapp.local")

// Multiple hostnames to one IP
hosts.AddHosts("127.0.0.1", []string{"app1", "app2", "app3"})

// With an inline comment
hosts.AddHostWithComment("127.0.0.1", "myapp", "dev environment")
hosts.AddHostsWithComment("127.0.0.1", []string{"svc1", "svc2"}, "kubefwd")

Removing Hosts

// By hostname
hosts.RemoveHost("myapp.local")
hosts.RemoveHosts([]string{"app1", "app2"})

// By IP address
hosts.RemoveAddress("127.0.0.1")
hosts.RemoveAddresses([]string{"10.0.0.1", "10.0.0.2"})

// By CIDR range
err := hosts.RemoveCIDRs([]string{"10.0.0.0/24"})

// By comment
hosts.RemoveByComment("dev environment")
hosts.RemoveByComments([]string{"old-env", "deprecated"})

Querying

// List hostnames at an IP
hostnames := hosts.ListHostsByIP("127.0.0.1")

// List IPs for a hostname (exact or partial match)
addresses := hosts.ListAddressesByHost("myapp", true)   // exact
addresses = hosts.ListAddressesByHost("myapp", false)    // contains

// List hostnames in a CIDR range
hostnames = hosts.ListHostsByCIDR("10.0.0.0/24")

// Lookup a specific hostname
found, ip, ipFamily := hosts.HostAddressLookup("myapp", txeh.IPFamilyV4)

// List by comment
entries := hosts.ListHostsByComment("kubefwd")

Saving and Rendering

// Save to the configured write path
err := hosts.Save()

// Save to a specific path
err = hosts.SaveAs("/tmp/hosts.test")

// Render without saving
output := hosts.RenderHostsFile()
fmt.Println(output)

CIDR Operations

txeh supports CIDR (Classless Inter-Domain Routing) notation for bulk operations on IP address ranges.

Removing by CIDR

Remove all host entries whose IP addresses fall within one or more CIDR ranges.

err := hosts.RemoveCIDRs([]string{"10.0.0.0/24", "172.16.0.0/12"})
if err != nil {
    log.Fatal(err)
}

Note RemoveCIDRs is the only removal method that returns an error, since CIDR parsing can fail with invalid input.

Listing by CIDR

hostnames := hosts.ListHostsByCIDR("10.0.0.0/24")
for _, hn := range hostnames {
    fmt.Println(hn)
}

Example: cleaning up development entries

// Remove stale entries from a previous deployment
cidrs := []string{"10.244.0.0/16", "10.96.0.0/12"}
if err := hosts.RemoveCIDRs(cidrs); err != nil {
    log.Fatal(err)
}
hosts.Save()

Inline Comments

txeh supports inline comments on host entries. Comments are useful for tracking which tool or purpose added specific entries.

Comments use the standard hosts file format: IP HOSTNAME [HOSTNAME...] # comment

Key behavior:

Comments are used for grouping: hosts with the same IP and same comment are placed on the same line.
Hosts added without a comment only match lines without a comment.
Hosts added with a comment only match lines with the same comment.
Comments are never modified on existing lines.
If no matching line exists, a new line is created.

Adding with comments

hosts.AddHostWithComment("127.0.0.1", "myapp", "local development")
hosts.AddHostsWithComment("127.0.0.1", []string{"svc1", "svc2"}, "my project")

Listing and removing by comment

// List by comment
entries := hosts.ListHostsByComment("local development")

// Remove by comment
hosts.RemoveByComment("local development")
hosts.RemoveByComments([]string{"old-env", "deprecated"})

Modifying comments

Comments are never modified on existing lines. To change a comment, remove and re-add:

hosts.RemoveByComment("old comment")
hosts.AddHostsWithComment("127.0.0.1", []string{"app1", "app2"}, "new comment")

Configuration

MaxHostsPerLine

Controls how many hostnames can appear on a single line.

Value	Behavior
`0`	Auto (9 on Windows, unlimited elsewhere)
`-1`	Unlimited
`>0`	Explicit limit

When the limit is reached, additional hostnames are placed on a new line with the same IP address.

hosts, err := txeh.NewHosts(&txeh.HostsConfig{
    MaxHostsPerLine: 5,
})

ReadFilePath and WriteFilePath

Override the default system hosts file location. If only ReadFilePath is set, WriteFilePath defaults to the same path.

hosts, err := txeh.NewHosts(&txeh.HostsConfig{
    ReadFilePath:  "/etc/hosts",
    WriteFilePath: "/tmp/hosts.modified",
})

Thread Safety

All public methods on Hosts acquire a mutex before reading or modifying the internal state. This makes txeh safe for concurrent use from multiple goroutines.