INSTALL

This document describes how to build and install the Phoenix CMC server.
See the "INSTALL.generic" file for generic build instructions for using
the "configure" script generated by Autoconf.

Use "./configure --help" to see the configuration options available.  Use
"./configure" alone to configure with the defaults.  After configuring,
build the server with "make" and install it with "make install".  Include
the "--prefix" option if an installation prefix other than "/usr/local" is
desired.  (For users without root access, the user's home directory could
be used as the prefix.)

The default TCP port number is 9999.  Use the "--enable-port" configure
option to change this.  For example, "--enable-port=23" will use the
standard port for the TELNET protocol.  This would require running the
server as root to bind to the privileged port.  There is currently no code
to give up root privileges, so use caution.  If a port number over 1024 is
used, any user can run the server.

If a "guest" login is not desired, use the "--disable-guest" option.

If any errors occur during the build, please create a new GitHub issue with
relevant information:

     https://github.com/deven/phoenix/issues

By default, the server is installed as "/usr/local/sbin/phoenixd", and the
"makepw" utility program is installed as "/usr/local/bin/makepw".  Logs and
the "passwd" file are stored in "/usr/local/lib/phoenix".  The "passwd"
file in the distribution may be used as an example.  (Since the password file
is read dynamically when needed, there is no need to restart the server after
modifying the password file.)

Copy the example password file to "/usr/local/lib/phoenix/passwd" and edit
it to create server accounts.  The default file contains a (commented-out)
sample administrative account for the author.  The field containing "100" is
a privilege level (NOT a user ID number!) -- guest users have a privilege
level of 0 (and are not allowed to detach), while normal users should have a
privilege level of 10.  Only administrative users should have a privilege
level as high as 100; they are allowed to nuke user sessions and shut down
the server, etc.

If the password file is not found, only accounts hardcoded in "user.cc" will
work until a password file is put in place.  By default, this is the "guest"
account only, but administrative and/or accounts could easily be added also.

The server accepts a "--cron" option, which was was designed to run once per
minute from cron, to ensure that the server remains running.  With the --cron
option, the server will silently exit if it CANNOT bind to its port, on the
assumption that another server is already running.  If the server can bind
to the port, it will startup normally.  To use this option, add cron job such
as "* * * * * /usr/local/sbin/phoenixd --cron" to the crontab of the user to
run the server under.

The "makepw" program is a simple utility to encrypt Unix-style passwords,
either by prompting for input or taking a cleartext password as an argument.
This is a straightforward way to apply crypt(3) encryption to passwords for
use in the password file.