hostsfile

README

Go package for working with a system's hostsfile

Reads the content of a file in the hosts format into go structs for easy manipulation in go programs. When all changes are complete you can Flush the hosts file back to disk to save your changes. Supports an indexing system on both ips and hosts for quick management of large hosts files.

Simple Usage

Simple usage reading in your system's hosts file and adding an entry for the ip 192.168.1.1 and the host my-hostname

package main

import (
	"log"
	
	"github.com/goodhosts/hostsfile"
)

func main() {
    hosts, err := hostsfile.NewHosts()
    if err != nil {
        log.Fatal(err.Error())
    }
    if err := hosts.Add("192.168.1.1", "my-hostname"); err != nil {
        log.Fatal(err.Error())
    }
    if err := hosts.Flush(); err != nil {
        log.Fatal(err.Error())
    }
}

Other Usage

Read in a hosts file from a custom location which is not the system default, this is useful for tests or systems with non-standard hosts file locations.

hosts, err := hostsfile.NewCustomHosts("./my-custom-hostsfile")

Use Add to put an ip and host combination in the hosts file

err := hosts.Add("192.168.1.1", "my-hostname")

Add is variadic and can take multiple hosts to add for the same ip

err := hosts.Add("192.168.1.1", "my-hostname", "another-hostname")

Use Remove to drop an ip and host combination from the hosts file

err := hosts.Remove("192.168.1.1", "my-hostname")

Remove is variadic and can take multiple hosts to remove from the same ip

err := hosts.Remove("192.168.1.1", "my-hostname", "another-hostname")

Flush the hosts file changes back to disk

err := hosts.Flush()

Documentation

Index

• Variables
• type Hosts
  • func NewCustomHosts(osHostsFilePath string) (*Hosts, error)
  • func NewHosts() (*Hosts, error)
  • func (h *Hosts) Add(ip string, hosts ...string) error
  • func (h *Hosts) AddRaw(raw ...string) error
  • func (h *Hosts) Clean()
  • func (h *Hosts) Clear()
  • func (h *Hosts) CombineDuplicateIPs()
  • func (h *Hosts) Flush() error
  • func (h *Hosts) Has(ip string, host string) bool
  • func (h *Hosts) HasHostname(host string) bool
  • func (h *Hosts) HasIP(ip string) bool
  • func (h *Hosts) HasIp(ip string) bool
  • func (h *Hosts) HostsPerLine(count int)
  • func (h *Hosts) IsWritable() bool
  • func (h *Hosts) Load() error
  • func (h *Hosts) Remove(ip string, hosts ...string) error
  • func (h *Hosts) RemoveByHostname(host string) error
  • func (h *Hosts) RemoveByIP(ip string)
  • func (h *Hosts) RemoveByIp(ip string) error
  • func (h *Hosts) RemoveDuplicateHosts()
  • func (h *Hosts) RemoveDuplicateIps()
  • func (h *Hosts) SortByIp()
  • func (h *Hosts) SortHosts()
  • func (h *Hosts) SortIPs()
  • func (h *Hosts) String() string
• type HostsLine
  • func NewHostsLine(raw string) HostsLine
  • func (l *HostsLine) Combine(hostline HostsLine)
  • func (l *HostsLine) HasComment() bool
  • func (l *HostsLine) IsComment() bool
  • func (l *HostsLine) IsMalformed() bool
  • func (l *HostsLine) IsValid() bool
  • func (l *HostsLine) RegenRaw()
  • func (l *HostsLine) RemoveDuplicateHosts()
  • func (l *HostsLine) SortHosts()
  • func (l *HostsLine) String() string
  • func (l *HostsLine) ToRaw() string

Variables

var (
	HostsPerLine  = -1 // unlimited
	HostsFilePath = "/etc/hosts"
)

Types

type Hosts

type Hosts struct {
	Path  string      // Path to the location of the hosts file that will be loaded/flushed
	Lines []HostsLine // Slice containing all the lines parsed from the hosts file
	// contains filtered or unexported fields
}

Hosts represents hosts file with the path and parsed contents of each line

func NewCustomHosts

func NewCustomHosts(osHostsFilePath string) (*Hosts, error)

NewCustomHosts return a new instance of Hosts using a custom hosts file path.

func NewHosts

func NewHosts() (*Hosts, error)

NewHosts return a new instance of Hosts using the default hosts file path.

func (*Hosts) Add

func (h *Hosts) Add(ip string, hosts ...string) error

Add an entry to the hosts file.

func (*Hosts) AddRaw

func (h *Hosts) AddRaw(raw ...string) error

AddRaw takes a line from a hosts file and parses/adds the HostsLine

func (*Hosts) Clean

func (h *Hosts) Clean()

Clean merge duplicate ips and hosts per ip

func (*Hosts) Clear

func (h *Hosts) Clear()

func (*Hosts) CombineDuplicateIPs

func (h *Hosts) CombineDuplicateIPs()

CombineDuplicateIPs finds all duplicate ips and combines all their hosts into one line

func (*Hosts) Flush

func (h *Hosts) Flush() error

Flush writes to the file located at Path the contents of Lines in a hostsfile format

func (*Hosts) Has

func (h *Hosts) Has(ip string, host string) bool

Has return a bool if ip/host combo exists in the Lines

func (*Hosts) HasHostname

func (h *Hosts) HasHostname(host string) bool

HasHostname return a bool if hostname in hosts file.

func (*Hosts) HasIP

func (h *Hosts) HasIP(ip string) bool

HasIP will check if the ip exists

func (*Hosts) HasIp

func (h *Hosts) HasIp(ip string) bool

Deprecated: HasIp will be replaced by HasIP

func (*Hosts) HostsPerLine

func (h *Hosts) HostsPerLine(count int)

HostsPerLine checks all ips and if their host count is greater than count will split into multiple lines with max of count hosts per line

func (*Hosts) IsWritable

func (h *Hosts) IsWritable() bool

IsWritable return true if hosts file is writable.

func (*Hosts) Load

func (h *Hosts) Load() error

Load the hosts file from the Path into Lines, called by NewHosts() and Hosts.Flush() and you should not need to call this yourself.

func (*Hosts) Remove

func (h *Hosts) Remove(ip string, hosts ...string) error

Remove takes an ip and an optional host(s), if only an ip is passed the whole line is removed when the optional hosts param is passed it will remove only those specific hosts from that ip

func (*Hosts) RemoveByHostname

func (h *Hosts) RemoveByHostname(host string) error

RemoveByHostname go through all lines and remove a hostname if it exists

func (*Hosts) RemoveByIP

func (h *Hosts) RemoveByIP(ip string)

func (*Hosts) RemoveByIp

func (h *Hosts) RemoveByIp(ip string) error

Deprecated: RemoveByIp this got refactored and wont return an error any more leaving it for stable api purposes, will be removed in a major release

func (*Hosts) RemoveDuplicateHosts

func (h *Hosts) RemoveDuplicateHosts()

RemoveDuplicateHosts will check each line and remove hosts if they are the same

func (*Hosts) RemoveDuplicateIps

func (h *Hosts) RemoveDuplicateIps()

Deprecated: RemoveDuplicateIps deprecated will be deprecated, use Combine

func (*Hosts) SortByIp

func (h *Hosts) SortByIp()

Deprecated: SortByIp switch to SortByIP

func (*Hosts) SortHosts

func (h *Hosts) SortHosts()

SortHosts will go through each line and sort the hosts in alpha order

func (*Hosts) SortIPs

func (h *Hosts) SortIPs()

SortByIP convert to net.IP and byte.Compare, maintains all comment only lines at the top

func (*Hosts) String

func (h *Hosts) String() string

String get a string of the contents of the contents to put in the hosts file

type HostsLine

type HostsLine struct {
	IP      string   // IP found at the beginning of the line
	Hosts   []string // Hosts split into a slice on the space char
	Comment string   // Contents of everything after the comment char in the line

	Raw string // Raw contents of the line as parsed in or updated after changes
	Err error  // Used for error checking during parsing
}

HostsLine represents a line of the hosts file after being parsed into their respective parts

func NewHostsLine

func NewHostsLine(raw string) HostsLine

NewHostsLine takes a raw line as a string and parses it into a new instance of HostsLine e.g. "192.168.1.1 host1 host2 # comments"

func (*HostsLine) Combine

func (l *HostsLine) Combine(hostline HostsLine)

Deprecated: will be made internal, combines the hosts and comments of two lines together,

func (*HostsLine) HasComment

func (l *HostsLine) HasComment() bool

func (*HostsLine) IsComment

func (l *HostsLine) IsComment() bool

func (*HostsLine) IsMalformed

func (l *HostsLine) IsMalformed() bool

func (*HostsLine) IsValid

func (l *HostsLine) IsValid() bool

func (*HostsLine) RegenRaw

func (l *HostsLine) RegenRaw()

func (*HostsLine) RemoveDuplicateHosts

func (l *HostsLine) RemoveDuplicateHosts()

RemoveDuplicateHosts checks all hosts in a line and removes duplicates

func (*HostsLine) SortHosts

func (l *HostsLine) SortHosts()

func (*HostsLine) String

func (l *HostsLine) String() string

String to make HostsLine a fmt.Stringer

func (*HostsLine) ToRaw

func (l *HostsLine) ToRaw() string

ToRaw returns the HostsLine's contents as a raw string