Logs.idl

Go to the documentation of this file.

/**
 * @file   Logs.idl
 * @brief  Application logs
 *
 * @author Dusan Juhas, Martin Kuchar, Martin Jezek
 *
 * @copyright Copyright © 2017 Kerio Technologies s.r.o.
 */

#import <kerio/web/idl/SharedStructures.idl>

module kerio {
module web {

/**
 * Global limits:
 * 1. maximum of returned lines at once is 50000
 * 2. maximal line length is 1024 (it does not include date, time, ID in the beginning of log line)
 */

/**
 * Type of the log
 * valid Connect names: config, debug, error, mail, security, spam, warning
 * valid Control names: alert, config, connection, debug, dial, error, filter, http, security, sslvpn, warning, web
 */
typedef string LogType;

/**
 * 1 log
 */
struct LogItem {
   LogType        logName;    ///< name of the log
   boolean        hasMessages;   ///< has the log messages?
};

/**
 * List of valid logs
 */
typedef sequence<LogItem> LogSet;

/**
 * Period of rotation
 */
enum RotationPeriod {
   RotateNever,                  ///< don't rotate
   RotateHourly,                 ///< rotate hourly
   RotateDaily,                  ///< rotate daily
   RotateWeekly,                 ///< rotate weekly
   RotateMonthly                 ///< rotate monthly
};

/**
 * Available types of syslog facility according RFC 3164
 */
enum FacilityUnit {
   FacilityKernel,         ///<  0 = kernel messages
   FacilityUserLevel,      ///<  1 = user-level messages
    FacilityMailSystem,    ///<  2 = mail system
   FacilitySystemDaemons,  ///<  3 = system daemons
   FacilitySecurity1,      ///<  4 = security/authorization messages
   FacilityInternal,    ///<  5 = messages generated internally by syslogd
   FacilityLinePrinter, ///<  6 = line printer subsystem
   FacilityNetworkNews, ///<  7 = network news subsystem
   FacilityUucpSubsystem,  ///<  8 = UUCP subsystem
   FacilityClockDaemon1,   ///<  9 = clock daemon
   FacilitySecurity2,      ///< 10 = security/authorization messages
   FacilityFtpDaemon,      ///< 11 = FTP daemon
   FacilityNtpSubsystem,   ///< 12 = NTP subsystem
    FacilityLogAudit,      ///< 13 = log audit
    FacilityLogAlert,      ///< 14 = log alert
   FacilityClockDaemon2,   ///< 15 = clock daemon
    FacilityLocal0,        ///< 16 = local use 0
    FacilityLocal1,        ///< 17 = local use 1
    FacilityLocal2,        ///< 18 = local use 2
    FacilityLocal3,        ///< 19 = local use 3
    FacilityLocal4,        ///< 20 = local use 4
    FacilityLocal5,        ///< 21 = local use 5
    FacilityLocal6,        ///< 22 = local use 6
    FacilityLocal7         ///< 23 = local use 7
};

/**
 * Available types of severity
 */
enum SeverityUnit {
    SeverityEmergency,
    SeverityAlert,
    SeverityCritical,
    SeverityError,
    SeverityWarning,
    SeverityNotice,
    SeverityInformational,
    SeverityDebug
};

/**
 * general log settings
 */
struct LogFileSettings {
   boolean enabled;  ///< Is logging to file enabled
   string fileName;  ///< log file name
};

/**
 * log rotation settings
 */
struct LogRotationSettings {
   RotationPeriod period;  ///< How often does log rotate?
    long maxLogSize;    ///< Maximum log file size [MegaBytes]; Unlimited CAN be used
    long rotateCount;      ///< How many rotated files can be kept at most?; Unlimited CANNOT be used
};

/**
 * syslog settings
 */
struct SyslogSettings {
    boolean enabled;    ///< Syslog is [dis|en]abled
    string serverUrl;      ///< Path to syslog server
    FacilityUnit facility; ///< which facility is message sent from
    SeverityUnit severity; ///< read-only; severity level of message
    string application;    ///< user defined application name; it is 1*48PRINTUSASCII where PRINTUSASCII = %d33-126.
};

/**
 * Log file and output settings for 1 log
 */
struct LogSettings {
   LogFileSettings general;      ///< general log settings
   LogRotationSettings rotation; ///< log rotation settings
   SyslogSettings syslog;        ///< syslog settings
};

/**
 * Highlight color definition in format RRGGBB
 */
typedef string HighlightColor;

/**
 * Log highlighting item
 */
struct HighlightItem {
   KId   id;               ///< global identification
   boolean enabled;     ///< Rule is [dis|en]abled
   string description;     ///< Text description
   string condition;    ///< Match condition
   boolean isRegex;     ///< Is condition held as regular expression? (server does NOT check if regex is valid)
   HighlightColor color;   ///< Highlight matching log lines by this color
   boolean isOrderChanged; ///< True if item order was changed by user
};

/**
 * List of highlight items to be applied on all logs (global settings)
 */
typedef sequence<HighlightItem> HighlightRules;

/**
 * Leaf item of the tree
 */
struct TreeLeaf {
   long id;       ///< leaf identification
   string parentName;   ///< name of the group
   string description;  ///< text after checkbox
   boolean enabled;  ///< leaf is [not] enabled
};

/**
 * sequence of leaves
 */
typedef sequence<TreeLeaf> TreeLeafList;

/**
 * File type for log export
 */
enum ExportFormat {
   PlainText,          ///< export in plain text
   Html                ///< export in html
};

/**
 * row of the log
 */
struct LogRow {
   string         content; ///< 1 data row
   HighlightColor highlight;  ///< appropriate highlight color
};

typedef sequence<LogRow> LogRowList;

/**
 * Status of the Search
 */
enum SearchStatus {
   ResultFound,   ///< the seach is finished and the match has been found
   Searching,     ///< the search still continues, the result is not available so far
   Cancelled,     ///< the search was cancelled by client
   ResultNotFound ///< the seach is finished but nothing was found
};

/**
 * Log object
 */
interface Logs {

   /**
    * Cancel search on server (useful for large logs).
    *
    * @param searchId - identifier from search()
    */
   void cancelSearch(in string searchId);

   /**
    * Delete all log lines.
    *
    * @param logName - unique name of the log
    */
   void clear(in LogType logName);

   /**
    * Exporting a given log.
    *
    * @param fileDownload - file download structure
    * @param logName - unique name of the log
    * @param fromLine - number of the line to start the search from;
    * @param countLines - number of lines to transfer; Unlimited - symbolic name for end of log
    * @param type - export file type
    */
   void exportLog(out Download fileDownload, in LogType logName, in long fromLine, in long countLines, in ExportFormat type);
   
   /**
    * Exporting a given log with relative download path.
    *
    * @param fileDownload - file download structure
    * @param logName - unique name of the log
    * @param fromLine - number of the line to start the search from;
    * @param countLines - number of lines to transfer; Unlimited - symbolic name for end of log
    * @param type - export file type
    */
   void exportLogRelative(out Download fileDownload, in LogType logName, in long fromLine, in long countLines, in ExportFormat type);

   /**
    * Obtain log data without linebreaks.
    *
    * @param viewport - list of log lines; count of lines = min(count, NUMBER_OF_CURRENT LINES - from)
    * @param totalItems - current count of all log lines
    * @param logName - unique name of the log
    * @param fromLine - number of the line to start from; if (fromLine == Unlimited) then fromline is end of log minus countLines
    * @param countLines - number of lines to transfer
    */
   void get(out LogRowList viewport, out long totalItems, in LogType logName, in long fromLine, in long countLines);

   /**
    * Obtain a list of sorted highlighting rules.
    *
    * @param rules - highlight rules
    */
   void getHighlightRules(out HighlightRules rules);

   /**
    * Retrieve set of valid logs.
    *
    * @param logSet - list of valid logs
    */
   void getLogSet(out LogSet logSet);

   /**
    * Obtain log message settings; make sense only if LogItem.hasMessages == true.
    *
    * @param messages - tree of log messages
    */
   void getMessages(out TreeLeafList messages);

   /**
    * Clears timeout for search() and obtains status of the search.
    *
    * @param viewport - list of log lines
    * @param firstLine - first matching line
    * @param totalItems - current count of all log lines
    * @param status - current status of the search
    * @param percentage - already finished search <0;100>
    * @param countLines - number of lines to transfer
    * @param searchId - identifier from search()
    */
   void getSearchProgress(
      out LogRowList viewport,
      out long firstLine,
      out long totalItems,
      out SearchStatus status,
      out long percentage,
      in long countLines,
      in string searchId
   );

   /**
    * Obtain log settings.
    *
    * @param currentSettings - current valid settings (or undefined data on failure)
    * @param logName - unique name of the log
    */
   void getSettings(out LogSettings currentSettings, in LogType logName);

   /**
    * Start searching for a string in a given log; The search exists 1 minute unless prolonged by getSearchProgress.
    *
    * @param searchId - identifier that can be used for cancelSearch and getSearchProgress
    * @param logName - unique name of the log
    * @param what - searched string
    * @param fromLine - line to start searching from; fromLine>toLine means search up; Unlimited - symbolic name for end of log
    * @param toLine - line to start searching from; fromLine<toLine means search down
    * @param forward - direction of the search; true = forward, false = backward
    */
   void search(out string searchId, in LogType logName, in string what, in long fromLine, in long toLine, in boolean forward);


   /**
    * Set highlighting rules, rules have to be sorted purposely, the only way to change a rule is to change the whole ruleset.
    *
    * @param rules - highlight rules (ordered by priority)
   */
   void setHighlightRules(in HighlightRules rules);

   /**
    * Change log message settings; makes sense only if LogItem.hasMessages == true.
    *
    * @param messages - tree of log messages
    */
   void setMessages(in TreeLeafList messages);

   /**
    * Change log settings.
    *
    * @param logName - unique name of the log
    * @param newSettings
    */
   void setSettings(in LogType logName, in LogSettings newSettings);
};

}; // module web
}; // module kerio