...
How to define Report Schedules
In the GUI
Each scheduled job is defined by a separate JSON file. The scheduler expects these files in /usr/local/omk/conf/schedule (but this is configurable - see <omk_schedule> in conf/opCommon.nmis). As of version 3.0 schedule files must be managed using an external editor, but support for editing schedules from the GUI is already planned.
All job files must be called <something>.json, and only letters, digits, dot, underscore and hyphen are allowed in the file name. All other files are silently ignored. You can thus disable a job by naming it something like !disabled_job.json. opReports ships with a number of example schedule files (all set to be inactive) and a brief README file in the conf/schedule directory.
A job file must consist of one "hash" datastructure, with the following properties:
.2 using the GUI schedule editor is the most convenient method for managing report schedules. The GUI schedule editor is a front-end that handles schedule files, so the technical details given in the next section remain applicable.
Using Schedule Files
For ease of automated deployment and scriptability opReports provides access to all job schedule options using schedule files.
Each scheduled job is defined by a separate JSON file. The scheduler expects these files in /usr/local/omk/conf/schedule (but this is configurable - see <omk_schedule> in conf/opCommon.nmis).
All job files must be called <something>.json, and only letters, digits, dot, underscore and hyphen are allowed in the file name. All other files are silently ignored. You can thus disable a job by naming it something like !disabled_job.json. opReports ships with a number of example schedule files (all set to be inactive) and a brief README file in the conf/schedule directory.
A job file must consist of one "hash" datastructure, with the following properties:
| Property | Example | Property | Example | Description |
|---|---|---|---|---|
type | "util" "wan" | The report type to generate. Required. See the opReports Report Descriptions for a list of available types. | ||
| active | "true" or "false" | Whether this schedule is active or not. Only active schedules can create new reports, inactive schedules are consulted only for pruning of old report data. If active is not specified, then the schedule is inactive. | ||
| description | "some text" | A free-form description of the scheduled job. Optional. | ||
| frequency | "daily", "weekly", "monthly" or "yearly" | Not present for one-off reports. | ||
| start | "1-14-2015 20:00:00", "mon 10:30", various others depending on the frequency | The date + time the report collection is to start at. Required. | ||
| end | The date + time the report collection is to end at. Same format as start. | |||
| from | 13 or any integer between 0 and 24 | Start of Business Hours reporting. Optional. Default: 0. See the Formats for Report Periods and Frequencies page for details. | ||
| to | End of Business Hours reporting. Optional. Default: 24. | |||
| exclude | "fri-sun", "sat-mon" | Business week selection. Optional, supported in opReports 3.0.8 and newer. | ||
| node_intf_list | /some/where/some.file | The file describing the nodes and interfaces to collect. See section below for format. | ||
| util_threshold | 80 | The desired interface utilisation threshold value (in percent), default: 80 (percent). | ||
| util_threshold_mincount | 1 | The desired minimum number of threshold exceedences for flagging the interface as over-limit, default: 1. | ||
format
| a hash with the keys "html", "csv" and "xlsx", and values true/false or 1/0. e.g. { "html":0, "csv": true, "xlsx": false} | The formats the report should be saved in. | ||
| outputdir | /some/where/ | Where the report should be saved. This has to be a full path pointing to a directory. GUI-scheduled reports will always use one of the configured directories (see opreports_output_dirs in opCommon.nmis), and it is recommended that you use only these even if editing schedule files by hand.Every report schedule can use a different output directory. | ||
| naming | "simple" or "precise" | What naming scheme should be used for the output files. Default is "simple". Mainly important if you plan to manually work with saved report files. | ||
sourcesand (at most) one of node_list, node_regexp, node_group, node_intf_list or node_intf_type_list | "everything" | See How to select Nodes (and Interfaces) for details. | ||
| keep_for | 47 | How many days to keep an old report instance. If set to zero, the report is not expired. If not set, then the defaults for the report type are applied (configuration entry "default_report_keep_for"). | ||
| options | { "title" : "My Custom ReportTitle" }
| Optional settings. Some are specific to particular report types. See the section on Optional Settings below. | ||
| control_nmis | "true" or "false" | Whether NMIS should be "remote controlled" or left in peace. See section on Remote Controlling NMIS below. Only relevant for one-off reports. | ||
| nmis_options | "mthread=true maxthreads=15" | Options to be given to | ||
| target_audience_group | "HQ" | If present and a known NMIS group name, then the generated report can be viewed only by users who are members of this group (and the administrator). If not present then report viewing is not limited to particular groups. |
...
The opReports scheduler is not a long-lived daemon process, but rather meant to be run suitably frequently from cron. The scheduler does log to opReports.log, but also prints error messages of higher urgency to STDERR, where cron will pick them up and mail them to root (or whatever recipient you have set up). By default opReports creates an /etc/cron.d/opreports which triggers the scheduler once every hour.
Recurring Schedules
Recurring jobs are processed repeatedly, as soon as the scheduler determines that the end of the report period for that schedule is past.
One-Off Reports
A one-off job is normally processed exactly once, as soon as the report period has passed. The job is then marked completed and will not be (re)generated.
It is, however, possible to generate another instance of a one-off schedule:
- This can be desirable if your one-off uses relative start and end times (e.g. '
now - 10 days' to 'midnight'). - The scheduler does not attempt to guess that your one-off report may be rerun safely;
it needs to be told to reconsider the schedule. This is achieved by clearing thecompletedflag in the report schedule. - If you work on the schedule files directly, simply remove the
completedproperty and save the modified file. - In the GUI, simply open the respective schedule for editing and hit the Save button; this also clears the
completedproperty.
Remote-Controlling NMIS
This experimental feature is primarily meant for Interface Utilisation Reports at this time and works only for one-off jobs. If your job has control_nmis true AND a node_intf_list file, then the following actions are taken:
...