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 © 2017 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  * Exporting a given log with relative download path.
231  *
232  * @param fileDownload - file download structure
233  * @param logName - unique name of the log
234  * @param fromLine - number of the line to start the search from;
235  * @param countLines - number of lines to transfer; Unlimited - symbolic name for end of log
236  * @param type - export file type
237  */
238  void exportLogRelative(out Download fileDownload, in LogType logName, in long fromLine, in long countLines, in ExportFormat type);
239 
240  /**
241  * Obtain log data without linebreaks.
242  *
243  * @param viewport - list of log lines; count of lines = min(count, NUMBER_OF_CURRENT LINES - from)
244  * @param totalItems - current count of all log lines
245  * @param logName - unique name of the log
246  * @param fromLine - number of the line to start from; if (fromLine == Unlimited) then fromline is end of log minus countLines
247  * @param countLines - number of lines to transfer
248  */
249  void get(out LogRowList viewport, out long totalItems, in LogType logName, in long fromLine, in long countLines);
250 
251  /**
252  * Obtain a list of sorted highlighting rules.
253  *
254  * @param rules - highlight rules
255  */
256  void getHighlightRules(out HighlightRules rules);
257 
258  /**
259  * Retrieve set of valid logs.
260  *
261  * @param logSet - list of valid logs
262  */
263  void getLogSet(out LogSet logSet);
264 
265  /**
266  * Obtain log message settings; make sense only if LogItem.hasMessages == true.
267  *
268  * @param messages - tree of log messages
269  */
270  void getMessages(out TreeLeafList messages);
271 
272  /**
273  * Clears timeout for search() and obtains status of the search.
274  *
275  * @param viewport - list of log lines
276  * @param firstLine - first matching line
277  * @param totalItems - current count of all log lines
278  * @param status - current status of the search
279  * @param percentage - already finished search <0;100>
280  * @param countLines - number of lines to transfer
281  * @param searchId - identifier from search()
282  */
283  void getSearchProgress(
284  out LogRowList viewport,
285  out long firstLine,
286  out long totalItems,
287  out SearchStatus status,
288  out long percentage,
289  in long countLines,
290  in string searchId
291  );
292 
293  /**
294  * Obtain log settings.
295  *
296  * @param currentSettings - current valid settings (or undefined data on failure)
297  * @param logName - unique name of the log
298  */
299  void getSettings(out LogSettings currentSettings, in LogType logName);
300 
301  /**
302  * Start searching for a string in a given log; The search exists 1 minute unless prolonged by getSearchProgress.
303  *
304  * @param searchId - identifier that can be used for cancelSearch and getSearchProgress
305  * @param logName - unique name of the log
306  * @param what - searched string
307  * @param fromLine - line to start searching from; fromLine>toLine means search up; Unlimited - symbolic name for end of log
308  * @param toLine - line to start searching from; fromLine<toLine means search down
309  * @param forward - direction of the search; true = forward, false = backward
310  */
311  void search(out string searchId, in LogType logName, in string what, in long fromLine, in long toLine, in boolean forward);
312 
313 
314  /**
315  * Set highlighting rules, rules have to be sorted purposely, the only way to change a rule is to change the whole ruleset.
316  *
317  * @param rules - highlight rules (ordered by priority)
318  */
319  void setHighlightRules(in HighlightRules rules);
320 
321  /**
322  * Change log message settings; makes sense only if LogItem.hasMessages == true.
323  *
324  * @param messages - tree of log messages
325  */
326  void setMessages(in TreeLeafList messages);
327 
328  /**
329  * Change log settings.
330  *
331  * @param logName - unique name of the log
332  * @param newSettings
333  */
334  void setSettings(in LogType logName, in LogSettings newSettings);
335 };
336 
337 }; // module web
338 }; // module kerio