listener

README

go-listener

src.agwa.name/go-listener is a Go library for creating net.Listeners.

Typically, server software only supports listening on TCP ports. go-listener makes it easy to also listen on:

• TCP ports
• UNIX domain sockets
• Pre-opened file descriptors

Additionally, go-listener makes it easy to support:

• The PROXY protocol
• TLS (with several options for certificate management, including ACME)

Listeners are specified using a string syntax, which makes them easy to pass as command line arguments.

How To Use

import "src.agwa.name/go-listener"

netListener, err := listener.Open(listenerString)
if err != nil {
	// Handle err
}
defer netListener.Close()

listener.Open takes a string which describes a listener per the syntax described below, and returns a net.Listener, which you can use by calling Accept, passing to http.Serve, etc.

Listener Syntax

TCP

Listen on all interfaces:

tcp:PORT

Listen on a specific IPv4 interface:

tcp:IPV4ADDRESS:PORT

Listen on a specific IPv6 interface:

tcp:[IPV6ADDRESS]:PORT

Listen on all IPv4 interfaces:

tcp:0.0.0.0:PORT

Listen on all IPv6 interfaces:

tcp:[::]:PORT

UNIX Domain Socket

unix:PATH

File Descriptor

Listen on a file descriptor that is already open, bound, and listening:

fd:NUMBER

Named File Descriptor (compatible with systemd socket activation)

Listen on a named file descriptor that is already open, bound, and listening:

fdname:NAME

NAME must match the FileDescriptorName option in the systemd socket file.

PROXY Protocol

Wrap a listener with the PROXY Protocol version 2:

proxy:LISTENER

(where LISTENER is one of the syntaxes specified here)

go-listener will transparently read the PROXY protocol header and make the true client IP address available via the net.Conn's LocalAddr method.

TLS

Note: TLS support must be enabled by importing src.agwa.name/go-listener/tls like this:

import _ "src.agwa.name/go-listener/tls"

Wrap a listener with TLS, using the certificate/key in the given file (which must be absolute path):

tls:/PATH/TO/CERTIFICATE_FILE:LISTENER

Wrap a listener with TLS, using the certificate/key named SERVER_NAME.pem in the given directory (which must be an absolute path and end with a slash):

tls:/PATH/TO/CERTIFICATE_DIRECTORY/:LISTENER

Wrap a listener with TLS and automatically obtain certificates for each hostname using ACME (requires the hostname to be publicly-accessible on port 443):

tls:HOSTNAME,HOSTNAME,...:LISTENER

Certificate Files

When you specify a certificate file or directory, certificates must be PEM-encoded and contain the following blocks:

• Exactly one PRIVATE KEY, containing the private key in PKCS#8 format.
• At least one CERTIFICATE, comprising the certificate chain, leaf certificate first and root certificate omitted.
• Up to one OCSP RESPONSE, containing a stapled OCSP response.
• Any number of SIGNED CERTIFICATE TIMESTAMP, containing stapled SCTs.

Certificate files are automatically reloaded when they change.

ACME Configuration

When you obtain certificates automatically, the following environment variables can be used to configure the ACME client:

Environment Variable	Description	Default
AUTOCERT_ACME_SERVER	The directory URL of the certificate authority's ACME server	autocert.DefaultACMEDirectory
AUTOCERT_EMAIL	Contact email address for your ACME account, used by certificate authority to notify you of certificate problems (highly recommended)	(none)
AUTOCERT_EAB_KID	Key ID of the External Account Binding to use with ACME	(none)
AUTOCERT_EAB_KEY	base64url-encoded HMAC-SHA256 key of the External Account Binding to use with ACME	(none)
AUTOCERT_CACHE_DIR	The directory where issued certificates are stored	When root, /var/lib/autocert-cache; otherwise, autocert-cache under $XDG_DATA_HOME

Example

Here's how to use go-listener with http.Server:

package main

import (
	"flag"
	"log"
	"net/http"

	"src.agwa.name/go-listener"
	_ "src.agwa.name/go-listener/tls"
)

func main() {
	var listenerString string
	flag.StringVar(&listenerString, "listen", "", "Socket to listen on")
	flag.Parse()

	netListener, err := listener.Open(listenerString)
	if err != nil {
		log.Fatal(err)
	}
	defer netListener.Close()

	log.Fatal(http.Serve(netListener, nil))
}

Listen on localhost, port 80:

httpd -listen tcp:127.0.0.1:80

Listen on IPv6 localhost, port 80:

httpd -listen tcp:[::1]:80

Listen on file descriptor 3:

httpd -listen fd:3

Listen on port 443, all interfaces, with TLS, using certificates in /var/certs:

httpd -listen tls:/var/certs/:tcp:443

Listen on port 443, all interfaces, with TLS, with automatic certificates for www.example.com and example.com:

httpd -listen tls:www.example.com,example.com:tcp:443

Listen on UNIX domain docket /run/example.sock with the PROXY protocol:

httpd -listen proxy:unix:/run/example.sock

Listen on UNIX domain socket /run/example.sock with TLS and the PROXY protocol, with certificate in /etc/ssl/example.com.pem:

httpd -listen tls:/etc/ssl/example.com.pem:proxy:unix:/run/example.sock

(Details: go-listener will listen on /run/example.sock. When a connection is accepted, go-listener will first read the PROXY protocol header to get the true client IP address, which will be made available through the net.Conn's LocalAddr method. It will then do a TLS handshake using the private key and certificate in /etc/ssl/example.com.pem.)

Socket Activation

Here's how to use systemd socket activation to run httpd as an unprivileged user listening on port 80 (which is a privileged port):

In /etc/systemd/system/httpd.socket put:

[Socket]
ListenStream=80

[Install]
WantedBy=sockets.target

In /etc/systemd/system/httpd.service put:

[Service]
ExecStart=/path/to/httpd -listen fd:3
DynamicUser=yes

[Install]
WantedBy=multi-user.target

You can also name the socket using the FileDescriptorName option in the httpd.socket file, and refer to it using the fdname listener type (instead of fd:3).

You don't have to use systemd; the fd listener type can be used with any process supervisor which supports listening on a file descriptor, dropping privileges, and passing the listening file descriptor to the daemon.

Documentation

Overview

Package listener provides functions for creating net.Listeners

Index

• func CloseAll(listeners []net.Listener)
• func MultiListener(listeners ...net.Listener) net.Listener
• func Open(spec string) (net.Listener, error)
• func OpenAll(specs []string) ([]net.Listener, error)
• func OpenJSON(spec map[string]interface{}) (net.Listener, error)
• func RegisterListenerType(name string, openListener OpenListenerFunc)
• type OpenListenerFunc

Functions

func CloseAll

func CloseAll(listeners []net.Listener)

CloseAll invokes Close on every listener. Errors are ignored.

func MultiListener

func MultiListener(listeners ...net.Listener) net.Listener

Create a net.Listener that aggregates the provided listeners. Calling Accept() returns the next available connection among all the listeners. Calling Close() closes each of the listeners, and causes blocked Accept calls to return with net.ErrClosed. Addr() returns a placeholder address that is probably not useful.

func Open

func Open(spec string) (net.Listener, error)

Open a listener with the given string notation

func OpenAll

func OpenAll(specs []string) ([]net.Listener, error)

Open all of the listeners specified in specs (using string notation). If any listener fails to open, an error is returned, and none of the listeners are left open.

func OpenJSON

func OpenJSON(spec map[string]interface{}) (net.Listener, error)

Experimental: Open a listener with the given JSON notation. Note that numbers in spec must be represented using json.Number.

func RegisterListenerType

func RegisterListenerType(name string, openListener OpenListenerFunc)

RegisterListenerType makes a listener type available by the provided name. Use this function to extend go-listener with your own custom listener types. See the documentation for OpenListenerFunc for details.

If RegisterListenerType is called twice with the same name or if openListener is nil, it panics.

Types

type OpenListenerFunc

type OpenListenerFunc func(map[string]interface{}, string) (net.Listener, error)

A function that is called by Open or OpenJSON to create a net.Listener of a particular type. If called by Open, then the first argument is nil, and the second argument is the string passed to Open, with the listener type and colon character removed. If called by OpenJSON, the first argument is the JSON object passed to OpenJSON, and the second argument is empty.

You only need to care about this if you are extending go-listener with your own custom listener types using RegisterListenerType.