All Classes Files Functions Variables Enumerations Enumerator Groups Pages
Logs.idl
Go to the documentation of this file.
1 /**
2  * @file Logs.idl
3  * @brief Application logs
4  *
5  * @author Dusan Juhas, Martin Kuchar, Martin Jezek
6  *
7  * @copyright Copyright © 2011-2014 Kerio Technologies s.r.o.
8  */
9 
10 #import <kerio/web/idl/SharedStructures.idl>
11 
12 module kerio {
13 module web {
14 
15 /**
16  * Global limits:
17  * 1. maximum of returned lines at once is 50000
18  * 2. maximal line length is 1024 (it does not include date, time, ID in the beginning of log line)
19  */
20 
21 /**
22  * Type of the log
23  * valid Connect names: config, debug, error, mail, security, spam, warning
24  * valid Control names: alert, config, connection, debug, dial, error, filter, http, security, sslvpn, warning, web
25  */
26 typedef string LogType;
27 
28 /**
29  * 1 log
30  */
31 struct LogItem {
32  LogType logName; ///< name of the log
33  boolean hasMessages; ///< has the log messages?
34 };
35 
36 /**
37  * List of valid logs
38  */
39 typedef sequence<LogItem> LogSet;
40 
41 /**
42  * Period of rotation
43  */
44 enum RotationPeriod {
45  RotateNever, ///< don't rotate
46  RotateHourly, ///< rotate hourly
47  RotateDaily, ///< rotate daily
48  RotateWeekly, ///< rotate weekly
49  RotateMonthly ///< rotate monthly
50 };
51 
52 /**
53  * Available types of syslog facility according RFC 3164
54  */
55 enum FacilityUnit {
56  FacilityKernel, ///< 0 = kernel messages
57  FacilityUserLevel, ///< 1 = user-level messages
58  FacilityMailSystem, ///< 2 = mail system
59  FacilitySystemDaemons, ///< 3 = system daemons
60  FacilitySecurity1, ///< 4 = security/authorization messages
61  FacilityInternal, ///< 5 = messages generated internally by syslogd
62  FacilityLinePrinter, ///< 6 = line printer subsystem
63  FacilityNetworkNews, ///< 7 = network news subsystem
64  FacilityUucpSubsystem, ///< 8 = UUCP subsystem
65  FacilityClockDaemon1, ///< 9 = clock daemon
66  FacilitySecurity2, ///< 10 = security/authorization messages
67  FacilityFtpDaemon, ///< 11 = FTP daemon
68  FacilityNtpSubsystem, ///< 12 = NTP subsystem
69  FacilityLogAudit, ///< 13 = log audit
70  FacilityLogAlert, ///< 14 = log alert
71  FacilityClockDaemon2, ///< 15 = clock daemon
72  FacilityLocal0, ///< 16 = local use 0
73  FacilityLocal1, ///< 17 = local use 1
74  FacilityLocal2, ///< 18 = local use 2
75  FacilityLocal3, ///< 19 = local use 3
76  FacilityLocal4, ///< 20 = local use 4
77  FacilityLocal5, ///< 21 = local use 5
78  FacilityLocal6, ///< 22 = local use 6
79  FacilityLocal7 ///< 23 = local use 7
80 };
81 
82 /**
83  * Available types of severity
84  */
85 enum SeverityUnit {
86  SeverityEmergency,
87  SeverityAlert,
88  SeverityCritical,
89  SeverityError,
90  SeverityWarning,
91  SeverityNotice,
92  SeverityInformational,
93  SeverityDebug
94 };
95 
96 /**
97  * general log settings
98  */
100  boolean enabled; ///< Is logging to file enabled
101  string fileName; ///< log file name
102 };
103 
104 /**
105  * log rotation settings
106  */
108  RotationPeriod period; ///< How often does log rotate?
109  long maxLogSize; ///< Maximum log file size [MegaBytes]; Unlimited CAN be used
110  long rotateCount; ///< How many rotated files can be kept at most?; Unlimited CANNOT be used
111 };
112 
113 /**
114  * syslog settings
115  */
117  boolean enabled; ///< Syslog is [dis|en]abled
118  string serverUrl; ///< Path to syslog server
119  FacilityUnit facility; ///< which facility is message sent from
120  SeverityUnit severity; ///< read-only; severity level of message
121  string application; ///< user defined application name; it is 1*48PRINTUSASCII where PRINTUSASCII = %d33-126.
122 };
123 
124 /**
125  * Log file and output settings for 1 log
126  */
127 struct LogSettings {
128  LogFileSettings general; ///< general log settings
129  LogRotationSettings rotation; ///< log rotation settings
130  SyslogSettings syslog; ///< syslog settings
131 };
132 
133 /**
134  * Highlight color definition in format RRGGBB
135  */
136 typedef string HighlightColor;
137 
138 /**
139  * Log highlighting item
140  */
142  KId id; ///< global identification
143  boolean enabled; ///< Rule is [dis|en]abled
144  string description; ///< Text description
145  string condition; ///< Match condition
146  boolean isRegex; ///< Is condition held as regular expression? (server does NOT check if regex is valid)
147  HighlightColor color; ///< Highlight matching log lines by this color
148  boolean isOrderChanged; ///< True if item order was changed by user
149 };
150 
151 /**
152  * List of highlight items to be applied on all logs (global settings)
153  */
154 typedef sequence<HighlightItem> HighlightRules;
155 
156 /**
157  * Leaf item of the tree
158  */
159 struct TreeLeaf {
160  long id; ///< leaf identification
161  string parentName; ///< name of the group
162  string description; ///< text after checkbox
163  boolean enabled; ///< leaf is [not] enabled
164 };
165 
166 /**
167  * sequence of leaves
168  */
169 typedef sequence<TreeLeaf> TreeLeafList;
170 
171 /**
172  * File type for log export
173  */
174 enum ExportFormat {
175  PlainText, ///< export in plain text
176  Html ///< export in html
177 };
178 
179 /**
180  * row of the log
181  */
182 struct LogRow {
183  string content; ///< 1 data row
184  HighlightColor highlight; ///< appropriate highlight color
185 };
186 
187 typedef sequence<LogRow> LogRowList;
188 
189 /**
190  * Status of the Search
191  */
192 enum SearchStatus {
193  ResultFound, ///< the seach is finished and the match has been found
194  Searching, ///< the search still continues, the result is not available so far
195  Cancelled, ///< the search was cancelled by client
196  ResultNotFound ///< the seach is finished but nothing was found
197 };
198 
199 /**
200  * Log object
201  */
202 interface Logs {
203 
204  /**
205  * Cancel search on server (useful for large logs).
206  *
207  * @param searchId - identifier from search()
208  */
209  void cancelSearch(in string searchId);
210 
211  /**
212  * Delete all log lines.
213  *
214  * @param logName - unique name of the log
215  */
216  void clear(in LogType logName);
217 
218  /**
219  * Exporting a given log.
220  *
221  * @param fileDownload - file download structure
222  * @param logName - unique name of the log
223  * @param fromLine - number of the line to start the search from;
224  * @param countLines - number of lines to transfer; Unlimited - symbolic name for end of log
225  * @param type - export file type
226  */
227  void exportLog(out Download fileDownload, in LogType logName, in long fromLine, in long countLines, in ExportFormat type);
228 
229  /**
230  * Obtain log data without linebreaks.
231  *
232  * @param viewport - list of log lines; count of lines = min(count, NUMBER_OF_CURRENT LINES - from)
233  * @param totalItems - current count of all log lines
234  * @param logName - unique name of the log
235  * @param fromLine - number of the line to start from; if (fromLine == Unlimited) then fromline is end of log minus countLines
236  * @param countLines - number of lines to transfer
237  */
238  void get(out LogRowList viewport, out long totalItems, in LogType logName, in long fromLine, in long countLines);
239 
240  /**
241  * Obtain a list of sorted highlighting rules.
242  *
243  * @param rules - highlight rules
244  */
245  void getHighlightRules(out HighlightRules rules);
246 
247  /**
248  * Retrieve set of valid logs.
249  *
250  * @param logSet - list of valid logs
251  */
252  void getLogSet(out LogSet logSet);
253 
254  /**
255  * Obtain log message settings; make sense only if LogItem.hasMessages == true.
256  *
257  * @param messages - tree of log messages
258  */
259  void getMessages(out TreeLeafList messages);
260 
261  /**
262  * Clears timeout for search() and obtains status of the search.
263  *
264  * @param viewport - list of log lines
265  * @param firstLine - first matching line
266  * @param totalItems - current count of all log lines
267  * @param status - current status of the search
268  * @param percentage - already finished search <0;100>
269  * @param countLines - number of lines to transfer
270  * @param searchId - identifier from search()
271  */
272  void getSearchProgress(
273  out LogRowList viewport,
274  out long firstLine,
275  out long totalItems,
276  out SearchStatus status,
277  out long percentage,
278  in long countLines,
279  in string searchId
280  );
281 
282  /**
283  * Obtain log settings.
284  *
285  * @param currentSettings - current valid settings (or undefined data on failure)
286  * @param logName - unique name of the log
287  */
288  void getSettings(out LogSettings currentSettings, in LogType logName);
289 
290  /**
291  * Start searching for a string in a given log; The search exists 1 minute unless prolonged by getSearchProgress.
292  *
293  * @param searchId - identifier that can be used for cancelSearch and getSearchProgress
294  * @param logName - unique name of the log
295  * @param what - searched string
296  * @param fromLine - line to start searching from; fromLine>toLine means search up; Unlimited - symbolic name for end of log
297  * @param toLine - line to start searching from; fromLine<toLine means search down
298  * @param forward - direction of the search; true = forward, false = backward
299  */
300  void search(out string searchId, in LogType logName, in string what, in long fromLine, in long toLine, in boolean forward);
301 
302 
303  /**
304  * Set highlighting rules, rules have to be sorted purposely, the only way to change a rule is to change the whole ruleset.
305  *
306  * @param rules - highlight rules (ordered by priority)
307  */
308  void setHighlightRules(in HighlightRules rules);
309 
310  /**
311  * Change log message settings; makes sense only if LogItem.hasMessages == true.
312  *
313  * @param messages - tree of log messages
314  */
315  void setMessages(in TreeLeafList messages);
316 
317  /**
318  * Change log settings.
319  *
320  * @param logName - unique name of the log
321  * @param newSettings
322  */
323  void setSettings(in LogType logName, in LogSettings newSettings);
324 };
325 
326 }; // module web
327 }; // module kerio