Requirements as of May 13, 2012.

git-svn-id: https://svn.microneil.com/svn/SNFUtility/trunk@14 aa37657e-1934-4a5f-aa6d-2d8eab27ff7c

SNFMilterConfig/SNFMilterConfigRequirements.txt

@@ -0,0 +1,149 @@
+	     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.