82
If you would like sample versions of the configuration files to
83
be installed, use the install-conf target:
87
Sample files are installed with names like ups.conf.sample so they
88
will not overwrite any existing real config files you may have
79
91
If you are packaging this software, then you will probably want to
80
92
use the DESTDIR variable to redirect the build into another place,
83
95
make DESTDIR=/tmp/package install
96
make DESTDIR=/tmp/package install-conf
85
98
---------------------------------------------------------------------------
87
5. Create a directory for the driver(s) and server to use for data,
88
and make it owned by the user you created.
100
5. Create the state path directory for the driver(s) and server to use
101
for storing UPS status data and other auxiliary files, and make it
102
owned by the user you created.
104
mkdir -p /var/state/ups
91
105
chmod 0700 /var/state/ups
92
106
chown nut:nut /var/state/ups
98
112
the user you created earlier.
100
114
These examples assume the second serial port (ttyS1) on a typical
101
Slackware system. Serial port device names vary greatly, so yours
102
may be quite different.
115
Slackware system. On FreeBSD, that would be cuaa1. Serial ports
116
vary greatly, so yours may be called something else.
104
118
chmod 0600 /dev/ttyS1
105
119
chown nut:nut /dev/ttyS1
107
121
NOTE: if you are using something like devfs, make sure these
108
permissions do not reset themselves when your system reboots.
109
Otherwise, your driver(s) may fail to start.
122
permissions stay set across a reboot. If they revert to the old
123
values, your drivers may fail to start.
111
125
---------------------------------------------------------------------------
113
7. Create section(s) for your hardware in /usr/local/ups/etc/ups.conf
127
7. Create one section per UPS in /usr/local/ups/etc/ups.conf
115
129
To find out which driver to use, check the "HARDWARE SUPPORT TABLE"
116
in the README file, or docs/driver.list.
118
Once you have picked a driver, create an entry for your UPS in
119
ups.conf. If the driver does not need any extra configuration
120
options, then it should resemble this:
130
in the README file, or data/driver.list.
132
Once you have picked a driver, create a section for your UPS in
133
ups.conf. You must supply values for "driver" and "port".
135
Some drivers may require other flags or settings. The "desc" value
136
is optional, but is recommended to provide a better description of
137
what your UPS is supporting.
139
A typical UPS without any extra settings looks like this:
123
142
driver = mydriver
124
143
port = /dev/ttyS1
134
153
/usr/local/ups/bin/upsdrvctl start
136
If the driver doesn't start cleanly, make sure you're starting the
137
right one for your hardware. Also check the man page for the
138
driver to see if there are any extra values that you can set.
155
Make sure the driver doesn't report any errors. It should show a
156
few details about the hardware and then enter the background. You
157
should get back to the command prompt a few seconds later. For
158
reference, a successful start of the belkin driver looks like this:
160
# /usr/local/ups/bin/upsdrvctl start
161
Network UPS Tools - UPS driver controller 1.5.12
162
Network UPS Tools - Belkin Smart protocol driver 0.21 (1.5.12)
163
Detected F6C525-SER on /dev/cuaa0
166
If the driver doesn't start cleanly, make sure you have picked the
167
right one for your hardware. You might need to try other drivers
168
by changing the "driver=" value in ups.conf.
170
Be sure to check the driver's man page to see if it needs any extra
171
settings in ups.conf to detect your hardware.
140
173
If it says "can't bind /var/state/ups/..." or similar, then your
141
174
state path probably isn't writable by the driver. Check the
142
permissions and mode on that directory.
175
permissions and mode on that directory (step 5).
144
177
After making changes, try step 6 again.
148
181
---------------------------------------------------------------------------
150
9. Configure the network server (upsd). The files that need your
151
attention are upsd.conf and upsd.users. Sample versions are
152
installed in most cases.
183
9. Configure upsd, which serves data from the drivers to the clients.
154
At the very least, you need something like this in upsd.conf:
185
First, edit upsd.conf to allow access to your client systems.
186
A minimal configuration which allows localhost to read status
187
data (and nothing else) looks like this:
156
189
ACL all 0.0.0.0/0
157
190
ACL localhost 127.0.0.1/32
159
ACCESS grant monitor localhost
162
That much is already in the sample upsd.conf, so just copying that
163
to the proper name should get you started. You should add
164
additional ACL/ACCESS directives for other hosts/networks that need
165
to talk to upsd on this system.
167
Note: upsd.conf and upsd.users must not be world-readable, since
168
they control access controls and passwords. They do need to be
169
readable by the user you created in the preparation process.
171
The suggested configuration is to make it owned by that user,
174
chown nut:nut upsd.conf upsd.users
175
chmod 0400 upsd.conf upsd.users
195
If you have other hosts or networks which will need to talk to
196
upsd, you should create ACL and ACCEPT directives for them.
198
Next, create upsd.users. For now, this can be an empty file.
199
You can come back and add more to it later when it's time to
200
configure upsmon or run one of the management tools.
202
Do not make either file world-readable, since they both hold
203
access control data and passwords. They just need to be readable by
204
the user you created in the preparation process.
206
The suggested configuration is to chown it to root, chgrp it to the
207
group you created, then make it readable by the group.
209
chown root:nut upsd.conf upsd.users
210
chmod 0640 upsd.conf upsd.users
177
212
*** References: man pages: upsd.conf(5), upsd.users(5), upsd(8)
183
218
/usr/local/ups/sbin/upsd
220
Make sure it is able to connect to the driver(s) on your system.
221
A successful run looks like this:
223
# /usr/local/ups/sbin/upsd
224
Network UPS Tools upsd 1.5.12
225
Connected to UPS [belkin]: belkin-cuaa0
229
upsd prints dots while it waits for the driver to respond. Your
230
system may print more or less depending on how many drivers you
231
have and how fast they are.
185
233
NOTE: if upsd says that it can't connect to a UPS or that the data
186
234
is stale, then your ups.conf is not configured correctly, or you
187
have a driver that isn't working properly.
189
Nothing else will work until you fix it.
235
have a driver that isn't working properly. You must fix this before
236
going on to the next step.
191
238
*** Reference: man page: upsd(8)
195
242
11. Make sure that the UPS is providing good status data.
197
/usr/local/ups/bin/upsc myupsname@localhost
199
Ignore everything but "ups.status" for now. If your system is
200
running on line power, it should have "OL" in that field.
201
Otherwise, something is wrong with the driver that was configured in
244
/usr/local/ups/bin/upsc myupsname@localhost ups.status
246
You should see just one line in response:
250
OL means your system is running on line power. If it says something
251
else (like OB - on battery, or LB - low battery), your driver was
252
probably misconfigured in step 7. If you reconfigure the driver,
253
use 'upsdrvctl stop' to stop it, then start it again in step 8.
204
255
If upsc says "access denied", then your upsd.conf probably doesn't
205
have a good ACL/ACCESS definition for your host.
207
*** Reference: man page: upsc(8)
209
---------------------------------------------------------------------------
211
12. Edit your startup scripts.
256
have a good ACL/ACCEPT definition for your host. Go back to step
257
9 and fix it. If you reconfigure upsd, you must either stop and
258
restart it, or tell it to reload (upsd -c reload).
260
*** Reference: man page: upsc(8)
262
---------------------------------------------------------------------------
264
12. Look at all of the status data which is being monitored.
266
/usr/local/ups/bin/upsc myupsname@localhost
268
What happens now depends on the kind of UPS and driver you have.
269
In the list, you should see ups.status with the same value you got
270
above. A sample run on a Belkin Regulator Pro looks like this:
273
battery.temperature: 048
274
battery.voltage: 13.9
276
driver.parameter.port: /dev/cuaa0
277
driver.version: 1.5.12
278
driver.version.internal: 0.21
279
input.frequency: 59.9
280
input.transfer.high: 127.6
281
input.transfer.low: 96.6
283
output.frequency: 59.9
284
output.voltage: 119.0
288
ups.model: F6C525-SER
292
*** Reference: man page: upsc(8)
294
---------------------------------------------------------------------------
296
13. Edit your startup scripts.
213
298
Make sure upsdrvctl and upsd are run every time your system starts.
224
309
sure your system shuts down properly, you will need to perform some
225
310
additional configuration and run upsmon. Here are the basics:
312
---------------------------------------------------------------------------
227
314
1. Configure upsd to recognize upsmon.
229
316
First create an ACL in upsd.conf for the host that will be running
230
upsmon. Be sure to grant it monitor privileges with an ACCESS line.
231
This will allow upsmon to connect to upsd.
317
upsmon. Then use it in an ACCEPT line to allow that host to monitor
318
the UPS. This will let upsmon connect to upsd.
320
Assuming a host called mybox with the IP address of 192.168.1.50,
321
the configuration looks like this:
323
ACL mybox 192.168.1.50/32
326
You probably have other ACL and ACCEPT/REJECT lines, so be sure this
327
ACCEPT happens above any REJECTs which may match this client. Most
328
users have a "REJECT all" at the bottom. Here's an example which
329
grants access to localhost and mybox, then rejects anything else.
233
331
ACL all 0.0.0.0/0
235
ACCESS grant monitor mybox
332
ACL localhost 127.0.0.1/32
333
ACL mybox 192.168.1.50/32
339
Note: if you run a firewall of some sort, you may have to add a rule
340
to allow this connection. upsd runs on port 3493/tcp by default.
238
342
*** References: man pages: upsd(8), upsd.conf(5)
240
344
---------------------------------------------------------------------------
242
2. Edit upsd.users, and create a user for upsmon to use. This will
243
allow upsmon to coordinate shutdowns with other systems.
346
2. Create a upsd user for upsmon to use while monitoring this UPS.
348
Edit upsd.users and create a new section. upsmon will connect
349
to upsd and use this user name (in brackets) and password to
350
authenticate. This example is for a user called "monuser":
246
353
password = mypass
247
354
allowfrom = mybox
248
upsmon master (or upsmon slave)
355
upsmon master # or upsmon slave
250
357
*** References: man pages: upsd(8), upsd.users(5)
252
359
---------------------------------------------------------------------------
254
3. Edit upsmon.conf, and create a MONITOR directive with that host,
255
username, and password.
257
MONITOR myupsname@mybox 1 monuser mypass master (or slave)
259
Also check the POWERDOWNFLAG to make sure it's what you want.
261
*** References: man pages: upsmon(8), upsmon.conf(5)
263
---------------------------------------------------------------------------
265
4. Reload upsd. Depending on your configuration, you may be able to
361
3. Reload upsd. Depending on your configuration, you may be able to
266
362
do this without stopping upsd:
268
364
/usr/local/ups/sbin/upsd -c reload
278
374
---------------------------------------------------------------------------
376
4. Set the POWERDOWNFLAG location for upsmon.
378
In upsmon.conf, add a POWERDOWNFLAG directive with a filename.
379
upsmon will create this file when the UPS needs to be powered off
380
during a power failure when low battery is reached.
382
We will test for the presence of this file in a later step.
384
POWERDOWNFLAG /etc/killpower
386
*** References: man pages: upsmon(8), upsmon.conf(5)
388
---------------------------------------------------------------------------
390
5. Secure upsmon.conf.
392
The recommended setting is to have it owned by root:nut, then
393
make it readable by the group and not world. This file contains
394
passwords that could be used by an attacker to start a shutdown,
397
chown root:nut upsmon.conf
398
chmod 0640 upsmon.conf
400
This step has been placed early in the process so you secure this
401
file before adding sensitive data in the next step.
403
---------------------------------------------------------------------------
405
6. Create a MONITOR directive for upsmon
407
Edit upsmon.conf and create a MONITOR line with the UPS definition
408
(<upsname>@<hostname>), username and password from step 2, and
409
the master or slave setting.
411
If it's the master (i.e., it's connected to this UPS directly):
413
MONITOR myupsname@mybox 1 monuser mypass master
415
If it's just monitoring this UPS over the network, and some other
416
system is the master:
418
MONITOR myupsname@mybox 1 monuser mypass slave
420
The number "1" here is the power value. This should always be set
421
to 1 unless you have a very special (read: expensive) system with
422
redundant power supplies. See big-servers.txt and data-room.txt.
424
*** References: man pages: upsmon(8), upsmon.conf(5)
426
---------------------------------------------------------------------------
428
7. Define a SHUTDOWNCMD for upsmon.
430
Still in upsmon.conf, add a directive that tells upsmon how to
431
shut down your system. This example seems to work on most systems:
433
SHUTDOWNCMD "/sbin/shutdown -h +0"
435
Notice the presence of "quotes" here to keep it together.
437
If your system has special needs, you may want to set this to
438
a script which does local shutdown tasks before calling init.
440
---------------------------------------------------------------------------
282
444
/usr/local/ups/sbin/upsmon
446
If it complains about something, then check your configuration.
284
448
---------------------------------------------------------------------------
286
6. Look for messages in the syslog to indicate success. It should look
450
9. Look for messages in the syslog to indicate success. It should look
287
451
something like this:
289
453
May 29 01:11:27 mybox upsmon[102]: Startup successful
290
May 29 01:11:28 mybox upsd[100]: Client monuser@a.b.c.d logged into UPS [myupsname]
454
May 29 01:11:28 mybox upsd[100]: Client monuser@192.168.50.1
455
logged into UPS [myupsname]
457
Any errors seen here are probably due to an error in the config
458
files of either upsmon or upsd. You should fix them before
292
461
---------------------------------------------------------------------------
294
7. Edit your startup scripts: add upsmon
463
10. Edit your startup scripts: add upsmon
296
465
Make sure upsmon starts when your system comes up. Do it after
297
466
upsdrvctl and upsd, or it will complain about not being able to
added
removed
INSTALL
