aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Makefile19
-rw-r--r--README.txt44
-rw-r--r--doc/einhyrningsins.1.ronn96
-rw-r--r--doc/einhyrningsinsctl.1.ronn19
-rw-r--r--doc/index.txt7
5 files changed, 149 insertions, 36 deletions
diff --git a/Makefile b/Makefile
index fff0e0b..9fd1521 100644
--- a/Makefile
+++ b/Makefile
@@ -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
diff --git a/README.txt b/README.txt
index 304522e..01500ae 100644
--- a/README.txt
+++ b/README.txt
@@ -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