# Network UPS Tools: example ups.conf
#
# --- SECURITY NOTE ---
#
# If you use snmp-ups and set a community string in here, you
# will have to secure this file to keep other users from obtaining
# that string.  It needs to be readable by upsdrvctl and any drivers,
# and by upsd.
#
# ---
#
# NOTE: Contents of this file should be pure ASCII (character codes
# not in range would be ignored with a warning message).
#
# This is where you configure all the UPSes that this system will be
# monitoring directly.  These are usually attached to serial ports, but
# USB devices and SNMP devices are also supported.
#
# This file is used by upsdrvctl to start and stop your driver(s), and
# is also used by upsd to determine which drivers to monitor.  The
# drivers themselves also read this file for configuration directives.
#
# The general form is:
#
# [upsname]
#       driver = <drivername>
#         port = <portname>
#       < any other directives here >
#
# The section header ([upsname]) can be just about anything as long as
# it is a single word inside brackets.  upsd uses this to uniquely
# identify a UPS on this system.
#
# If you have a UPS called snoopy, your section header would be "[snoopy]".
# On a system called "doghouse", the line in your upsmon.conf to monitor
# and manage it would look something like this:
#
#   MONITOR snoopy@doghouse 1 monuser mypassword primary
#
# It might look like this if monitoring in "secondary" mode (without any
# ability to directly manage the UPS) from a different system:
#
#   MONITOR snoopy@doghouse 1 monuser mypassword secondary
#
# Configuration directives
# ------------------------
#
# These directives are used by upsdrvctl only and should be specified outside
# of a driver definition:
#
#      chroot: OPTIONAL. Used for securing. See man page for details.
#
#  driverpath: OPTIONAL. Used for custom setups. See man page for details.
#
#   statepath: OPTIONAL. Used for custom setups. Tell drivers to place their
#              state sockets for communication with 'upsd' in 'path' rather
#              than the default location that was compiled into the program.
#              Note that the drivers must use the same path as 'upsd', so the
#              data server would prefer this setting from `ups.conf` global
#              section, if present, over its own in `upsd.conf`.
#              Environment variable NUT_STATEPATH set by caller can override
#              this setting.
#
#      nowait: OPTIONAL. Tell upsdrvctl to not wait at all for the driver(s)
#              to execute the requested command. Fire and forget.
#
# pollinterval: OPTIONAL. The status of the UPS will be refreshed after a
#              maximum delay which is controlled by this setting (default
#              2 seconds). This may be useful if the driver is creating too
#              much of a load on your system or network.
#              Note that some drivers also have an option called *pollfreq*
#              which controls how frequently some of the less critical
#              parameters are polled. See respective driver man pages.
#

# Set maxretry to 3 by default, this should mitigate race with slow devices:
maxretry = 3

# These directives can be set outside and inside a driver definition,
# sometimes with slightly different meanings per context:
#
#    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 built-in 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.
#
# 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.
#                Note that after this time upsdrvctl would just move
#                along with its business (whether retrying the same
#                driver if `maxretry>1`, or trying another driver if
#                starting them all, or just eventually exit); however,
#                each such most recently started "stuck" driver process
#                may be further initializing in the background, and
#                might even succeed eventually.
#                They would not be actively killed by upsdrvctl after
#                this timeout expires.
#
#                The default is 75 seconds.
#
#   debug_min: OPTIONAL.  Specify a minimum debug level for all driver daemons
#              and for the upsdrvctl tool (when specified at global level),
#              or for this driver daemon (when specified in a driver section),
#              e.g. for troubleshooting a deployment without changing init
#              scripts. This does not directly impact the foreground or
#              background running mode. If both the global and driver level
#              `debug_min` are set, the driver-level setting takes precedence.
#              Command-line option `-D` can only increase this verbosity level.
#
# LIBUSB_DEBUG: OPTIONAL.  For run-time troubleshooting of USB-capable NUT
#                drivers, you can specify the verbosity of LibUSB specific
#                debugging as a numeric value such as `4` ("All messages
#                are emitted").  Should not have any practical impact on
#                other NUT drivers. For more details, see the library's
#                documentation at e.g. https://libusb.sourceforge.io/api-1.0/
#
# user, group: OPTIONAL. Overrides the compiled-in (also global-section,
#                when used in driver section) default unprivileged user/group
#                name for NUT device driver. Impacts access rights used for
#                the socket file access (group) and communication ports (user
#                and its default group; you may want to add that user in the
#                operating system to `dialout` group to access serial ports).
#
# synchronous: OPTIONAL.  The driver work by default in asynchronous
#              mode (like *no*) with fallback to synchronous if sending
#              fails (i.e *synchronous=auto*).  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.  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.
#

# These directives are common to all drivers that support ups.conf:
#
#  driver: REQUIRED.  Specify the program to run to talk to this UPS.
#          apcsmart, bestups, and sec are some examples.
#
#    port: REQUIRED.  The serial port where your UPS is connected.
#          For example:
#            /dev/ttyS0 is usually the first port on Linux boxes.
#            "\\\\.\\COM1" is the first port on Windows boxes (note that
#                the backslash characters themselves must be escaped,
#                for the NUT configuration parser to yield "\\.\COM1").
#
# 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.
#
# sdcommands: OPTIONAL.  Comma-separated list of instant command name(s)
#          to send to the UPS when you request its shutdown.  For more
#          details about relevant use-cases see the ups.conf manual page.
#
#          The default value is built into each driver (where supported).
#
#    desc: optional, to keep a note of the UPS purpose, location, etc.
#
#  nolock: optional, and not recommended for use in this file.
#
#          If you put nolock in here, the driver will not lock the
#          serial port every time it starts.  This may allow other
#          processes to seize the port if you start more than one by
#          mistake.
#
#          This is only intended to be used on systems where locking
#          absolutely must be disabled for the software to work.
#
# ignorelb: OPTIONAL. Ignore low battery condition reported by device,
#           and evaluate remaining battery charge or runtime instead.
#           See man page for details.
#
# usb_set_altinterface(=num): OPTIONAL. Require that NUT calls this method
#           to set the interface, even if 0 (default). Some devices require
#           the call to initialize; others however can get stuck due to it -
#           so it is not called by default. Yet others can be composite
#           devices which use a non-zero interface to represent the UPS.
#
# usb_config_index=hexnum, usb_hid_rep_index=hexnum,
# usb_hid_desc_index=hexnum, usb_hid_ep_in=hexnum, usb_hid_ep_out=hexnum:
#           OPTIONAL. Force use of specific interface, endpoint, descriptor
#           index etc. numbers, rather than defaulting to 0 (rarely other
#           values in certain drivers for some devices known to use non-zero
#           numbers). As a rule of thumb for `usb_hid_desc_index` discovery,
#           you can see larger `wDescriptorLength` values (roughly 600+ bytes)
#           in reports of `lsusb` or similar tools.
#
# default.<variable>: OPTIONAL. Set a default value for <variable> which is
#           used in case the UPS doesn't provide a value, but which will be
#           overwritten if a value is available from the UPS, e.g.:
#               default.input.voltage.nominal = 230
#           will report the nominal input voltage to be 230, unless the UPS
#           eventually tells us differently.
#
# override.<variable>: OPTIONAL. Set a value for <value> that overrides
#           (for NUT) any value that may be read from the UPS.
#           Used for overriding values from the UPS that are clearly wrong
#           (e.g. some devices report wrong values for battery voltage):
#               override.battery.voltage.nominal = 12
#           Use with caution!  This will only change the appearance of the
#           variable to the outside world (and NUT calculations), internally
#           in the UPS the original value is used.
#
# Anything else is passed through to the hardware-specific part of
# the driver.
#
# Examples
# --------
#
# A simple example for a UPS called "powerpal" that uses the blazer_ser
# driver on /dev/ttyS0 is:
#
# [powerpal]
#   driver = blazer_ser
#   port = /dev/ttyS0
#   desc = "Web server"
#
# If your UPS driver requires additional settings, you can specify them
# here.  For example, if it supports a setting of "1234" for the
# variable "cable", it would look like this:
#
# [myups]
#   driver = mydriver
#   port = /dev/ttyS1
#   cable = 1234
#   desc = "Something descriptive"
#
# To find out if your driver supports any extra settings, start it with
# the -h option and/or read the driver's documentation.
