aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorbnewbold <bnewbold@robocracy.org>2016-10-16 20:46:05 -0700
committerbnewbold <bnewbold@robocracy.org>2016-10-16 20:46:05 -0700
commit8ec307163bd487dcbf9522dba7d7cbcc757867dd (patch)
tree7c0478c907c295620a6b2615e82cbb34fb836497 /doc
parentb48e412eb2111fd3b24bcac991c77c41ef240627 (diff)
downloadeinhyrningsins-8ec307163bd487dcbf9522dba7d7cbcc757867dd.tar.gz
einhyrningsins-8ec307163bd487dcbf9522dba7d7cbcc757867dd.zip
update docs
Diffstat (limited to 'doc')
-rw-r--r--doc/einhyrningsins.1.ronn96
-rw-r--r--doc/einhyrningsinsctl.1.ronn19
-rw-r--r--doc/index.txt7
3 files changed, 96 insertions, 26 deletions
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