1UPSDRVSVCCTL(8)                   NUT Manual                   UPSDRVSVCCTL(8)
2
3
4

NAME

6       upsdrvsvcctl - UPS driver service instance controller
7

SYNOPSIS

9       upsdrvsvcctl -h
10
11       upsdrvsvcctl [OPTIONS] {start | stop } [ups]
12

DESCRIPTION

14       upsdrvsvcctl provides a uniform interface for controlling your UPS
15       drivers wrapped into service instances on platforms which support that
16       (currently this covers Linux distributions with systemd and systems
17       derived from Solaris 10 codebase, including proprietary Sun/Oracle
18       Solaris and numerous open-source illumos distributions with SMF). It
19       may be not installed in packaging for other operating systems.
20
21       When used properly, upsdrvsvcctl lets you maintain identical startup
22       scripts across multiple systems with different UPS configurations.
23
24       The goal of this solution is to allow the services of upsd data server
25       to start up even if some of the power devices are currently not
26       accessible, and for NUT drivers to be automatically restarted by the
27       system in case of problems (driver bug, startup failure). It also
28       allows for faster startup of systems which monitor several devices, by
29       letting each driver to start in parallel with others, and not with a
30       sequential loop like was done previously.
31
32       Independent service instances for each NUT driver also allow one to
33       configure further dependencies, such as that networking must be
34       available for SNMP and similar drivers (but is not needed for
35       local-medium drivers such as serial or USB).
36
37       The old monolithic "all or nothing" solution requiring that all drivers
38       must be running, which sufficed for deployments with a few UPSes, did
39       not really work well for monitoring larger deployments. It was also not
40       easy to strike a pre-packaged balance between early UPS protection for
41       USB/serial home setups vs. waiting for network on larger ones.
42
43       upsdrvsvcctl is a script which mimics the operation of upsdrvctl
44       program (where possible) to provide similar end-user experience when
45       manipulating drivers wrapped into service instances rather than as
46       directly executed daemons. It relies on nut-driver-enumerator.sh for a
47       large part of actual operations.
48
49       You should use upsdrvsvcctl instead of direct calls to the drivers and
50       daemon-based management with upsdrvctl whenever possible (that is, for
51       "production" use on compatible OSes). Otherwise (testing, other OSes)
52       the upsdrvctl is a recommended option.
53

OPTIONS

55       -h
56           Display the help text.
57
58       -t
59           Enable testing mode. Testing mode makes upsdrvsvcctl display the
60           actions it would execute without actually doing them.
61

OPTIONS OF UPSDRVCTL NOT (CURRENTLY) APPLICABLE TO UPSDRVSVCCTL

63       Options like -r, -u or -D could be handled by properties of the service
64       instances themselves, with this script helping to configure them
65       (assuming proper privileges of the user who called it). This is not a
66       "production" use case, though, to change such options on a configured
67       system — so for experiments and troubleshooting, it may be better to
68       stop the service instance and play with upsdrvctl directly.
69
70       -r directory
71           If starting a driver, this value will direct it to chroot(2) into
72           directory. This can be useful when securing systems.
73
74       This may be set in the ups.conf with "chroot" in the global section.
75
76       -u username
77           If starting a driver, this value will direct it to setuid(2) to the
78           user id associated with username.
79
80       If the driver is started as root without specifying this value, it will
81       use the username that was compiled into the binary. This defaults to
82       "nobody", and is far from ideal.
83
84       This may be set in ups.conf with "user" in the global section.
85
86       -D
87           Raise the driver debug level. Use this multiple times for
88           additional details.
89

COMMANDS

91       upsdrvsvcctl supports three of the commands processed by upsdrvctl 
92       start, stop and shutdown. They take an optional argument which is a UPS
93       name from ups.conf(5). Without that argument, they operate on every UPS
94       that is currently configured.
95
96       Note: shutdown is currently supported by stopping the driver service
97       instances to release the potentially held ports etc., calling the
98       upsdrvctl directly for issuing the shutdown command, and restarting the
99       driver service instances to reconnect when the device comes back
100       online.
101
102       start
103           Start the UPS driver(s). In case of failure, further attempts may
104           be executed by using the maxretry and retrydelay options - see
105           ups.conf(5).
106
107       stop
108           Stop the UPS driver(s).
109
110       upsdrvsvcctl also supports further operations for troubleshooting the
111       mapping of NUT driver section names to the service instance names
112       (which may differ due to limitations of various systems).
113
114       list
115           list the currently active mapping of service instances to device
116           sections
117
118       resync
119           update the mapping of service instances for NUT drivers to device
120           section names used in ups.conf (register new instances, tear down
121           obsoleted ones).
122

COMMANDS OF UPSDRVCTL NOT (CURRENTLY) APPLICABLE TO UPSDRVSVCCTL

124       shutdown
125           Command the UPS driver(s) to run their shutdown sequence. Drivers
126           are stopped according to their sdorder value - see ups.conf(5).
127
128           Warning
129           this will probably power off your computers, so don’t play around
130           with this option. Only use it when your systems are prepared to
131           lose power.
132
133           Note
134           refer to ups.conf(5) for using the nowait parameter.
135

ENVIRONMENT VARIABLES

137       NUT_CONFPATH is the path name of the directory that contains upsd.conf
138       and other configuration files. If this variable is not set,
139       upsdrvsvcctl (or rather nut-driver-enumerator.sh) would use a built-in
140       default, which is often /usr/local/ups/etc.
141

DIAGNOSTICS

143       upsdrvsvcctl will return a nonzero exit code if it encounters an error
144       while performing the desired operation. This will also happen if a
145       driver takes longer than the maxstartdelay period to enter the
146       background.
147
148       Any messages issued by the upsdrvctl program used to start the NUT
149       drivers as part of the service instances' implementations, or by the
150       drivers themselves, will be logged by the service management framework
151       facilities and will not appear in your interactive terminal used to
152       manage the driver.
153
154       Use upsdrvsvcctl list or upsdrvsvcctl list NUT-device to find out the
155       service instance name for the NUT driver (section name) you are
156       interested in. Then look up the service logs (where the outputs of the
157       service implementation program as well as the framework messages about
158       this service are stored), as suggested below:
159
160       Linux systemd
161           Messages will normally be kept in the service journal, so:
162
163               journalctl -lu nut-driver@instance-name
164
165       Note that your local system configuration may be impacted by such
166       nuances as passing the journal data to a standard syslog server, and/or
167       by having a small cache for locally stored journal messages (so older
168       entries would disappear). There may also be or not be a copy of the
169       journals stored in the filesystem.
170
171       Solaris SMF
172           Look for /var/svc/log/system-power-nut-driver:instance-name.log
173           file.
174

AUTHOR

176       Jim Klimov <jimklimov+nut@gmail.com>
177

SEE ALSO

179       upsdrvctl(8), nutupsdrv(8), upsd(8), nut-driver-enumerator(8),
180       ups.conf(5)
181
182   Internet resources:
183       The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
184
185
186
187Network UPS Tools 2.8.0           04/26/2022                   UPSDRVSVCCTL(8)
Impressum