                                  xnew v0.4a
                                  2 Mar 1998


                               Table of Contents

   I..........................................................Introduction
  II..........................................................Compiling
 III..........................................................Configuring
  IV..........................................................Modules
   V..........................................................Security
  VI..........................................................Design Notes
 VII..........................................................Contacts
 IIX..........................................................Acknowledgements


I. Introduction

Xnew is a highly configurable and modular set of programs that was written to
be a portable and easily maintainable method for people to request accounts
on a UNIX system.  There are undoubetly other tasks that xnew could be used
for, but the focus of xnew is a new account request or newuser system.

The main strength of xnew is its modular design.  This is also, however, a
drawback in that xnew is not "Plug-and-Play."  For more details about the
design, see Section VII.

Xnew is currently in the ALPHA testing stage.  What this means is that
features are missing and there may be bugs in the program.  The documentation
is also sketchy or incomplete.  If you want to use this program in a non-
testing environment, please wait until version 1.0 is released.


II. Compiling

Xnew was written on the Linux operating system, but should compile on other
brands of *NIX with a standard C compiler.  To compile xnew, follow these
steps:

1. Visit http://www.xenos.net/~xenon/software/xnew to get the latest version.
2. Unpack the source somewhere on the system that will be used to compile it.
   If you downloaded xnew-0.4a.tar.gz, entering

     gzip -d -c xnew-0.4a.tar.gz | tar xf -

   should decompress the package.  If you downloaded xnew-0.4a.tar.Z, then

     uncompress -c xnew-0.4a.tar.Z | tar xf -

   should decompress the package.  After unpacking the source, you will have a
   directory called xnew-0.4a.  Change into that directory, (e.g. type cd
   xnew-0.4a).
3. (optional) Edit config.h and change anything necessary.
4. (optional) Edit Makefile and change anything necessary.
5. Type make.  There should be no warnings or errors.
6. Go to the modules directory and read the README in there to find out how
   to compile and install the supplied modules.

You should now have an executable called xnew and a set of modules to work
with.


III. Configuring

Xnew is configured by creating a script that tells xnew what to do.  The
default script file is defined in config.h.  To tell xnew to use another
script besides the default one, you can use the -f argument to xnew to specify
the name of the script to use.

The configure script takes the following form:

# This is a sample configuration file for xnew.

# Blank lines and lines begining with a # mark are ignored.  Leading and
# trailing spaces are also ignored.  Comments can be inserted at the end
# of a line as well as long as there is at least one space seperating the
# comment mark, (the # character), and the last character of the command.

# Each line in this file may take one of the following forms:
#
# <module> [argument [argument ...]]
# system <argument> [argument [argument ...]]
# exec <argument> [argument [argument ...]]
# set <argument> [argument]
# <while loop>
# <if conditional>
# user <argument>

# Arguments may contain any number of arguments to pass to the program or
# module being called as long as the arguments do not begin with a #
# character.  They may be any of the following:
#
# &<module>   - This means to use the return value of the module <module> as
#               the argument.  For example, if you called a module called
#               get_login, the argument &get_login would expand to whatever
#               value the get_login module returned, (or "NULL" if none).
# $<variable> - This inserts the value of <variable> as the argument.  See
#               the section about variables below to find out how to define
#               and manipulate them.
# NULL        - This is used to specify a NULL (empty) argument.
# <string>    - Any other string is treated literally.

# Modules are special, stand-alone programs, that take specific arguments and
# may return values back to xnew.  For more information about modules, please
# see the README and modules/README files.

# A system command is any command that is not a module.  You can NOT use the
# output of a system command as an argument to another command from within the
# xnew program.  The argument to a system command is the command to execute.
# You should always include a full path for these commands.

# The exec command is similar to the system command except the command run
# overlays the xnew program.  In other words, as soon as an exec is issued,
# the command it calls takes over and the current invocation of xnew is no
# longer in memory.

# While loops are implemented with the following construct:
#
# while <arg1> <op> <arg2>
# [command lines]
# done
#
# <arg1> and <arg2> - Arguments as defined above.
# <op>              - Any one of the following:
#                     =  - Equal          != - Not equal
#                     >  - Greater than   >= - Greater than or equal to
#                     <  - Less than      <= - Less than or equal to

# If conditionals are implemented with the following construct:
#
# if <arg1> <op> <arg2>
# [command lines]
# [else
# [command lines]]
# fi
#
# <arg1>, <arg2>, and <op> are the same as for the while command.  The else
# may or may not be included.  An fi is needed at the end of the if.

# Other built-in commands:
#
# user <argument>
#   Changes the EUID of the program to the value of <argument>.
#
# set <argument> [argument]
#   Sets the environment variable as given by the first argument to the value
#   given by the second argument.  If the value argument is not given or
#   defined, then the environment variable is cleared from the environment.
#   The following values for the first argument have special meanings:
#
#     erase - Set the current erase (delete) key to the value of the second
#             argument.

To explain this further, each line in the xnew script, (that is not a comment
or a blank line), is treated as a command to run.  Modules are run by giving
the name of the module as the first argument on a line.  Regular programs can
be run by starting the line with the word system, (or exec if you want the
external program to "take over"), followed by the full name, (including the
path), of the command to run.

When a module is run, the results that it returns can be accessed by other
modules or system commands by giving the module name preceeded by a &
character as an argument.  For example, if you call a module called get_login
and then want to use the result it returned as the first argument to the
module check_login, the following line would be entered:

  check_login &get_login

Currently, the configuration script is unforgiving of commands that do not
strictly conform to the configuration language.  For example, you must enter
a space on either side of a loop or conditional operator.

A full example configuration file, (which is in use on at least one system),
can be found in the sample_xnew.config file.


IV. Modules

Modules are C normal programs that take as the first argument a file to
return all of their data through.  A skeleton modules is as follows:

#include <stdio.h>

main(int argc, char *argv[]) {
  FILE *ofp;

  /* Make sure we got at least one argument (the pipe to write to) */
  if (argc <= 1)
    exit(1);

  /* Open the file for writing */
  if ((ofp = fopen(argv[1], "w")) == NULL) {
    fprintf(stderr, "Error: Child %s unable to access file %s\n", argv[0],
            argv[1]);
    exit(1);
  }

  /* Do all of your processing here */

  /* Write the return data to the file.  For example: */
  /* fprintf(ofp, "<return_data>");                   */

  /* Close the file */
  fclose(ofp);
}

For more information about modules, read the README file in the modules
directory.


V. Security

Although xnew is designed to be rhobust as possible, there may be flaws in the
design that can be exploited by attackers to gain unauthorized access or mess
with the xnew process.  If you are worried about possible security flaws,
please wait until this program has been tested more and is no longer in the
ALPHA stage.  This is no guarantee that flaws will not exist, however.  On the
other hand, xnew has been in heavy use on at least one system without any ill
effects.

Xnew is installed by default to be SUID root.  This is so the password file
can be updated and the login program can be run after the new account is
made.  Even though temporary files are (hopefully) created securely, it is a
good idea to use the user command to switch to an unprivleged user ID while
root access is not needed.  Use the user command to switch back to running as
root when the password file and login need to be run.


VI. Design Notes

Xnew was created to meet the following goals:

1. Configurability: Xnew should be easily configurable by administrators
2. Security: Xnew should be able to graciously handle all sorts of input from
   users and administrators and not be exploitable.
3. Portability: Xnew should be portable to a wide range of systems and account
   adding procedures.


VII. Contacts

All comments, questions, and bug reports can be sent to Karyl F. Stein via
E-Mail to xenon@xenos.net.  If you are submitting a bug report, please be sure
to include the operating system and compiler being used as well as all error
messages; the more details the better.


IIX. Acknowledgements

Thanks go to:

* Ernie Hershey IV <casper@arbornet.org> for discussions about the design
  philosophy.
