Systems Authentication Process - Unix
-------------------------------------

This program is an external authentication process, it uses Netwin
standards for external authentication. Documentation on this standard
can be found in the Dmail Mail Server manual at 
http://www.netwinsite.com/dmail/manual.htm

Contents
--------

1. Ini Settings.
2. Error codes.
3. Output.

-----------------------------------------------------------------------
1. Ini settings

General
-------
  path <path>        Path sets the path for locating the ini file, and
                     also determines where the log file will be created.
                     For example running sysauth -path \here will cause
                     it to load the sysauth.ini file from the \here directory
                     if in the \here\sysauth.ini file there is a path
                     setting sysauth will then create it's log file in the
                     new directory.

  log <level>        This setting can be used as just "log" or you can specify
                     a level of logging like so, "log debug" or "-log debug".
                     It has three valid logging levels error, info, and debug.

  debug              This setting causes sysauth to run with logging set to
                     debug mode, it is equivalent to a "log debug" or "-log debug".

  group <name>       This specifies the group that user created will belong to,
                     this group must belong on the host the users are being
                     added to. This can be a string or on Unix a GID.

  script_path        Path to the shell files, any shell setting must exist 
                     in this path, there is no default for this, if no setting 
                     is found shell settings are assumed to be from the root.

  uname		     Set default "name" field, automatically set to "Unix Auth <version> User".

  shell              Default "shell" field. Automatically set to "/bin/bash".

  base_uid           Base number to start adding new UID's. Automatically set to "100".

  home_path          Default base-directory for "home" field. Actual "home" field
                     is set to <base>/<username>. i.e. /home/root. Automatically
                     set to "/home"

EXAMPLE unix ini file <sysauth.ini>
  path /usr/local/dmail
  log error
  group users
  base_uid 500
-----------------------------------------------------------------------
2. Error codes

These errors were written in an attempt to be descriptive enough so that
you could problem solve without too much hassle. If you are completely
stumped and have no idea why you are recieving an error then it could be
our fault entirely :-), so simply email the error and what you were trying
to do at "Sysauth Help" <support-netauth@netwinsite.com>

"-ERR ##:Unknown error has occurred."
  There was an error. We need the error number ## to determine what went
  wrong.

"-ERR Not a valid command (nocommand) use help"
  You didn't enter a command.

"-ERR Not a valid command (<command>) use "help""
  You entered <command> which was not recognised by sysauth as a valid
  command.

"-DEAD Unable to open {<file>,<reason>}"
"-DEAD Error with open of password file {<file>,<reason>}"
"-DEAD Unable to open password file {<file>,<reason>}"
"-DEAD Error with open of group file {<file>,<reason>}"
"-DEAD Unable to open temporary file {<file>,<reason>}"
"-DEAD Error with lock of password file {<file>,<reason>}."
"-DEAD Error with un-lock of password file {<file>, <reason>}."
"-DEAD Unable to create init.log, <reason>"
  Sysauth couldn't open / close the required file <file> for <reason>.

"-DEAD Error with lock of password file {<file>,<reason>}."
  Unable to obtain a lock for the <file>, for <reason>.

"-DEAD Unable to close log file {<reason>}"
  Sysauth could not close it's log file for <reason>.

"-ERR Error writing current entries {<reason>}."
  Sysauth encountered an error while trying to copy entries in the 
  password and/or group file.

"-ERR Error removing current password file, <reason>"
  Sysauth could not remove old copy of password file.

"-ERR Error copying temporary file -> password file, <reason>"
  Sysauth could not replace the password file with an updated copy.

"-DEAD No more UID's available."
  Sysauth could not locate a free UID.

"-ERR Invalid user info parameter."
  Either the home directory, name and / or shell parameter is in error.

"-ERR Unknown error occurred."
  Something strange has happened.

"-ERR Home directory must exist."
  The home directory given must exist.

"-ERR setting <setting> incorrect"
  The format of setting <setting> was incorrect, user setting="value".

"-ERR Shell must exist."
  The shell file given must exist.

"-ERR Unknown user info {<setting>}"
  The <setting> was an unknown user setting.

"-ERR Error locating GID for {<group>}, group does not exist."
  The group <group> could not be found.
-----------------------------------------------------------------------
3. Output

The reply messages are part of the Netwin standard.

Command          Message
-------          -------
set, set         +OK User <name> added to the database

del              +OK Deleted user successfully

lookup           +OK <user> config 0 <info>
                 -ERR <user> not found

check            +OK <user> config 0 <info>
                 -ERR <user> password wrong or not a valid user

search           +DATA ...
                 +DATA ...
                 +OK search complete <number> items found

version          +OK NT Auth version <version number>

help             +DATA Valid commands
                 +DATA   <command>
                 +DATA   <command>
                 +DATA   <command>
                 +OK

