From e0fc82203d677a6f1e808e9a1a46176c109d89be Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 15 Dec 2014 23:08:59 +0000 Subject: Initial commit --- doc/index.html | 182 ++++++++++++++++++++ doc/libs6net/accessrules.html | 331 ++++++++++++++++++++++++++++++++++++ doc/libs6net/ident.html | 124 ++++++++++++++ doc/libs6net/index.html | 63 +++++++ doc/localservice.html | 151 ++++++++++++++++ doc/minidentd.html | 83 +++++++++ doc/s6-accessrules-cdb-from-fs.html | 141 +++++++++++++++ doc/s6-accessrules-fs-from-cdb.html | 60 +++++++ doc/s6-clockadd.html | 61 +++++++ doc/s6-clockview.html | 41 +++++ doc/s6-connlimit.html | 96 +++++++++++ doc/s6-getservbyname.html | 48 ++++++ doc/s6-ident-client.html | 52 ++++++ doc/s6-ioconnect.html | 84 +++++++++ doc/s6-ipcclient.html | 65 +++++++ doc/s6-ipcserver-access.html | 172 +++++++++++++++++++ doc/s6-ipcserver.html | 148 ++++++++++++++++ doc/s6-sntpclock.html | 166 ++++++++++++++++++ doc/s6-sudo.html | 59 +++++++ doc/s6-sudoc.html | 80 +++++++++ doc/s6-sudod.html | 162 ++++++++++++++++++ doc/s6-taiclock.html | 114 +++++++++++++ doc/s6-taiclockd.html | 51 ++++++ doc/s6-tcpclient.html | 133 +++++++++++++++ doc/s6-tcpserver-access.html | 239 ++++++++++++++++++++++++++ doc/s6-tcpserver.html | 72 ++++++++ doc/s6-tcpserver4.html | 123 ++++++++++++++ doc/s6-tcpserver6.html | 122 +++++++++++++ doc/seekablepipe.html | 36 ++++ doc/upgrade.html | 34 ++++ 30 files changed, 3293 insertions(+) create mode 100644 doc/index.html create mode 100644 doc/libs6net/accessrules.html create mode 100644 doc/libs6net/ident.html create mode 100644 doc/libs6net/index.html create mode 100644 doc/localservice.html create mode 100644 doc/minidentd.html create mode 100644 doc/s6-accessrules-cdb-from-fs.html create mode 100644 doc/s6-accessrules-fs-from-cdb.html create mode 100644 doc/s6-clockadd.html create mode 100644 doc/s6-clockview.html create mode 100644 doc/s6-connlimit.html create mode 100644 doc/s6-getservbyname.html create mode 100644 doc/s6-ident-client.html create mode 100644 doc/s6-ioconnect.html create mode 100644 doc/s6-ipcclient.html create mode 100644 doc/s6-ipcserver-access.html create mode 100644 doc/s6-ipcserver.html create mode 100644 doc/s6-sntpclock.html create mode 100644 doc/s6-sudo.html create mode 100644 doc/s6-sudoc.html create mode 100644 doc/s6-sudod.html create mode 100644 doc/s6-taiclock.html create mode 100644 doc/s6-taiclockd.html create mode 100644 doc/s6-tcpclient.html create mode 100644 doc/s6-tcpserver-access.html create mode 100644 doc/s6-tcpserver.html create mode 100644 doc/s6-tcpserver4.html create mode 100644 doc/s6-tcpserver6.html create mode 100644 doc/seekablepipe.html create mode 100644 doc/upgrade.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..93d68ce --- /dev/null +++ b/doc/index.html @@ -0,0 +1,182 @@ + + + + + s6-networking - small networking utilities + + + + + + +

+ +

s6-networking

+ +

What is it ?

+ +

+ s6-networking is a suite of small networking utilities for Unix systems. +It includes command-line client and server management, TCP access +control, privilege escalation across UNIX domain sockets, IDENT +protocol management and clock synchronization. +

+ +

+ If the underlying +skalibs has been +compiled with IPv6 support, s6-networking is IPv6-ready. +

+ +

Installation

+ +

Requirements

+ +

A POSIX-compliant system with a standard C development environment
GNU make, version 3.81 or later
skalibs version +2.0.0.0 or later
execline version +2.0.0.0 or later
s6-dns version +2.0.0.0 or later

+ +

Licensing

+ +

+ s6-networking is free software. It is available under the +ISC license. +

+ +

Download

+ +

The current released version of s6-networking is 2.0.0.0.
Alternatively, you can checkout a copy of the s6-networking git repository: +
```
 git clone git://git.skarnet.org/s6-networking 
```

+ +

Compilation

+ +

See the enclosed INSTALL file for installation details.

+ +

Upgrade notes

+ +

This page lists the differences to be aware of between +the previous versions of s6-networking and the current one.

+ +

Reference

+ +

Commands

+ +

+ All these commands exit 111 if they encounter a temporary error or +hardware error, and +100 if they encounter a permanent error - such as a misuse. Short-lived +commands exit 0 on success. Other exit codes are documented in the +relevant page. +

+ +

System clock synchronization

+ +

UCSPI implementation

+ +

TCP and Unix access control

+ +

suidless privilege gain

+ +

IDENT protocol implementation

+ +

Miscellaneous utilities

+ +

Libraries

+ +

+ + +

Related resources

+ + +

s6-networking discussion

+ +

s6-networking is discussed on the +skaware mailing-list.
s6-networking has a +freecode page. +

+ +

Similar work

+ +

ucspi-tcp is the +original inspiration for s6-networking. +It works, but is unfortunately unmaintained by the author. s6-networking +follows the +same design principles.
ipsvd is a very similar program +suite.

+ + + diff --git a/doc/libs6net/accessrules.html b/doc/libs6net/accessrules.html new file mode 100644 index 0000000..ea996b7 --- /dev/null +++ b/doc/libs6net/accessrules.html @@ -0,0 +1,331 @@ + + + + + s6-networking: the accessrules library interface + + + + + + +

+libs6net
+s6-networking
+Software
+skarnet.org +

+ +

The `accessrules` library interface

+ +

+ The following functions and structures are declared in the s6-networking/accessrules.h header, +and implemented in the libs6net.a or libs6net.so library. +

+ +

General information

+ +

+ s6net_accessrules is an access control library. It looks up +a key in a user-specified database, then returns a code depending on +whether the database allows access (in which case additional information +can also be returned), denies access, or does not contain the key. +

+ +

+ accessrules has been designed to be easily extensible to any +database format and any key format. +

+ +

+ Check the s6-networking/accessrules.h header for the exact definitions. +

+ +

Data structures

+ +

A s6net_accessrules_result_t is a scalar that +can have the following values: S6NET_ACCESSRULES_ERROR, +S6NET_ACCESSRULES_DENY, S6NET_ACCESSRULES_ALLOW or S6NET_ACCESSRULES_NOTFOUND.
A s6net_accessrules_params_t is a structure containing two +strallocs, +.env and .exec, used to return data contained in the +database when a key has been allowed. The interpretation of this data is +application-defined.

+ +

Function types

+ +

Backend lookups

+ +

+ A s6net_accessrules_backend_func_t is the type of a function +that takes a single key, looks it up in a database, and returns the result. +Namely: +

+ +

+s6net_accessrules_result_t f (char const *key, unsigned int keylen, void *handle, s6net_accessrules_params_t *params) +

+ +

+ f looks up key key of length keylen in the database +represented by handle in an implementation-defined way. It returns a +number that says the key has been allowed, denied or not found, or an error +occurred. If the key has been allowed, f stores additional information +from the database into *params. +

+ +

+ Two s6net_accessrules_backend_func_t functions are natively implemented: +

+ +

s6net_accessrules_backend_fs takes a char const * +handle and interprets it as a base directory to look up key +under, in the format understood by +s6-accessrules-cdb-from-fs.
s6net_accessrules_backend_cdb takes a struct cdb * +handle and looks up key in the +CDB it points to. handle must +already be mapped to a CDB file. Such a file can be built with the +s6-accessrules-cdb-from-fs +utility.

+ +

Frontend key checking

+ +

+ A s6net_accessrules_keycheck_func_t is the type of a function that +takes a user-level key, makes a list of corresponding backend-level keys and +calls a s6net_accessrules_backend_func_t function until it finds +a match. Namely: +

+ +

+s6net_accessrules_result_t f (void const *key, void *handle, s6net_accessrules_params_t *params, s6net_accessrules_backend_func_t *backend) +

+ +

+ f derives a list of low-level keys to check from key. +Then, for each key k of length klen in this list, it calls +(*backend)(k, klen, handle, params), returning *backend's result if it +is not S6NET_ACCESSRULES_NOTFOUND. If no match can be found in the whole list, +f finally returns S6NET_ACCESSRULES_NOTFOUND. +

+ +

+ Five s6net_accessrules_keycheck_func_t functions are natively implemented: +

+ +

+ + s6net_accessrules_keycheck_uidgid interprets key as a +diuint, i.e. a +structure containing two unsigned ints. The first one is interpreted as an +uid u, the second one as a gid g. The function first looks +for a uid/u match; if it cannot find one, it looks for a +gid/g match. If it cannot find one either, it checks +uid/default and returns the result.
+
+ s6net_accessrules_keycheck_reversedns interprets key +as a string containing a FQDN. Then for each suffix k of key, +starting with key itself and ending with key's TLD, +it looks up reversedns/k. The final dot is excluded from +k. If no match can be found, the function checks reversedns/@ +and returns the result. For instance, if key is "foo.bar.com", +the following strings are looked up, in that order: +
- reversedns/foo.bar.com
- reversedns/bar.com
- reversedns/com
- reversedns/@

+
+ s6net_accessrules_keycheck_ip4 interprets key as +4 network-byte-order characters containing an IPv4 address. Then for each +netmask mask from 32 to 0, it constructs the IPv4 network +prefix addr corresponding to that address, and looks up +ip4/addr_mask. For instance, if key +is "\300\250\001\007", representing the 192.168.1.7 address, the following +strings are looked up, in that order: +
- ip4/192.168.1.7_32
- ip4/192.168.1.6_31
- ip4/192.168.1.4_30
- ip4/192.168.1.0_29
- ip4/192.168.0.0_28
- ip4/192.168.0.0_27
+ and so on, down to: +
- ip4/192.0.0.0_3
- ip4/192.0.0.0_2
- ip4/128.0.0.0_1
- ip4/0.0.0.0_0
+ Note that the ip4/0.0.0.0_0 string is a catch-all key that +matches everything.

+
+ s6net_accessrules_keycheck_ip6 interprets key as +16 network-byte-order characters containing an IPv6 address. Then for each +netmask mask from 128 to 0, it constructs the IPv6 network +prefix addr corresponding to that address, +in canonical form, +and looks up +ip6/addr_mask. For instance, if key +is "*\0\024P@\002\b\003\0\0\0\0\0\0\020\006", representing the +2a00:1450:4002:803::1006 address, the following +strings are looked up, in that order: +
- ip6/2a00:1450:4002:803::1006_128
- ip6/2a00:1450:4002:803::1006_127
- ip6/2a00:1450:4002:803::1004_126
- ip6/2a00:1450:4002:803::1000_125
- ip6/2a00:1450:4002:803::1000_124
- ip6/2a00:1450:4002:803::1000_123
- ip6/2a00:1450:4002:803::1000_122
- ip6/2a00:1450:4002:803::1000_121
- ip6/2a00:1450:4002:803::1000_120
- ip6/2a00:1450:4002:803::1000_119
- ip6/2a00:1450:4002:803::1000_118
- ip6/2a00:1450:4002:803::1000_117
- ip6/2a00:1450:4002:803::1000_116
- ip6/2a00:1450:4002:803::1000_115
- ip6/2a00:1450:4002:803::1000_114
- ip6/2a00:1450:4002:803::1000_113
- ip6/2a00:1450:4002:803::_112
- ip6/2a00:1450:4002:803::_111
+ and so on, down to: +
- ip6/2a00::_11
- ip6/2800::_10
- ip6/2800::_9
- ip6/2000::_8
- ip6/2000::_7
- ip6/2000::_6
- ip6/2000::_5
- ip6/2000::_4
- ip6/2000::_3
- ip6/::_2
- ip6/::_1
- ip6/::_0
+ Note that the ip6/::_0 string is a catch-all key that +matches everything.

+ + s6net_accessrules_keycheck_ip46 interprets key as a pointer to an +ip46_t, and +behaves either as s6net_accessrules_keycheck_ip6 or s6net_accessrules_keycheck_ip4, +depending on the type of address *key contains.

+ +

Ready-to-use functions

+ + Those functions are mostly macros; they're built by associating a frontend +function with a backend function. + +

+s6net_accessrules_result_t s6net_accessrules_uidgid_cdb +(unsigned int u, unsigned int g, struct cdb *c, +s6net_accessrules_params_t *params)
+Checks the *c CDB database for an authorization for uid u +and gid g. If the result is S6NET_ACCESSRULES_ALLOW, additional +information may be stored into params. +

+ +

+s6net_accessrules_result_t s6net_accessrules_uidgid_fs +(unsigned int u, unsigned int g, char const *dir, +s6net_accessrules_params_t *params)
+Checks the dir base directory for an authorization for uid u +and gid g. If the result is S6NET_ACCESSRULES_ALLOW, additional +information may be stored into params. +

+ +

+s6net_accessrules_result_t s6net_accessrules_reversedns_cdb +(char const *name, struct cdb *c, +s6net_accessrules_params_t *params)
+Checks the *c CDB database for an authorization for the +name FQDN. If the result is S6NET_ACCESSRULES_ALLOW, additional +information may be stored into params. +

+ +

+s6net_accessrules_result_t s6net_accessrules_reversedns_fs +(char const *name, char const *dir, +s6net_accessrules_params_t *params)
+Checks the dir base directory for an authorization for the +name FQDN. If the result is S6NET_ACCESSRULES_ALLOW, additional +information may be stored into params. +

+ +

+s6net_accessrules_result_t s6net_accessrules_ip4_cdb +(char const *ip4, struct cdb *c, +s6net_accessrules_params_t *params)
+Checks the *c CDB database for an authorization for the +ip4 IPv4 address (4 network byte order characters). +If the result is S6NET_ACCESSRULES_ALLOW, additional +information may be stored into params. +

+ +

+s6net_accessrules_result_t s6net_accessrules_ip4_fs +(char const *ip4, char const *dir, +s6net_accessrules_params_t *params)
+Checks the dir base directory for an authorization for the +ip4 IPv4 address (4 network byte order characters). +If the result is S6NET_ACCESSRULES_ALLOW, additional +information may be stored into params. +

+ +

+s6net_accessrules_result_t s6net_accessrules_ip6_cdb +(char const *ip6, struct cdb *c, +s6net_accessrules_params_t *params)
+Checks the *c CDB database for an authorization for the +ip6 IPv6 address (16 network byte order characters). +If the result is S6NET_ACCESSRULES_ALLOW, additional +information may be stored into params. +

+ +

+s6net_accessrules_result_t s6net_accessrules_ip6_fs +(char const *ip6, char const *dir, +s6net_accessrules_params_t *params)
+Checks the dir base directory for an authorization for the +ip6 IPv6 address (16 network byte order characters). +If the result is S6NET_ACCESSRULES_ALLOW, additional +information may be stored into params. +

+ +

+s6net_accessrules_result_t s6net_accessrules_ip46_cdb +(ip46_t *ip, struct cdb *c, +s6net_accessrules_params_t *params)
+Checks the *c CDB database for an authorization for the +ip IP address. +If the result is S6NET_ACCESSRULES_ALLOW, additional +information may be stored into params. +

+ +

+s6net_accessrules_result_t s6net_accessrules_ip46_fs +(ip46_t const *ip, char const *dir, +s6net_accessrules_params_t *params)
+Checks the dir base directory for an authorization for the +ip IP address. +If the result is S6NET_ACCESSRULES_ALLOW, additional +information may be stored into params. +

+ + + diff --git a/doc/libs6net/ident.html b/doc/libs6net/ident.html new file mode 100644 index 0000000..74a9217 --- /dev/null +++ b/doc/libs6net/ident.html @@ -0,0 +1,124 @@ + + + + + s6-networking: the ident library interface + + + + + + +

+libs6net
+s6-networking
+Software
+skarnet.org +

+ +

The `ident` library interface

+ +

+ The following functions and structures are declared in the s6-networking/ident.h header, +and implemented in the libs6net.a or libs6net.so library. +

+ +

General information

+ +

+ ident provides a C IDENT client, following RFC 1413. +

+ +

+ Please note that this protocol is of historical interest exclusively; +this client, as well as the minidentd +server, is only provided for convenience and interoperability with +legacy systems. The IDENT protocol absolutely cannot be relied on for +any kind of authentication or secure operation. +

+ +

Functions

+ +

+ Check the s6-networking/ident.h header for the exact function prototypes. +

+ +

Main interface

+ +

+int s6net_ident_client (char *s, unsigned int max, ip46_t const *remoteip, uint16 remoteport, ip46_t const *localip, uint16 localport, +struct taia const *deadline, struct taia *stamp) +

+ +

+Makes an IDENT request to a server listening on IP remoteip port 113 +about the connection from IP remoteip port remoteport to +IP localip port localport. Writes the answer into +preallocated string s of max length max, and returns the +number of bytes in the answer. +

+ +

An ip46_t +is a structure holding either an IPv4 address or an IPv6 address.
If an error occurs, the function returns -1 and sets errno to a +suitable value. If no answer can be gotten from the server, the function +returns 0 and sets errno to a suitable value.
If max is too small for s to hold the answer, the +function returns -1 ENAMETOOLONG. +This can be avoided by using S6NET_IDENT_REPLY_SIZE +as max.
Negative answers are mapped to errno in the following way: +
- INVALID-PORT is reported as EINVAL
- NO-USER is reported as ESRCH
- HIDDEN-USER is reported as EPERM
- UNKNOWN-ERROR is reported as EIO
- extended error codes are reported as EEXIST
*deadline and *stamp are +absolute dates: +*stamp must be an accurate enough approximation of the current time, and +is automatically updated when the function returns. If no answer has been gotten +from the server by *deadline, then the call is aborted and returns +-1 ETIMEDOUT.

+ +

+ char const *s6net_ident_error_str (int e) +

+ +

+ Maps an error code representing a negative answer (i.e. errno when +s6net_ident_client returned 0) to a suitable string. +

+ +

Low-level functions

+ +

+int s6net_ident_reply_get (char *s, ip46_t const *ra, uint16 rp, ip46_t const *la, uint16 lp, +struct taia const *deadline, struct taia *stamp) +

+ +

+The network part of s6net_ident_client. Connects to *ra:113 +and asks the server about (*ra:rp, *la:lp), +aborting if *deadline goes by. Writes the server answer into s; +at least S6NET_IDENT_REPLY_SIZE bytes must be preallocated in s. +Returns -1 if an error occurs, or the number of bytes written into s. +

+ +

+ int s6net_ident_reply_parse (char const *s, uint16 rp, uint16 lp) +

+ +

+The local part of s6net_ident_client. Parses the server answer in +s for the connection from port rp to port lp. +Returns -1 EPROTO if the answer does not make sense, 0 if the answer is +negative, or a positive number if the answer is positive. This number is +an index where the ID can be found in s. +

+ + + diff --git a/doc/libs6net/index.html b/doc/libs6net/index.html new file mode 100644 index 0000000..7a6a75b --- /dev/null +++ b/doc/libs6net/index.html @@ -0,0 +1,63 @@ + + + + + s6-networking: the s6net library interface + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6net` library interface

+ +

General information

+ +

+ libs6net is a collection of networking-related utility +C interfaces, used in the s6-networking executables. +

+ +

Compiling

+ +

Make sure the s6-networking headers, as well as the skalibs headers, +are visible in your header search path.
Use #include <s6-networking/s6net.h>

+ +

Linking

+ +

Make sure the s6-networking libraries, as well as the skalibs +libraries, are visible in your library search path.
Link against -ls6net, -lskarnet,

`cat $SYSDEPS/socket.lib`

`cat $SYSDEPS/tainnow.lib`

+ +

Programming

+ +

+ The s6-networking/s6net.h header is actually a +concatenation of other headers: +the libs6net is separated into several modules, each of them with its +own header. +

+ +

The s6-networking/accessrules.h header +provides function to check credentials against configuration files.
The s6-networking/ident.h header provides +a small IDENT client (RFC 1413).

+ + + diff --git a/doc/localservice.html b/doc/localservice.html new file mode 100644 index 0000000..af7aafb --- /dev/null +++ b/doc/localservice.html @@ -0,0 +1,151 @@ + + + + + s6-networking: what is a local service + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

Local services

+ +

+ A local service is a daemon that listens to incoming connections +on a Unix domain socket. Clients of the service are programs connecting to +this socket: the daemon performs operations on their behalf. +

+ +

+ The service is called local because it is not accessible to +clients from the network. +

+ +

+ A widely known example of a local service is the syslogd daemon. +On most implementations, it listens to the /dev/log socket. +Its clients connect to it and send their logs via the socket. The +openlog() function is just a wrapper arround the connect() +system call, the syslog() function a wrapper around write(), +and so on. +

+ +

Benefits

+ +

Privileges

+ +

+ The most important benefit of a local service is that it permits +controlled privilege gains without using setuid programs. +The daemon is run as user S; a client running as user C and connecting to +the daemon asks it to perform operations: those will be done as user S. +

+ +

+ Standard Unix permissions on the listening socket can be used to implement +some basic access control: to restrict access to clients belonging to group +G, change the socket to user S and group G, and give it 0420 permissions. +This is functionally equivalent to the basic access control for setuid +programs: a program having user S, group G and permissions 4750 will be +executable by group G and run with S rights. +

+ +

+ But modern systems implement the +getpeereid() +system call or library function. This function allows the server to know the +client's credentials: so fine-grained access control is possible. On those +systems, local services can do as much authentication as setuid programs, +in a much more controlled environment. +

+ +

fd-passing

+ +

+ The most obvious difference between a local service and a network service +is that a local service does not serve network clients. But local services +have another nice perk: while network services usually only provide you +with a single channel (a TCP or UDP socket) of communication between the +client and the server, forcing you to multiplex your data into that +channel, local services allow you to have as many +communication channels as you want. +

+ +

+(The SCTP transport layer provides a way for network services to use +several communication channels. Unfortunately, it is not widely deployed +yet, and a lot of network services still depend on TCP.) +

+ +

+ The fd-passing mechanism is Unix domain socket black magic +that allows one peer of the socket to send open file descriptors to +the other peer. So, if the server opens a pipe and sends one end of +this pipe to a client via this mechanism, there is effectively a +socket and a pipe between the client and the server. +

+ +

UCSPI

+ +

+ The UCSPI protocol +is an easy way of abstracting clients and servers from the network. +A server written as a UCSPI server, just as it can be run +under inetd or s6-tcpserver, can be run under +s6-ipcserver: choose a socket +location and you have a local service. +

+ +

+ Fine-grained access control can be added by inserting +s6-ipcserver-access in +your server command line after s6-ipcserver. +

+ +

+ A client written as an UCSPI client, i.e. assuming it has descriptor +6 (resp. 7) open and reading from (resp. writing to) the server socket, +can be run under s6-ipcclient. +

+ +

Use in skarnet.org software

+ +

+ skarnet.org libraries often use a separate process to handle +asynchronicity and background work in a way that's invisible to +the user. Among them are: +

+ +

s6-ftrigrd, +managing the reception of notifications and only waking up the client process +when the notification pattern matches a regular expression.
s6lockd, +handling time-constrained lock acquisition on client behalf.
skadnsd, +performing asynchronous DNS queries and only waking up the client process +when an answer arrives.

+ +

+ Those processes are usually spawned from a client, via the corresponding +*_startf*() library call. But they can also be spawned from a +s6-ipcserver program in a local service configuration. In both cases, they +need an additional control channel to be passed from the server to +the client: the main socket is used for synchronous commands from the client +to the server and their answers, whereas the additional channel, which is +now implemented as a socket as well (but created by the server on-demand +and not bound to a local path), is used for asynchronous +notifications from the server to the client. The fd-passing mechanism +is used to transfer the additional channel from the server to the client. +

+ + + diff --git a/doc/minidentd.html b/doc/minidentd.html new file mode 100644 index 0000000..e23fa86 --- /dev/null +++ b/doc/minidentd.html @@ -0,0 +1,83 @@ + + + + + s6-networking: the minidentd program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `minidentd` program

+ +

+minidentd is a small +UCSPI server application +that answers IDENT requests. +

+ +

Interface

+ +

+     minidentd [ -v ] [ -n | -i | -r ] [ -y file ] [ -t timeout ]
+

+ +

+minidentd reads a series of IDENT requests on stdin and answers +them on stdout. It logs what it's doing on stderr. The environment +variables xLOCALIP and xREMOTEIP, where x is +the value of the PROTO environment variable, must contain the IDENT +server address and the IDENT client address, respectively. +

+ +

+ minidentd exits 0 on success, 100 on a usage error and 111 on a system +call failure. +

+ +

+ minidentd does not contact the network directly. It's meant to +run under a superserver like +s6-tcpserver. minidentd will +work with IPv4 as well as IPv6. +

+ +

Options

+ +

-v : verbose mode. Log queries and replies..
-n : send ERROR : HIDDEN-USER replies if +the user has a .ident file in his home directory.
-i : user-defined answers. The first 14 chars of the +user's .ident file, up to EOF or newline, are used instead of +the user name. If the file exists and is empty, send +ERROR : HIDDEN-USER. If it doesn't exist, send a normal reply.
-r : send random replies.
-y file : valid with -n or -i. +Use file instead of .ident.
-t timeout : close connection after +timeout milliseconds without a client request.

+ +

Notes

+ +

minidentd works only under Linux (2.2 or later); +on other systems, it will compile and run, but report an error for every +request. +The problem is that there is no portable Unix way of listing active +outgoing TCP connections with the relevant uids. On Linux, minidentd parses +the /proc/net/tcp or /proc/net/tcp6 virtual file. Other +systems have their own way of doing this, if you want your system to be +supported by minidentd, please contact the author.

+ + + diff --git a/doc/s6-accessrules-cdb-from-fs.html b/doc/s6-accessrules-cdb-from-fs.html new file mode 100644 index 0000000..26105b1 --- /dev/null +++ b/doc/s6-accessrules-cdb-from-fs.html @@ -0,0 +1,141 @@ + + + + + s6-networking: the s6-accessrules-cdb-from-fs program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-accessrules-cdb-from-fs` program

+ +

+s6-accessrules-cdb-from-fs compiles a directory +containing a ruleset suitable for +s6-ipcserver-access or +s6-tcpserver-access into a +CDB file. +

+ +

Interface

+ +

+     s6-accessrules-cdb-from-fs cdbfile dir
+

+ +

s6-accessrules-cdb-from-fs compiles the dir +directory containing a ruleset into a +CDB file +cdbfile then exits 0.

+ +

Ruleset directory format

+ +

+ To be understood by s6-accessrules-cdb-from-fs, +s6-ipcserver-access , or +s6-tcpserver-access , +dir must have a specific format. +

+ +

+ dir contains a series of directories: +

+ +

ip4 for rules on IPv4 addresses
ip6 for rules on IPv6 addresses
reversedns for rules on host names
uid for rules on user IDs
gid for rules on group IDs

+ +

+Depending on the application, other directories can appear in dir +and be compiled into cdbfile, but +s6-tcpserver-access only +uses the first three, and +s6-ipcserver-access only +uses the last two. +

+ +

+ Each of those directories contains a set of rules. A rule is +a subdirectory named after the set of keys it matches, and containing +actions that will be executed if the rule is the first matching rule +for the tested key. +

+ +

+ The syntax for the rule name is dependent on the nature of keys, and +fully documented on the +accessrules +library page. For instance, a subdirectory named 192.168.0.0_27 +in the ip4 directory will match every IPv4 address in the +192.168.0.0/27 network that does not match a more precise rule. +

+ +

+ The syntax for the actions, however, is the same for every type of key. +A rule subdirectory can contain the following elements: +

+ +

a file (that can be empty) named allow. If such a file exists, +a key matching this rule will be immediately accepted.
a file (that can be empty) named deny. If such a file exists and +no allow file exists, a key matching this rule will be immediately +denied.
a subdirectory named env. If such a directory exists along +with an allow file, then its contents represent environment +modifications that will be applied after accepting the connection and +before executing the next program in the chain, as if the +s6-envdir +program, without options, was applied to env. env +has exactly the same format as a directory suitable for s6-envdir; +however, if the modifications take up more than 4096 bytes when +compiled into cdbfile, then s6-accessrules-cdb-from-fs will +complain and exit 100.
a file named exec. If such a file exists along with an +allow file, then its contents represent a command line that, +interpreted by the +execlineb +launcher, will be executed after accepting the connection, totally bypassing the +original command line. s6-accessrules-cdb-from-fs truncates the exec +file to 4096 bytes max when embedding it into cdbfile, so make +sure it is not larger than that.

+ +

Notes

+ +

cdbfile can exist prior to, and during, the compilation, +which actually works in a temporary file in the same directory as +cdbfile and performs an atomic replacement when it is done. +So it is not necessary to interrupt a running service during the +compilation.
If s6-accessrules-cdb-from-fs fails at some point, the temporary +file is removed. However, this doesn't happen if +s6-accessrules-cdb-from-fs is interrupted by a signal.
After the program successfully completes, if dir +was a suitable candidate for the -i option of +s6-ipcserver-access or +s6-tcpserver-access, then +cdbfile will be a suitable candidate for the -x option +of the same program, implementing the same ruleset.
cdbfile can be decompiled by the +s6-accessrules-fs-from-cdb +program.

+ + + diff --git a/doc/s6-accessrules-fs-from-cdb.html b/doc/s6-accessrules-fs-from-cdb.html new file mode 100644 index 0000000..91ec98e --- /dev/null +++ b/doc/s6-accessrules-fs-from-cdb.html @@ -0,0 +1,60 @@ + + + + + s6-networking: the s6-accessrules-fs-from-cdb program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-accessrules-fs-from-cdb` program

+ +

+s6-accessrules-fs-from-cdb decompiles a CDB database +containing a ruleset suitable for +s6-ipcserver-access or +s6-tcpserver-access and +that has been compiled with +s6-accessrules-cdb-from-fs . +

+ +

Interface

+ +

+     s6-accessrules-fs-from-cdb dir cdbfile
+

+ +

s6-accessrules-fs-from-cdb decompiles the +CDB file +cdbfile into the directory dir, then exits 0.

+ +

Notes

+ +

dir must not exist prior to the decompilation.
dir must be considered as a work in progress as long as +s6-accessrules-fs-from-cdb is running. It is only safe to use dir +as a ruleset once the program has exited.
If s6-accessrules-fs-from-cdb fails at some point, the partial +arborescence at dir is removed. However, this doesn't happen if +s6-accessrules-fs-from-cdb is interrupted by a signal.
After the program successfully completes, if cdbfile +was a suitable candidate for the -x option of +s6-ipcserver-access or +s6-tcpserver-access, then +dir will be a suitable candidate for the -i option +of the same program, implementing the same ruleset.

+ + + diff --git a/doc/s6-clockadd.html b/doc/s6-clockadd.html new file mode 100644 index 0000000..a998cd1 --- /dev/null +++ b/doc/s6-clockadd.html @@ -0,0 +1,61 @@ + + + + + s6-networking: the s6-clockadd program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-clockadd` program

+ +

+s6-clockadd adjusts the system clock depending on the input +provided by a time client. +

+ +

Interface

+ +

+     s6-taiclock server | s6-clockadd [ -f ] [ -e errmax ]
+

+ +

s6-clockadd reads its stdin, expecting input from a program such +s6-taiclock or +s6-sntpclock (which get time from a +time server).
It sets the system clock so the system time becomes the one +given by the server. Then it exits 0.

+ +

Options

+ +

-f : force. Normally, s6-clockadd exits 1 if the +time discrepancy read from stdin is bigger than errmax +milliseconds. If this +option is set, it will print a warning message, but still set the +system time and exit 0.
-e errmax : accept a maximum time +discrepancy of errmax milliseconds. By default, errmax +is 2000.

+ +

Notes

+ +

s6-clockadd must be run as root. The client getting the time +from a time server, however, does not have to.

+ + + diff --git a/doc/s6-clockview.html b/doc/s6-clockview.html new file mode 100644 index 0000000..58d8ac9 --- /dev/null +++ b/doc/s6-clockview.html @@ -0,0 +1,41 @@ + + + + + s6-networking: the s6-clockview program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-clockview` program

+ +

+s6-clockview prints the time discrepancy between the local +system clock and the time provided by a time server. +

+ +

Interface

+ +

+     s6-taiclock server | s6-clockview
+

+ +

s6-clockview reads its stdin, expecting input from a program such +s6-taiclock or +s6-sntpclock (which get time from a +time server).
It prints the local system time, and the time given by the +server, in human-readable form, then exits 0.

+ + + diff --git a/doc/s6-connlimit.html b/doc/s6-connlimit.html new file mode 100644 index 0000000..f0422e6 --- /dev/null +++ b/doc/s6-connlimit.html @@ -0,0 +1,96 @@ + + + + + s6-networking: the s6-connlimit program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-connlimit` program

+ +

+s6-connlimit is a small utility to perform IP-based +control on the number of client connections to a TCP socket, and +uid-based control on the number of client connections to a Unix +domain socket. +

+ +

Interface

+ +

+     s6-connlimit prog...
+

+ +

s6-connlimit reads its environment for the PROTO +environment variable, and then for ${PROTO}CONNNUM and ${PROTO}CONNMAX, +which must contain integers.
If the value of ${PROTO}CONNNUM is superior or equal to the value +of ${PROTO}CONNMAX, s6-connlimit exits 1 with an error message.
Else it execs into prog....
If ${PROTO}CONNMAX is unset, s6-connlimit directly execs into +prog... without performing any check: +no maximum number of connection has been defined.

+ +

Usage

+ +

+ The s6-tcpserver4 and +s6-tcpserver6 define the PROTO environment +variable to "TCP", and spawn every child server with the TCPCONNNUM environment +variable set to the number of connections from the same IP address. + The s6-tcpserver-access program +can set environment variables depending on the client's IP address. If the +s6-tcpserver-access database is configured to set the TCPCONNMAX environment +variable for a given set of IP addresses, and s6-tcpserver-access execs into +s6-connlimit, then s6-connlimit will drop connections if there already are +${TCPCONNMAX} connections from the same client IP address. +

+ +

+ The s6-ipcserver and +s6-ipcserver-access programs can +be used the same way, with "IPC" instead of "TCP", to limit the number +of client connections by UID. +

+ +

Example

+ +

+ The following command line: +

+ +

+     s6-tcpserver4 -v2 -c1000 -C40 1.2.3.4 80 \
+     s6-tcpserver-access -v2 -RHl0 -i dir \
+     s6-connlimit \
+     prog...
+

+ +

+ will run a server listening to IPv4 address 1.2.3.4, on port 80, +serving up to 1000 concurrent connections, and up to 40 concurrent +connections from the same IP address, no matter what the IP address. +For every client connection, it will look up the database set up +in dir; if the connection is accepted, it will run prog.... +

+ +

+ If the dir/ip4/5.6.7.8_32/env/TCPCONNMAX file +exists and contains the string 30, then at most 30 concurrent +connections from 5.6.7.8 will execute prog..., instead of the +default of 40. +

+ + + diff --git a/doc/s6-getservbyname.html b/doc/s6-getservbyname.html new file mode 100644 index 0000000..29a8235 --- /dev/null +++ b/doc/s6-getservbyname.html @@ -0,0 +1,48 @@ + + + + + s6-networking: the s6-getservbyname program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-getservbyname` program

+ +

+s6-getservbyname is a simple command-line interface to the +getservbyname() +function, converting a service name and protocole into a port number. +

+ +

Interface

+ +

+     s6-getservbyname name proto
+

+ +

s6-getservbyname looks up the network services database +for an entry containing name name and protocol proto.
It prints the corresponding port number to stdout, then exits 0.
If it cannot find a related entry, it exits 1.

+ +

Example

+ +

+ On a standard machine with a correct /etc/services file and +a non-garbled NSS configuration: + s6-getservbyname smtp tcp prints 25. +

+ + + diff --git a/doc/s6-ident-client.html b/doc/s6-ident-client.html new file mode 100644 index 0000000..fb7b0bf --- /dev/null +++ b/doc/s6-ident-client.html @@ -0,0 +1,52 @@ + + + + + s6-networking: the s6-ident-client program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-ident-client` program

+ +

+s6-ident-client is a command-line client application that +performs IDENT (RFC 1413) queries. +

+ +

Interface

+ +

+     s6-ident-client [ -t millisecs ] remoteaddr remoteport localaddr localport
+

+ +

s6-ident-client contacts the IDENT server on address remoteaddr +port 113 and asks it about the connection from address remoteaddr +port remoteport to address localaddr port localport.
It prints the answer to stdout.
It exits 0 if the answer is positive or 1 if the answer is negative, +in which case it also prints an informative message to stderr.
remoteaddr and localaddr can be either IPv4 +or IPv6 addresses; however, they must both be of the same type.

+ +

Options

+ +

-t millisecs : if no answer has been +obtained within millisecs milliseconds, s6-ident-client will +exit 99 with an error message. By default, millisecs is 0, +which means no time limit.

+ + + diff --git a/doc/s6-ioconnect.html b/doc/s6-ioconnect.html new file mode 100644 index 0000000..5e2b6c6 --- /dev/null +++ b/doc/s6-ioconnect.html @@ -0,0 +1,84 @@ + + + + + s6-networking: the s6-ioconnect program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-ioconnect` program

+ +

+s6-ioconnect performs full-duplex data transmission +between two sets of open file descriptors. +

+ +

Interface

+ +

+     s6-ioconnect [ -t millisecs ] [ -r fdr ] [ -w fdw ] [ -0 ] [ -1 ] [ -6 ] [ -7 ]
+

+ +

s6-ioconnect reads data from its stdin and writes it as is to +file descriptor 7, which is assumed to be open.
It also reads data from its file descriptor 6, which is assumed +to be open, and writes it as is to its stdout.
When both sides have transmitted EOF and s6-ioconnect has +flushed its buffers, it exits 0.

+ +

Options

+ +

-t millisecs : if no activity on +either side happens for millisecs milliseconds, s6-ioconnect +closes the connection on both ends and exits 1. By default, +millisecs is 0, which means no such timeout.
-r fdr : Use fd fdr for +"remote" reading instead of fd 6.
-w fdw : Use fd fdw for +"remote" writing instead of fd 7.
-0: assume stdin is a socket and needs to be shut down +for reading after an EOF.
-1: assume stdout is a socket and needs to be shut down +for writing to correctly transmit an EOF.
-6: assume the remote reading fd is a socket and needs to be shut down +for reading after an EOF.
-7: assume the remote writing fd is a socket and needs to be shut down +for writing to correctly transmit an EOF.

+ +

Notes

+ +

Transmitting EOF across full-duplex sockets +is ugly. The right thing +in every case cannot be automatically determined, so it is up to the user +to mention that a socket must be shut down. Most of the time, though, +shutting down sockets after EOF is the right thing to do, so +s6-ioconnect -67 should be the common use case.
The point of s6-ioconnect is to be used together with +s6-tcpclient or +s6-ipcclient to establish a full- +duplex connection between the client and the server, for instance +for testing purposes. s6-ioconnect is to s6-tcpclient as +cat is to s6-tcpserver: a program that will just echo +what it gets.
On modern Linux systems, s6-ioconnect will perform zero-copy +data transmission, via the +splice +system call.

+ + + diff --git a/doc/s6-ipcclient.html b/doc/s6-ipcclient.html new file mode 100644 index 0000000..2bb66aa --- /dev/null +++ b/doc/s6-ipcclient.html @@ -0,0 +1,65 @@ + + + + + s6-networking: the s6-ipcclient program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-ipcclient` program

+ +

+s6-ipcclient is an +UCSPI client tool for +Unix domain sockets. It connects to a socket, then executes into +a program. +

+ +

Interface

+ +

+     s6-ipcclient [ -q | -Q | -v ] [ -p bindpath ] [ -l localname ] path prog...
+

+ +

s6-ipcclient connects to a Unix domain socket on path.
It executes into prog... with descriptor 6 reading from +the socket and descriptor 7 writing to it.

+ +

Environment variables

+ +

+ prog... is run with +the following variables set: +

+ +

PROTO: always set to IPC
IPCLOCALPATH: set to the path associated with the local socket, +if any. Be aware that it may contain arbitrary characters.

+ +

Options

+ +

-q : be quiet.
-Q : be normally verbose. This is the default.
-v : be verbose.
-p localpath : bind the local +socket to localpath before connecting to path.
-l localname : use localname +as the value of the IPCLOCALPATH environment variable.

+ + + diff --git a/doc/s6-ipcserver-access.html b/doc/s6-ipcserver-access.html new file mode 100644 index 0000000..817425b --- /dev/null +++ b/doc/s6-ipcserver-access.html @@ -0,0 +1,172 @@ + + + + + s6-networking: the s6-ipcserver-access program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-ipcserver-access` program

+ +

+s6-ipcserver-access is a command-line access +control tool for Unix domain sockets on systems where the +getpeereid() system call can be implemented. +It is meant to be run after +s6-ipcserver and before +the application program on the s6-ipcserver command line. +

+ +

Interface

+ +

+     s6-ipcserver-access [ -v verbosity ] [ -E | -e ] [ -l localname ] [ -i rulesdir | -x rulesfile ] prog...
+

+ +

s6-ipcserver-access checks it is run under a UCSPI server tool +such as s6-ipcserver. +
It checks that the remote end of the connection fits the +accepted criteria defined by the database contained in rulesdir +or rulesfile. If the database tells it to reject the connection, +the program exits 1.
It sets up a few additional environment variables.
It executes into prog..., +unless the first matching rule in the rule database +includes instructions to override prog....

+ +

Environment variables

+ +

+s6-ipcserver-access expects to inherit some environment variables from +its parent: +

+ +

PROTO: normally IPC, but could be anything else, like UNIX.
${PROTO}REMOTEEUID: the effective UID of the client program connecting to the socket.
${PROTO}REMOTEEGID: the effective GID of the client program connecting to the socket.

+ +

+ Additionally, it exports the following variables before executing into +prog...: +

+ +

${PROTO}LOCALPATH: set to the local "address" of the socket, as +reported by the +getsockname() +system call, truncated to 99 characters max.

+ +

+ Also, the access rules database can instruct s6-ipcserver-access to set +up, or unset, more environment variables, depending on the client address. +

+ +

Options

+ +

-v verbosity : be more or less verbose, i.e. +print more or less information to stderr: +
- 0: only log error messages.
- 1: only log error and warning messages, and accepted connections. +This is the default.
- 2: also log rejected connections and more warning messages.
-E : no environment. All environment variables potentially +set by s6-ipcserver-access, as well as those set by +s6-ipcserver, will be unset instead.
-e : set up environment variables normally. +This is the default.
-l localname : use localname +as the value for the ${PROTO}LOCALPATH environment variable, instead of +looking it up via getsockname().
-i rulesdir : check client credentials +against a filesystem-based database in the rulesdir directory.
-x rulesfile : check client credentials +against a cdb +database in the rulesfile file. -i and -x are +mutually exclusive. If none of those options is given, no credential checking will be +performed, and a warning will be emitted on every connection if +verbosity is 2 or more.

+ +

Access rule checking

+ +

+ s6-ipcserver-access checks its client connection against +a ruleset. This ruleset can be implemented: +

+ +

either in the filesystem as an arborescence of directories and files, +if the -i option has been given. This option is the most flexible +one: the directory format is simple enough for scripts to understand and +modify it, and the ruleset can be changed dynamically. This is practical, +for instance, for roaming users.
or in a CDB +file, if the -x option has been given. This option is the most +efficient one if the ruleset is static enough: a lot less system calls are +needed to perform searches in a CDB than in the filesystem.

+ +

+ The exact format of the ruleset is described on the +s6-accessrules-cdb-from-fs page. +

+ +

+s6-ipcserver-access first reads the client UID uid and +GID gid from the +${PROTO}REMOTEEUID and ${PROTO}REMOTEEGID environment variables, and checks +them with the +s6net_accessrules_keycheck_uidgid() +function. In other words, it tries to match: + +

uid/uid
gid/gid
uid/default

+ +

+ in that order. If no S6NET_ACCESSRULES_ALLOW result can be obtained, +the connection is denied. +

+ +

Environment and executable modifications

+ +

+ s6-ipcserver-access interprets non-empty env subdirectories +and exec files +it finds in the first matching rule of the ruleset, as explained +in the s6-accessrules-cdb-from-fs +page. +

+ +

An env subdirectory is interpreted as if the +s6-envdir +command had been called before executing prog: the environment +is modified according to the contents of env.
An exec file containing newprog completely +bypasses the rest of s6-ipcserver-access' command line. After +environment modifications, if any, s6-ipcserver-access execs into +execlineb -c newprog.

+ + + diff --git a/doc/s6-ipcserver.html b/doc/s6-ipcserver.html new file mode 100644 index 0000000..331b139 --- /dev/null +++ b/doc/s6-ipcserver.html @@ -0,0 +1,148 @@ + + + + + s6-networking: the s6-ipcserver program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-ipcserver` program

+ +

+s6-ipcserver is an +UCSPI server tool for +Unix domain sockets, i.e. a super-server. +It accepts connections from clients, and forks a +program to handle each connection. +

+ +

Interface

+ +

+     s6-ipcserver [ -1 ] [ -q | -Q | -v ] [ -d | -D ] [ -P | -p ] [ -c maxconn ] [ -C localmaxconn ] [ -b backlog ] [ -G gidlist ] [ -g gid ] [ -u uid ] [ -U ] path prog...
+

+ +

s6-ipcserver binds to a Unix domain socket on path.
It closes its stdin and stdout.
For every client connection to this socket, it +forks. The child sets some environment variables, then +executes prog... with stdin reading from the socket and +stdout writing to it.
Depending on the verbosity level, it logs what it does to stderr.
It runs until killed by a signal. Depending on the received +signal, it may kill its children before exiting.

+ +

Environment variables

+ +

+ For each connection, an instance of prog... is spawned with +the following variables set: +

+ +

PROTO: always set to IPC
IPCREMOTEEUID: set to the effective UID of the client, +unless credentials lookups have been disabled
IPCREMOTEEGID: set to the effective GID of the client, +unless credentials lookups have been disabled
IPCREMOTEPATH: set to the path associated with the remote socket, +if any. Be aware that it may contain arbitrary characters.
IPCCONNNUM: set to the number of connections originating from +the same user (i.e. same uid)

+ +

+ If client credentials lookup has been disabled, IPCREMOTEEUID and +IPCREMOTEEUID will be set, but empty. +

+ + +

Options

+ +

-1 : write path, followed by a newline, +to stdout, before +closing it, right after binding and listening to the Unix socket. +If stdout is suitably redirected, this can be used by monitoring +programs to check when the server is ready to accept connections.
-q : be quiet.
-Q : be normally verbose. This is the default.
-v : be verbose.
-d : allow instant rebinding to the same path +even if it has been used not long ago - this is the SO_REUSEADDR flag to +setsockopt() +and is generally used with server programs. This is the default. Note that +path will be deleted if it already exists at program start time.
-D : disallow instant rebinding to the same path.
-P : disable client credentials lookups. The +IPCREMOTEEUID and IPCREMOTEEGID environment variables will be unset +in every instance of prog.... This is the portable option, +because not every system supports credential lookup across Unix domain +sockets; but it is not as secure.
-p : enable client credentials lookups. This +is the default; it works at least on Linux, Solaris, and +*BSD systems. On systems that do not support it, every connection +attempt will fail with a warning message.
-c maxconn : accept at most +maxconn concurrent connections. Default is 40. It is +impossible to set it higher than 1000.
-C localmaxconn : accept at most +localmaxconn connections from the same user ID. +Default is 40. It is impossible to set it higher than maxconn.
-b backlog : set a maximum of +backlog backlog connections on the socket. Extra +connection attempts will rejected by the kernel.
-G gidlist : change s6-ipcserver's +supplementary group list to gidlist after binding the socket. +This is only valid when run as root. gidlist must be a +comma-separated list of numerical group IDs.
-g gid : change s6-ipcserver's groupid +to gid after binding the socket. This is only valid when run +as root.
-u uid : change s6-ipcserver's userid +to uid after binding the socket. This is only valid when run +as root.
-U : change s6-ipcserver's user id, group id and +supplementary group list +according to the values of the UID, GID and GIDLIST environment variables +after binding the socket. This is only valid when run as root. +This can be used with the +s6-envuidgid +program to easily script a service that binds to a privileged socket +then drops its privileges to those of a named non-root account.

+ +

Signals

+ +

SIGTERM: exit.
SIGHUP: send a SIGTERM and a SIGCONT to all children.
SIGQUIT: send a SIGTERM and a SIGCONT to all children, then exit.
SIGABRT: send a SIGKILL to all children, then exit.

+ +

Notes

+ +

Unlike his close cousin +ipcserver, +s6-ipcserver does not perform operations such as access control. Those are +delegated to the +s6-ipcserver-access program.
s6-ipcserver can be used to set up +local services.

+ + + diff --git a/doc/s6-sntpclock.html b/doc/s6-sntpclock.html new file mode 100644 index 0000000..0d4c45b --- /dev/null +++ b/doc/s6-sntpclock.html @@ -0,0 +1,166 @@ + + + + + s6-networking: the s6-sntpclock program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-sntpclock` program

+ +

+s6-sntpclock is a small SNTP client. It connects to a +SNTP or NTP server, computes an estimated discrepancy between the +local clock time and the absolute time given by the server, and +outputs it on stdout. +

+ +

Interface

+ +

+     s6-sntpclock [ -f ] [ -v verbosity ] [ -r roundtrips ] [ -t triptimeout ] [ -h throttle ] [ -T totaltimeout ] [ -e errmax ] [ -p port ] ipaddress | s6-clockview
+

+ +

s6-sntpclock exchanges SNTPv4 messages with a SNTP server +listening on ipaddress, UDP port 123. +ipaddress can be IPv4 or IPv6.
It computes the mean difference between the absolute time +given by the system clock and the one given by the server.
It prints the difference to stdout in a format understood +by s6-clockadd and +s6-clockview. It then exits 0.

+ +

Options

+ +

-f : force. Normally, s6-sntpclock exits 111 if it cannot +compute a time with a smaller uncertainty than errmax. If this +option is set, it will output a time difference and exit 0 even if the +error is too big.
-v verbosity : be more or less verbose. +By default, verbosity is 1. 0 means only print fatal error +messages; 3 means trace every exchange with the server.
-r roundtrips : perform roundtrips +exchanges with the server. By default, roundtrip is 10. A lower +value yields a higher time uncertainty; a higher value puts more load on +the server.
-t triptimeout : if a SNTP exchange with +the server takes more than triptimeout milliseconds, abort this +exchange and move on to the next one. By default, triptimeout +is 2000.
-h throttle : wait throttle +milliseconds between exchanges with the server. A lower value gets the +final result earlier, but exerts more load on the server. A higher +value puts a lighter load on the server, but delays the computation. +By default, throttle is 0. It is recommended to set it to a +reasonable nonzero value when increasing roundtrips.
-T totaltimeout : if the whole +operation takes more than totaltimeout milliseconds, abort +and exit 1. By default, totaltimeout is 10000.
-e errmax : accept a maximum time +uncertainty of errmax milliseconds. By default, errmax +is 100.
-p port : contact a server on port +port. By default, port is 123.

+ +

Notes

+ +

There are a lot of infelicities in the NTP protocol (which SNTP is +a subset of). The biggest offender is probably that NTP cannot handle +a time difference of more than 34 years: if the time given by the NTP +server is more than 34 years away from the time given by the system clock, +then NTP just cannot compute. This is a problem for CMOS-less systems, +where the system clock is initialized to the Unix Epoch. The solution +is to first manually initialize the system clock with a program such as +date or +s6-clock +to a closer time (such as 2013-01-01, which will be good up to 2047), then +contact the NTP server.
A less obvious problem with NTP is that it works with UTC time, +which means that it gives inaccurate results when close to a leap second, +up to one second off when used during a leap second, and this +is bound to the use of UTC: there is nothing you can do about it. The +only solution to get reliable results even around a leap second is to +use linear time such as TAI; the +s6-taiclock and +s6-taiclockd programs provide tools to +do so.

+ + +

A word on ntpd

+ +

+ From a Unix software engineering standpoint, the well-known +ntpd program is an +eldritch abomination. The main reason for it is that, just like its +lovely cousin BIND, +ntpd performs a lot of different tasks in a unique process, instead +of separating what could, and should, be separated. This is confusing +for both the programmer and the software user. +

+ +

The term "NTP server" means two different things: +
- A program that serves NTP time to the Internet and can be +accessed by NTP clients.
- A daemon, i.e. a long-lived process, that runs on a machine +and handles NTP-related stuff such as keeping the system clock accurate.
+ The former is the real meaning of "NTP server". The latter is a common +usage for the term, but comes from a misuse of "server" to mean "daemon". +ntpd does not help clear the misunderstanding since it does both. It acts +as an NTP server, and as an NTP client getting its time from +lower-strata NTP servers, and as a local system clock management +daemon. Those are already 3 separate tasks.
Local system clock management itself involves several duties. There +is the regular setting of the system clock, which can be done with +a loop over a simple program such as s6-clockadd. +There is also control of the clock skew, which s6-networking does not +provide because there is no portable interface for that; there is such a tool +in the clockspeed package.
ntpd includes a complete cryptographic key management system for the +crypto part of NTP. NTP is not the only protocol that uses cryptography +and asymmetric keys; managing keys in a separate tool, not in the NTP +daemon itself, would be simpler and smarter.
ntpd provides monitoring support for client and server timekeeping +performance. This would be best implemented as a separate specific log +analyzing tool.

+ +

+ And of course, no matter how many layers of complexity you add onto +ntpd, it will never be able to give accurate time in the vicinity of a +leap second, since the very protocol is flawed by design - but +the ntpd authors cannot be blamed for that. Also, the ntpd +writers, not the designers, should be praised: the history of +ntpd security flaws is remarkably small, which is quite a feat for a +huge monolithic root daemon. +

+ +

+ Network synchronization is important, NTP has its perks and +valid use cases, and its existence is a good thing. However, I wish that +the main NTP implementation weren't written as a big fat clumsy process +running as root. s6-sntpclock together with +s6-clockadd aims to provide a small, simple +tool to keep system clocks, especially in embedded devices, synchronized +to a NTP server. +

+ + + diff --git a/doc/s6-sudo.html b/doc/s6-sudo.html new file mode 100644 index 0000000..603ad8a --- /dev/null +++ b/doc/s6-sudo.html @@ -0,0 +1,59 @@ + + + + + s6-networking: the s6-sudo program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-sudo` program

+ +

+s6-sudo connects to a Unix domain socket and passes +its standard file descriptors, command-line arguments and +environment to a program running on the server side, potentially +with different privileges. +

+ +

Interface

+ +

+     s6-sudo [ -q | -Q | -v ] [ -p bindpath ] [ -l localname ] [ -e ] [ -t timeoutconn ] [ -T timeoutrun ] path [ args... ]
+

+ +

s6-sudo executes into s6-ipcclient path +s6-sudoc args... It does nothing else: it is just a +convenience program. The s6-ipcclient program connects +to a Unix socket at path, and the +s6-sudoc program transmits the desired elements over the +socket.
It should be used to connect to a +local service running the +s6-sudod program, which will run a server program on the +client's behalf.

+ +

Options

+ +

The -q, -Q, -v, -p and -l +options are passed to s6-ipcclient.
The -e, -t and -T options are passed to +s6-sudoc.
Command-line arguments, if any, are also passed to +s6-sudoc, which will transmit them to +s6-sudod over the socket. +

+ + + diff --git a/doc/s6-sudoc.html b/doc/s6-sudoc.html new file mode 100644 index 0000000..0ca9918 --- /dev/null +++ b/doc/s6-sudoc.html @@ -0,0 +1,80 @@ + + + + + s6-networking: the s6-sudoc program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-sudoc` program

+ +

+s6-sudoc talks to a peer s6-sudod +program over a Unix socket, passing it command-line arguments, environment +variables and standard descriptors. +

+ +

Interface

+ +

+     s6-sudoc [ -e ] [ -t timeoutconn ] [ -T timeoutrun ] [ args... ]
+

+ +

s6-sudoc transmits its standard input, standard output and standard error +via fd-passing over a Unix socket that must be open on its descriptors 6 and 7. + It expects a s6-sudod process to be receiving them +on the other side.
It also transmits its command-line arguments args, and also its +environment by default. Note that s6-sudod will not necessarily accept all the +environment variables that s6-sudoc tries to transmit.
s6-sudoc waits for the server program run by s6-sudod to finish. It exits +the same exit code as the server program. If the server program is killed by a +signal, s6-sudoc kills itself with the same signal.

+ +

Options

+ +

-e : do not attempt to transmit any environment variables +to s6-sudod.
-t timeoutconn : if s6-sudod has not +managed to process the given information and start the server program after +timeoutconn milliseconds, give up. By default, timeoutconn +is 0, meaning infinite. Note that there is no reason to set up a nonzero +timeoutconn with a large value: s6-sudod is not supposed to block. +The option is only there to protect against ill-written services.
-T timeoutrun : if the server program +has not exited after timeoutrun milliseconds, give up. By +default, timeoutrun is 0, meaning infinite.

+ +

Notes

+ +

If s6-sudoc is killed, or exits after timeoutrun milliseconds, +while the server program is still running, s6-sudod will send a SIGTERM and a +SIGCONT to the server program - but this does not guarantee that it will die. +If the server program keeps running, it might still read from the file that +was s6-sudoc's stdin, or write to the files that were s6-sudod's stdout or +stderr. This is a potential security risk. +Administrators should audit their server programs to make sure this does not +happen.
More generally, anything using signals or terminals will not be +handled transparently by the s6-sudoc + s6-sudod mechanism. The mechanism +was designed to allow programs to gain privileges in specific situations: +short-lived, simple, noninteractive processes. It was not designed to emulate +the full suid functionality and will not go out of its way to do so.

+ + + diff --git a/doc/s6-sudod.html b/doc/s6-sudod.html new file mode 100644 index 0000000..ac93219 --- /dev/null +++ b/doc/s6-sudod.html @@ -0,0 +1,162 @@ + + + + + s6-networking: the s6-sudod program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-sudod` program

+ +

+s6-sudod receives command-line arguments, environment variables +and standard descriptors from a peer s6-sudoc +program over a Unix socket, then forks another program. +

+ +

Interface

+ +

+     s6-sudod [ -0 ] [ -1 ] [ -2 ] [ -s ] [ -t timeout ] [ sargv... ]
+

+ +

s6-sudod gets 3 file descriptors via fd-passing over a Unix socket that +must be open on its descriptors 0 and 1. (The received descriptors will be the +stdin, stdout and stderr of the server program.) It expects a +s6-sudoc process to be sending them on the +client side.
It also receives a list of command-line arguments cargv..., and +an environment clientenv.
s6-sudod forks and executes sargv... cargv... +The client command line is appended to the server command line.
s6-sudod waits for its child to exit and transmits its exit code +to the peer s6-sudoc process. It then exits 0.

+ +

Environment

+ +

+s6-sudod transmits its own environment to its child, plus the environment sent +by s6-sudoc, filtered in the following manner: +for every variable sent by s6-sudoc, if the +variable is present but empty in s6-sudod's environment, then +its value is overriden by the value given by s6-sudoc. A variable that is +already nonempty, or that doesn't exist, in s6-sudod's environment, will not +be transmitted to the child. +

+ +

Options

+ +

-0 : do not inherit stdin from s6-sudoc. The child will be +run with its stdin pointing to /dev/null instead.
-1 : do not inherit stdout from s6-sudoc. The child will be +run with its stdout pointing to /dev/null instead.
-2 : do not inherit stderr from s6-sudoc. The child will be +run with its stderr being a copy of s6-sudod's stderr instead. (This is useful +to still log the child's error messages without sending them to the client.)
-t timeout : if s6-sudod has not +received all the needed data from the client after timeout +milliseconds, it will exit without spawning a child. By default, timeout +is 0, meaning infinite. This mechanism exists to protect the server from +malicious or buggy clients that would uselessly consume resources.

+ +

Usage example

+ +

+ The typical use of s6-sudod is in a +local service with a +s6-ipcserver process listening on a Unix +socket, a s6-ipcserver-access process +performing client authentication and access control, and possibly a +s6-envdir +process setting up the environment variables that will be accepted by +s6-sudod. The following script, meant to be a run script in a +service directory, +will set up a privileged program: +

+ +

+#!/command/execlineb -P
+fdmove -c 2 1
+s6-envuidgid serveruser
+s6-ipcserver -U -- serversocket
+s6-ipcserver-access -v2 -l0 -i rules --
+exec -c
+s6-envdir env
+s6-sudod
+sargv
+

+ +

execlineb +executes the script.
fdmove makes +sure the script's error messages are sent to the service's logger.
s6-envuidgid +sets the UID, GID and GIDLIST environment variables for s6-ipcserver to interpret.
s6-ipcserver binds to serversocket +and drops its privileges to those of serveruser. Then, for every client +connecting to serversocket: +
- s6-ipcserver-access checks the +client's credentials according to the rules in directory rules. +
- exec -c +clears the environment.
- s6-envdir +sets environment variables according to the directory env. You can +make sure that a variable VAR will be present but empty by performing +echo > env/VAR. (A single newline is interpreted by s6-envdir as +an empty variable; whereas if env/VAR is totally empty, then the +VAR variable will be removed from the environment.)
- s6-sudod reads a command line cargv, a client environment +and file descriptors over the socket.
- s6-sudod spawns sargv cargv.
+

+ +

+ This means that user clientuser running +s6-sudo serversocket cargv will be +able, if authorized by the configuration in rules, to run +sargv cargv as user serveruser, with stdin, +stdout, stderr and the environment variables properly listed in env +transmitted to sargv. +

+ +

Notes

+ +

If s6-sudoc is killed, or exits after timeoutrun milliseconds, +while the server program is still running, s6-sudod will send a SIGTERM and a +SIGCONT to its child, then exit 1. However, sending a SIGTERM to the child +does not guarantee that it will die; and +if it keeps running, it might still read from the file that +was s6-sudoc's stdin, or write to the files that were s6-sudod's stdout or +stderr. This is a potential security risk. +Administrators should audit their server programs to make sure this does not +happen.
More generally, anything using signals or terminals will not be +handled transparently by the s6-sudoc + s6-sudod mechanism. The mechanism +was designed to allow programs to gain privileges in specific situations: +short-lived, simple, noninteractive processes. It was not designed to emulate +the full suid functionality and will not go out of its way to do so.
sargv may be empty. In that case, the client is in complete +control of the command line executed as serveruser. This setup is +permitted by s6-sudod, but it is very dangerous, and extreme attention should +be paid to the construction of the s6-ipcserver-access rules.

+ + + diff --git a/doc/s6-taiclock.html b/doc/s6-taiclock.html new file mode 100644 index 0000000..bbdc680 --- /dev/null +++ b/doc/s6-taiclock.html @@ -0,0 +1,114 @@ + + + + + s6-networking: the s6-taiclock program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-taiclock` program

+ +

+s6-taiclock is a client for the +TAICLOCK protocol. +It connects to a TAICLOCK server, computes an estimated discrepancy +between the local clock time and the absolute time given by the server, +and outputs it on stdout. +

+ +

Interface

+ +

+     s6-taiclock [ -f ] [ -v verbosity ] [ -r roundtrips ] [ -t triptimeout ] [ -h throttle ] [ -T totaltimeout ] [ -e errmax ] [ -p port ] ipaddress | s6-clockview
+

+ +

s6-taiclock exchanges TAICLOCK messages with a server such as +s6-taiclockd +listening on ipaddress, UDP port 4014. +ipaddress can be IPv4 or IPv6.
It computes the mean difference between the absolute time +given by the system clock and the one given by the server.
It prints the difference to stdout in a format understood +by s6-clockadd and +s6-clockview. It then exits 0.

+ +

Options

+ +

-f : force. Normally, s6-taiclock exits 111 if it cannot +compute a time with a smaller uncertainty than errmax. If this +option is set, it will output a time difference and exit 0 even if the +error is too big.
-v verbosity : be more or less verbose. +By default, verbosity is 1. 0 means only print fatal error +messages; 2 means print advanced warnings.
-r roundtrips : perform roundtrips +exchanges with the server. By default, roundtrip is 10. A lower +value yields a higher time uncertainty; a higher value puts more load on +the server.
-t triptimeout : if a TAICLOCK exchange with +the server takes more than triptimeout milliseconds, abort this +exchange and move on to the next one. By default, triptimeout +is 2000.
-h throttle : wait throttle +milliseconds between exchanges with the server. A lower value gets the +final result earlier, but exerts more load on the server. A higher +value puts a lighter load on the server, but delays the computation. +By default, throttle is 0. It is recommended to set it to a +reasonable nonzero value when increasing roundtrips.
-T totaltimeout : if the whole +operation takes more than totaltimeout milliseconds, abort +and exit 1. By default, totaltimeout is 10000.
-e errmax : accept a maximum time +uncertainty of errmax milliseconds. By default, errmax +is 100.
-p port : contact a server on port +port. By default, port is 4014.

+ +

Notes

+ +

On the usage of NTP vs. TAICLOCK

+ +

TAICLOCK is not as generic or failproof as NTP. It is not as +resistant to network latency. It has been designed to broadcast +time on a local area network, whereas NTP has been designed to +broadcast time over the whole Internet.
TAICLOCK will produce faster results on a LAN; moreover, the +point of TAICLOCK is to broadcast TAI instead of UTC, so it is +more accurate around a leap second.
The Internet is much more reliable latency-wise today +than it was when dialout connections and broken routing protocols +were the norm. So it is possible to use TAICLOCK +across a WAN if the accuracy expectations are not too strict.
TAICLOCK is much easier to implement. The +s6-sntpclock client binary code +(statically linked on a i386) is 50% bigger than the s6-taiclock +client. Also, the s6-taiclockd +server is extremely small (close to 50% smaller than the client), +whereas NTP servers, even SNTP servers, are behemoths requiring +a project of their own.

+ +

Related work

+ +

The clockspeed package +is the original inspiration for the clock management part of s6-networking. +Unfortunately, it is unmaintained.

+ + + diff --git a/doc/s6-taiclockd.html b/doc/s6-taiclockd.html new file mode 100644 index 0000000..915c181 --- /dev/null +++ b/doc/s6-taiclockd.html @@ -0,0 +1,51 @@ + + + + + s6-networking: the s6-taiclockd program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-taiclockd` program

+ +

+s6-taiclockd is a server for the +TAICLOCK protocol. +It's a long-lived program listening to the network and answering +to TAICLOCK clients such as s6-taiclock. +

+ +

Interface

+ +

+     s6-taiclockd [ -i ip ] [ -p port ]
+

+ +

s6-taiclockd listens to all network addresses on UDP +port 4014.
Whenever it receives a TAICLOCK request, it answers +immediately with the TAI time given by its local system clock.
It runs until killed by a signal.

+ +

Options

+ +

-i ip : bind to ip instead +of all available addresses. ip can be IPv4 or IPv6.
-p port : bind to port +port instead of 4014.

+ + + diff --git a/doc/s6-tcpclient.html b/doc/s6-tcpclient.html new file mode 100644 index 0000000..42edaa9 --- /dev/null +++ b/doc/s6-tcpclient.html @@ -0,0 +1,133 @@ + + + + + s6-networking: the s6-tcpclient program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-tcpclient` program

+ +

+s6-tcpclient is an +UCSPI client tool for +INET domain sockets. It establishes a TCP connection to a server, +then executes into a program. +

+ +

Interface

+ +

+     s6-tcpclient [ -q | -Q | -v ] [ -4 | -6 ] [ -d | -D ] [ -r | -R ] [ -h | -H ] [ -n | -N ] [ -t timeout ] [ -l localname ] [ -T timeoutconn ] [ -i localip ] [ -p localport ] host port prog...
+

+ +

s6-tcpclient establishes a TCP connection to host host +port port.
It executes into prog... with descriptor 6 reading from +the network and descriptor 7 writing to it.

+ +

Host address determination

+ +

host may be an IP address, in which case s6-tcpclient will +connect to that IP address. If the underlying skalibs has been +compiled with IPv6 support, host can be an IPv6 address as +well as an IPv4 one.
host may be a domain name, in which case a DNS +resolution will be performed on it, and a connection will be tried to +all the resulting IP addresses in a round-robin fashion, twice: +first with a small timeout, then with a longer timeout. The first +address to answer wins. The connection attempt fails if no address +in the list is able to answer.

+ +

Environment variables

+ +

+ prog... is run with the following variables set: +

+ +

PROTO: always set to TCP
TCPREMOTEIP: set to the chosen IP address of host.
TCPREMOTEPORT: set to port.
TCPREMOTEHOST: if the -H has been given, set to the +name obtained by a reverse DNS resolution of the IP address chosen +for host. Else unset.
TCPLOCALHOST: if the -l option has been given, set to +localname. Else set to the name obtained by a reverse DNS +resolution of the IP address chosen for the local host.
TCPREMOTEINFO: if the -r option has been given, set +to the information given by an IDENT server on host about +the current connection (very unreliable). Else unset.

+ +

Options

+ +

-q : be quiet.
-Q : be normally verbose. This is the default.
-v : be verbose.
-4 : (only valid if the underlying skalibs has +IPv6 support) Interpret host as an IPv4 address or make A +queries to determine its addresses.
-6 : (only valid if the underlying skalibs has +IPv6 support) Interpret host as an IPv6 address or make +AAAA queries to determine its addresses. This option and the previous +one are not mutually exclusive: if both are given, both IPv6 and +IPv4 addresses will be tried and IPv6 addresses will be given priority. +If neither option is given, only IPv4 address will be tried.
-d : don't use the TCP_NODELAY socket option. This +is the default.
-D : use the TCP_NODELAY socket option, which disables +Nagle's algorithm.
-r : try and obtain a TCPREMOTEINFO string via the +IDENT protocol. This is obsolete and unreliable, and should only be used for +compatibility with legacy programs.
-R : do not use the IDENT protocol. This is the +default.
-h : try and obtain the remote host name via DNS. +This is the default.
-H : do not try and obtain the remote host name +via DNS.
-n : qualify host when resolving it to +find suitable IP addresses. This is the default.
-N : do not qualify host.
-t :timeout : put a global timeout +on the connection attempt. If no fully functional connection has been +established after timeout seconds, abort the program. By +default, timeout is 0, which means no timeout.
-i localip : use localip as +the local socket address for the connection. By default, address selection +is left to the operating system.
-p localport : use localport +as the local socket port for the connection. By default, port selection +is left to the operating system.
-l localname : use localname +as the value of the TCPLOCALPATH environment variable instead of +looking it up via the DNS.
-T :timeoutconn : configure the +connection timeouts. timeoutconn must be of the form +x+y, where x and y are +integers. x is the first timeout and y is the +second one: all suitable addresses for host are first +tried with a timeout of x seconds, and if all of them +fail, then they are tried again with a timeout of y +seconds. (Be aware that the timeout specified with the -t +option overrides everything.) By default, x is 2 and +y is 58.

+ + + diff --git a/doc/s6-tcpserver-access.html b/doc/s6-tcpserver-access.html new file mode 100644 index 0000000..7bf15a0 --- /dev/null +++ b/doc/s6-tcpserver-access.html @@ -0,0 +1,239 @@ + + + + + s6-networking: the s6-tcpserver-access program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-tcpserver-access` program

+ +

+s6-tcpserver-access is a command-line TCP access +control tool, and additionally performs some fine-tuning on a +TCP socket. It is meant to be run after +s6-tcpserver and before +the application program on the s6-tcpserver command line, +just like tcpwrappers' tcpd program. +

+ +

Interface

+ +

+     s6-tcpserver-access [ -v verbosity ] [ -W | -w ] [ -D | -d ] [ -H | -h ] [ -R | -r ] [ -P | -p ] [ -l localname ] [ -B banner ] [ -t timeout ] [ -i rulesdir | -x rulesfile ] prog...
+

+ +

s6-tcpserver-access checks it is run under a UCSPI server tool +such as s6-tcpserver, + s6-tcpserver4 or + s6-tcpserver6.
It checks that the remote end of the connection fits the +accepted criteria defined by the database contained in rulesdir +or rulesfile. If the database tells it to reject the connection, +the program exits 1.
It sets up a few additional environment variables.
It executes into prog..., +unless the first matching rule in the rule database +includes instructions to override prog....

+ +

Environment variables

+ +

+s6-tcpserver-access expects to inherit some environment variables from +its parent: +

+ +

PROTO: normally TCP, but could be anything else, like SSL.
${PROTO}REMOTEIP: the remote address of the socket, i.e. the client's +IP address. This can be IPv4 or (if the underlying skalibs supports it) IPv6.
${PROTO}REMOTEPORT: the remote port of the socket.

+ +

+ Additionally, it exports the following variables before executing into +prog...: +

+ +

${PROTO}LOCALIP: set to the local address of the socket.
${PROTO}LOCALPORT: set to the local port of the socket.
${PROTO}REMOTEINFO: normally unset, but set to the information +retrieved from ${PROTO}REMOTEIP via the IDENT protocol if the -R +option has been given.
${PROTO}REMOTEHOST: set to the remote host name obtained from +a DNS lookup. Unset if the -H option has been given.
${PROTO}LOCALHOST: set to the local host name obtained from a +DNS lookup. If the -l option has been given, set to +localname instead.

+ +

+ Also, the access rules database can instruct s6-tcpserver-access to set +up, or unset, more environment variables, depending on the client address. +

+ +

Options

+ +

-v verbosity : be more or less verbose, i.e. +print more or less information to stderr: +
- 0: only log error messages.
- 1: only log error and warning messages, and accepted connections. +This is the default.
- 2: also log rejected connections and more warning messages.
- 3: also log detailed warning messages from DNS and IDENT resolution.
-W : non-fatal. If errors happen during DNS or IDENT +resolution, the connection process is not aborted. However, incorrect or +incomplete results might still prevent a legitimate connection from being +authenticated against a DNS name. This is the default.
-w : fatal. Errors during DNS or IDENT resolution will +drop the connection.
-D : disable Nagle's algorithm. Sets the TCP_NODELAY +flag on the network socket.
-d : enable Nagle's algorithm. This is the default.
-H : disable DNS lookups for the ${PROTO}LOCALHOST and +${PROTO}REMOTEHOST environment variables.
-h : enable DNS lookups. This is the default.
-R : disable IDENT lookups for the ${PROTO}REMOTEINFO +environment variable. This is the default.
-r : enable IDENT lookups. This should only be done +for legacy programs that need it.
-P : no paranoid DNS lookups. This is the default.
-p : paranoid. After looking up a name for the remote +host, s6-tcpserver-access will lookup IP addresses for this name, and drop +the connection if none of the results matches the address the connection +is originating from. Note that this still does not replace real +authentication via a cryptographic protocol.
-l localname : use localname +as the value for the ${PROTO}LOCALHOST environment variable, instead of +looking it up in the DNS.
-B banner : print banner to +the network as soon as the connection is attempted, even before +checking client credentials. The point is to speed up network protocols +that start with a server-side message.
-t timeout : set a timeout on all the +operations performed by s6-tcpserver-access. If it is not able to do +its job in timeout milliseconds, it will instantly exit 99. +The default is 0, meaning no such timeout.
-i rulesdir : check client credentials +against a filesystem-based database in the rulesdir directory.
-x rulesfile : check client credentials +against a cdb +database in the rulesfile file. -i and -x are +mutually exclusive. If none of those options is given, no credential checking will be +performed, and a warning will be emitted on every connection if +verbosity is 2 or more.

+ +

Access rule checking

+ +

+ s6-tcpserver-access checks its client connection against +a ruleset. This ruleset can be implemented: +

+ +

either in the filesystem as an arborescence of directories and files, +if the -i option has been given. This option is the most flexible +one: the directory format is simple enough for scripts to understand and +modify it, and the ruleset can be changed dynamically. This is practical, +for instance, for roaming users.
or in a CDB +file, if the -x option has been given. This option is the most +efficient one if the ruleset is static enough: a lot less system calls are +needed to perform searches in a CDB than in the filesystem.

+ +

+ The exact format of the ruleset is described on the +s6-accessrules-cdb-from-fs page. +

+ +

+s6-tcpserver-access first gets the remote address ip of the +client and converts it to canonical form. Then it checks it with the +s6net_accessrules_keycheck_ip46() +function. In other words, it tries to match broader and broader network +prefixes of ip, from ip4/ip_32 to +ip4/0.0.0.0_0 if ip is v4, or from +ip6/ip/128 to ip6/::_0 if ip +is v6. If the result is: +

+ +

S6NET_ACCESSRULES_ERROR: it immediately exits 111.

S6NET_ACCESSRULES_DENY: it immediately exits 1.

S6NET_ACCESSRULES_ALLOW: it grants access.

S6NET_ACCESSRULES_NOTFOUND: more information is needed.

+ + +

+ In the last case, if DNS lookups have been deactivated (-H) then access +is denied. But if s6-tcpserver-access is authorized to perform DNS lookups, +then it gets the remote name of the client, remotehost, and +checks it with the +s6net_accessrules_keycheck_reversedns() +function. In other words, it tries to match shorter and shorter suffixes +of remotehost, from reversedns/remotehost to +reversedns/@. +This time, the connection is denied is the result is anything else than +S6NET_ACCESSRULES_ALLOW. +

+ +

+ Note that even if the access check succeeds, the connection can still be +denied if paranoid mode has been required (-p) and a forward DNS query +on remotehost does not match ip. +

+ +

Environment and executable modifications

+ +

+ s6-tcpserver-access interprets non-empty env subdirectories +and exec files +it finds in the matching rule of the ruleset, as explained +in the s6-accessrules-cdb-from-fs +page. +

+ +

An env subdirectory is interpreted as if the +s6-envdir +command had been called before executing prog: the environment +is modified according to the contents of env.
An exec file containing newprog completely +bypasses the rest of s6-tcpserver-access' command line. After +environment modifications, if any, s6-tcpserver-access execs into +execlineb -c newprog.

+ +

Notes

+ +

s6-tcpserver-access works with +s6-tcpserver4, handling IPv4 addresses, +as well as +s6-tcpserver6, handling IPv6 addresses. +It will automatically detect the remote address type and match it against the +correct subdatabase.
s6-tcpserver-access may perform several DNS queries. For efficiency +purposes, it does as many of them as possible in parallel. However, if asked +to do an IDENT query, it does not parallelize it with DNS queries. Take +that into account when estimating a proper timeout value.

+ + + diff --git a/doc/s6-tcpserver.html b/doc/s6-tcpserver.html new file mode 100644 index 0000000..41eb176 --- /dev/null +++ b/doc/s6-tcpserver.html @@ -0,0 +1,72 @@ + + + + + s6-networking: the s6-tcpserver program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-tcpserver` program

+ +

+s6-tcpserver is an +UCSPI tool for +TCP connections, i.e. a super-server. It accepts connections from +clients, and forks a program to handle each connection. +

+ +

Interface

+ +

+     s6-tcpserver [ -q | -Q | -v ] [ -4 | -6 ] [ -1 ] [ -c maxconn ] [ -C localmaxconn ] [ -b backlog ] [ -G gidlist ] [ -g gid ] [ -u uid ] [ -U ] ip port prog...
+

+ +

s6-tcpserver executes into +s6-tcpserver4 or +s6-tcpserver6 depending on whether +ip is an IPv4 or IPv6 address. It modifies some of its +option syntax to match s6-tcpserver4 and s6-tcpserver6's.
s6-tcpserver4 or s6-tcpserver6 handles the connection itself.

+ +

Options

+ +

-q : be quiet. This is converted into -v 0 +for s6-tcpserver4 or s6-tcpserver6.
-Q : be normally quiet. This is converted into -v 1 +for s6-tcpserver4 or s6-tcpserver6. This is the default.
-v : be verbose. This is converted into -v 2 +for s6-tcpserver4 or s6-tcpserver6.
-4 : IPv4 only. Interpret ip as IPv4; if it is +invalid, exit 100.
-6 : IPv6 only. Interpret ip as IPv6; if it is +invalid, exit 100. If neither the -4 nor the -6 option is +given, s6-tcpserver will parse ip to determine its family.
Every other option is passed verbatim to s6-tcpserver4 or s6-tcpserver6.

+ +

Notes

+ +

s6-tcpserver executes either into s6-tcpserver4, which only serves +IPv4, or into IPv6, which only serves IPv6. It will not bind to every +available IP address of the machine whether they are v4 or v6; on the +other hand, it can bind to every available IPv4 address (if ip +is 0.0.0.0) or to every available IPv6 address (if ip +is ::). Two instances of s6-tcpserver can cover every +available address.

+ + + diff --git a/doc/s6-tcpserver4.html b/doc/s6-tcpserver4.html new file mode 100644 index 0000000..e0270e0 --- /dev/null +++ b/doc/s6-tcpserver4.html @@ -0,0 +1,123 @@ + + + + + s6-networking: the s6-tcpserver4 program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-tcpserver4` program

+ +

+s6-tcpserver4 is a super-server for IPv4 TCP +connections. It accepts connections from clients, and forks a +program to handle each connection. +

+ +

Interface

+ +

+     s6-tcpserver4 [ -1 ] [ -v verbosity ] [ -c maxconn ] [ -C localmaxconn ] [ -b backlog ] [ -G gidlist ] [ -g gid ] [ -u uid ] [ -U ] ip port prog...
+

+ +

s6-tcpserver4 binds to local IPv4 address ip, +port port.
It closes its stdin and stdout.
For every TCP connection to this address and port, it +forks. The child sets some environment variables, then +executes prog... with stdin reading from the network +socket and stdout writing to it.
Depending on the verbosity level, it logs what it does to stderr.
It runs until killed by a signal. Depending on the received +signal, it may kill its children before exiting.

+ +

Environment variables

+ +

+ For each connection, an instance of prog... is spawned with +the following variables set: +

+ +

PROTO: always set to TCP
TCPREMOTEIP: set to the originating address
TCPREMOTEPORT: set to the originating port
TCPCONNNUM: set to the number of connections originating from +the same IP address

+ +

Options

+ +

-1 : write port to stdout, before +closing it, right after binding and listening to the network socket. +If stdout is suitably redirected, this can be used by monitoring +programs to check when the server is ready to accept connections.
-v verbosity : be more or less verbose. +By default, verbosity is 1: print warning messages to stderr. +0 means only print fatal error messages ; 2 means print status and +connection information for every client.
-c maxconn : accept at most +maxconn concurrent connections. Default is 40. It is +impossible to set it higher than 1000.
-C localmaxconn : accept at most +localmaxconn connections from the same IP address. +Default is 40. It is impossible to set it higher than maxconn.
-b backlog : set a maximum of +backlog backlog connections on the socket. Extra +connection attempts will rejected by the kernel.
-G gidlist : change s6-tcpserver4's +supplementary group list to gidlist after binding the socket. +This is only valid when run as root. gidlist must be a +comma-separated list of numerical group IDs.
-g gid : change s6-tcpserver4's groupid +to gid after binding the socket. This is only valid when run +as root.
-u uid : change s6-tcpserver4's userid +to uid after binding the socket. This is only valid when run +as root.
-U : change s6-tcpserver4's user id, group id and +supplementary group list +according to the values of the UID, GID and GIDLIST environment variables +after binding the socket. This is only valid when run as root. +This can be used with the +s6-envuidgid +program to easily script a service that binds to a privileged socket +then drops its privileges to those of a named non-root account.

+ +

Signals

+ +

SIGTERM: exit.
SIGHUP: send a SIGTERM and a SIGCONT to all children.
SIGQUIT: send a SIGTERM and a SIGCONT to all children, then exit.
SIGABRT: send a SIGKILL to all children, then exit.

+ +

Notes

+ +

Unlike its ancestor +tcpserver, +s6-tcpserver4 performs just the bare minimum: the point is to have a +very small and very fast process to serve connections with the least +possible overhead. Features such as additional environment variables, +access control and DNS resolution are provided +via the s6-tcpserver-access +program.

+ + + diff --git a/doc/s6-tcpserver6.html b/doc/s6-tcpserver6.html new file mode 100644 index 0000000..e571010 --- /dev/null +++ b/doc/s6-tcpserver6.html @@ -0,0 +1,122 @@ + + + + + s6-networking: the s6-tcpserver6 program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `s6-tcpserver6` program

+ +

+s6-tcpserver6 is a super-server for IPv6 TCP +connections. It accepts connections from clients, and forks a +program to handle each connection. +

+ +

Interface

+ +

+     s6-tcpserver6 [ -1 ] [ -v verbosity ] [ -c maxconn ] [ -C localmaxconn ] [ -b backlog ] [ -G gidlist ] [ -g gid ] [ -u uid ] [ -U ] ip port prog...
+

+ +

s6-tcpserver6 binds to local IPv6 address ip, +port port.
It closes its stdin and stdout.
For every TCP connection to this address and port, it +forks. The child sets some environment variables, then +executes prog... with stdin reading from the network socket +and stdout writing to it.
Depending on the verbosity level, it logs what it does to stderr.
It runs until killed by a signal. Depending on the received +signal, it may kill its children before exiting.

+ +

Environment variables

+ +

+ For each connection, an instance of prog... is spawned with +the following variables set: +

+ +

PROTO: always set to TCP
TCPREMOTEIP: set to the originating address, in canonical IPv6 form
TCPREMOTEPORT: set to the originating port
TCPCONNNUM: set to the number of connections originating from +the same IPv6 address

+ +

Options

+ +

-1 : write port to stdout, before +closing it, right after binding and listening to the network socket. +If stdout is suitably redirected, this can be used by monitoring +programs to check when the server is ready to accept connections.
-v verbosity : be more or less verbose. +By default, verbosity is 1: print warning messages to stderr. +0 means only print fatal error messages ; 2 means print status and +connection information for every client.
-c maxconn : accept at most +maxconn concurrent connections. Default is 40. It is +impossible to set it higher than 1000.
-C localmaxconn : accept at most +localmaxconn connections from the same IP address. +Default is 40. It is impossible to set it higher than maxconn.
-b backlog : set a maximum of +backlog backlog connections on the socket. Extra +connection attempts will rejected by the kernel.
-G gidlist : change s6-tcpserver6's +supplementary group list to gidlist after binding the socket. +This is only valid when run as root. gidlist must be a +comma-separated list of numerical group IDs.
-g gid : change s6-tcpserver6's groupid +to gid after binding the socket. This is only valid when run +as root.
-u uid : change s6-tcpserver6's userid +to uid after binding the socket. This is only valid when run +as root.
-U : change s6-tcpserver6's user id, group id and +supplementary group list +according to the values of the UID, GID and GIDLIST environment variables +after binding the socket. This is only valid when run as root. +This can be used with the +s6-envuidgid +program to easily script a service that binds to a privileged socket +then drops its privileges to those of a named non-root account.

+ +

Signals

+ +

SIGTERM: exit.
SIGHUP: send a SIGTERM and a SIGCONT to all children.
SIGQUIT: send a SIGTERM and a SIGCONT to all children, then exit.
SIGABRT: send a SIGKILL to all children, then exit.

+ +

Notes

+ +

s6-tcpserver6 will only serve real IPv6 addresses; it does not +default to an IPv4 address. The +s6-tcpserver4 program should be +used to serve IPv4 addresses.
s6-tcpserver6 will only work if the underlying +skalibs has +been compiled with IPv6 support.

+ + + diff --git a/doc/seekablepipe.html b/doc/seekablepipe.html new file mode 100644 index 0000000..cd17b2e --- /dev/null +++ b/doc/seekablepipe.html @@ -0,0 +1,36 @@ + + + + + s6-networking: the seekablepipe program + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

The `seekablepipe` program

+ +seekablepipe turns the reading end of a pipe into a seekable +file descriptor, using a temporary file. + +

Interface

+ +

+     writer | seekablepipe tmpfile reader [ args ... ]
+

+ +

+seekablepipe writes writer's output to tmpfile, +which is unlinked as soon as it is created. Then it execs into +reader, reading from a file descriptor on tmpfile. +

+ + + diff --git a/doc/upgrade.html b/doc/upgrade.html new file mode 100644 index 0000000..0f7e635 --- /dev/null +++ b/doc/upgrade.html @@ -0,0 +1,34 @@ + + + + + s6-networking: how to upgrade + + + + + + +

+s6-networking
+Software
+skarnet.org +

+ +

What has changed in s6-networking

+ +

n 2.0.0.0

+ +

The build system has completely changed. It is now a standard +./configure && make && sudo make install +build system. See the enclosed INSTALL file for details.
slashpackage is not activated by default.
shared libraries are not used by default.
skalibs dependency bumped to 2.0.0.0.
execline dependency bumped to 2.0.0.0.
s6-dns dependency bumped to 2.0.0.0.

+ + + -- cgit v1.3.1

s6-networking

What is it ?

Installation

Requirements

Licensing

Download

Compilation

Upgrade notes

Reference

Commands

System clock synchronization

UCSPI implementation

TCP and Unix access control

suidless privilege gain

IDENT protocol implementation

Miscellaneous utilities

Libraries

Related resources

s6-networking discussion

Similar work

The accessrules library interface

General information

Data structures

Function types

Backend lookups

Frontend key checking

Ready-to-use functions

The ident library interface

General information

Functions

Main interface

Low-level functions

The s6net library interface

General information

Compiling

Linking

Programming

Local services

Benefits

Privileges

fd-passing

UCSPI

Use in skarnet.org software

The minidentd program

Interface

Options

Notes

The s6-accessrules-cdb-from-fs program

Interface

Ruleset directory format

Notes

The s6-accessrules-fs-from-cdb program

Interface

Notes

The s6-clockadd program

Interface

Options

Notes

The s6-clockview program

Interface

The s6-connlimit program

Interface

Usage

Example

The s6-getservbyname program

Interface

Example

The s6-ident-client program

Interface

Options

The s6-ioconnect program

Interface

Options

Notes

The s6-ipcclient program

Interface

Environment variables

Options

The s6-ipcserver-access program

Interface

The `accessrules` library interface

The `ident` library interface

The `s6net` library interface

The `minidentd` program

The `s6-accessrules-cdb-from-fs` program

The `s6-accessrules-fs-from-cdb` program

The `s6-clockadd` program

The `s6-clockview` program

The `s6-connlimit` program

The `s6-getservbyname` program

The `s6-ident-client` program

The `s6-ioconnect` program

The `s6-ipcclient` program

The `s6-ipcserver-access` program

The `s6-ipcserver` program

The `s6-sntpclock` program

The `s6-sudo` program

The `s6-sudoc` program

The `s6-sudod` program

The `s6-taiclock` program

The `s6-taiclockd` program

The `s6-tcpclient` program

The `s6-tcpserver-access` program

The `s6-tcpserver` program

The `s6-tcpserver4` program

The `s6-tcpserver6` program

The `seekablepipe` program