diff options
| -rw-r--r-- | Makefile | 19 | ||||
| -rw-r--r-- | README.txt | 44 | ||||
| -rw-r--r-- | doc/einhyrningsins.1.ronn | 96 | ||||
| -rw-r--r-- | doc/einhyrningsinsctl.1.ronn | 19 | ||||
| -rw-r--r-- | doc/index.txt | 7 |
5 files changed, 149 insertions, 36 deletions
@@ -2,16 +2,17 @@ RONN = ronn MANPAGE = einhyrningsins.1 -doc/$(MANPAGE): doc/$(MANPAGE).ronn - $(RONN) -r $< +docs: doc/*.ronn + $(RONN) -r doc/*.ronn + $(RONN) --style toc -5 doc/*.ronn -doc/$(MANPAGE).html: doc/$(MANPAGE).ronn - $(RONN) --style toc -5 $< - -gh-pages: doc/$(MANPAGE).html - cp doc/$(MANPAGE).html /tmp/index.html +gh-pages: docs + mkdir -p /tmp/einhyrningsins-ronn + cp doc/*.1.html /tmp/einhyrningsins-ronn git checkout gh-pages - cp /tmp/index.html index.html - git add -u index.html + cp /tmp/einhyrningsins-ronn/*.html . + cp einhyrningsins.1.html index.html + git add -u *.html git commit -m "updating rendered manpage for github docs" git checkout master + rm -r /tmp/einhyrningsins-ronn @@ -8,7 +8,49 @@ ... is einhorn in Rust! -See doc/refs.txt for further reading. +`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. + +`einhyrningsins` is a partially-comparible re-implementation of Einhorn (a Ruby +program) in Rust. Einhorn itself derived from Unicorn. The word +"einhyrningsins" is Icelandic for unicorn. + +Read the manual page at: +https://bnewbold.github.io/einhyrningsins/einhyrningsins.1.html + +NOTE: `einhyrningsins` is a for-fun hobby project. It is not feature complete, +fully documented, or tested. See also ./TODO and unstructured notes in ./doc/. + +Building and Installation +--------------------------- + +For now both building and installation are done with rust's cargo tool, usually +bundled with the toolchain. If you haven't used rust before, "rustup" is highly +recommended. einhyrningsins builds with the 'stable' compiler, and was +developed against version 1.12 of the toolchain (September 2016). To build and +install: + + cargo build --release + cargo install + +Manpages (in both roff and HTML format) are built using the `ronn` tool, which +is available in many package managers. To build those pages, run: + + make docs + +There (currently) isn't an automated way to install the manpages. + +Differences from Einhorn +-------------------------- + + * Ruby pre-loading is not possible + * einhyrningsins does not reload *itself* on upgrades (aka restarts) + * control socket message line format is JSON, not YAML-in-URL-encoding + * passing control socket file descriptor is unimplemented + * children start all-at-once, not with a delay between spawns License --------- diff --git a/doc/einhyrningsins.1.ronn b/doc/einhyrningsins.1.ronn index 90ea89f..3a1d1c0 100644 --- a/doc/einhyrningsins.1.ronn +++ b/doc/einhyrningsins.1.ronn @@ -3,40 +3,98 @@ einhyrningsins(1) -- graceful restarts for socket-based daemons ## SYNOPSIS -`einhyrningsins` [OPTIONS] -- PROGRAM [PROGRAM_ARGS] +`einhyrningsins` [<OPTIONS>] [--] <PROGRAM> [<PROGRAM_ARGS>] ## DESCRIPTION -This is a socket multiplexer featuring graceful restarts. It runs multiple -copies of the child program that are passed a shared socket (or more than one) -to bind to and accept connections from. Graceful rolling restarts enable -updates of the child program with zero downtime and no dropped connections. +`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 and bind to inherited file descriptors indicated by -environment variables. +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. -einhyrningsins(1) is a partially-comparible re-implementation of einhorn(1) (a -Ruby program) in Rust. Einhorn itself derived from Unicorn. - - * `-n`, `--number`=COUNT + * `-n`, `--number` <COUNT>: How many child processes to spawn. - * `-b`, `--bind` ADDR - Socket(s) to bind to. This argument can be repeated. + + * `-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` + + * `-6`, `--ipv6-only`: Only accept IPv6 connections - * `-h`, `--help` + + * `-h`, `--help`: Print a help menu - * `--version` + + * `--version`: Print program version - * `-v`, `--verbose` + + * `-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 -This is a fun fun hobby project. Still in progress, and notably untested. +`Einhyrningsins` is a for-fun hobby project. It is not feature complete, fully +documented, or tested. ## COPYRIGHT Copyright 2016 Bryan Newbold @@ -45,4 +103,4 @@ This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. ## SEE ALSO -`einhorn (1)`, `einhyrningsinsctl(1)` +einhorn(1), einhyrningsinsctl(1), socket(7) diff --git a/doc/einhyrningsinsctl.1.ronn b/doc/einhyrningsinsctl.1.ronn index 1c9056f..37e8d70 100644 --- a/doc/einhyrningsinsctl.1.ronn +++ b/doc/einhyrningsinsctl.1.ronn @@ -3,21 +3,26 @@ einhyrningsinsctl(1) -- control of einhyrningsins ## SYNOPSIS -`einhyrningsinsctl` [OPTIONS] [-e CMD] +`einhyrningsinsctl` [<OPTIONS>] [-e <CMD>] ## DESCRIPTION -Tiny shell client for einhyrningsins(1), which connects to a control socket -(UNIX domain socket) and either sends a single command or acts as an -interactive shell. +`Einhyrningsinsctl` is a shell client for einhyrningsins(1), which connects to +a control socket (UNIX domain socket) and either sends a single command (via +`-e`) or acts as an interactive shell. - * `-e`, `--execute`=CMD: +For a list of valid commands, start in shell mode and run `help`. + + * `-e`, `--execute` <CMD>: Instead of starting a shell, just execute the CMD. - * `-d`, `--socket-path`=PATH: + + * `-d`, `--socket-path` <PATH>: Where to look for the control socket (a UNIX domain socket). Defaults to `/tmp/einhorn.sock`. + * `-h`, `--help`: Summary of options (of course) + * `--version`: Prints version number @@ -28,4 +33,4 @@ This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. ## SEE ALSO -`einhorn (1)`, `einhyrningsins(1)` +einhorn(1), einhyrningsins(1) diff --git a/doc/index.txt b/doc/index.txt new file mode 100644 index 0000000..d2a3714 --- /dev/null +++ b/doc/index.txt @@ -0,0 +1,7 @@ + +# These are cross-links for ronn (manpage+html documentation creator) +einhyrningsins(1) einhyrningsins.1 +einhyrningsinsctl(1) einhyrningsinsctl.1 + +# External links +einhorn(1) https://github.com/stripe/einhorn |