Overview of the Major Components of NMIS9
The NMIS9 daemon bin/nmisd
In NMIS9 almost all work is controlled, scheduled and executed by the nmis daemon and its worker child processes.
The nmis daemon is controllable using the typical
service interface with the service name being "nmis9d"; e.g.
sudo service nmis9d restart .
The daemon should be running by the end of the initial NMIS9 installation.
The primary CLI took bin/nmis-cli
The nmis-cli tool is your primary tool to interact NMIS on the command line; e.g. for querying the status of the nmis daemons, for scheduling new operations and for scheduling outages.
Besides these administrative duties the cli tool is currently the only entity that can create saved reports (which is scheduled using a minimal NMIS 9 cron job).
The Node administration CLI tool admin/node_admin.pl
Like with NMIS8, in NMIS9 nodes can be administered using the GUI or with the node_admin cli tool. NMIS9's version has a few extra features over NMIS8's but otherwise doesn't differ excessively.
The node admin tool is described in more detail on the Node Administration Tools page.
Because of its reliance on a database NMIS9 is more strict about identifying objects, which means that nodes for example are identified exclusively by UUIDs. Node names are of course still present, but as informal properties only. The relationship between these is queried most easily by the node_admin tool using the
The adminstrative capabilities of the NMIS9 GUI are almost identical to how NMIS8 worked; the only major exception being that "Edit and Update Node" cannot display any logs of the Node Update operation as that's scheduled asynchronously. The NMIS9 GUI plays a slightly more passive and and limited role, i.e. only schedules certain operations for the nmis daemon to pick up - different from NMIS8 where some of these were executed directly by GUI components.
NMIS9 makes extensive use of MongoDB behind the scenes; most of the time that should be invisible to you past the initial installation stage, where you will have to interact with
setup_mongodb.pl to prime the environment.
NMIS9 is much more powerful than NMIS8 when it comes to clustering; amongst other things that also means that each NMIS9 installation has to be uniquely identified by what we call its
cluster_id configuration setting (which is automatically generated for you during the initial installation).
Interacting with the daemon directly
The NMIS9 daemon accepts just a small number of command line arguments, which are shown when you run it with
The most commonly used ones would be
stopyou're instructing a running nmis daemon and all its workers to terminate gracefully, i.e. when any operations that were in progress are completed.
aborta running nmis daemon and its workers are stopped immediately and without regard to operations that are in progress.
In both of these cases no new nmis daemon is started.
Job Scheduling in NMIS9
In NMIS9 the nmis daemon controls the scheduling of all work based on various heuristics and manages a queue of these jobs; the nmis daemon's worker processes then pick and process jobs from the queue. Normally all job scheduling is automatic but it is possible to manually schedule activities using the nmis cli.
All enqueued jobs have a target execution time and a priority value.
The nmis daemon normally does not schedule another instance of a particular job, if that job is already active or overdue for processing. In such a case you'll see a log message warning about this issue.
If two or more already scheduled jobs should interfere with each other (e.g. a manually scheduled job for the same operation on one node where another job with the same parameters is already active), then the nmis daemon either discards the new job or postpones the new job for a short period to let the active job finish: the configuration item
postpone_clashing_schedule sets the number of seconds to postpone. In both cases a log message will warn you about the unexpected clash.
Each job instance is given a priority value (between 0 and 1 inclusive, 1 meaning highest priority), and the queue processing takes these into account. Jobs ready for processing are selected first by highest priority, then by scheduled job execution time (i.e. with equal priority the most overdue job is picked first).
The normal priorities are configured in
Config.nmis in the
priority_schedule section, with these defaults:
If you schedule a job manually then you can give it a priority value of your choice; if you don't then nmis-cli defaults to
job.priority=1 (i.e. highest).
Periodically Scheduled Jobs
The nmis daemon automatically schedules various activities periodically, based on global configuration settings. This overview is part of nmis-cli's schedule listing output:
The configuration items controlling these activities' scheduling frequencies are grouped in the
schedule section of
Config.nmis, with these defaults:
If you want to manually schedule one of these with nmis-cli, use the suffix after
schedule_ as the job type, e.g.
permission_test for the extended selftest.
Node Activity Scheduling
The node-centric actions (e.g. collect, update) are scheduled based on the node's last activity timestamps and its polling policy, which works the same as in NMIS8. Service checks are scheduled based on the service's period definition, again mostly unchanged from NMIS8.
If a job remains stuck as active job for too long then the nmis daemon will abort it and reschedule a suitable new job. Such stuck jobs can appear in the queue if you terminate the nmis daemon with
service nmis9d stop, because these actions immediately kill the relevant processes and don't take active operations into account.
When and whether NMIS should attempt to recover from stuck jobs is configurable, in
overtime_schedule, with these defaults:
NMIS also warns about unexpected queue states, e.g. if there are too many overdue queued jobs or if there are excessively many queued jobs altogether.
Interacting with the daemon using nmis-cli
Just like all other NMIS9 command line tools nmis-cli shows an overview of its arguments and capabilities when you run it with
--help (or without any arguments whatsoever):
To find out what processes are running and doing what, use
act=process-status ; it'll provide you with an overview like the following example:
Normally you should have one "nmisd scheduler" process, one "nmisd fping" worker and a few workers. The default configuration (see config item
nmisd_max_workers) is to start up and maintain 10 workers. In the example above two of these are idle and two are currently processing particular jobs. Please take note of the process id or PID; both are relevant for logging (e.g. finding particulars in the log file as well as adjusting the logging verbosity).
It is often useful to find out what activities are currently being performed and what and how much work is enqueued for future processing.
nmis-cli shows this information when run with the argument
act=list-schedules, like this:
In this example, two jobs are in progress, and no jobs are queued, awaiting processing. Because jobs may have substantial amounts of job parameters, the display omits these parameters unless you add the option
verbose=1 to the nmis-cli invocation. With verbose, you'll see a result like this:
The important aspects of this verbose display are the 'uuid', which uniquely identifies the node in question for this particular collect operation, and the job 'Id' which is visible in the logs and can be used to abort a job if problems arise.
How to delete Queued Jobs or abort Active Jobs
You can remove queued jobs individually or wholesale using the
act=delete-schedule option of nmis-cli; either pass in the job's Id, (e.g.
id=5d3a48fc0a6b3126df1a1a55) or use the argument
id=ALL with optional further job property filters (e.g.
job.type=services job.uuid=<somenodeuuid> ) to delete just the matching jobs.
A similar operation is possible for aborting active jobs, but please be aware of possible negative consequences: if you abort an active job with
act=abort, then the worker process handling that job is forcibly terminated immediately which may result in data corruption.
Manual Scheduling of Jobs
The nmis cli can be used to create new job schedules manually, and the expected arguments for queue management are shown when you run nmis-cli with
act=schedule without any further parameters):
For example, if you wanted to schedule a forced
update operation for one particular node to be performed five minutes from now, you'd use the following invocation:
If successful nmis-cli will report the queue Id and the expanded parameters of your new job.
Administrative and Other CLI Operations
- If you edit or transfer NMIS files across machines then some file permissions may change for the worse, and the NMIS9 selftest may alert you about invalid file permissions.
The fastest way to resolve this is to use the nmis cli with the
config-backupargument instructs nmis-cli to produce a backup of your configuration files right now;
normally configuration backups are performed automatically and daily.
Logging and Verbosity
Standard Log Files
logs/fping.log: the fping worker process (managed by the nmis daemon) logs all its operations to this log file.
logs/auth.log: contains all authentication-related logging that the NMIS9 GUI produces, in the same format that NMIS8 used.
logs/event.log: contains all nmis node events in a machine-consumable format, identical to NMIS8.
logs/nmis.log: all log data that isn't directed elsewhere goes into this log file.
Please note that in NMIS9 all logs are written to in buffered form: information may arrive on disk a few seconds delayed, but at much less performance cost that NMIS8 incurred.
Log files are now also kept open permanently, until the nmis daemon is instructed to reopen them (by sending a
SIGHUP signal the the nmis daemon process).
The format of the log files
nmis.log has changed:
Now all log messages are prefixed by time tag, severity level and the process name/role and process identifier of the process in question. In the example above the supervisor component of the nmis daemon has logged this informational announcement.
What gets logged?
NMIS9 is able to log a bit more detail than NMIS8, but much more controllable in terms of what to include when.
There are 13 verbosity levels (in increasing order of noisiness):
debug3 and so on to
All messages with severities
debug9 are logged with the tag "
When you set a particular verbosity level then all messages of higher verbosity are suppressed; e.g. at level
info messages of severity
info are logged but messages belonging to severities
debug9 are suppressed.
- By default the configuration property
log_levelcontrols all logging. The default value for this is
- If you start the nmis daemon with a
debug=<level> command line argument, then that will be used for this daemon and its workers.
- For node-admin and nmis-cli invocations the same
debug=<level>command line argument is available.
- A manually scheduled daemon job can have custom
outputpropertes, which control verbosity and target log file for the processing of this job only.
- All NMIS daemon instances can be instructed to change their verbosity levels on the fly while the processes remain running, by sending particular UNIX signals to those processes.
Per-job verbosity and custom log file
If a job schedule includes the property
job.verbosity=<level> , then the job will be processed with that verbosity level. At the end of processing the previous verbosity level is restored.
The related but independent property
job.output=<prefixtext> instructs the NMIS daemon to divert all logging for this one job to a different log file. The log data is saved in the normal
logs directory, and the file is named
<prefixtext>-<highprecision-timestamp>.log , e.g.
logs/quicktest-1564031667.44838.log. When processing completes log output reverts back to the standard log file.
Adjusting process verbosity levels on the fly
All NMIS daemon processes listen for two particular UNIX signals:
- When a daemon process instance receives the
SIGUSR1signal, it increments its verbosity by one level, e.g. from
info, or from
- When a daemon receives the
SIGUSR2signal, it decrements its verbosity by one level.
In both cases a message is logged at the new verbosity level, e.g.:
How to determine which process to signal?
nmis-cli act=statusto see the list of active daemon processes and use
killwith the correct process id,
- or use a smarter
pkilland select by full daemon command line,
pkill -ef -USR2 "nmisd fping"