Move some documentation into wiki, and add wiki as submodule

WIP README

WIP README

WIP README

Reformat existing README sections

README WIP

WIP Create doc dir and some wiki pages

Add wiki to repo as submodule

Move resources.md to wiki

diff --git a/.gitignore b/.gitignore
index 0dc832bccaea0f1c2071ada3a1ab413c7d788940..306b8a808a65f41c3be21374b727e562486a092e 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,3 @@
-
 # /
 /configure
 /Makefile

diff --git a/.gitmodules b/.gitmodules
new file mode 100644 (file)
index 0000000..0bde9ca
--- /dev/null
+++ b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "doc/wiki"]
+       path = doc/wiki
+       url = git@github.com:zalethon/dgamelaunch.wiki.git

diff --git a/Makefile.in b/Makefile.in
index ea09bf84326b39450cd35c2361a23dd43e21aab2..89eb64b379f1b06669049741a6bec0ab5eb8799d 100644 (file)
--- a/Makefile.in
+++ b/Makefile.in
@@ -51,7 +51,7 @@ install: all
        mkdir -p $(DESTDIR)$(sbindir)
        $(INSTALL) -m 755 $(NAME) $(DESTDIR)$(sbindir)
        mkdir -p $(DESTDIR)$(mandir)/man8
-       $(INSTALL) -m 644 $(MAN8) $(DESTDIR)$(mandir)/man8
+       $(INSTALL) -m 644 doc/$(MAN8) $(DESTDIR)$(mandir)/man8
 
 indent:
        indent -nut -ts2 *.c *.h

diff --git a/README.bak b/README.bak
deleted file mode 100644 (file)
index 241b804..0000000
--- a/README.bak
+++ /dev/null
@@ -1,247 +0,0 @@
-dgamelaunch
-===========
-
-dgamelaunch is a network-based game shell where anyone can sign up for an
-account and start playing any game which suits your fancy - games known to
-work with dgamelaunch are for example NetHack (http://www.nethack.org) and
-Crawl (http://crawl.develz.org).
-
-
-DGAMELAUNCH VERSIONS
-====================
-
-Development version can be fetched from the source repository with git:
-
-  git clone git://github.com/paxed/dgamelaunch.git
-
-Releases are downloadable at http://alt.org/nethack/dgamelaunch/
-
-
-REQUIREMENTS
-============
-
-- normal development tools (make, etc)
-- autotools (autogen, autoconf, automake)
-- ncurses library and development files
-- bison (or yacc or byacc)
-- flex (or lex)
-- optionally sqlite3 library and development files
-
-
-COMPILING
-=========
-
-Basically all you have to do is:
-
-  ./autogen.sh && make
-
-Some options you might want give to autogen:
-
- --with-config-file=/absolute/path/to/dgamelaunch.config
- --enable-shmem
- --enable-sqlite
-
-
-Dgamelaunch should compile without issue on Linux, Solaris, FreeBSD 4 and 5.
-(Whether it _runs_ on all of these platforms is a different issue. We'd
-like to hear about it.)
-
-dgamelaunch was originally developed by M. Drew Streib <dtype@dtype.org> but
-is now a collaborative project. Copyright and contact information is in the
-COPYING file, included with this package.
-
-
-BASIC SETUP INSTRUCTIONS
-========================
-
-These instructions are not current. For a more up-to-date ones, see
-http://nethackwiki.com/wiki/User:Paxed/HowTo_setup_dgamelaunch
-
-
-
-
-1) Setup a chroot jail. There is a helpful script included to accomplish this,
-called dgl-create-chroot, in the source directory. The default settings are
-viewable by editing the script; to customize the installation, look at
-dgl-create-chroot.conf.example.* (also in the source directory) and edit it to
-suit your needs, and save it into the same directory as dgl-create-chroot as
-dgl-create-chroot.conf. It's very likely you need to run the script as root.
-The script will not work with the very limited System V /bin/sh, such found on
-Solaris; start it with ksh instead.
-
-If you decide to not use dgl-create-chroot, you're on your own and we assume
-you have enough clue to figure out exactly what's needed for the chroot to
-operate correctly.
-
-2) Compile nethack. Make sure the directories in the chroot match up with
-where nethack thinks everything is. You may need to edit the VAR_PLAYGROUND
-variable in include/unixconf.h and/or the HACKDIR variable in include/config.h.
-
-(Note: Try not to, for security, to put anything else in the chroot. You may
-need to put gzip in there though if you compile nethack to use it for 
-compression.)
-
-3) Make a copy of dgamelaunch.conf and edit it. This will contain information
-for dgamelaunch about what uid/username, gid/group to shed privileges to at
-runtime. It must also contain the path to nethack, and needs to know certain
-aspects of your chroot.
-
-Note that using a username in dgamelaunch.conf will cause (part of) your
-passwd database to be loaded into dgamelaunch's memory space. If you use BSD,
-this will also include encrypted passwords. Therefore, it's recommended to
-put the uid in the dgamelaunch.conf. The same applies to groups, but openpty(3)
-often looks up the tty group anyway.
-
-4) Setup dgamelaunch as one of the following:
-        a) The shell for a single login.
-        b) An (x)inetd service.
-
-If you choose a login shell make sure dgamelaunch is setuid root. (that is,
-chmod 4755 dgamelaunch.) It will shed privs right after entering the chroot
-jail though.
-
-Example xinetd lines:
-
-service telnet
-{
-  socket_type     = stream
-  protocol  = tcp
-  wait      = no
-  user      = root
-  server    = /usr/sbin/in.telnetd
-  server_args     = -h -L /opt/nethack/nethack.dtype.org/dgamelaunch -q -f /etc/dgamelaunch.conf
-  rlimit_cpu      = 3600
-  bind      = 64.71.163.206
-}
-
-A classic inetd line would look like this:
-
-telnet stream tcp nowait root.root /usr/sbin/tcpd /usr/sbin/in.telnetd -h -L /usr/sbin/dgamelaunch -q -f /etc/dgamelaunch.conf
-
-In both cases, the -L specifies an alternate login program (telnetlogin is
-invoked by default) and -h prevents revealing of a login banner (for 
-example, "Debian GNU/Linux testing/unstable influx") before starting the
-login shell.
-
-It goes without saying that the argument after -L must point to dgamelaunch's
-exact location. Also, the location of dgamelaunch.conf is variable and of
-course should be customized by you.
-
-NOTE: It appears that the -L option is not very widely supported. FreeBSD's
-telnetd uses -p instead, and you can't give arguments (arguments appropriate
-to standard login are used). Some other telnetds do not support anything
-like this at all.
-
-The -f option, followed by a filename, specifies the path to the config file
-to use for dgamelaunch.  If you specify the right path for DEFCONFIG in the
-Makefile, you may be able to omit this.
-
-For dgamelaunch, the -q option will silence errors pertaining to the server
-configuration. This is recommended for use within inetd to prevent spamming
-the clients, but when testing and setting up we strongly suggest you leave it
-off until running dgamelaunch produces no error output on stderr.
-
-5) Test your compilation of dgamelaunch by running it as root. If this
-works, a shell login or (x)inetd will work with the correct configuration.
-If you have problems with dgamelaunch's display make sure that your chroot's
-/etc/terminfo directory (or whatever directory your ncurses uses) is
-populated.
-
-
-COMMANDLINE PARAMETERS
-======================
-
- -a            Ignored.
- -c            Shows error message and exits. (login shell command)
- -e            Ignored.
- -h            Ignored.
- -i user       Autologin and run the register -command hook for "user"
-               (with password "user").
- -p            Ignored.
- -q            Be quiet, suppress errors.
- -s            Show players currently playing.
- -W user:msg   Send message "msg" to all players. The message seems
-               to come from "user".
- -S            Free the shared memory block.
- -D            Show contents of the shared memory block.
-
-
-ENVIRONMENT VARIABLES
-=====================
-
- Linux telnetd allows importing the USER environment variables via telnet,
- while FreeBSD does not.  FreeBSD, on the other hand, does allow the LOGNAME
- environment variable.  Dgamelaunch will first check USER, then LOGNAME,
- for "username:password", and tries autologin if either exists.
- Dgamelaunch-specific DGLAUTH is checked before either of those.
-
-
-ERROR CODES
-===========
-
-   1   Could not terminate stale processes
-   2   Cannot chroot()
-   3   Cannot chdir()
-   4   Cannot setgroups()
-   5   Cannot setgid()
-   6   Cannot setuid()
-   7   Caught HUP
-   8   Cannot run as root: Config file has shed_user = "root"
-   9   Cannot run as root: Config file has shed_user set to UID 0 user.
-  10   Could not setup player
-  11   Cannot run as root: Config file has shed_uid = 0
-  12   Config file has an unrecognized token
-  13   Config file: Negative value not accepted
-  14   Cannot unshare()
-  15   dgamelaunch called with -c (login shell command); exited
-  20   No menu defined, or no banner found for menu
-  60   Cannot create a new terminal, or no termcap files.
-  61   Cannot openpty()
-  62   Cannot open /dev/ptmx
-  65   Cannot open master ptsname
-  68   Cannot fcntl inprogress-lock
-  70   Cannot write to inprogress-lock
-  71   ftok() error for shm_key, no "dgamelaunch" file found?
-  72   ftok() error for shm_sem_key, no "dgamelaunch" file found?
-  73   shmget() error, cannot connect to shared memory
-  74   smat() error, cannot attach to shared memory
-  75   Nothing in shared memory?
-  76   sem_init() error, could not initialize shared memory
-  77   sem_wait() error
-  78   sem_post() error
-  95   Cannot fnctl lockfile
-  96   sqlite3_open() failed when checking user existence: could not open login database
-  97   sqlite3_open() failed in writefile()
-  98   sqlite3_exec() failed in writefile()
-  99   Could not open password file
- 100   Username field too long in login file
- 101   Email field too long in login file
- 102   password field too long in login file
- 103   env field too long in login file
- 104   Cannot read config file
- 105   Cannot read default config file
- 106   Cannot open lockfile or password file
- 107   fcntl failed on login database in writefile()
- 108   sqlite3_exec() failed when checking user existence.
- 109   Too many registered users. (see maxusers setting in config file)
- 110   Login failed
- 111   Two users trying to register at the same time
- 112   Error changing password: cannot have ':' in password
- 113   Error parsing configuration file
- 114   exec-command fork failed
- 115   could not read lock file in writefile()
- 116   Too many registered users. (see maxusers setting in config file)
- 117   wall error: no message to send
- 118   wall error: no players
- 119   User has a retarded terminal
- 120   wall error: message too long
- 121   wall error: "from" username is too short
- 122   Error changing password: struct "me" does not exist
- 123   chdir() failed in dgl commands.
- 140   populate_games(): Cannot open inprogress-dir
- 145   populate_games(): Inprogress-filename does not have ':' in it
- 146   populate_games(): Inprogress-filename does not have ': in it (pt. 2)
- 200   purge_stale_locks(): could not open inprogress-dir
- 201   purge_stale_locks(): inprogress-file did not have ':' in it
- 202   purge_stale_locks(): could not read inprogress-file
- 203   purge_stale_locks(): could not get inprogress-file contents

diff --git a/README.md b/README.md
index 32f849fa6bcc5d232c711031949b769548ea2fa8..2e18d6ef88b1ff49e4d6aa65696d57b596dd2753 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,13 +1,15 @@
-The main feature of the master branch of this fork is install-dgl-nh500, which does what it says on the tin.
-It will fetch, compile, and install nethack 5.0.0, and do the same for DGL (although it is already fetched
-by the time you're using the script), and put them into a chroot of your choosing.
+The main feature of the master branch of this fork is install-dgl-nh500, which
+does what it says on the tin. It will fetch, compile, and install
+nethack 5.0.0, and do the same for DGL (although it is already fetched by the
+time you're using the script), and put them into a chroot of your choosing.
 
-autoconf branch is for making dgl's configure/makefile stuff work, without having to use these bash scripts
-people have written over the years.
+autoconf branch is for making dgl's configure/makefile stuff work, without
+having to use these bash scripts people have written over the years.
 
-I'm pretty interested in the history of this program -- so much so that I went through pains trying to make
-sure I was forking a version of the repository that contained accurate commit hashes -- crawl's fork has
-somehow mangled them such that its history appears entirely-unrelated to git.
+I'm pretty interested in the history of this program -- so much so that I went
+through pains trying to make sure I was forking a version of the repository
+that contained accurate commit hashes -- crawl's fork has somehow mangled them
+such that its history appears entirely-unrelated to git.
 
 Anyway, if you know anything of the history, reach out.
 
@@ -156,13 +158,14 @@ will not see a shell when it exits.
 Congrats on your new server...
 
 
-# Dungeon Crawl Stone Soup
-First, though, here's how to install Dungeon Crawl Stone Soup:
+# Hints
+## Dungeon Crawl Stone Soup
 1) obtain the source, navigate to that directory
-2) `sudo make install prefix=/ DATADIR=/etc/dcss0341 SAVEDIR=/var/dcss0341 USE_DGAMELAUNCH=1`
-Note: 2) instead of setting USE_DGAMELAUNCH, you can also edi
-`<src>/crawl-ref/source/AppHdr.h`, and `#define DGAMELAUNCH=1` there. (and tweak
-    other settings which interest you)
+2) ...
+```bash
+sudo make install prefix=/ DATADIR=/etc/dcss0341 \
+SAVEDIR=/var/dcss0341 USE_DGAMELAUNCH=1
+```
 3) navigate to the directory with these scripts (dgamelaunch source dir)
 4) ...
 ```bash
@@ -170,7 +173,8 @@ Note: 2) instead of setting USE_DGAMELAUNCH, you can also edi
 sudo cp /etc/dcss0341 /opt/dgamelaunch/etc/
 sudo cp /var/dcss0341 /opt/dgamelaunch/var/
 ```
-5) (clean up in `/bin/crawl`, `/etc/dcss0341`, `/var/dcss0341` if you want to; don't need those files anymore)
+5) (clean up in `/bin/crawl`, `/etc/dcss0341`, `/var/dcss0341` if you want to;
+don't need those files anymore)
 6) Modify `dgamelaunch.conf` to uncomment relevant lines
 7) ...
 ```bash
@@ -179,7 +183,19 @@ sudo chown -R games:games /opt/dgamelaunch/var
 ```
 8) Modify the main menu (it might help to `dcss-menu.patch` to it)
 
-That's it!
+## Angband
+1) obtain source, navigate to the directory
+2) ...
+```bash
+./configure --prefix=/. --bindir=/bin --datarootdir=/var --with-gamedata-in-lib
+```
+3) `make DESTDIR=/opt/dgamelaunch install`
+4) Try out `cpbin`, with `--libs-only`, to see if you can just automagically
+transfer libraries
+4a) otherwise do it by hand, check out the `ldd` command and other parts of
+this readme for more.
+5) Uncomment relevant lines in dgamelaunch.conf, and make/chown the inprogress
+dir
 
 # Resources
 More resources for troubleshooting vis NetHack:

diff --git a/dgamelaunch.8 b/dgamelaunch.8
deleted file mode 100644 (file)
index 87fe2a7..0000000
--- a/dgamelaunch.8
+++ /dev/null
@@ -1,152 +0,0 @@
-.TH DGAMELAUNCH 8 "17 March 2004" "joshk et al" "System Manager's Manual"
-.SH NAME
-dgamelaunch \- Network console game launcher
-.SH SYNOPSIS
-.na
-.hy 0
-.B dgamelaunch
-[
-.B \-h
-.I hostname
-]
-[
-.B \-f
-.I config
-]
-[
-.B \-q
-]
-[
-.B \-p
-]
-[
-.B \-a
-]
-[
-.B \-e
-]
-.ad
-.hy 14
-.SH DESCRIPTION
-.PP
-.I dgamelaunch
-is a network-based game shell where anyone can sign up for an
-account and start playing any game which suits your fancy - currently
-it supports NetHack and Slash'Em.
-
-The user is presented with a curses-based menu to watch other games, edit the
-options or play the game.
-
-.SH OPTIONS
-.TP
-.B
--f config
-Specify the location of the configuration file.
-.TP
-.B
--q
-Don't print errors pertaining to the server configuration.
-.TP
-.B
--a
-Enter user authentication mode.
-.I
-dgamelaunch
-will read user name and password from stdin, check them, check whether the
-user doesn't have a game in progress already, then write the inprogress lock.
-Returns 0 if everything was successful.
-.TP
-.B
--e
-Start game server to handle incoming NhExt connection.
-.I
-dgamelaunch
-will execute /bin/nethack --proxy after chroot and shedding privs.
-.TP
-.B
--p
-Ignored; solely for compatibility with
-.B
-login(1)
-.TP
-.B
--h hostname
-Ignored; solely for compatibility with
-.B
-login(1)
-.SH "CRASH RECOVERY"
-.PP
-If a user somehow disconnects in an unclean way,
-.I
-dgamelaunch
-will usually send nethack the SIGHUP signal, which causes nethack to save
-the game.
-.PP
-If a user tries to play while he already has a game in progress (for example
-because nethack hung),
-.I
-dgamelaunch
-will warn the user and send nethack the SIGHUP signal if the user agrees. If
-nethack does not shut down within 10 seconds,
-.I
-dgamelaunch
-will ask the user for permission to send it the SIGTERM signal, which causes
-nethack to terminate quickly (without leaving a savefile usually).
-.PP
-In some cases (e.g. at "Restoring save file...--More--") nethack doesn't leave
-a savefile if sent SIGHUP. To avoid loss of games,
-.I
-dgamelaunch
-can backup the savefile. A human must then restore the backup if necessary.
-This must be configured with the
-.B
-savefilefmt
-option in the configuration file.
-.SH AUTHORS
-.PP
-M. Drew Streib wrote the original version.
-.PP
-Later, Joshua Kwan, Brett Carrington and Jilles Tjoelker added many new
-features.
-.PP
-NhExt support was written by J. Ali Harlow.
-.SH FILES
-.DT
-.ta \w'dgldir/ttyrec/<login>/*.ttyrec\ \ \ 'u
-/etc/dgamelaunch.conf          Default configuration file (can
-                               be changed at compile time).
-.br
-.PP
-All other files are in the chroot as defined in the configuration file. Most
-of these filenames can be changed in the configuration file.
-.PP
-.DT
-.ta \w'dgldir/ttyrec/<login>/*.ttyrec\ \ \ 'u
-dgl-login              Login names, passwords and email
-                       addresses.
-.br
-dgl-lock               Lockfile for dgl-login, locked
-                       with fcntl(2).
-.br
-dgl-banner             Text shown on the screen.
-.br
-dgl-default-rcfile     Options file for new accounts.
-.br
-bin/nethack            The NetHack binary.
-.br
-dgldir/inprogress/*    A file for each game in progress;
-                       the file is locked (with fcntl(2))
-                       when the dgamelaunch process
-                       is still alive.
-.br
-dgldir/rcfiles/*       Options files.
-.br
-dgldir/ttyrec/<login>/*.ttyrec Recorded games, this may get
-                               very big very quickly.
-.\".SH ENVIRONMENT
-.SH "SEE ALSO"
-.PP
-nethack(6), slashem(6), telnetd(8), login(1), curses(3), fcntl(2)
-.SH BUGS
-.PP
-None known.

diff --git a/doc/README.bak b/doc/README.bak
new file mode 100644 (file)
index 0000000..241b804
--- /dev/null
+++ b/doc/README.bak
@@ -0,0 +1,247 @@
+dgamelaunch
+===========
+
+dgamelaunch is a network-based game shell where anyone can sign up for an
+account and start playing any game which suits your fancy - games known to
+work with dgamelaunch are for example NetHack (http://www.nethack.org) and
+Crawl (http://crawl.develz.org).
+
+
+DGAMELAUNCH VERSIONS
+====================
+
+Development version can be fetched from the source repository with git:
+
+  git clone git://github.com/paxed/dgamelaunch.git
+
+Releases are downloadable at http://alt.org/nethack/dgamelaunch/
+
+
+REQUIREMENTS
+============
+
+- normal development tools (make, etc)
+- autotools (autogen, autoconf, automake)
+- ncurses library and development files
+- bison (or yacc or byacc)
+- flex (or lex)
+- optionally sqlite3 library and development files
+
+
+COMPILING
+=========
+
+Basically all you have to do is:
+
+  ./autogen.sh && make
+
+Some options you might want give to autogen:
+
+ --with-config-file=/absolute/path/to/dgamelaunch.config
+ --enable-shmem
+ --enable-sqlite
+
+
+Dgamelaunch should compile without issue on Linux, Solaris, FreeBSD 4 and 5.
+(Whether it _runs_ on all of these platforms is a different issue. We'd
+like to hear about it.)
+
+dgamelaunch was originally developed by M. Drew Streib <dtype@dtype.org> but
+is now a collaborative project. Copyright and contact information is in the
+COPYING file, included with this package.
+
+
+BASIC SETUP INSTRUCTIONS
+========================
+
+These instructions are not current. For a more up-to-date ones, see
+http://nethackwiki.com/wiki/User:Paxed/HowTo_setup_dgamelaunch
+
+
+
+
+1) Setup a chroot jail. There is a helpful script included to accomplish this,
+called dgl-create-chroot, in the source directory. The default settings are
+viewable by editing the script; to customize the installation, look at
+dgl-create-chroot.conf.example.* (also in the source directory) and edit it to
+suit your needs, and save it into the same directory as dgl-create-chroot as
+dgl-create-chroot.conf. It's very likely you need to run the script as root.
+The script will not work with the very limited System V /bin/sh, such found on
+Solaris; start it with ksh instead.
+
+If you decide to not use dgl-create-chroot, you're on your own and we assume
+you have enough clue to figure out exactly what's needed for the chroot to
+operate correctly.
+
+2) Compile nethack. Make sure the directories in the chroot match up with
+where nethack thinks everything is. You may need to edit the VAR_PLAYGROUND
+variable in include/unixconf.h and/or the HACKDIR variable in include/config.h.
+
+(Note: Try not to, for security, to put anything else in the chroot. You may
+need to put gzip in there though if you compile nethack to use it for 
+compression.)
+
+3) Make a copy of dgamelaunch.conf and edit it. This will contain information
+for dgamelaunch about what uid/username, gid/group to shed privileges to at
+runtime. It must also contain the path to nethack, and needs to know certain
+aspects of your chroot.
+
+Note that using a username in dgamelaunch.conf will cause (part of) your
+passwd database to be loaded into dgamelaunch's memory space. If you use BSD,
+this will also include encrypted passwords. Therefore, it's recommended to
+put the uid in the dgamelaunch.conf. The same applies to groups, but openpty(3)
+often looks up the tty group anyway.
+
+4) Setup dgamelaunch as one of the following:
+        a) The shell for a single login.
+        b) An (x)inetd service.
+
+If you choose a login shell make sure dgamelaunch is setuid root. (that is,
+chmod 4755 dgamelaunch.) It will shed privs right after entering the chroot
+jail though.
+
+Example xinetd lines:
+
+service telnet
+{
+  socket_type     = stream
+  protocol  = tcp
+  wait      = no
+  user      = root
+  server    = /usr/sbin/in.telnetd
+  server_args     = -h -L /opt/nethack/nethack.dtype.org/dgamelaunch -q -f /etc/dgamelaunch.conf
+  rlimit_cpu      = 3600
+  bind      = 64.71.163.206
+}
+
+A classic inetd line would look like this:
+
+telnet stream tcp nowait root.root /usr/sbin/tcpd /usr/sbin/in.telnetd -h -L /usr/sbin/dgamelaunch -q -f /etc/dgamelaunch.conf
+
+In both cases, the -L specifies an alternate login program (telnetlogin is
+invoked by default) and -h prevents revealing of a login banner (for 
+example, "Debian GNU/Linux testing/unstable influx") before starting the
+login shell.
+
+It goes without saying that the argument after -L must point to dgamelaunch's
+exact location. Also, the location of dgamelaunch.conf is variable and of
+course should be customized by you.
+
+NOTE: It appears that the -L option is not very widely supported. FreeBSD's
+telnetd uses -p instead, and you can't give arguments (arguments appropriate
+to standard login are used). Some other telnetds do not support anything
+like this at all.
+
+The -f option, followed by a filename, specifies the path to the config file
+to use for dgamelaunch.  If you specify the right path for DEFCONFIG in the
+Makefile, you may be able to omit this.
+
+For dgamelaunch, the -q option will silence errors pertaining to the server
+configuration. This is recommended for use within inetd to prevent spamming
+the clients, but when testing and setting up we strongly suggest you leave it
+off until running dgamelaunch produces no error output on stderr.
+
+5) Test your compilation of dgamelaunch by running it as root. If this
+works, a shell login or (x)inetd will work with the correct configuration.
+If you have problems with dgamelaunch's display make sure that your chroot's
+/etc/terminfo directory (or whatever directory your ncurses uses) is
+populated.
+
+
+COMMANDLINE PARAMETERS
+======================
+
+ -a            Ignored.
+ -c            Shows error message and exits. (login shell command)
+ -e            Ignored.
+ -h            Ignored.
+ -i user       Autologin and run the register -command hook for "user"
+               (with password "user").
+ -p            Ignored.
+ -q            Be quiet, suppress errors.
+ -s            Show players currently playing.
+ -W user:msg   Send message "msg" to all players. The message seems
+               to come from "user".
+ -S            Free the shared memory block.
+ -D            Show contents of the shared memory block.
+
+
+ENVIRONMENT VARIABLES
+=====================
+
+ Linux telnetd allows importing the USER environment variables via telnet,
+ while FreeBSD does not.  FreeBSD, on the other hand, does allow the LOGNAME
+ environment variable.  Dgamelaunch will first check USER, then LOGNAME,
+ for "username:password", and tries autologin if either exists.
+ Dgamelaunch-specific DGLAUTH is checked before either of those.
+
+
+ERROR CODES
+===========
+
+   1   Could not terminate stale processes
+   2   Cannot chroot()
+   3   Cannot chdir()
+   4   Cannot setgroups()
+   5   Cannot setgid()
+   6   Cannot setuid()
+   7   Caught HUP
+   8   Cannot run as root: Config file has shed_user = "root"
+   9   Cannot run as root: Config file has shed_user set to UID 0 user.
+  10   Could not setup player
+  11   Cannot run as root: Config file has shed_uid = 0
+  12   Config file has an unrecognized token
+  13   Config file: Negative value not accepted
+  14   Cannot unshare()
+  15   dgamelaunch called with -c (login shell command); exited
+  20   No menu defined, or no banner found for menu
+  60   Cannot create a new terminal, or no termcap files.
+  61   Cannot openpty()
+  62   Cannot open /dev/ptmx
+  65   Cannot open master ptsname
+  68   Cannot fcntl inprogress-lock
+  70   Cannot write to inprogress-lock
+  71   ftok() error for shm_key, no "dgamelaunch" file found?
+  72   ftok() error for shm_sem_key, no "dgamelaunch" file found?
+  73   shmget() error, cannot connect to shared memory
+  74   smat() error, cannot attach to shared memory
+  75   Nothing in shared memory?
+  76   sem_init() error, could not initialize shared memory
+  77   sem_wait() error
+  78   sem_post() error
+  95   Cannot fnctl lockfile
+  96   sqlite3_open() failed when checking user existence: could not open login database
+  97   sqlite3_open() failed in writefile()
+  98   sqlite3_exec() failed in writefile()
+  99   Could not open password file
+ 100   Username field too long in login file
+ 101   Email field too long in login file
+ 102   password field too long in login file
+ 103   env field too long in login file
+ 104   Cannot read config file
+ 105   Cannot read default config file
+ 106   Cannot open lockfile or password file
+ 107   fcntl failed on login database in writefile()
+ 108   sqlite3_exec() failed when checking user existence.
+ 109   Too many registered users. (see maxusers setting in config file)
+ 110   Login failed
+ 111   Two users trying to register at the same time
+ 112   Error changing password: cannot have ':' in password
+ 113   Error parsing configuration file
+ 114   exec-command fork failed
+ 115   could not read lock file in writefile()
+ 116   Too many registered users. (see maxusers setting in config file)
+ 117   wall error: no message to send
+ 118   wall error: no players
+ 119   User has a retarded terminal
+ 120   wall error: message too long
+ 121   wall error: "from" username is too short
+ 122   Error changing password: struct "me" does not exist
+ 123   chdir() failed in dgl commands.
+ 140   populate_games(): Cannot open inprogress-dir
+ 145   populate_games(): Inprogress-filename does not have ':' in it
+ 146   populate_games(): Inprogress-filename does not have ': in it (pt. 2)
+ 200   purge_stale_locks(): could not open inprogress-dir
+ 201   purge_stale_locks(): inprogress-file did not have ':' in it
+ 202   purge_stale_locks(): could not read inprogress-file
+ 203   purge_stale_locks(): could not get inprogress-file contents

diff --git a/doc/dgamelaunch.8 b/doc/dgamelaunch.8
new file mode 100644 (file)
index 0000000..87fe2a7
--- /dev/null
+++ b/doc/dgamelaunch.8
@@ -0,0 +1,152 @@
+.TH DGAMELAUNCH 8 "17 March 2004" "joshk et al" "System Manager's Manual"
+.SH NAME
+dgamelaunch \- Network console game launcher
+.SH SYNOPSIS
+.na
+.hy 0
+.B dgamelaunch
+[
+.B \-h
+.I hostname
+]
+[
+.B \-f
+.I config
+]
+[
+.B \-q
+]
+[
+.B \-p
+]
+[
+.B \-a
+]
+[
+.B \-e
+]
+.ad
+.hy 14
+.SH DESCRIPTION
+.PP
+.I dgamelaunch
+is a network-based game shell where anyone can sign up for an
+account and start playing any game which suits your fancy - currently
+it supports NetHack and Slash'Em.
+
+The user is presented with a curses-based menu to watch other games, edit the
+options or play the game.
+
+.SH OPTIONS
+.TP
+.B
+-f config
+Specify the location of the configuration file.
+.TP
+.B
+-q
+Don't print errors pertaining to the server configuration.
+.TP
+.B
+-a
+Enter user authentication mode.
+.I
+dgamelaunch
+will read user name and password from stdin, check them, check whether the
+user doesn't have a game in progress already, then write the inprogress lock.
+Returns 0 if everything was successful.
+.TP
+.B
+-e
+Start game server to handle incoming NhExt connection.
+.I
+dgamelaunch
+will execute /bin/nethack --proxy after chroot and shedding privs.
+.TP
+.B
+-p
+Ignored; solely for compatibility with
+.B
+login(1)
+.TP
+.B
+-h hostname
+Ignored; solely for compatibility with
+.B
+login(1)
+.SH "CRASH RECOVERY"
+.PP
+If a user somehow disconnects in an unclean way,
+.I
+dgamelaunch
+will usually send nethack the SIGHUP signal, which causes nethack to save
+the game.
+.PP
+If a user tries to play while he already has a game in progress (for example
+because nethack hung),
+.I
+dgamelaunch
+will warn the user and send nethack the SIGHUP signal if the user agrees. If
+nethack does not shut down within 10 seconds,
+.I
+dgamelaunch
+will ask the user for permission to send it the SIGTERM signal, which causes
+nethack to terminate quickly (without leaving a savefile usually).
+.PP
+In some cases (e.g. at "Restoring save file...--More--") nethack doesn't leave
+a savefile if sent SIGHUP. To avoid loss of games,
+.I
+dgamelaunch
+can backup the savefile. A human must then restore the backup if necessary.
+This must be configured with the
+.B
+savefilefmt
+option in the configuration file.
+.SH AUTHORS
+.PP
+M. Drew Streib wrote the original version.
+.PP
+Later, Joshua Kwan, Brett Carrington and Jilles Tjoelker added many new
+features.
+.PP
+NhExt support was written by J. Ali Harlow.
+.SH FILES
+.DT
+.ta \w'dgldir/ttyrec/<login>/*.ttyrec\ \ \ 'u
+/etc/dgamelaunch.conf          Default configuration file (can
+                               be changed at compile time).
+.br
+.PP
+All other files are in the chroot as defined in the configuration file. Most
+of these filenames can be changed in the configuration file.
+.PP
+.DT
+.ta \w'dgldir/ttyrec/<login>/*.ttyrec\ \ \ 'u
+dgl-login              Login names, passwords and email
+                       addresses.
+.br
+dgl-lock               Lockfile for dgl-login, locked
+                       with fcntl(2).
+.br
+dgl-banner             Text shown on the screen.
+.br
+dgl-default-rcfile     Options file for new accounts.
+.br
+bin/nethack            The NetHack binary.
+.br
+dgldir/inprogress/*    A file for each game in progress;
+                       the file is locked (with fcntl(2))
+                       when the dgamelaunch process
+                       is still alive.
+.br
+dgldir/rcfiles/*       Options files.
+.br
+dgldir/ttyrec/<login>/*.ttyrec Recorded games, this may get
+                               very big very quickly.
+.\".SH ENVIRONMENT
+.SH "SEE ALSO"
+.PP
+nethack(6), slashem(6), telnetd(8), login(1), curses(3), fcntl(2)
+.SH BUGS
+.PP
+None known.

diff --git a/doc/history.md b/doc/history.md
new file mode 100644 (file)
index 0000000..3d29394
--- /dev/null
+++ b/doc/history.md
@@ -0,0 +1,16 @@
+# History
+This is not an exhaustive or particularly-well-researched history, but I felt a desire to put it all in one place. Both what _very_ little I know about the history of the thing itself, and a bit about the git repo's history since I have direct access to that.
+
+I find git histories pretty interesting in general. I kind of botched this one at first, ngl. A reckless fast-forward and there's all this junk. But anyway, here's what I know.
+
+## Origin
+```
+ dgamelaunch is copyright (C) 2001-2003 M. Drew Streib
+ also parts (C) 2003-4 Joshua Kwan <joshk@triplehelix.org>,
+ Brett Carrington <brettcar@segvio.org>,
+ Jilles Tjoelker <jilles@stack.nl>
+```
+
+I have done no research here except to know that there's nothing of the original original repos around on a cursory search.
+
+## paxed

diff --git a/doc/wiki b/doc/wiki
new file mode 160000 (submodule)
index 0000000..c31b532
--- /dev/null
+++ b/doc/wiki
@@ -0,0 +1 @@
+Subproject commit c31b532862ffb7e1d964b25ea088dfe6527a58b4