Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
UPS.CONF(5)			  NUT Manual			   UPS.CONF(5)

NAME
       ups.conf	- UPS definitions for Network UPS Tools

DESCRIPTION
       This file is read by the	driver controller upsdrvctl(8),	the UPS
       drivers that use	the common core	(see nutupsdrv(8), and upsd(8)). The
       file begins with	global directives, and then each UPS has a section
       which contains a	number of directives that set parameters for that UPS.

       A UPS section begins with the name of the UPS in	brackets, and
       continues until the next	UPS name in brackets or	until EOF. The name
       "default" is used internally in upsd, so	you can't use it in this file.

       You must	define the driver and port elements for	each entry. Anything
       after that in a section is optional. A simple example might look	like
       this:

	   [myups]
		   driver = blazer_ser
		   port	= /dev/ttyS0
		   desc	= "Web server UPS"

       A slightly more complicated version includes some extras	for the
       hardware-specific part of the driver:

	   [bigups]
		   driver = apcsmart
		   port	= /dev/cua00
		   cable = 940-0095B
		   sdtype = 2
		   desc	= "Database server UPS"

       In this case, the apcsmart(8) driver will receive variables called
       "cable" and "sdtype" which have special meanings. See the man pages of
       your driver(s) to learn which variables are supported and what they do.

GLOBAL DIRECTIVES
       chroot
	   Optional. The driver	will chroot(2) to this directory during
	   initialization. This	can be useful when securing systems.

       driverpath
	   Optional. Path name of the directory	in which the UPS driver
	   executables reside. If you don't specify this, the programs look in
	   a built-in default directory, which is often	/usr/local/ups/bin.

       maxstartdelay
	   Optional. Same as the UPS field of the same name, but this is the
	   default for UPSes that don't	have the field.

       maxretry
	   Optional. Specify the number	of attempts to start the driver(s), in
	   case	of failure, before giving up. A	delay of retrydelay is
	   inserted between each attempt. Caution should be taken when using
	   this	option,	since it can impact the	time taken by your system to
	   start.

	   The default is 1 attempt.

       retrydelay
	   Optional. Specify the delay between each restart attempt of the
	   driver(s), as specified by maxretry.	Caution	should be taken	when
	   using this option, since it can impact the time taken by your
	   system to start.

	   The default is 5 seconds.

       pollinterval
	   Optional. The status	of the UPS will	be refreshed after a maximum
	   delay which is controlled by	this setting. This is normally 2
	   seconds. This may be	useful if the driver is	creating too much of a
	   load	on your	system or network.

       synchronous
	   Optional. The driver	work by	default	in asynchronous	mode (i.e
	   synchronous=no). This means that all	data are pushed	by the driver
	   on the communication	socket to upsd (Unix socket on Unix, Named
	   pipe	on Windows) without waiting for	these data to be actually
	   consumed. With some HW, such	as ePDUs, that can produce a lot of
	   data, asynchronous mode may cause some congestion, resulting	in the
	   socket to be	full, and the driver to	appear as not connected. In
	   such	case, the driver will provide the following debug message:

	       write XX	bytes to socket	Y failed

	   By enabling the synchronous flag (value = yes), the driver will
	   wait	for data to be consumed	by upsd, prior to publishing more.
	   This	can be enabled either globally or per driver.

	   The default is no (i.e. asynchronous	mode) for backward
	   compatibility of the	driver behavior.

       user
	   Optional. If	started	as root, the driver will setuid(2) to the user
	   id associated with username.

UPS FIELDS
       driver
	   Required. This specifies which program will be monitoring this UPS.
	   You need to specify the one that is compatible with your hardware.
	   See nutupsdrv(8) for	more information on drivers in general and
	   pointers to the man pages of	specific drivers.

       port
	   Required. This is the serial	port where the UPS is connected. On a
	   Linux system, the first serial port usually is /dev/ttyS0. On
	   FreeBSD and similar systems,	it probably will be /dev/cuaa0.

       sdorder
	   Optional. When you have multiple UPSes on your system, you usually
	   need	to turn	them off in a certain order. upsdrvctl shuts down all
	   the 0s, then	the 1s,	2s, and	so on. To exclude a UPS	from the
	   shutdown sequence, set this to -1.

	   The default value for this parameter	is 0.

       desc
	   Optional. This allows you to	set a brief description	that upsd will
	   provide to clients that ask for a list of connected equipment.

       nolock
	   Optional. When you specify this, the	driver skips the port locking
	   routines every time it starts. This may allow other processes to
	   seize the port if you start more than one accidentally.

	   You should only use this if your system won't work without it.

	   This	may be needed on Mac OS	X systems.

       ignorelb
	   Optional. When you specify this, the	driver ignores a low battery
	   condition flag that is reported by the UPS (some devices will
	   switch off almost immediately after setting this flag, or will
	   report this as soons	as the mains fails). Instead it	will use
	   either of the following conditions to determine when	the battery is
	   low:

	       battery.charge <	battery.charge.low
	       battery.runtime < battery.runtime.low

	   The idea is to set the battery.charge.low and/or
	   battery.runtime.low levels in ups.conf to a value that gives	enough
	   time	to cleanly shutdown your system:

	       override.battery.charge.low = 30
	       override.battery.runtime.low = 180

	   In order for	this to	work, your UPS should be able to (reliably)
	   report charge and/or	runtime	remaining on battery. Use with
	   caution!

       maxstartdelay
	   Optional. This can be set as	a global variable above	your first UPS
	   definition and it can also be set in	a UPS section. This value
	   controls how	long upsdrvctl will wait for the driver	to finish
	   starting. This keeps	your system from getting stuck due to a	broken
	   driver or UPS.

	   The default is 45 seconds.

       synchronous
	   Optional. Same as the global	directive of the same name, but	this
	   is for a specific device.

       usb_set_altinterface[=altinterface]
	   Optional. Force the USB code	to call	usb_set_altinterface(0), as
	   was done in NUT 2.7.2 and earlier. This should not be necessary,
	   since the default for bAlternateSetting (as shown in	lsusb) is zero
	   on all USB devices seen to date. However, this redundant call to
	   usb_set_altinterface() prevents certain UPSes from working on Mac
	   OS X. If your UPS requires explicitly setting the alternate
	   interface, include this flag, and email the nut-upsdev list with
	   details about your UPS and operating	system.

       default.<variable>
	   Optional. Set a default value for <variable>	which is used in case
	   the UPS doesn't provide a value, but	will be	overwritten if a value
	   is available	from the UPS:

	       default.input.voltage.nominal = 230

	   The above will report the nominal input voltage to be 230, unless
	   the UPS tells us differently.

       override.<variable>
	   Optional. Set a value for <value> that overrides any	value that may
	   be read from	the UPS. Used for overriding values from the UPS that
	   are clearly wrong (some devices report wrong	values for battery
	   voltage for instance):

	       override.battery.voltage.nominal	= 12

	   Use with caution! This will only change the appearance of the
	   variable to the outside world, internally in	the UPS	the original
	   value is used.

       All other fields	are passed through to the hardware-specific part of
       the driver. See those manuals for the list of what is allowed.

INTEGRATION
       upsdrvctl(8) uses this file to start and	stop the drivers.

       The drivers themselves also obtain configuration	data from this file.
       Each driver looks up its	section	and uses that to configure itself.

       upsd(8) learns about which UPSes	are installed on this system by
       reading this file. If this system is called "doghouse" and you have
       defined a UPS in	your ups.conf called "snoopy", then you	can monitor it
       from upsc(8) or similar as "snoopy@doghouse".

SEE ALSO
       upsd(8),	nutupsdrv(8), upsdrvctl(8)

   Internet resources
       The NUT (Network	UPS Tools) home	page: http://www.networkupstools.org/

Network	UPS Tools 2.7.3.	  12/29/2015			   UPS.CONF(5)

NAME | DESCRIPTION | GLOBAL DIRECTIVES | UPS FIELDS | INTEGRATION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ups.conf&manpath=FreeBSD+11.2-RELEASE+and+Ports>

home | help