einhyrningsins(1) - graceful restarts for socket-based daemons

+ + + +

einhyrningsins(1)
einhyrningsins(1)

+ +

NAME

+ einhyrningsins - graceful restarts for socket-based daemons +

+ +

SYNOPSIS

+ +

einhyrningsins [OPTIONS] [--] PROGRAM [PROGRAM_ARGS]

+ +

DESCRIPTION

+ +

Einhyrningsins is a socket multiplexer featuring graceful restarts. It runs +multiple copies of a child program, each of which are passed a shared socket +(or multiple shared sockets) to bind(2) to and accept(2) connections from. +Graceful, rolling restarts enable updates of the child program with zero +downtime and no dropped connections.

+ +

This program requires special support in the child program to achive the +graceful restarts (aka, exiting only after all connection close) and to be able +to bind to inherited file descriptors (as indicated by environment variables). +Child programs must also be able to run in parallel: for example, each copy +must not try to write to the same output file without some form of locking.

+ +

-n, --number COUNT: +How many child processes to spawn.
-b, --bind ADDR:PORT[,OPT...]: +Socket(s) to bind to. OPT specifies flags to be set on the socket. Options +are n for non-blocking (O_NONBLOCK) and r for re-using addresses +(SO_REUSEADDR). Eg, for both options, could pass -b 127.0.0.1:1234,r,n. +This argument can be repeated.
-4, --ipv4-only: +Only accept IPv4 connections
-6, --ipv6-only: +Only accept IPv6 connections
-h, --help: +Print a help menu
--version: +Print program version
-v, --verbose: +More verbose logging and output
--syslog: +Enables logging via syslog(2) (for WARN and above).
-m, --manual: +Enable manual (explicit) acknowledge mode, in which each child program must +connect to the master's control socket and "ACK" within a graceperiod, or it +will be considered unhealthy and get restarted.
--drop-env-var VAR: +Clears the given variable from the child's environment. All other variables +are passed through by default. This argument can be repeated.
-d, --socket-path PATH: +Where to create the control socket (default: /tmp/einhorn.sock).
-r, --retries COUNT +How many times to attempt re-spawning before giving up.

+ + +

CHILD API

+ +

Einhyrningsins creates children by fork(1)-ing a new process and +execve(1)-ing to run the proces itself. For every socket specified by a -b +flag, a socket is bound in the main einhyrningsins process and then +explicitly flagged to be passed on to the child processes. This means the child +process will already have a valid file descriptor bound to each of the shared +sockets. The file descriptor numbers are passed via the following environment +variables:

+ +

EINHORN_FD_COUNT: How many sockets have been passed.
EINHORN_FD_<NUM>: One evironment for each socket with NUM from 0 to EINHORN_FD_COUNT-1.

+ + +

When einhyrningsins is run in manual mode, each child process should connect +to the control socket (at the UNIX path given by the EINHORN_SOCK_PATH +variable) and write(2) a newline-terminated string like the following, +containing the child's PID number:

+ +

{"command":"worker:ack", "pid":<PID>}

+ +

HISTORY

+ +

Einhyrningsins is a partially-comparible re-implementation of einhorn(1) (a +Ruby program) in Rust. Einhorn itself derived from Unicorn.

+ +

The word "Einhyrningsins" is Icelandic for unicorn.

+ +

STATUS

+ +

Einhyrningsins is a for-fun hobby project. It is not feature complete, fully +documented, or tested.

+ +

COPYRIGHT

+ +

Copyright 2016 Bryan Newbold +License GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html. +This is free software: you are free to change and redistribute it. There is NO +WARRANTY, to the extent permitted by law.

+ +