1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
UPSDRVSVCCTL(8)
===============
NAME
----
upsdrvsvcctl - Network UPS Tools driver service instance controller
SYNOPSIS
--------
*upsdrvsvcctl* -h
*upsdrvsvcctl* ['OPTIONS'] {start | stop | status} ['ups']
DESCRIPTION
-----------
*upsdrvsvcctl* provides a uniform interface for controlling your UPS
drivers wrapped into service instances on platforms which support that
(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.
When used properly, `upsdrvsvcctl` lets you maintain identical startup
scripts across multiple systems with different UPS configurations.
The goal of this solution is to allow the services of linkman:upsd[8]
data server to start up even if some of the power devices are currently
not accessible, and for NUT drivers to be automatically restarted
by the system in case of problems (driver bug, startup failure).
It also allows for faster startup of systems which monitor several
devices, by letting each driver to start in parallel with others
and as soon as the required subsystem for the specific driver's media
is available, i.e. not with a sequential loop like was done previously.
Independent service instances for each NUT driver also allow one
to configure further dependencies, such as that networking must be
available for SNMP and similar drivers (but is not needed for
local-medium drivers such as serial or USB).
The old monolithic "all or nothing" solution requiring that all
drivers must be running, which sufficed for deployments with a few
UPSes, did not really work well for monitoring larger deployments.
It was also not easy to strike a pre-packaged balance between early
UPS protection for USB/serial home setups vs. waiting for network
on larger ones.
*upsdrvsvcctl* is a script which mimics the operation of linkman:upsdrvctl[8]
program (where possible) to provide similar end-user experience when
manipulating drivers wrapped into service instances rather than as
directly executed daemons. It relies on linkman:nut-driver-enumerator[8]
for a large part of actual operations.
You should use `upsdrvsvcctl` instead of direct calls to the drivers
and daemon-based management with linkman:upsdrvctl[8] whenever possible (that
is, for "production" use on compatible OSes). Otherwise (testing,
other OSes) the `upsdrvctl` is a recommended option.
OPTIONS
-------
*-h*::
Display the help text, including the built-in version of the script.
*-V*::
Display the version of NUT binaries (calling *upsdrvctl -V*), which
normally should not differ much from the built-in version of the script
shown in help. But with custom builds everything is possible, so it may
be useful to know.
*-t*::
Enable testing mode. Testing mode makes upsdrvsvcctl display the actions
it would execute without actually doing them.
*--timeout-cmd <prog>* and *--timeout-args <arg>*::
Service management calls will be time-limited by calling the specified
program with its args. By default, if coreutils timeout is found, it
would be used to limit service calls by 90 sec, to avoid/work around
certain hangs that happen in some systemd version under stress.
OPTIONS OF UPSDRVCTL NOT (CURRENTLY) APPLICABLE TO UPSDRVSVCCTL
---------------------------------------------------------------
Options like '-r', '-u' or '-D' could be handled by properties of the
service instances themselves, with this script helping to configure
them (assuming proper privileges of the user who called it). This is
not a "production" use case, though, to change such options on a
configured system -- so for experiments and troubleshooting, it may
be better to stop the service instance and play with *upsdrvctl*
directly.
*-r* 'directory'::
If starting a driver, this value will direct it to linkmanext:chroot[2]
into 'directory'. This can be useful when securing systems.
+
This may be set in the linkman:ups.conf[5] with the +chroot+ directive
in the global section.
*-u* 'username'::
If starting a driver, this value will direct it to linkmanext:setuid[2] to
the user id associated with 'username'.
+
If the driver is started as 'root' without specifying this value, it will
use the username that was compiled into the binary. This defaults to
'nobody' (if not otherwise configured), which is far from ideal.
+
This may be set in linkman:ups.conf[5] with the +user+ directive in the
global section.
*-D*::
Raise the driver debug level. Use this multiple times for additional
details.
COMMANDS
--------
*upsdrvsvcctl* supports three of the commands processed by *upsdrvctl* --
start, stop and shutdown. They take an optional argument which is a UPS
name from linkman:ups.conf[5]. Without that argument, they operate on
every UPS that is currently configured.
Note: shutdown is currently supported by stopping the driver service
instances to release the potentially held ports etc., calling the
*upsdrvctl* directly for issuing the shutdown command, and restarting
the driver service instances to reconnect when the device comes back
online.
*start*::
Start the UPS driver(s). In case of failure, further attempts may be executed
by using the 'maxretry' and 'retrydelay' options -- see linkman:ups.conf[5].
*stop*::
Stop the UPS driver(s).
*status*::
Query run-time status of all configured devices (or one specified device).
Currently defers work to linkman:upsdrvctl[8], to list known device
configurations and their driver daemon details (PID, responsiveness,
`ups.status`) and to linkman:nut-driver-enumerator[8] to map device
names to service unit instances to report their names and states in
the service management framework.
*upsdrvsvcctl* also supports further operations for troubleshooting the
mapping of NUT driver section names to the service instance names (which
may differ due to limitations of various systems).
*list*::
list the currently active mapping of service instances to device sections
*resync*::
update the mapping of service instances for NUT drivers to device section
names used in 'ups.conf' (register new instances, tear down obsoleted ones).
COMMANDS OF UPSDRVCTL NOT (CURRENTLY) APPLICABLE TO UPSDRVSVCCTL
----------------------------------------------------------------
*shutdown*::
Command the UPS driver(s) to run their shutdown sequence. Drivers are
stopped according to their `sdorder` value -- see linkman:ups.conf[5].
WARNING: this will probably power off your computers, so don't
play around with this option. Only use it when your systems are prepared
to lose power.
NOTE: refer to linkman:ups.conf[5] for using the *nowait* parameter.
It can be overridden by `NUT_IGNORE_NOWAIT` environment variable
(e.g. used to work around certain issues with systemd otherwise).
ENVIRONMENT VARIABLES
---------------------
*NUT_CONFPATH* is the path name of the directory that contains
`upsd.conf` and other configuration files. If this variable is not set,
*upsdrvsvcctl* (or rather *nut-driver-enumerator.sh*) would use a built-in
default, which is often `/usr/local/ups/etc`.
DIAGNOSTICS
-----------
upsdrvsvcctl will return a nonzero exit code if it encounters an error
while performing the desired operation. This will also happen if a
driver takes longer than the 'maxstartdelay' period to enter the
background.
Any messages issued by the *upsdrvctl* program used to start the NUT
drivers as part of the service instances' implementations, or by the
drivers themselves, will be logged by the service management framework
facilities and will not appear in your interactive terminal used to
manage the driver.
Use `upsdrvsvcctl list` or `upsdrvsvcctl list NUT-device` to find out
the service instance name for the NUT driver (section name) you are
interested in. Then look up the service logs (where the outputs of the
service implementation program as well as the framework messages about
this service are stored), as suggested below:
*Linux systemd*::
Messages will normally be kept in the service journal, so:
journalctl -lu nut-driver@instance-name
+
Note that your local system configuration may be impacted by such
nuances as passing the journal data to a standard syslog server,
and/or by having a small cache for locally stored journal messages
(so older entries would disappear). There may also be or not be a
copy of the journals stored in the persistent filesystem at all.
*Solaris SMF*::
Look for `/var/svc/log/system-power-nut-driver:instance-name.log` file.
AUTHOR
------
Jim Klimov <jimklimov+nut@gmail.com>
SEE ALSO
--------
linkman:upsdrvctl[8], linkman:nutupsdrv[8], linkman:upsd[8],
linkman:nut-driver-enumerator[8], linkman:ups.conf[5]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/
|
