SNFUtility/Common/UtilityConfig.hpp

// UtilityConfig.hpp
//
// Copyright (C) 2011 ARM Research Labs, LLC.
// See www.armresearch.com for the copyright terms.
//
// This file defines the interface used by the configuration utilities.
//

#ifndef UtilityConfighpp_included
#define UtilityConfighpp_included

#include <string>

#include "SNFMulti.hpp"
#include "Utility.hpp"
#include "FileBackup.hpp"

/// Base class for the Sniffer configuration.
//
// This class provides capability common to the configuration applications.
//
//////////////////////////////////////////////////////////////////////////////////////////////////////////
class UtilityConfig : public Utility {

public:

    /// Running status of the Sniffer application.
    enum SnifferRunningStateEnum {
	SnifferIsRunning, ///< Sniffer is running.
	SnifferIsStopped ///< Sniffer is not running.
    };

    /// Default constructor.
    UtilityConfig(void);

    /// Object to back up and restore files.
    FileBackup SaveFile;

    /// If the configuration file doesn't exist, create it from the
    /// sample file.  In any case, set the owner and mode.
    //
    // This method creates the default configuration file if the
    // specified configuration file doesn't exist.
    //
    // The method SetConfigFileName must be called before this
    // method.
    //
    // \param[in] SampleConfigFile is the name of the sample
    // configuration file.
    //
    void CreateDefaultConfigFile(std::string SampleConfigFile);

    /// Setup/repair the configuration.
    //
    // This method creates any configuration files that don't exist
    // from the sample files.
    void SetupCreate(void);

    /// Load the configuration from the file specified by SetConfigFileName.
    //
    void LoadConfig(void);

    /// Set the configuration file name.
    //
    // \param[in] Name is the name of the configuration file.
    //
    void SetConfigFileName(std::string Name);

    /// Get the configuration file name.
    //
    // \returns the name of the configuration file.
    //
    std::string GetConfigFileName(void);

    /// Get the contents of the <platform> element of the loaded
    /// config file.
    //
    // \returns the contents of the <platform> element.
    //
    std::string GetPlatformContents(void);

    /// Get the workspace path.
    //
    // \returns the workspace path.
    std::string GetWorkspacePath(void);

    /// Get the rulebase path.
    //
    // \returns the rulebase path.
    std::string GetRulebasePath(void);

    /// Get the log path.
    //
    // \returns the log path.
    std::string GetLogPath(void);

    /// Get the status.second log file name.
    //
    // \returns the status.second log file name.
    std::string GetStatusSecondLogFileName(void);

    /// Get the status.minute log file name.
    //
    // \returns the status.minute log file name.
    std::string GetStatusMinuteLogFileName(void);

    /// Append the datestamp to the log file name if configured.
    //
    // \param[in, out] FileBaseName is the log file name up to and not
    // including any datestamp.
    //
    void AppendDatestampToLogFileName(std::string *FileBaseName);

    /// Get the identity file name.
    //
    // \returns the identity file name.
    std::string GetIdentityFileName(void);

    /// Get the rulebase script file name.
    //
    // \returns the rulebase script file name.
    std::string GetRulebaseScriptName(void);

    /// Get the ignore list file name.
    //
    // \returns the ignore list file name.
    //
    std::string GetIgnoreListFileName(void);

    /// Return the rulebase file name.
    //
    // \returns the name of the rulebase file, including the path.
    //
    std::string GetRulebaseFileName(void);

    /// Get the operating system type.
    //
    // \returns the operating system type.  This is the value of
    // SNF_OSTYPE specified on the compile commandline.  For *nix, it
    // is identical to the value of the --enable-os-type command-line
    // input to ./configure:
    //
    // <ol>
    //  <li>OpenBSD</li>
    //  <li>FreeBSD</li>
    //  <li>Suse</li>
    //  <li>RedHat</li>
    //  <li>Ubuntu</li>
    // </ol>
    //
    std::string GetOperatingSystemType(void);

    /// Load the operating-system-dependent info (file locations, etc).
    //
    // This method updates the public members that contain the OS
    // specification and file paths.
    //
    void LoadInfo(void);

    /// Load the credentials from the identity.xml file.
    //
    // This method loads the license ID and authentication from the
    // identity.xml file specified in the previously-loaded
    // configuration.
    //
    void LoadCredentials(void);

    /// Postfix main.cf file path.
    std::string PostfixMainCfPath;

    /// Postfix master.cf file path.
    std::string PostfixMasterCfPath;

    /// Directory containing the Sniffer start script.
    std::string SnifferStartScriptDir;

    /// Setup/repair the configuration.
    //
    // Copy the following files from the sample files if they don't
    // exist:
    //
    // <ol>
    //   <li> Identity file. </li>
    //   <li> Ignore list file. </li>
    //   <li> Rulebase script. </li>
    // </ol>
    //
    // Set the owner/group of each of the above files.
    //
    // Make sure that the log directory exists and has the correct
    // owner and permissions.
    //
    // \param[in] SampleIdentityFile is the name of the sample identity file.
    //
    // \note The configuration information must be loaded before calling this method.
    //
    // \see SetConfigFileName.
    //
    // \see CreateDefaultConfigFile.
    //
    // \see LoadConfig.
    //
    // \see LoadInfo.
    //
    void SetupRepair(const std::string SampleIdentityFile);

    /// Restore any missing configuration files.
    //
    // Restore missing configuration files from the sample files.  The
    // files restored are the ones restored by SetupRepair.
    //
    // \param[in] SampleIdentityFile is the name of the sample identity file.
    //
    void RestoreMissingConfigFiles(const std::string SampleIdentityFile);

    /// Set the owner, group, and permissions of the configuration
    /// files and directories.
    //
    // This method sets the ownership, group, and permissions of all
    // the configuration files.
    //
    void SetOwnerPermissionsOfConfigFiles(void);

    /// Update the rulebase script credentials.
    //
    // This method updates the rulebase with the credentials specified
    // on the command line.
    //
    void UpdateRulebaseScriptCredentials(void);

    /// Download the rulebase.
    //
    void DownloadRulebase(void);

    /// Update the identity file.
    //
    // If the credentials were supplied, this method updates the
    // identity file with the supplied credentials.
    //
    // In any case, the owner/group is changed by SetOwnerGroup(), and
    // the permissions are changed to readonly for the owner.
    //
    // \pre Either the identity file must exist, or the credentials
    // must be supplied so that the identity file is created.
    //
    // \see SetOwnerGroup().
    //
    void UpdateIdentityFile(void);

    /// Get the Sniffer running status.
    //
    // This method determines whether or not the specified application
    // is running.
    //
    // \param[in] ApplicationName is the specified application name.
    //
    // \returns enumeration specifying the running state.
    // 
    SnifferRunningStateEnum GetRunningState(std::string ApplicationName);

    /// Start the Sniffer application if it isn't running.
    //
    // This method runs the specified sniffer start script and
    // arguments in the appropriate (i.e. OS-dependent) directory.
    // The script is prepended with the directory.
    //
    // \param[in] ScriptAndArgs contains the name of the start script
    // and any arguments.
    //
    // \param[in] ApplicationName is the name of the application to
    // run.  This is passed to GetRunningState().
    //
    // \pre LoadInfo() must have been called.  That method initializes
    // the directory the script resides in.
    //
    void StartSniffer(std::string ScriptAndArgs, std::string ApplicationName);

    /// Stop the Sniffer application if it's running.
    //
    // This method runs the specified sniffer stop script and
    // arguments in the appropriate (i.e. OS-dependent) directory.
    // The script is prepended with the directory.
    //
    // \param[in] ScriptAndArgs contains the name of the stop script
    // and any arguments.
    //
    // \param[in] ApplicationName is the name of the application to
    // top.  This is passed to GetRunningState().
    //
    // \pre LoadInfo() must have been called.  That method initializes
    // the directory the script resides in.
    //
    void StopSniffer(std::string ScriptAndArgs, std::string ApplicationName);

    /// Process one command-line item.
    //
    // \param[in] OneInput is the command-line item to process.
    //
    bool ProcessCommandLineItem(std::string OneInput);

    /// Check whether the command-line parameters were specified
    /// correctly.
    //
    // This method checks that either both the LicenseID and
    // Authentication were specified, or neither were.
    //
    // This method does not check for multiple commands specified on
    // the command line.
    //
    // \returns if the command-line parameters were specified
    // correctly, false otherwise.
    //
    bool CommandLineIsOkay(void);

    /// Output the legal command-line input.
    //
    // \param[in] ExclusiveCommands contains the command-line help of
    // the additional commands implemented by the descendent classes.
    // Only one command may be specified when invoking the
    // configuration utility.
    //
    std::string HelpCommandLine(std::string ExclusiveCommands);

    /// Output the description of the legal command-line input.
    //
    // \param[in] ExclusiveCommandsHelp contains the description of
    // the additional commands implemented by the descendent classes.
    //
    std::string HelpDescription(std::string ExclusiveCommandsHelp);

    /// Store whether the setup/help command was specified.
    //
    // \param[in] Specified specifies whether the command was specified.
    //
    void SetSetupRepair(bool Specified);

    /// Setup/repair specified?
    //
    // \returns true if the setup/help command was specified on the command line.
    //
    bool SetupRepairSpecified(void);

    /// Determine whether the credentials should be updated.
    //
    // This method determines whether the credentials should be
    // updated.  If the user specified both the License ID and
    // Authentication, then the credentials should be updated.
    //
    // \returns true if the credentials should be updated.
    //
    bool UpdateCredentialsSpecified(void);

    /// Store whether the start sniffer command was specified.
    //
    // \param[in] Specified specifies whether the command was specified.
    //
    void SetStartSniffer(bool Specified);

    /// Start sniffer specified?
    //
    // \returns true if the start sniffer command was specified on the command line.
    //
    bool StartSnifferSpecified(void);

    /// Store whether the stop sniffer command was specified.
    //
    // \param[in] Specified specifies whether the command was specified.
    //
    void SetStopSniffer(bool Specified);

    /// Stop sniffer specified?
    //
    // \returns true if the stop sniffer command was specified on the command line.
    //
    bool StopSnifferSpecified(void);

private:

    /// Method for checking the status of Sniffer.
    enum StatusCheckMethod {
	StatusCheckXci, ///< Check using XCI.
	StatusCheckSecond, ///< Check using status.second log file.
	StatusCheckMinute, ///< Check using status.minute log file.
	StatusCheckNotAvailable ///< No method for checking is available.
    };

    /// Typedef for pointer to member function that returns the log
    /// file name.
    typedef std::string (UtilityConfig::*GetLogFileName) (void);

    /// Determine the mode for checking the status of Sniffer.
    //
    // This method determines how the status of the sniffer should be
    // checked.  The configuration loaded from the configuration file
    // is used to determine the method.
    //
    // If XCI is enabled, then the preferred method is XCI.
    // Otherwise, if status.second logging is enabled, the preferred
    // method is to check the status.second file.  Otherwise, if
    // status.minute logging is enabled, the preferred method is to
    // check the status.minute file.
    //
    // \returns Enumeration value indicating how to check the sniffer
    // status.
    //
    StatusCheckMethod GetPreferredStatusCheckMethod(void);

    /// Get the Sniffer status report using the preferred method.
    //
    // \returns Status report obtained from Sniffer using the method
    // specified by GetPrefferedStatusCheckMethod() if the Sniffer is
    // running.  If the Sniffer is not running, "" is returned.
    //
    // \see GetPreferredStatusCheckMethod().
    //
    std::string GetSnifferStatusReport();

    /// Check the Sniffer status report.
    //
    // This method checks that the status report is well-formed by
    // extracting the <platform> element contents, and also checks
    // that the <platform> element contents contains the specified
    // application name.
    //
    // If the status report is not well-formed, or the expected
    // application name isn't in the <platform> element content, an
    // exception is thrown.
    //
    // \param[in] StatusReport is the status report obtained by
    // GetSnifferStatusReport().
    //
    // \param[in] ApplicationName is the specified application name.
    // 
    void CheckSnifferStatusReport(std::string StatusReport, std::string ApplicationName);

    /// Get the Sniffer status report using XCI.
    //
    // \returns Status report obtained from Sniffer using XCI if the
    // Sniffer is running.  Otherwise, "" is returned.
    //
    std::string GetReportViaXci();

    /// Get the Sniffer status report from the specified log file.
    //
    // This method gets the status report of a running Sniffer.
    // Whether or not the Sniffer is running is determined by reading
    // the specified log file twice, separated by the specified time
    // interval.  If the log file contents are different, then the
    // Sniffer is running.  Otherwise, the Sniffer is not running.
    //
    // \param[in] GetLogFileNamePtr is pointer to the member function
    // that returns the log file name.
    //
    // \param[in] SleepTime_msec is the length of time to wait between
    // log file reads.
    //
    // \param[in] TimeoutTime_msec is the length of time to wait for
    // the file to change.
    //
    // \returns Status report obtained from Sniffer using the
    // specified log file if the Sniffer is running.  Otherwise, "" is
    // returned.
    //
    std::string GetReportViaLogFile(GetLogFileName GetLogFileNamePtr, int SleepTime_msec, int TimeoutTime_msec);

    std::string ConfigFileName; ///< Configuration file name.
    std::string LicenseId; ///< License ID string.
    bool LicenseIdIsSpecified; ///< true if the License ID was specified on the command line.
    std::string Authentication; ///< Authentication string.
    bool AuthenticationIsSpecified; ///< true if the Authentication was specified on the command line.

    static const std::string RulebaseDownloadCommand; ///< Command to download the rulebase.
    static const std::string RulebaseDownloadStatusFile; ///< Status file for rulebase download status.

    static const std::string SampleIgnoreListFile; ///< Sample ignore list file.
    static const std::string SampleRulebaseScriptFile; ///< Sample rulebase script file.

    static const long LogFileReportSize = 4096; ///< Size of log file report.

    snfCFGData CFGData; ///< Configuration data.

    /// Operating system type.
    //
    // This is either Windows or the value specified for
    // --enable-os-type when configuring for *nix.
    static const std::string OperatingSystemType;

    bool SetupRepairRequested; ///< User requested setup/repair.
    bool StartSnifferRequested; ///< User requested that Sniffer be started.
    bool StopSnifferRequested; ///< User requested that Sniffer be stopped.

};

#endif