Functional Requirements for SNFMilterConfig

$Id: SNFMilterConfigRequirements.txt,v 1.6 2012/05/19 00:37:12 adeniz Exp $

This note specifies the requirements SNFMilterConfig, a command-line
utility to integrate SNFMilter an MTA.

Functional requirements
-----------------------

  SNFMilterConfig has four main functional capabilities:

    1) Repair/setup.  This directs SNFMilterConfig to copy any missing
       configuration files from the sample files.  SNFMilterConfig
       doesn't check for corrupted configuration files.

       When repairing the credentials (identity.xml and getRulebase),
       SNFMilterConfig does the following:

       a) If only one file exists, copy the other from the sample file,
       	and propagate the credentials from the file that exists to the
       	new file.

       b) If both files exist but the credentials are not consistent,
       	propagate the non-testmode credentials from one file to the
       	other.  If both are non-testmode, copy the credentials from
       	identity.xml to getRulebase.

       c) If neither file exists, copy from the sample files.

       d) Otherwise, both files exist and are consistent; do nothing.

    2) Integrate/unintegrate.  This directs SNFMilterConfig to integrate
       with the specified MTA, or to unintegrate from all supported
       MTAs.

    3) Specify credentials.  This directs SNFMilterConfig to update the
       identity.xml and getRulebase files with the specified
       credentials.  The credentials are updated as follows:

       a) Update getRulebase.

       b) Download the rulebase.

       c) Update identity.xml.

    4) Start/stop SNFMilter.  This directs SNFMilterConfig to start or
       stop SNFMilter.  SNFMilterConfig determines whether or not the
       action was successful and that SNFMilter is running as follows:

       a) If SNFMilter is configured to use the XCI interface,
          SNFMilterConfig attempts to communicate with SNFMilter using
          the XCI interface.

       b) Otherwise, if SNFMilter is configured to update the status log
          every second, SNFMilterConfig checks whether the status.second
          log is updated after several seconds.

       c) Otherwise, if SNFMilter is configured to update the status log
          every minute, SNFMilterConfig checks whether the status.minute
          log is updated after a time period sufficiently longer than
          one minute.

       d) Otherwise, SNFMilterConfig outputs an advisory message.

  These functions are independent.  For example, specifying credentials
  will not create any configuration files that don't exist.

  If an error occurs, SNFMilterConfig does the following:

    1) Restores the state of the configuration files, and

    2) Saves a copy of the new configuration files that resulted
       in the failure in a file with the same name as the configuration
       file, but appended with ".failed".

  If an error does not occur, any ".failed" files from a previous run on
  SNFMilterConfig are deleted.

  The configuration file back and restore is progressive; files are
  backed up as they are modified.

  Command-line interface
----------------------

  SNFMilterConfig requires exactly one of the following sets of
  command-line parameters:

    1) "-repair" or "-setup".  Repair/setup the configuration.

    2) "-mta=SPEC", where SPEC is "postfix", "sendmail", or "none".
       Integrate with postfix, sendmail, or unintegrate with postfix and
       sendmail, respectively.

    3) "-auth=AUTH" and "-id=LICENSE", in any order.  Specify the
       credentials.

    4) "-start" or "-stop".  Start or stop SNFMilter.

    5) "-explain".  Output a description of each step as the step is
       executed.

    6) "-verbose".  Output a description of each step that would be
       executed, but not execute any steps.

  If no command-line arguments are specified, SNFMilterConfig outputs a
  help message that includes the version, and then exists.

Integration with MTAs
---------------------
  postfix--

    1) Add/remove milter specification in main.cf.

    2) Make postfix a member of snfuser ("usermod -G snfuser postfix"
       for RedHat).

    3) Create the socket and any parent directories.

  sendmail--

    1) Add/remove milter specification in sendmail.mc.

    2) Run "make" to create sendmail.cf.

    3) Create the socket and any parent directories.

Return status
-------------

  SNFMilterConfig returns 0 if the specified action was completed with
  no detected error.  If an error was detected, either in completing
  the specified action or in the command-line arguments,
  SNFMilterConfig returns -1.

Output
------

  If an error is encountered, SNFMilterConfig outputs a description of
  the error encountered.

Non-functional requirements
---------------------------

  Exit status is 0 of success with no detected error, -1 if an error
  is detected.

  When modifying files, SNFMilterConfig includes comments documenting
  the changes and the name of the program.