netdb

README

netdb

netdb provides information about TCP/IP subsystem protocols and internet services, all this in (pure) Go. By default, it uses its built-in database instead of consulting /etc/protocols and /etc/services. If needed, it can also consult these files, please see the examples in the documentation.

The built-in database has been auto-generated from the etc/protocols and etc/services files courtesy of the netbase package of the Debian project.

This netdb package does not even try to slavishly replicate the POSIX C API; instead, it attempts to be Go-ish. For instance, the C type servent has simply become the netdb.Service type in order to avoid arcane POSIX-rooted type names.

Please refer to the reference documentation for usage examples.

Acknowledgement

In some sense, this netdb package picks up the baton from the @dominikh/go-netdb package. However, it is not a fork but was written from scratch, considering (at least some of) the advice in issue #1 of the go-netdb package.

Copyright and License

netdb is Copyright 2021-23 Harald Albrecht, and licensed under the Apache License, Version 2.0.

Documentation

Overview

Package netdb provides information about TCP/IP subsystem protocols and internet services, as commonly stored in files /etc/protocols and /etc/services. It is a pure Go implementation.

This netdb package does not even try to slavishly replicate the POSIX C API; instead, it attempts to be Go-ish. For instance, the C type "servent" has simply become the netdb.Service type in order to avoid the arcane POSIX-rooted type names.

The netdb package defaults to looking up protocols and services information from its built-in database instead of consulting /etc/protocols and /etc/services. Additionally, it also supports reading the protocol and service descriptions from the well-known /etc/protocols and /etc/services files; please see the examples for how to access these sources.

Notes

This package bases on the file format descriptions for protocols(5) and services(5), as documented in https://man7.org/linux/man-pages/man5/protocols.5.html and https://man7.org/linux/man-pages/man5/services.5.html.

The built-in database has been auto-generated from the etc/protocols and etc/services files courtesy of the netbase package of the Debian project (https://salsa.debian.org/md/netbase).

In some sense, this netdb package picks up the baton from the https://github.com/dominikh/go-netdb package. However, it is not a fork but was written from scratch, considering (at least some of) the advice in issue #1 of the go-netdb package.

Example (MergeEtc)

Where required, merges protocol and service descriptions from /etc/protocols and /etc/services with the built-in database, replacing builtin descriptions with those found in the files.

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	etcprotocols, _ := netdb.LoadProtocols("/etc/protocols")
	netdb.Protocols.MergeIndex(etcprotocols)
	etcservices, _ := netdb.LoadServices("/etc/services", netdb.Protocols)
	netdb.Services.MergeIndex(etcservices)
	dns := netdb.ServiceByName("domain", "udp")
	fmt.Printf("%s: %d via %s", dns.Name, dns.Port, dns.Protocol.Name)
}

Output:

domain: 53 via udp

Example (OnlyEtc)

Where required, uses protocol and service descriptions only from /etc/protocols and /etc/services, ignoring the builtin data completely.

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	etcprotocols, _ := netdb.LoadProtocols("/etc/protocols")
	netdb.Protocols = etcprotocols
	etcservices, _ := netdb.LoadServices("/etc/services", netdb.Protocols)
	netdb.Services = etcservices
	dns := netdb.ServiceByName("domain", "udp")
	fmt.Printf("%s: %d via %s", dns.Name, dns.Port, dns.Protocol.Name)
}

Output:

domain: 53 via udp

Example (ProtocolByName)

Look up a (TCP/IP subsystem) protocol by its name.

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	tcp := netdb.ProtocolByName("tcp")
	fmt.Println(tcp.Number)
}

Output:

6

Example (ProtocolByNumber)

Looks up a (TCP/IP subsystem) protocol by its (uint8) number.

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	udp := netdb.ProtocolByNumber(17)
	fmt.Println(udp.Name)
}

Output:

udp

Example (ServiceByName)

Look up a service by its name and protocol name.

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	dns := netdb.ServiceByName("domain", "udp")
	fmt.Println(dns.Port)
}

Output:

53

Example (ServiceByPort)

Look up a service by its port number and protocol name.

package main

import (
	"fmt"

	"github.com/thediveo/netdb"
)

func main() {
	dns := netdb.ServiceByPort(53, "udp")
	fmt.Println(dns.Name)
}

Output:

domain

Index

• Variables
• type Protocol
  • func ParseProtocols(r io.Reader) ([]Protocol, error)
  • func ProtocolByName(name string) *Protocol
  • func ProtocolByNumber(number uint8) *Protocol
• type ProtocolIndex
  • func LoadProtocols(name string) (ProtocolIndex, error)
  • func NewProtocolIndex(protos []Protocol) ProtocolIndex
  • func (i *ProtocolIndex) Merge(protos []Protocol)
  • func (i *ProtocolIndex) MergeIndex(pi ProtocolIndex)
• type Service
  • func ParseServices(r io.Reader, p ProtocolIndex) ([]Service, error)
  • func ServiceByName(name string, protocol string) *Service
  • func ServiceByPort(port int, protocol string) *Service
• type ServiceIndex
  • func LoadServices(name string, protos ProtocolIndex) (ServiceIndex, error)
  • func NewServiceIndex(services []Service) ServiceIndex
  • func (i *ServiceIndex) ByName(name string, protocol string) *Service
  • func (i *ServiceIndex) ByPort(port int, protocol string) *Service
  • func (i *ServiceIndex) Merge(services []Service)
  • func (i *ServiceIndex) MergeIndex(si ServiceIndex)
• type ServicePort
• type ServiceProtocol

Examples

• Package (MergeEtc)
• Package (OnlyEtc)
• Package (ProtocolByName)
• Package (ProtocolByNumber)
• Package (ServiceByName)
• Package (ServiceByPort)

Variables

var BuiltinProtocols []Protocol = builtinProtocols

var BuiltinServices []Service = builtinServices

Types

type Protocol

type Protocol struct {
	Name    string   // Official protocol name.
	Number  uint8    // Protocol number.
	Aliases []string // List of aliases.
}

Protocol describes a network communications protocol by its native name and official protocol number as appearing within IP headers, with optional alias names.

According to http://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml the Assigned Internet Protocol Numbers are 8 bit (unsigned) numbers.

On purpose, we don't stick with the stuttering POSIX C library names, but instead aim for more Go-like type names. After all, Go isn't similar to C, except for using letters, signs, and braces.

func ParseProtocols

func ParseProtocols(r io.Reader) ([]Protocol, error)

ParseProtocols parses Internet protocol definitions for the TCP/IP subsystem from the given Reader and returns them as a list of Protcol(s).

func ProtocolByName

func ProtocolByName(name string) *Protocol

ProtocolByName returns the Protocol details for the specified (alias) name, or nil if not defined.

func ProtocolByNumber

func ProtocolByNumber(number uint8) *Protocol

ProtocolByNumber returns the Protocol details for the specified protocol number, or nil if not defined.

type ProtocolIndex

type ProtocolIndex struct {
	Names   map[string]*Protocol // Index by protocol name, including aliases.
	Numbers map[uint8]*Protocol  // Index by protocol number.
}

ProtocolIndex indexes the known network communication protocols by either name (native as well as aliases) and by number.

var Protocols ProtocolIndex

Protocols is the index of protocol names and numbers. If left to the zero value then it will be automatically initialized with the builtin definitions upon first use of ProtocolByName or ProtocolByNumber.

func LoadProtocols

func LoadProtocols(name string) (ProtocolIndex, error)

LoadProtocols returns a ProtocolIndex object initialized from the definitions in the named file.

func NewProtocolIndex

func NewProtocolIndex(protos []Protocol) ProtocolIndex

NewProtocolIndex returns a ProtocolsIndex object initialized with the specified protocols.

func (*ProtocolIndex) Merge

func (i *ProtocolIndex) Merge(protos []Protocol)

Merge a list of Protocol descriptions into the current Protocols index, potentially overriding existing entries in the index in case of duplicates.

func (*ProtocolIndex) MergeIndex

func (i *ProtocolIndex) MergeIndex(pi ProtocolIndex)

MergeIndex merges another ProtocolIndex into the current index, potentially overriding existing entries in case of duplicates.

type Service

type Service struct {
	Name         string    // Official service name.
	Port         int       // Transport port number.
	ProtocolName string    // Name of protocol to use.
	Protocol     *Protocol // Protocol details, if known.
	Aliases      []string  // List of service name aliases.
}

Service describes a network service by its official service name, port number and network protocol, with optional service alias names.

On purpose, we don't stick with the stuttering POSIX C library names, but instead aim for more Go-like type names. After all, Go isn't similar to C, except for using letters, signs, and braces.

func ParseServices

func ParseServices(r io.Reader, p ProtocolIndex) ([]Service, error)

ParseServices parses network service definitions from the given Reader and returns them as a list of Service(s).

func ServiceByName

func ServiceByName(name string, protocol string) *Service

ServiceByName returns the Service details for the specified (alias) name and (optional) protocol name, or nil if not defined.

func ServiceByPort

func ServiceByPort(port int, protocol string) *Service

ServiceByPort returns the Service details for the specified port number and (optional) protocol name, or nil if not defined.

type ServiceIndex

type ServiceIndex struct {
	Names map[ServiceProtocol]*Service // Index by service name and protocol name.
	Ports map[ServicePort]*Service     // Index by port number.
}

ServiceIndex indexes the known network services by either (alias) name or by transport port number.

var Services ServiceIndex

Services is the index of service names and protocols. If left to the zero value then it will be automatically initialized with the builtin definitions upon first use of ServiceByName or ServiceByPort.

func LoadServices

func LoadServices(name string, protos ProtocolIndex) (ServiceIndex, error)

LoadServices returns a ServiceIndex object initialized from the definitions in the named file.

func NewServiceIndex

func NewServiceIndex(services []Service) ServiceIndex

NewServiceIndex returns a Services index object initialized with the specified services.

func (*ServiceIndex) ByName

func (i *ServiceIndex) ByName(name string, protocol string) *Service

ByName returns the named Service for the given protocol, or nil if not found. If the protocol is the zero value ("") then the "first" Service matching the name is returned, where "first" refers to the order in which the services were originally described in a list of services, such as /etc/services.

func (*ServiceIndex) ByPort

func (i *ServiceIndex) ByPort(port int, protocol string) *Service

ByPort returns the service for the given port and protocol, or nil if not found. If the protocol is the zero value ("") then the "first" Service matching the name is returned, where "first" refers to the order in which the services were originally described in a list of services, such as /etc/services.

func (*ServiceIndex) Merge

func (i *ServiceIndex) Merge(services []Service)

Merge a list of service descriptions into the current Services index, potentially overriding existing entries in the index in case of duplicates.

func (*ServiceIndex) MergeIndex

func (i *ServiceIndex) MergeIndex(si ServiceIndex)

MergeIndex merges another ServiceIndex into the current index, potentially overriding existing entries in case of duplicates.

type ServicePort

type ServicePort struct {
	Port     int    // Transport port number.
	Protocol string // Protocol name; might be zero.
}

ServicePort represents a Service index key.

type ServiceProtocol

type ServiceProtocol struct {
	Name     string // Service name.
	Protocol string // Protocol name; might be zero.
}

ServiceProtocol represents a Service index key.