nut-debian/docs/man/nut-driver-enumerator.8
2022-07-10 09:23:45 +02:00

159 lines
6.6 KiB
Groff

'\" t
.\" Title: nut-driver-enumerator
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 04/26/2022
.\" Manual: NUT Manual
.\" Source: Network UPS Tools 2.8.0
.\" Language: English
.\"
.TH "NUT\-DRIVER\-ENUMERA" "8" "04/26/2022" "Network UPS Tools 2\&.8\&.0" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
nut-driver-enumerator \- tool to map NUT device entries to service instances
.SH "SYNOPSIS"
.sp
\fBnut\-driver\-enumerator\&.sh\fR \-h
.sp
\fBnut\-driver\-enumerator\&.sh\fR (no args)
.sp
\fBnut\-driver\-enumerator\&.sh\fR [\-\-COMMAND]
.SH "DESCRIPTION"
.sp
\fBnut\-driver\-enumerator\&.sh\fR implements the set\-up and querying of the mapping between NUT driver configuration sections for each individual monitored device, and the operating system service management framework service instances into which such drivers are wrapped for independent execution and management (on platforms where NUT currently supports this integration \(em currently this covers Linux distributions with systemd and systems derived from Solaris 10 codebase, including proprietary Sun/Oracle Solaris and numerous open\-source illumos distributions with SMF)\&. It may be not installed in packaging for other operating systems\&.
.sp
This script provides a uniform interface for further NUT tools such as \fBupsdrvsvcctl\fR(8) to implement their logic as platform\-independently as was possible and practical\&. It is not currently intended for end\-user consumption (and so is located in the \fIlibexec\fR directory), with \fBupsdrvsvcctl\fR exposing the most useful data and actions with its \fIlist\fR and \fIresync\fR arguments\&.
.sp
One part of the platform complexity that \fBnut\-driver\-enumerator\&.sh\fR hides is the difference of rules for valid service instance names in various frameworks, as well as system tools and naming patterns involved\&.
.SH "COMMANDS"
.PP
\fBnut\-driver\-enumerator\&.sh (no args)\fR
.RS 4
Update wrapping of devices into services
.RE
.PP
\fBnut\-driver\-enumerator\&.sh \-\-daemon(=freq)\fR
.RS 4
Update wrapping of devices into services in an infinite loop; Default freq is 60 sec\&.
.RE
.PP
\fBnut\-driver\-enumerator\&.sh \-\-reconfigure\fR
.RS 4
Stop and un\-register all service instances and recreate them (e\&.g\&. if new dependency template was defined in a new version of the script or package)
.RE
.PP
\fBnut\-driver\-enumerator\&.sh \-\-get\-service\-framework\fR
.RS 4
Print the detected service management framework in this OS
.RE
.PP
\fBnut\-driver\-enumerator\&.sh \-\-list\-devices\fR
.RS 4
Print list of devices in NUT config
.RE
.PP
\fBnut\-driver\-enumerator\&.sh \-\-list\-services\fR
.RS 4
Print list of service instances which wrap registered NUT devices (full name of service unit)
.RE
.PP
\fBnut\-driver\-enumerator\&.sh \-\-list\-instances\fR
.RS 4
Print list of service instances which wrap registered NUT devices (just instance suffix)
.RE
.PP
\fBnut\-driver\-enumerator\&.sh \-\-get\-service\-for\-device DEV\fR
.RS 4
Print the full name of service unit which wraps a NUT device named
DEV
.RE
.PP
\fBnut\-driver\-enumerator\&.sh \-\-get\-device\-for\-service SVC\fR
.RS 4
Print the NUT device name for full or instance\-suffix name of a service unit
SVC
which wraps it
.RE
.PP
\fBnut\-driver\-enumerator\&.sh \-\-list\-services\-for\-devices\fR
.RS 4
Print a TAB\-separated list of service units and corresponding NUT device names which each such unit wraps
.RE
.PP
\fBnut\-driver\-enumerator\&.sh \-\-show\-all\-configs\fR
.RS 4
Show the complete normalized list of device configuration blocks (same as used later by the parser in the script to make decisions)
.RE
.PP
\fBnut\-driver\-enumerator\&.sh \-\-show\-device\-config DEV\fR
.RS 4
Show configuration block of the specified NUT device
.RE
.PP
\fBnut\-driver\-enumerator\&.sh \-\-show\-device\-config\-value DEV KEY\fR
.RS 4
Show single configuration key of the specified NUT device
.RE
.SH "ENVIRONMENT VARIABLES"
.sp
By default \fBnut\-driver\-enumerator\&.sh\fR executed without arguments would automatically start any newly registered service instances wrapping the NUT devices, and would also restart the nut\-server service if the configuration was changed\&. Environment variable AUTO_START=no disables this default part of the action\&.
.sp
Also see below for environment variable REPORT_RESTART_42=no value\&.
.SH "DIAGNOSTICS"
.sp
\fBnut\-driver\-enumerator\&.sh\fR will return a zero exit code if it had nothing to do (all currently defined drivers match all of the currently defined service instances, one\-to\-one) and if it had no errors in its operation\&.
.sp
Other codes can be returned as a result of re\-synchronization of mappings:
.PP
\fB42\fR
.RS 4
NUT device sections and system service instances differed before, but now match up \(em so now the caller should likely restart some services\&. Note that the drivers\*(Aq service instances may have been started or stopped as required (by
AUTO_START=yes) \(em but maybe the upsmon or upssched services should restart\&. If you pass environment variable
REPORT_RESTART_42=no
then this codepath would return 0 (as a non\-error exit code)\&. In default mode, such non\-null reconfiguration should cause the nut\-driver\-enumerator service to restart and this would propagate to other NUT services that depend on it\&.
.RE
.PP
\fB13\fR
.RS 4
Sections and services differed, and still do not match up
.RE
.PP
\fB1\fR
.RS 4
Bad inputs, e\&.g\&. unrecognized service management framework
.RE
.PP
\fB2\fR
.RS 4
Absent or unreadable
ups\&.conf
file
.RE
.SH "AUTHOR"
.sp
Jim Klimov <jimklimov+nut@gmail\&.com>
.SH "SEE ALSO"
.sp
\fBupsdrvsvcctl\fR(8), \fBups.conf\fR(5)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/