1UPSDRVSVCCTL(8) NUT Manual UPSDRVSVCCTL(8)
2
6 upsdrvsvcctl - UPS driver service instance controller
7
9 upsdrvsvcctl -h
10 upsdrvsvcctl [OPTIONS] {start | stop } [ups]
12
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 When used properly, upsdrvsvcctl lets you maintain identical startup
22 scripts across multiple systems with different UPS configurations.
23 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 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 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 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 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
55 -h
56 Display the help text.
57 -t
59 Enable testing mode. Testing mode makes upsdrvsvcctl display the
60 actions it would execute without actually doing them.
61
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 -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 This may be set in the ups.conf with "chroot" in the global section.
75 -u username
77 If starting a driver, this value will direct it to setuid(2) to the
78 user id associated with username.
79 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 This may be set in ups.conf with "user" in the global section.
85 -D
87 Raise the driver debug level. Use this multiple times for
88 additional details.
89
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 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 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 stop
108 Stop the UPS driver(s).
109 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 list
115 list the currently active mapping of service instances to device
116 sections
117 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
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 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 Note
134 refer to ups.conf(5) for using the nowait parameter.
135
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
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 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 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 Linux systemd
161 Messages will normally be kept in the service journal, so:
162 journalctl -lu nut-driver@instance-name
164 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 Solaris SMF
172 Look for /var/svc/log/system-power-nut-driver:instance-name.log
173 file.
174
176 Jim Klimov <jimklimov+nut@gmail.com>
177
179 upsdrvctl(8), nutupsdrv(8), upsd(8), nut-driver-enumerator(8),
180 ups.conf(5)
181 Internet resources:
183 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
184Network UPS Tools 2.8.0 04/26/2022 UPSDRVSVCCTL(8)