Add restart scripts as used on the test server.

1 files changed, 55 insertions, 0 deletions

diff --git a/tools/README.restart b/tools/README.restart
new file mode 100644
index 00000000..0bd147e2
--- /dev/null
+++ b/tools/README.restart
@@ -0,0 +1,55 @@
+There are 3 front-facing scripts for this new pidfile-based restart system.
+
+All of them belong in ~/bin/, although one of them is not actually a script.
+(it is source'd, which follows $PATH)
+
+restart-all     Call this on first boot
+                if REBUILD is not empty, it will first pull, build, and install
+                from the tmw-eathena repository.
+                In bash you can do this like: REBUILD=sure restart-all
+restart-world   Call this if you only want to restart one server.
+                The first argument is the directory, e.g. ~/tmwa-server-data/
+                After that, you may pass --manual or --auto to not-pull or pull
+                script updates. If neither is specified, the value of PULL is
+                used.
+                This does NOT use AUTO_WORLDS or MANUAL_WORLDS.
+restart-config  Contains configuration settings.
+                SERVER_SOURCE is the location of the tmw-eathena clone.
+                LOGIN_WORLD is the location of the clone that contains the
+                    account data. It does not necessarily have to correspond to
+                    a world that actually starts, although it does in the
+                    current configuration
+                AUTO_WORLDS is an array (space separated, surrounded by
+                    parentheses) of world directories that will have updates
+                    pulled when calling restart-all.
+                MANUAL_WORLDS is an array of world directories that will not
+                    have updates pulled when calling restart-all
+                VERBOSE controls whether the servers will print their output
+                    to the tty or have it redirected to /dev/null. Use if if
+                    you have any problems. It is inspected by the low-level
+                    command restart-pid.
+                REBUILD controls whether the server sources will be rebuilt
+                    during restart-all.
+                PULL controls whether updates should be pulled by
+                    restart-world. It is ignored if --auto or --manual
+                    is specified, which is the case during restart-all.
+                All of these variables (except probably the arrays) can be
+                specified in the environment, but the values in restart-config
+                override them. However, since restart-config is a bash script,
+                you could conditionally set the variables by using if test ...
+
+There are also two commands you'll probably never have to call yourself:
+restart-login   is self-explanatory and is usually called only by restart-all
+restart-pid     is the low-level command that maintains the PID file and kills
+                the old servers. In order for the server to be killed, three
+                things must match: the PID, and name, and the user.
+                This will keep errors to a minimum in case PID files continue
+                to exist after the processes have died and new processes have
+                taken their IDs.
+
+                There's a theoretical case in which the replacing process will
+                be a new instance of the same process by the same user in a
+                different world directory. The odds of this happening are
+                theoretically 1 in 32767-ish, but in practice might be a bit
+                more common than that. If you find your newly-spawned children
+                did not survive, try running restart-all again.