ntfswipe

title: ntfswipe(8)

text:
# ntfswipe(8)

## NAME
ntfswipe - overwrite unused space on an NTFS volume

## SYNOPSIS
ntfswipe [options] device

## DESCRIPTION
ntfswipe clears all or part of unused space on an NTFS volume by overwriting with zeroes or random bytes.

## OPTIONS
Below is a summary of all the options that ntfswipe accepts. Nearly all options have two equivalent names. The short name is preceded by - and the long name is preceded by --. Any single letter options, that don't take an argument, can be combined into a single command, e.g. -fv is equivalent to -f -v. Long named options can be abbreviated to any unique prefix of their name.

-a, --all

Wipe all unused space. This may take significant time. If the option --unused-fast (or -U) is also present, the faster wiping method is used.

-b, --bytes BYTE-LIST

Define the allowed replacement bytes which are drawn randomly to overwrite the unused space. BYTE-LIST is a comma-separated list of values in range 0-255 expressed in octal, decimal or hexadecimal base.

-c, --count NUM

Define the number of times the unused space is to be overwritten. If both options --bytes and --count are set, the space is repeatedly overwritten this number of times by each of the values in the list.

-d, --directory

Wipe all the directory indexes, which may contain names of deleted files.

-f, --force

This will override some sensible defaults, such as not using a mounted volume. Use this option with caution.

-h, --help

Show a list of options with a brief description of each one.

-i, --info

Display details about unused space, without wiping anything.

-l, --logfile

Overwrite the logfile (update journal).

-m, --mft

Overwrite the unused space in the MFT (main file table, which contains the file names, and the contents of short files).

-n, --no-action

Executes the wiping process without writing to device.

-p, --pagefile

Overwrite the Windows swap space.

-q, --quiet

Suppress some debug/warning/error messages.

-s, --undel

Overwrite the space which had been allocated to a file which has been deleted recently and is still undeletable. This option is not compatible with --bytes and the replacement bytes are random ones or taken from a standard list.

-t, --tails

Overwrite the space at the end of files which is unused, but allocated because the allocations are always done by full clusters.

-u, --unused

Overwrite the space which is currently not allocated to any file (but may have been used in the past).

-U, --unused-fast

Overwrite the space which is currently not allocated to any file, trying not to overwrite the space not written to since the previous wiping.

-v, --verbose

Display more debug/warning/error messages. This option may be used twice to display even more messages.

-V, --version

Show the version number, copyright and license of ntfswipe.

## EXAMPLES
Wipe out all unused space in an NTFS volume.

ntfswipe -a /dev/sda1

Wipe out all deleted file names from an NTFS volume. ntfswipe -dms /dev/sda1

## BUGS
There are no known problems with ntfswipe. If you find a bug please send an email describing the problem to the development team:

ntfs-3g-devel@lists.sf.net

## AUTHORS
ntfswipe was written by Richard Russon, Anton Altaparmakov and Yura Pakhuchiy. It was ported to ntfs-3g by Erik Larsson.

## AVAILABILITY
ntfswipe is part of the ntfs-3g package and is available from:

https://github.com/tuxera/ntfs-3g/wiki/

## SEE ALSO
ntfs-3g(8), ntfsls(8), ntfsprogs(8)


ntpsweep

package: ntp-utils

title: ntpsweep(8)

text:
# ntpsweep(8)

## NAME
ntpsweep - Sweep NTP Servers and Report Relationships

## SYNOPSIS
ntpsweep [ --help|--peers|--strip <string>] <file>|[--host <hostname> ]

## DESCRIPTION
ntpsweep prints per host given in <file> the NTP stratum level, the clock offset in seconds, the daemon version, the operating system and the processor.

## OPTIONS
--help

Print this short help text and exit.

<file>

Specify the hosts file. File format is one hostname or ip number per line. Lines beginning with # are considered as comment.

--host <hostname>

Speficy a single host, bypassing the need for a hosts file.

--peers

List all peers a host synchronizes to.

--strip <string>

Strip <string> from hostnames.

## AUTHOR
Hans Lambermont. Manpage by Bdale Garbee <bdale@gag.com> for the Debian GNU/Linux distribution.


ntpd

package: ntpd

title: ntpd(8)

summary: Network Time Protocol (NTP) daemon.

text:
# ntpd(8)

## NAME
ntpd - Network Time Protocol (NTP) daemon.

## SYNOPSIS
ntpd [ -aAbdm ] [ -c conffile ] [ -f driftfile ] [ -k keyfile ] [ -l logfile ] [ -p pidfile ] [ -r broadcastdelay ] [ -s statsdir ] [ -t key ] [ -v variable ] [ -V variable ] [ -U server_user [ -T chroot_dir ] ] [ -x ]

## DESCRIPTION
ntpd is an operating system daemon which sets and maintains the system time-of-day in synchronism with Internet standard time servers. Ntpd is a complete implementation of the Network Time Protocol (NTP) version 4 but also retains compatibility with version 3, as defined by RFC-1305 and version 1 and 2, as defined by RFC-1059 and RFC-1119, respectively. ntpd does most computations in 64-bit floating point arithmetic and does relatively clumsy 64-bit fixed point operations only when necessary to preserve the ultimate precision, about 232 picoseconds. While the ultimate precision, is not achievable with ordinary workstations and networks of today, it may be required with future nanosecond CPU clocks and gigabit LANs.

The daemon can operate in any of several modes, including symmetric active/passive, client/server broadcast/multicast and manycast. A broadcast/multicast or manycast client can discover remote servers, compute server-client propagation delay correction factors and configure itself automatically. This makes it possible to deploy a fleet of workstations without specifying configuration details specific to the local environment.

Ordinarily, ntpd reads the ntp.conf configuration file at startup time in order to determine the synchronization sources and operating modes. It is also possible to specify a working, although limited configuration entirely on the command line, obviating the need for a configuration file. This may be particularly appropriate when the local host is to be configured as a broadcast/multicast client or manycast client, with all peers being determined by listening to broadcasts at run time.

If NetInfo support is built into ntpd then ntpd will attempt to read its configuration from the NetInfo if the default ntp.conf file cannot be read and no file is specified by the -c option.

Various internal ntpd variables can be displayed and configuration options altered while the daemon is running using the ntpq and ntpd utility programs.

When ntpd starts it looks at the value of umask, and if it is zero ntpd will set the umask to 0222.

## OPTIONS
-a

Enable authentication mode (default). -A

Disable authentication mode.

-b

Synchronize using NTP broadcast messages.

-c conffile

Specify the name and path of the configuration file.

-d

Specify debugging mode. This flag may occur multiple times, with each occurrence indicating greater detail of display.

-D level

Specify debugging level directly.

-f driftfile

Specify the name and path of the drift file.

-g

Normally, the daemon exits if the offset exceeds a 1000s sanity limit This option overrides this limit and allows the time to be set to an value without restriction.

-k keyfile

Specify the name and path of the file containing the NTP authentication keys.

-l logfile

Specify the name and path of the log file. The default is the system log facility.

-m

Synchronize using NTP multicast messages on the IP multicast group address 224.0.1.1 (requires multicast kernel).

-p pidfile

Specify the name and path to record the daemon's process ID.

-P

Override the priority limit set by the operating system. Not recommended for sissies.

-r broadcastdelay

Specify the default propagation delay from the broadcast/multicast server and this computer. This is necessary only if the delay cannot be computed automatically by the protocol.

-s statsdir

Specify the directory path for files created by the statistics facility.

-t key

Add a key number to the trusted key list.

-v variable, -V variable

Add a system variable listed by default.

-T chroot_dir

Chroot the ntpd server process into chroot_dir. To use this option you have to copy all the files that ntpd process needs into the chroot directory. This option takes effect only if the server also drops root privileges (see -U option). Empty chroot_dir value disables chroot jailing. By default, ntpd chroots to /var/lib/ntpd.

-U server_user

Ntpd process drops root privileges and changes user ID to server_user and group ID to the primary group of server_user. Empty server_user value disables dropping privileges. By default, ntpd switches to pseudouser ntpd.

-x

Ordinarily, if the time is to be adjusted more than 128 ms, it is stepped, not gradually slewed. This option forces the time to be slewed in all cases. Note: Since the slew rate is limited to 0.5 ms/s, each second of adjustment requires an amortization interval of 2000 s. Thus an adjustment of many seconds can take hours or days to amortize.

## THE CONFIGURATION FILE
The ntpd configuration file is read at initial startup in order to specify the synchronization sources, modes and other related information. Usually, it is installed in the /etc directory, but could be installed elsewhere (see the -c conffile command line option). The file format is similar to other Unix configuration files - comments begin with a # character and extend to the end of the line; blank lines are ignored. Configuration commands consist of an initial keyword followed by a list of arguments, some of which may be optionally separated by whitespace. Commands may not be continued over multiple lines. Arguments may be host names, host addresses written in numeric dotted-quad form, integers, floating point numbers (when specifying times in seconds) and text strings. Optional arguments are delimited by [ ] in the following descriptions, while alternatives are separated by |. The notation [ ... ] means an optional, indefinite repetition of the last item before the [ ... ].

While there is a rich set of options available, the only required option is one or more of the server, peer, broadcast or manycastclient commands.

Following is a description of the NTPv4 configuration commands. These commands have the same basic functions as in NTPv3 and in some cases new functions and new operands. The various modes are determined by the command keyword and the type of the required IP address. Addresses are classed by type as (s) a remote server or peer (IP class A, B and C), (b) the broadcast address of a local interface, (m) a multicast address (IP class D), or (r) a reference clock address (127.127.x.x). Note that, while autokey and burst modes are supported by these commands, their effect in some weird mode combinations can be meaningless or even destructive.

peer address

[autokey | key key] [burst] [version version] [prefer] [minpoll minpoll] [maxpoll maxpoll]

For type s addresses (only), this operates as the current peer command which mobilizes a persistent symmetric-active mode association, except that additional modes are available. This command should NOT be used for type b, m or r addresses.

The peer command specifies that the local server is to operate in symmetric active mode with the remote server. In this mode, the local server can be synchronized to the remote server and, in addition, the remote server can be synchronized by the local server. This is useful in a network of servers where, depending on various failure scenarios either the local or remote server may be the better source of time.

server address

[autokey | key key] [burst] [version version] [prefer] [minpoll minpoll] [maxpoll maxpoll]

For type s and r addresses, this operates as the NTPv3 server command which mobilizes a persistent client mode association. The server command specifies that the local server is to operate in client mode with the specified remote server. In this mode, the local server can be synchronized to the remote server, but the remote server can never be synchronized to the local server.

broadcast address

[autokey | key key] [burst] [version version] [minpoll minpoll] [maxpoll maxpoll] [ttl ttl]

For type b and m addresses (only), this operates as the current NTPv3 broadcast command, which mobilizes a persistent broadcast mode association, except that additional modes are available. Multiple commands can be used to specify multiple local broadcast interface (subnets) and/or multiple multicast groups. Note that local broadcast messages go only to the interface associated with the subnet specified but multicast messages go to all interfaces. In the current implementation, the source address used for these messages is the Unix host default address.

In broadcast mode, the local server sends periodic broadcast messages to a client population at the address specified, which is usually the broadcast address on (one of) the local network(s) or a multicast address assigned to NTP. The IANA has assigned the multicast group address 224.0.1.1 exclusively to NTP, but other nonconflicting addresses can be used to contain the messages within administrative boundaries. Ordinarily, this specification applies only to the local server operating as a sender; for operation as a broadcast client, see the broadcastclient or multicastclient commands below.

manycastclient address

[autokey | key key] [burst] [version version] [minpoll minpoll] [maxpoll maxpoll] [ttl ttl]

For type m addresses (only), this mobilizes a manycast client-mod association for the multicast address specified. In this case specific address must be supplied which matches the address used on th manycastserver command for the designated manycast servers. The NT multicast address 224.0.1.1 assigned by the IANA should NOT be used unless specific means are taken to avoid spraying large areas of th Internet with these messages and causing a possibly massive implosion o replies at the sender

The manycast command specifies that the local server is to operate i client mode with the remote server that are discovered as the result o broadcast/multicast messages. The client broadcasts a request message to the group address associated with the specified address an specifically enabled servers respond to these messages. The client selects the servers providing the best time and continues as with the server command. The remaining servers are discarded as if never heard

These four commands specify the time server name or address to be use and the mode in which to operate. The address can be either a DNS name or a IP address in dotted-quad notation. Additional information on association behaviour can be found in the Association Management page

autokey

All packets sent to the address are to include authentication field encrypted using the autokey scheme.

burst

At each poll interval, send a burst of eight packets spaced, instead of the usual one.

key key

All packets sent to the address are to include authentication field encrypted using the specified key identifier, which is an unsigned 32-bit integer less than 65536. The default is to include no encryption field.

version version

Specifies the version number to be used for outgoing NTP packets. Versions 1-4 are the choices, with version 4 the default.

prefer

Marks the server as preferred. All other things being equal, this host will be chosen for synchronization among a set of correctly operating hosts. See the Mitigation Rules and the prefer Keyword page for further information

ttl ttl

This option is used only with broadcast mode. It specifies the time-to-live ttl to use on multicast packets. Selection of the proper value, which defaults to 127, is something of a black art and must be coordinated with the network administrator.

minpoll minpoll maxpoll maxpoll

These options specify the minimum and maximum polling intervals for NTP messages, in seconds to the power of two. The default range is 6 (64 s) to 10 (1,024 s).The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.

broadcastclient

This command directs the local server to listen for and respond to broadcast messages received on any local interface. Upon hearing a broadcast message for the first time, the local server measures the nominal network delay using a brief client/server exchange with the remote server, then enters the broadcastclient mode, in which it listens for and synchronizes to succeeding broadcast messages. Note that, in order to avoid accidental or malicious disruption in this mode, both the local and remote servers should operate using authentication and the same trusted key and key identifiers.

multicastclient

[address] [...] This command directs the local server to listen for multicast messages at the group address(es) of these global network. The default address is that assigned by the Number Czar to NTP (224.0.1.1). This command operates in the same way as the broadcastclient command, but uses IP multicasting. Support for this command requires a multicast kernel.

driftfile driftfile

This command specifies the name of the file use to record the frequency offset of the local clock oscillator. If the file exists, it is read at startup in order to set the initial frequency offset and then updated once per hour with the current frequency offset computed by the daemon. If the file does not exist or this command is not given, the initial frequency offset is assume zero. In this case, it may take some hours for the frequency to stabilize and the residual timing errors to subside.

The file format consists of a single line containing a single floating point number, which records the frequency offset measured in parts-per-million (PPM). The file is updated by first writing the current drift value into a temporary file and then renaming this file to replace the old version. This implies that ntpd must have write permission for the directory the drift file is located in, and that file system links, symbolic or otherwise, should be avoided.

manycastserver address [...]

This command directs the local server to listen for and respond to broadcast messages received on any local interface, and in addition enables the server to respond to client mode messages to the multicast group address(es) (type m) specified. At least one address is required, but the NTP multicast address 224.0.1.1 assigned by the IANA should NOT be used, unless specific means are taken to limit the span of the reply and avoid a possible massive implosion at the original sender.

revoke [logsec]

Specifies the interval between recomputations of the private value used with the autokey feature, which ordinarily requires an expensive public- key computation. The default value is 12 (65,536 s or about 18 hours). For poll intervals above the specified interval, a new private value will be recomputed for every message sent.

autokey [logsec]

Specifies the interval between regenerations of the session key list used with the autokey feature. Note that the size of the key list for each association depends on this interval and the current poll interval. The default value is 12 (4096 s or about 1.1 hours). For poll intervals above the specified interval, a session key list with a single entry will be regenerated for every message sent.

enable [auth | bclient | kernel | monitor | ntp | stats]

disable [auth | bclient | kernel | monitor | ntp | stats]

Provides a way to enable or disable various server options. Flags not mentioned are unaffected. Note that all of these flags can be controlled remotely using the ntpdc utility program.

auth

Enables the server to synchronize with unconfigured peers only if the peer has been correctly authenticated using a trusted key and key identifier. The default for this flag is enable.

bclient

When enabled, this is identical to the broadcastclient command. The default for this flag is disable.

kernel

Enables the precision-time kernel support for the ntp_adjtime() system call, if implemented. Ordinarily, support for this routine is detected automatically when the NTP daemon is compiled, so it is not necessary for the user to worry about this flag. It flag is provided primarily so that this support can be disabled during kernel development.

monitor

Enables the monitoring facility. See the ntpdc program and the monlist command or further information. The default for this flag is enable.

ntp

Enables the server to adjust its local clock by means of NTP. If disabled, the local clock free-runs at its intrinsic time and frequency offset. This flag is useful in case the local clock is controlled by some other device or protocol and NTP is used only to provide synchronization to other clients In this case, the local clock driver can be used to provide this function and also certain time variables for error estimates and leap-indicators. The default for this flag is enable.

stats

Enables the statistics facility. The default for this flag is enable.

## FILES
/etc/ntp.conf

- the default name of the configuration file

/etc/ntp.drift

- the default name of the drift file

/etc/ntp.key

- the default name of the key file

## BUGS
Ntpd has gotten rather fat. While not huge, it has gotten larger than might be desirable for an elevated-priority daemon running on a workstation, particularly since many of the fancy features which consume the space were designed more with a busy primary server, rather than a high stratum workstation, in mind.

## AUTHOR
David L. Mills <mills@udel.edu>. Manpage abstracted from the html documentation by Peter Breuer <ptb@it.uc3m.es>.


ntpdate

package: ntpdate

title: ntpdate(8)

summary: set the date and time via NTP

text:
# ntpdate(8)

## NAME
ntpdate - set the date and time via NTP

## SYNOPSIS
ntpdate [-bBdoqsuv] [-a key] [-e authdelay] [-k keyfile] [-o version] [-p samples] [-U username [-T chroot_dir]] [-t timeout] server [...]

## DESCRIPTION
ntpdate sets the local date and time by polling the Network Time Protocol (NTP) server(s) given as the server arguments to determine the correct time. It must be run as root on the local host. A number of samples are obtained from each of the servers specified and a subset of the NTP clock filter and selection algorithms are applied to select the best of these. Note that the accuracy and reliability of ntpdate depends on the number of servers, the number of polls each time it is run and the interval between runs.

ntpdate can be run manually as necessary to set the host clock, or it can be run from the host startup script to set the clock at boot time. This is useful in some cases to set the clock initially before starting the NTP daemon ntpd. It is also possible to run ntpdate from a cron script. However, it is important to note that ntpdate with contrived cron scripts is no substitute for the NTP daemon, which uses sophisticated algorithms to maximize accuracy and reliability while minimizing resource use. Finally, since ntpdate does not discipline the host clock frequency as does ntpd, the accuracy using ntpdate is limited.

Time adjustments are made by ntpdate in one of two ways. If ntpdate determines the clock is in error more than 0.5 second it will simply step the time by calling the system settimeofday() routine. If the error is less than 0.5 seconds, it will slew the time by calling the system adjtime() routine. The latter technique is less disruptive and more accurate when the error is small, and works quite well when ntpdate is run by cron every hour or two.

ntpdate will decline to set the date if an NTP server daemon (e.g., ntpd) is running on the same host. When running ntpdate on a regular basis from cron as an alternative to running a daemon, doing so once every hour or two will result in precise enough timekeeping to avoid stepping the clock.

## OPTIONS
-a key

Enable the authentication function and specify the key identifier to be used for authentication as the argument keyntpdate. The keys and key identifiers must match in both the client and server key files. The default is to disable the authentication function.

-B

Force the time to always be slewed using the adjtime() system call, even if the measured offset is greater than +-128 ms. The default is to step the time using settimeofday() if the offset is greater than +-128 ms. Note that, if the offset is much greater than +-128 ms in this case, that it can take a long time (hours) to slew the clock to the correct value. During this time. the host should not be used to synchronize clients.

-b

Force the time to be stepped using the settimeofday() system call, rather than slewed (default) using the adjtime() system call. This option should be used when called from a startup file at boot time.

-d

Enable the debugging mode, in which ntpdate will go through all the steps, but not adjust the local clock. Information useful for general debugging will also be printed.

-e authdelay

Specify the processing delay to perform an authentication function as the value authdelay, in seconds and fraction (see ntpd for details). This number is usually small enough to be negligible for most purposes, though specifying a value may improve timekeeping on very slow CPU's.

-k keyfile

Specify the path for the authentication key file as the string keyfile. The default is /etc/ntp.keys. This file should be in the format described in ntpd.

-o version

Specify the NTP version for outgoint packets as the integer version, which can be 1 or 2. The default is 3. This allows ntpdate to be used with older NTP versions.

-p samples

Specify the number of samples to be acquired from each server as the integer samples, with values from 1 to 8 inclusive. The default is 4.

-q

Query only - don't set the clock.

-s

Divert logging output from the standard output (default) to the system syslog facility. This is designed primarily for convenience of cron scripts.

-t timeout

Specify the maximum time waiting for a server response as the value timeout, in seconds and fraction. The value is is rounded to a multiple of 0.2 seconds. The default is 1 second, a value suitable for polling across a LAN.

-u

Direct ntpdate to use an unprivileged port or outgoing packets. This is most useful when behind a firewall that blocks incoming traffic to privileged ports, and you want to synchronise with hosts beyond the firewall. Note that the -d option always uses unprivileged ports.

-v

Be verbose. This option will cause ntpdate's version identification string to be logged.

-T chroot_dir

Chroot the ntpdate process into chroot_dir. To use this option you have to copy all the files that ntpdate process needs into the chroot directory. This option takes effect only if the process also drops root privileges (see -U option). Empty chroot_dir value disables chroot jailing. By default, ntpdate chroots to /var/empty.

-U username

ntpdate process drops root privileges and changes user ID to user_name and group ID to the primary group of server_user. Empty user_name value disables dropping privileges. By default, ntpdate switches to pseudouser ntpd.

## FILES
/etc/ntp.keys

- encryption keys used by ntpdate.

## BUGS
The slew adjustment is actually 50% larger than the measured offset, since this (it is argued) will tend to keep a badly drifting clock more accurate. This is probably not a good idea and may cause a troubling hunt for some values of the kernel variables tick and tickadj.

## AUTHOR
David L. Mills (mills@udel.edu)

This manpage converted from html to roff by Fabrizio Polacco <fpolacco@debian.org>


memhog

package: numactl

title: memhog(8)

text:
# memhog(8)

## NAME
memhog - Allocates memory with policy for testing

## SYNOPSIS
memhog [ -r<NUM> ] [ size kmg ] [ policy nodeset ] [ -f<filename> ]

## DESCRIPTION
memhog mmaps a memory region for a given size and sets the numa policy (if specified). It then updates the memory region for the given number of iterations using memset.

-r<num>

Repeat memset NUM times

-f<file>

Open file for mmap backing

-H

Disable transparent hugepages

-size

Allocation size in bytes, may have case-insensitive order

suffix (G=gigabyte, M=megabyte, K=kilobyte)

Supported numa-policies:

interleave

Memory will be allocated using round robin on nodes. When memory cannot be allocated on the current interleave, target fall back to other nodes. Multiple nodes may be specified.

membind

Only allocate memory from nodes. Allocation will fail when there is not enough memory available on these nodes. Multiple nodes may be specified.

preferred

Preferably allocate memory on node, but if memory cannot be allocated there fall back to other nodes. This option takes only a single node number.

default

Memory will be allocated on the local node (the node the thread is running on)

## EXAMPLES
\# Allocate a 1G region, mmap backed by memhog.mmap file, membind to node 0, repeat test 6 times

memhog -r6 1G --membind 0 -fmemhog.mmap

\# Allocate a 1G region, interleave across nodes 0,1,2,3, repeat test 4 times

memhog -r4 1G --interleave 0-3

\# Allocate a 1G region, (implicit) default policy, repeat test 8 times

memhog -r8 1G

## AUTHORS
Andi Kleen (ak@suse.de)

## LICENSE
GPL v2

## SEE ALSO
mmap(2), memset(3), numactl(8), numastat(8)


migratepages

title: migratepages(8)

text:
# migratepages(8)

## NAME
migratepages - Migrate the physical location a processes pages

## SYNOPSIS
migratepages pid from-nodes to-nodes

## DESCRIPTION
migratepages moves the physical location of a processes pages without any changes of the virtual address space of the process. Moving the pages allows one to change the distances of a process to its memory. Performance may be optimized by moving a processes pages to the node where it is executing.

If multiple nodes are specified for from-nodes or to-nodes then an attempt is made to preserve the relative location of each page in each nodeset.

For example if we move from nodes 2-5 to 7,9,12-13 then the preferred mode of operation is to move pages from 2->7, 3->9, 4->12 and 5->13. However, this is only posssible if enough memory is available.

Valid node specifiers

all

All nodes

number

Node number

number1{,number2}

Node number1 and Node number2

number1-number2

Nodes from number1 to number2

! nodes

Invert selection of the following specification.

## NOTES
Requires a NUMA policy aware kernel with support for page migration (linux 2.6.16 and later).

migratepages will only move pages that are not shared with other processes if called by a user without administrative priviledges (but with the right to modify the process).

migratepages will move all pages if invoked from root (or a user with administrative priviledges).

## FILES
/proc/<pid>/numa_maps for information about the NUMA memory use of a process.

## COPYRIGHT
Copyright 2005-2006 Christoph Lameter, Silicon Graphics, Inc. migratepages is under the GNU General Public License, v.2

## SEE ALSO
numactl(8) , set_mempolicy(2) , get_mempolicy(2) , mbind(2) , sched_setaffinity(2) , sched_getaffinity(2) , proc(5) , ftok(3) , shmat(2) , taskset(1)


migspeed

title: migspeed(8)

summary: Test the speed of page migration

text:
# migspeed(8)

## NAME
migspeed - Test the speed of page migration

## SYNOPSIS
migspeed -p pages from-nodes to-nodes

## DESCRIPTION
migspeed attempts to move a sample of pages from the indicated node to the target node and measures the time it takes to perform the move.

-p pages

The default sample is 1000 pages. Override that with another number.

## NOTES
Requires a NUMA policy aware kernel with support for page migration (Linux 2.6.16 and later).

## COPYRIGHT
Copyright 2007 Christoph Lameter, Silicon Graphics, Inc. migratepages is under the GNU General Public License, v.2

## SEE ALSO
numactl(8)


numactl

title: numactl(8)

text:
# numactl(8)

## NAME
numactl - Control NUMA policy for processes or shared memory

## SYNOPSIS
numactl [ --all ] [ --balancing ] [ --interleave nodes ] [ --weighted-interleave nodes ] [ --preferred node ] [ --preferred-many nodes ] [ --membind nodes ] [ --cpunodebind nodes ] [ --physcpubind cpus ] [ --localalloc ] [--] command {arguments ...}

numactl --show

numactl --hardware [--cpu-compress]

numactl --version

numactl [ --huge ] [ --offset offset ] [ --shmmode shmmode ] [ --length length ] [ --strict ]

[ --shmid id ] --shm shmkeyfile | --file tmpfsfile

[ --touch ] [ --dump ] [ --dump-nodes ] memory policy

## DESCRIPTION
numactl runs processes with a specific NUMA scheduling or memory placement policy. The policy is set for command and inherited by all of its children. In addition it can set persistent policy for shared memory segments or files.

Use -- before command if using command options that could be confused with numactl options.

nodes may be specified as N,N,N or N-N or N,N-N or N-N,N-N and so forth. Relative nodes may be specified as +N,N,N or +N-N or +N,N-N and so forth. The + indicates that the node numbers are relative to the process' set of allowed nodes in its current cpuset. A !N-N notation indicates the inverse of N-N, in other words all nodes except N-N. If used with + notation, specify !+N-N. When same is specified the previous nodemask specified on the command line is used. all means all nodes in the current cpuset.

Instead of a number a node can also be:

netdev:DEV

The node connected to network device DEV.

file:PATH

The node the block device of PATH.

ip:HOST

The node of the network device of HOST

block:PATH

The node of block device PATH

pci:[seg:]bus:dev[:func]

The node of a PCI device.

Note that block resolves the kernel block device names only for udev names in /dev use file:

Policy settings are:

--all, -a

Unset default cpuset awareness, so user can use all possible CPUs/nodes for following policy settings.

--interleave=nodes, -i nodes

Set a memory interleave policy. Memory will be allocated using round robin on nodes. When memory cannot be allocated on the current interleave target fall back to other nodes. Multiple nodes may be specified on --interleave, --membind and --cpunodebind.

--weighted-interleave=nodes, -w nodes

Set a weighted memory interleave policy. Memory will be allocated using the weighted ratio for each node, which can be read from /sys/kernel/mm/mempolicy/weighted_interleave/node*. When memory cannot be allocated on the current interleave target fall back to other nodes.

--membind=nodes, -m nodes

Only allocate memory from nodes. Allocation will fail when there is not enough memory available on these nodes. nodes may be specified as noted above.

--cpunodebind=nodes, -N nodes

Only execute command on the CPUs of nodes. Note that nodes may consist of multiple CPUs. nodes may be specified as noted above.

--physcpubind=cpus, -C cpus

Only execute process on cpus. This accepts cpu numbers as shown in the processor fields of /proc/cpuinfo, or relative cpus as in relative to the current cpuset. You may specify "all", which means all cpus in the current cpuset. Physical cpus may be specified as N,N,N or N-N or N,N-N or N-N,N-N and so forth. Relative cpus may be specified as +N,N,N or +N-N or +N,N-N and so forth. The + indicates that the cpu numbers are relative to the process' set of allowed cpus in its current cpuset. A !N-N notation indicates the inverse of N-N, in other words all cpus except N-N. If used with + notation, specify !+N-N.

--localalloc, -l

Try to allocate on the current node of the process, but if memory cannot be allocated there fall back to other nodes.

--preferred=node, -p node

Preferably allocate memory on node, but if memory cannot be allocated there fall back to other nodes. This option takes only a single node number. Relative notation may be used.

--balancing, -b

Enable Linux kernel NUMA balancing for the process if it is supported by kernel. This should only be used with --membind, -m only, otherwise ignored.

--preferred-many=nodes, -P nodes

Preferably allocate memory on nodes, but if memory cannot be allocated there fall back to other nodes. This option takes a mask of preferred nodes where the closest node to local is considered most preferred. Relative notation may be used.

--show, -s

Show NUMA policy settings of the current process.

--hardware, -H

Show inventory of available nodes on the system. When the --cpu-compress option is set show cpu ranges. This is not default not break any existing scripts.

Numactl can set up policy for a SYSV shared memory segment or a file in shmfs/hugetlbfs.

--version

print the version of the numactl package and exit.

The following policy settings are persistent and will be used by

all mappings from that shared memory. The order of options matters here. The specification must at least include either of --shm, --shmid, --file to specify the shared memory segment or file and a memory policy like described above ( --interleave, --localalloc, --preferred, --preferred-many, --membind ).

--huge

When creating a SYSV shared memory segment use huge pages. Only valid before --shmid or --shm

--offset

Specify offset into the shared memory segment. Default 0. Valid units are m (for MB), g (for GB), k (for KB), otherwise it specifies bytes.

--strict

Give an error when a page in the policied area in the shared memory segment already was faulted in with a conflicting policy. Default is to silently ignore this.

--shmmode shmmode

Only valid before --shmid or --shm When creating a shared memory segment set it to numeric mode shmmode.

--length length

Apply policy to length range in the shared memory segment or make the segment length long Default is to use the remaining length Required when a shared memory segment is created and specifies the length of the new segment then. Valid units are m (for MB), g (for GB), k (for KB), otherwise it specifies bytes.

--shmid id

Create or use a shared memory segment with numeric ID id

--shm shmkeyfile

Create or use a shared memory segment, with the ID generated using ftok(3) from shmkeyfile

--file tmpfsfile

Set policy for a file in tmpfs or hugetlbfs

--touch

Touch pages to enforce policy early. Default is to not touch them, the policy is applied when an applications maps and accesses a page.

--dump

Dump policy in the specified range.

--dump-nodes

Dump all nodes of the specific range (very verbose!)

Valid node specifiers

all

All nodes

number

Node number

number1{,number2}

Node number1 and Node number2

number1-number2

Nodes from number1 to number2

! nodes

Invert selection of the following specification.

## EXAMPLES
numactl --physcpubind=+0-4,8-12 myapplic arguments Run myapplic on cpus 0-4 and 8-12 of the current cpuset.

numactl --interleave=all bigdatabase arguments Run big database with its memory interleaved on all CPUs.

numactl --weighted-interleave=all bigdatabase arguments Run big database with its memory interleaved with weighted ratio on all CPUs.

numactl --cpunodebind=0 --membind=0,1 process Run process on node 0 with memory allocated on node 0 and 1.

numactl --cpunodebind=0 --membind=0,1 -- process -l Run process as above, but with an option (-l) that would be confused with a numactl option.

numactl --cpunodebind=0 --balancing --membind=0,1 process Run process on node 0 with memory allocated on node 0 and 1. Optimize the page placement with Linux kernel NUMA balancing mechanism if possible.

numactl --cpunodebind=netdev:eth0 --membind=netdev:eth0 network-server Run network-server on the node of network device eth0 with its memory also in the same node.

numactl --preferred=1 numactl --show Set preferred node 1 and show the resulting state.

numactl --preferred-many=0x3 numactl --show Set preferred nodes 1 and 2, and show the resulting state.

numactl --length 1g --shm /tmp/shmkey --interleave=all Interleave all of the sysv shared memory region of size 1g specified by /tmp/shmkey over all nodes.

Place a tmpfs file on 2 nodes:

numactl --membind=2 dd if=/dev/zero of=/dev/shm/A bs=1M count=1024

numactl --membind=3 dd if=/dev/zero of=/dev/shm/A seek=1024 bs=1M count=1024

numactl --localalloc /dev/shm/file Reset the policy for the shared memory file file to the default localalloc policy.

## NOTES
Requires a NUMA policy aware kernel.

Command is not executed using a shell. If you want to use shell metacharacters in the child use sh -c as wrapper.

Setting policy for a hugetlbfs file does currently not work because it cannot be extended by truncate.

Shared memory segments larger than numactl's address space cannot be completely policied. This could be a problem on 32bit architectures. Changing it piece by piece may work.

The old --cpubind which accepts node numbers, not cpu numbers, is deprecated and replaced with the new --cpunodebind and --physcpubind options.

## FILES
/proc/cpuinfo for the listing of active CPUs. See proc(5) for details.

/sys/devices/system/node/node*/numastat for NUMA memory hit statistics.

## COPYRIGHT
Copyright 2002,2004 Andi Kleen, SuSE Labs. numactl and the demo programs are under the GNU General Public License, v.2

## SEE ALSO
set_mempolicy(2) , get_mempolicy(2) , mbind(2) , sched_setaffinity(2) , sched_getaffinity(2) , proc(5) , ftok(3) , shmat(2) , migratepages(8)


numastat

title: numastat(8)

text:
# numastat(8)

## NAME
numastat - Show per-NUMA-node memory statistics for processes and the operating system

## SYNTAX
numastat

numastat [-V]

numastat [<PID>|<pattern>...]

numastat [-c] [-m] [-n] [-p <PID>|<pattern>] [-s[<node>]] [-v] [-z] [<PID>|<pattern>...]

## DESCRIPTION
numastat with no command options or arguments at all, displays per-node NUMA hit and miss system statistics from the kernel memory allocator. This default numastat behavior is strictly compatible with the previous long-standing numastat perl script, written by Andi Kleen. The default numastat statistics shows per-node numbers (in units of pages of memory) in these categories:

numa_hit is memory successfully allocated on this node as intended.

numa_miss is memory allocated on this node despite the process preferring some different node. Each numa_miss has a numa_foreign on another node.

numa_foreign is memory intended for this node, but actually allocated on some different node. Each numa_foreign has a numa_miss on another node.

interleave_hit is interleaved memory successfully allocated on this node as intended.

local_node is memory allocated on this node while a process was running on it.

other_node is memory allocated on this node while a process was running on some other node.

Any supplied options or arguments with the numastat command will significantly change both the content and the format of the display. Specified options will cause display units to change to megabytes of memory, and will change other specific behaviors of numastat as described below.

Memory usage information reflects the resident pages on the system.

## OPTIONS
-c

Minimize table display width by dynamically shrinking column widths based on data contents. With this option, amounts of memory will be rounded to the nearest megabyte (rather than the usual display with two decimal places). Column width and inter-column spacing will be somewhat unpredictable with this option, but the more dense display will be very useful on systems with many NUMA nodes.

-m

Show the meminfo-like system-wide memory usage information. This option produces a per-node breakdown of memory usage information similar to that found in /proc/meminfo.

-n

Show the original numastat statistics info. This will show the same information as the default numastat behavior but the units will be megabytes of memory, and there will be other formatting and layout changes versus the original numastat behavior.

-p <PID> or <pattern>

Show per-node memory allocation information for the specified PID or pattern. If the -p argument is only digits, it is assumed to be a numerical PID. If the argument characters are not only digits, it is assumed to be a text fragment pattern to search for in process command lines. For example, numastat -p qemu will attempt to find and show information for processes with "qemu" in the command line. Any command line arguments remaining after numastat option flag processing is completed, are assumed to be additional <PID> or <pattern> process specifiers. In this sense, the -p option flag is optional: numastat qemu is equivalent to numastat -p qemu

-s[<node>]

Sort the table data in descending order before displaying it, so the biggest memory consumers are listed first. With no specified <node>, the table will be sorted by the total column. If the optional <node> argument is supplied, the data will be sorted by the <node> column. Note that <node> must follow the -s immediately with no intermediate white space (e.g., numastat -s2). Because -s can allow an optional argument, it must always be the last option character in a compound option character string. For example, instead of numastat -msc (which probably will not work as you expect), use numastat -mcs

-v

Make some reports more verbose. In particular, process information for multiple processes will display detailed information for each process. Normally when per-node information for multiple processes is displayed, only the total lines are shown.

-V

Display numastat version information and exit.

-z

Skip display of table rows and columns of only zero valuess. This can be used to greatly reduce the amount of uninteresting zero data on systems with many NUMA nodes. Note that when rows or columns of zeros are still displayed with this option, that probably means there is at least one value in the row or column that is actually non-zero, but rounded to zero for display.

## NOTES
numastat attempts to fold each table display so it will be conveniently readable on the output terminal. Normally a terminal width of 80 characters is assumed. When the resize command is available, numastat attempts to dynamically determine and fine tune the output tty width from resize output. If numastat output is not to a tty, very long output lines can be produced, depending on how many NUMA nodes are present. In all cases, output width can be explicitly specified via the NUMASTAT_WIDTH environment variable. For example, NUMASTAT_WIDTH=100 numastat. On systems with many NUMA nodes, numastat -c -z .... can be very helpful to selectively reduce the amount of displayed information.

## ENVIRONMENT VARIABLES
NUMASTAT_WIDTH

## FILES
/proc/*/numa_maps

/sys/devices/system/node/node*/meminfo

/sys/devices/system/node/node*/numastat

## EXAMPLES
numastat -c -z -m -n

numastat -czs libvirt kvm qemu

watch -n1 numastat

watch -n1 --differences=cumulative numastat

## AUTHORS
The original numastat perl script was written circa 2003 by Andi Kleen <andi.kleen@intel.com>. The current numastat program was written in 2012 by Bill Gray <bgray@redhat.com> to be compatible by default with the original, and to add options to display per-node system memory usage and per-node process memory allocation.

## SEE ALSO
numactl(8), set_mempolicy(2), numa(3)


upsc

package: nut

title: upsc(8)

summary: Lightweight read\-only NUT client

text:
# upsc(8)

## NAME
upsc - Lightweight read-only NUT client

## SYNOPSIS
upsc [-j] -l | -L [host]

upsc [-j] ups [variable]

upsc [-j] -c ups

## DESCRIPTION
upsc is provided as a quick way to poll the status of a UPS server. It can be used inside shell scripts and other programs that need UPS data but don’t want to include the full interface.

## OPTIONS
-j

Output the results in JSON format. This will bypass the standard text output and print a JSON object to stdout. The structure of the JSON depends on the mode:

```
`upsc -j -l`: Returns a JSON array of UPS names.
`upsc -j -L`: Returns a JSON object mapping UPS names to their descriptions.
`upsc -j <ups>`: Returns a JSON object of all variables and their values.
`upsc -j <ups> <variable>`: Returns a single JSON string (the value).
`upsc -j -c <ups>`: Returns a JSON array of client addresses.
```

-l host

List all UPS names configured at host, one name per line. The hostname defaults to "localhost". You may optionally add a colon and a port number.

-L host

As above, list all UPS names configured at host, including their description provided by the remote upsd(8) from its ups.conf(5). The hostname defaults to "localhost". You may optionally add a colon and a port number to override the default port.

-c ups

Lists each client connected on ups, one name per line.

ups

Display the status of that UPS. The format for this option is upsname[@hostname[:port]]. The default hostname is "localhost".

variable

Display the value of this variable only. By default, upsc retrieves the list of variables from the server and then displays the value for each. This option may be useful in shell scripts to save an additional pipe into grep.

## COMMON OPTIONS
-h

Show the command-line help message.

-D

Raise the debugging level. Use this option multiple times for more details. Overrides the optional NUT_DEBUG_LEVEL environment variable.

-V

Show NUT version banner. More details may be available if you also export NUT_DEBUG_LEVEL=1 or greater verbosity level.

-W secs

Set the timeout for initial network connections (by default they are indefinitely non-blocking, or until the system interrupts the attempt). Overrides the optional NUT_DEFAULT_CONNECT_TIMEOUT environment variable.

## EXAMPLES
To list all variables on an UPS named "myups" on a host called "mybox", with upsd(8) running on port 1234:

```
:; upsc myups@mybox:1234
battery.charge: 100.0
battery.voltage: 13.9
battery.voltage.nominal: 13.6
. . .
```

To retrieve all variables for "myups" as a JSON object:

```
:; upsc -j myups@mybox:1234
{

  "battery.charge": "100.0",

  "battery.voltage": "13.9",

  "battery.voltage.nominal": "13.6",

  ...
}
```

To list the UPSes configured on this system, along with their descriptions:

```
:; upsc -L
apc: Back-UPS 500
ppro2: Patriot Pro II
```

To retrieve the status for all UPSes connected to mybox, using Bourne-shell syntax:

```
:; for UPS in `upsc -l mybox:1234`; do

    upsc $UPS ups.status
done
```

To list clients connected on "myups":

```
:; upsc -c myups
127.0.0.1
::1
192.168.1.2
```

## SCRIPTED MODE
If you run this program inside a shell script or similar to get the list of devices and variables, you should only consider using output from stdout, not stderr.

## DIAGNOSTICS
upsc will either print a list of UPS names, a list of all supported variables and their values on the UPS, or an error message. If you do receive an error, make sure you have specified a valid UPS on the command line, that upsd(8) is really running on the other host, and that no firewalls are blocking you.

## HISTORY
Earlier versions of this program used the upsfetch library and UDP sockets to talk to upsd. This version of upsc uses the new upsclient library, which only talks TCP. This is why upsct no longer exists.

## SEE ALSO
upslog(8), ups.conf(5), upsd(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


upscmd

title: upscmd(8)

text:
# upscmd(8)

## NAME
upscmd - Network UPS Tools device/driver instant commands administration tool

## SYNOPSIS
upscmd -h

upscmd -l ups

upscmd [-u username] [-p password] [-w] [-t <timeout>] ups command

## DESCRIPTION
upscmd allows you to invoke "instant commands" in your UPS hardware. It sends commands via the server upsd(8) to your driver, which manages the hardware for you. You must use credentials defined in upsd.users(5) file on that data server with appropriate permissions.

Not all hardware supports this, so check the list with -l to see if anything will work on your equipment.

On hardware that supports it, you can use this program to start and stop battery tests, invoke a front panel test (beep!), turn the load on or off, and more.

## OPTIONS
-l ups

Show the list of supported instant commands on that UPS. Some hardware may not support any of them.

-u username

Set the username for the connection to the server. This is optional, and you will be prompted for this when invoking a command if -u is not used.

-p password

Set the password to authenticate to the server. This is also optional like -u, and you will be prompted for it if necessary.

-w

Wait for the completion of command execution by the driver and return its actual result from the device. Note that this feature requires that both upsd(8) and the driver support TRACKING (NUT version 2.8.0 or higher), or it will otherwise fail. The command will also block until an actual result is provided from the driver, or the timeout is reached (see -t).

-t seconds

Set a timeout when using -w. Defaults to 10 seconds.

ups

Connect to this UPS. The format is upsname[@hostname[:port]]. The default hostname is "localhost".

## COMMON OPTIONS
-h

Show the command-line help message.

-D

Raise the debugging level. Use this option multiple times for more details. Overrides the optional NUT_DEBUG_LEVEL environment variable.

-V

Show NUT version banner. More details may be available if you also export NUT_DEBUG_LEVEL=1 or greater verbosity level.

-W secs

Set the timeout for initial network connections (by default they are indefinitely non-blocking, or until the system interrupts the attempt). Overrides the optional NUT_DEFAULT_CONNECT_TIMEOUT environment variable.

## UNATTENDED MODE
If you run this program inside a shell script or similar to invoke a command, you will need to specify all of the information on the command line. This means using -u and -p. Otherwise it will put up a prompt and your program will hang.

This is not necessary when displaying the list, as the username and password are not required for read-only mode.

Moreover, if you run this program inside a shell script or similar, you should only consider using output from stdout, not stderr.

## DANGEROUS COMMANDS
Some drivers like apcsmart(8) have built-in paranoia for the dangerous commands like load.off. To make them actually turn off the load, you will have to send the command twice within a short window. That is, you will have to send it once, then send it again after 3 seconds elapse but before 15 seconds pass.

This paranoia is entirely defined within the driver. upsd and upscmd have no control over the timing.

## DIAGNOSTICS
upscmd won’t work unless you provide a valid username and password. If you get "access denied" errors, make sure that your upsd.users(5) has an entry for you, and that the username you are using has permissions to SET variables.

upscmd without -w would somewhat confusingly show "OK" meaning just that the data server connection was established, and the server did not immediately reject the request due to e.g. unknown instant command name. If you care to know the actual results, do use the -w (-t NUM) option(s) to wait for them.

## BUGS
There is currently no way to tell the user when the driver requires confirmation to invoke a command such as load.off.

This is on the list of things to fix in the future, so don’t despair. It involves magic cookies.

## SEE ALSO
upsd(8), upsrw(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


upslog

title: upslog(8)

summary: UPS status logger

text:
# upslog(8)

## NAME
upslog - UPS status logger

## SYNOPSIS
upslog -h

upslog [OPTIONS]

## DESCRIPTION
upslog is a daemon that will poll a UPS at periodic intervals, fetch the variables that interest you, format them, and write them to a file.

The default format string includes variables that are supported by many common UPS models. See the description below to make your own.

## OPTIONS
-f format

Monitor the UPS using this format string. Be sure to enclose format in quotes so your shell doesn’t split it up. Valid escapes within this string are: %%

Insert a single "%"

%t

Insert a single TAB character (like printf("\t"))

%TIME format%

Insert the time with strftime formatting

%ETIME%

Insert the number of seconds since the start of "Epoch", ala time_t. This is now a 10-digit number.

%HOST%

Insert the local hostname

%UPSHOST%

Insert the host of the UPS being monitored (the <system> part of your logging specification, e.g. ups[@host[:port]])

%PID%

Insert the PID of upslog itself

%VAR varname%

Insert the value of variable varname (see NUT developer documentation chapter "Variables" on-line or in the docs/nut-names.txt file in sources of the NUT version you have installed for more details)

The default format string is:

```
%TIME @Y@m@d @H@M@S% %VAR battery.charge% %VAR input.voltage%
%VAR ups.load% [%VAR ups.status%] %VAR ups.temperature%
%VAR input.frequency%
```

-N

Prefix %UPSHOST%%t before the format string (whether default or custom). Useful when logging many systems into same target.

Note

This option DOES NOT currently check if you already have %UPSHOST% in the formatting string (e.g. specified explicitly).

-i interval

Wait this many seconds between polls. This defaults to 30 seconds. If you require tighter timing, consider writing your own logger using the upsclient(3) library.

-d count

Exit after specified amount of updates. Default is 0 for infinite loop (until interrupted otherwise).

-l logfile

Store the results in this file. You can use - for stdout, but upslog will remain in the foreground by default.

Requires that the -s <system> option is also used for the single-system logging.

Can be used with the -m <tuple>, will be added to the list.

-D

Raise debugging verbosity level by one; upslog will remain in the foreground by default.

-F

upslog will run in the foreground, regardless of logging target.

-B

upslog will run in the background, regardless of logging target or debugging.

-s ups

Monitor this UPS. The format for this option is upsname[@hostname[:port]]. The default hostname is "localhost". The upsname may be an asterisk * to query UPSes currently served by hostname, and monitor each of them (into the same logging destination).

Requires that the -l <logfile> option is also used for the single-system logging.

Can be used with the -m <tuple>, will be added to the list.

-m tuple

Monitor multiple UPSs (provided several instances of such option). The format for this option is a tuple of UPS system and log file specification, separated by commas. An example would be:

```
upsname@hostname:9999,/var/log/nut/cps.log
```

The upsname may be an asterisk * to query UPSes currently served by hostname, and monitor each of them (into the same logging destination).

Tuples may specify - as the logfile, to emit messages on stdout (e.g. to be collected by the system journal for services).

Use of stdout via tuple-based logging specifications also implies that upslog will remain in the foreground by default.

-u username

If started as root, upslog will setuid(2) to the user id associated with username for security. If username is not defined, it will use the value that was compiled into the program. This defaults to nobody (if not otherwise configured), which is far from ideal.

## COMMON OPTIONS
-h

Show the command-line help message.

-V

Show NUT version banner. More details may be available if you also export NUT_DEBUG_LEVEL=1 or greater verbosity level.

-W secs

Set the timeout for initial network connections (by default they are indefinitely non-blocking, or until the system interrupts the attempt). Overrides the optional NUT_DEFAULT_CONNECT_TIMEOUT environment variable.

## SERVICE DELAYS
The interval value is merely the number given to sleep(3) after running through the format string. Therefore, a query will actually take slightly longer than the interval, depending on the speed of your system.

## ON-DEMAND LOGGING
Sending a SIGUSR1 to a running upslog process makes it wake from the current sleep and log immediately. This is useful when triggered from a upssched event trigger (e.g. AT ONBATT or AT ONLINE) to ensure that an entry always exists, even if the power goes away for a period of time shorter than that specified by the -i argument.

## LOG CO-LOCATION
It is possible and safe to specify the same log file (including - for stdout) in several tuples, and it would only be opened or closed once without conflict.

Consider adding %UPSHOST% to your custom formatting string (e.g. by using the -N command-line option), in order to easily differentiate lines corresponding to different systems, when logging them to the same target.

## LOG ROTATION
upslog writes its PID to upslog.pid, and will reopen the log file if you send it a SIGHUP. This allows it to keep running when the log is rotated by an external program.

## CAVEATS
Historically this daemon supported logging of data for one UPS system per run (specified by the -s option) into one log file name or stdout (specified by the -l option).

Since NUT v2.8.1 it allowed to log several devices (each logged into its individual destination file or common stdout) as specified by multiple -m tuple options. But the two modes were effectively exclusive of each other (single-UPS options were ignored if tuples are also provided).

Since NUT v2.8.3, the single-UPS options are added to the list of tuples, so both legacy and new options can be reliably used to monitor multiple devices in the same run.

## SEE ALSO

### Server:
upsd(8)

### Clients:
upsc(8), upscmd(8), upsrw(8), upsmon(8), upssched(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


upsmon

title: upsmon(8)

summary: UPS monitor and shutdown controller

text:
# upsmon(8)

## NAME
upsmon - UPS monitor and shutdown controller

## SYNOPSIS
upsmon -h

upsmon -c command [-P pid]

upsmon [-D] [-F | -B] [-K] [-p] [-u user]

## DESCRIPTION
upsmon is the client process that is responsible for the most important part of UPS monitoring — shutting down the system when the power goes out. It can call out to other helper programs for notification purposes during power events.

upsmon can monitor multiple systems using a single process. Every UPS that is defined in the upsmon.conf(5) configuration file is assigned a power value and a type (primary or secondary).

## OPTIONS
-c command

Send the command command to the existing upsmon process. Valid commands are: fsd

shutdown all primary-mode UPSes (use with caution)

stop

stop monitoring and exit

reload

reread upsmon.conf(5) configuration file. See "reloading nuances" below if this doesn’t work.

-P pid

Send the command signal above using specified PID number, rather than consulting the PID file. This can help define service units which start main upsmon as a foreground process so it does not have to rely on a PID file.

-D

Raise the debugging level. upsmon will run in the foreground by default, and will print information on stdout about the monitoring process. Use this option multiple times for more details.

-F

upsmon will run in the foreground, regardless of debugging settings.

-B

upsmon will run in the background, regardless of debugging settings.

-K

Test for the shutdown flag. If it exists and contains the magic string from upsmon, then upsmon will exit with EXIT_SUCCESS. Any other condition will make upsmon exit with EXIT_FAILURE. You can test for a successful exit from upsmon -K in your shutdown scripts to know when to call upsdrvctl(8) to shut down the UPS.

-p

Run privileged all the time. Normally upsmon will split into two processes. The majority of the code runs as an unprivileged user, and only a tiny stub runs as root to eventually call SHUTDOWNCMD if needed. This switch will disable that mode, and run the old "all root all the time" system. This is not the recommended mode, and you should not use this unless you have a very good reason.

-u user

Set the user for the unprivileged monitoring process. This has no effect when using -p. The default user is set at build configuration time with configure --with-user=.... Typically this is nobody (if not otherwise configured), which is far from ideal, so most packaged distributions will probably have a specific nut user for this task. If your notification scripts need to run as a specific user, set it here.

You can also set this in the upsmon.conf(5) file with the RUN_AS_USER directive.

## COMMON OPTIONS
-h

Show the command-line help message.

-V

Show NUT version banner. More details may be available if you also export NUT_DEBUG_LEVEL=1 or greater verbosity level.

-W secs

Set the timeout for initial network connections (by default they are indefinitely non-blocking, or until the system interrupts the attempt). Overrides the optional NUT_DEFAULT_CONNECT_TIMEOUT environment variable.

## UPS DEFINITIONS
In the upsmon.conf(5), you must specify at least one UPS that will be monitored. Use the MONITOR directive like this:

```
MONITOR 'system' 'powervalue' 'username' 'password' 'type'
```

The system refers to a upsd(8) server, in the form upsname[@hostname[:port]]. The default hostname is "localhost", and default port is 3493. Some examples follow:

•"su700@mybox" means a UPS called "su700" on a system called "mybox". This is the normal form.

•"fenton@bigbox:5678" is a UPS called "fenton" on a system called "bigbox" which runs upsd(8) on port "5678".

The powervalue refers to how many power supplies on this client system are being driven this UPS. This is typically set to 1, but see the section on power values below.

The username is a section in your upsd.users(5) file. Whatever password you set in that section must match the password set in this file for the corresponding data server instance.

The type set in that section of the data server configuration must also match the type here — primary or secondary (consider it an "upsmon role"). In general, a "primary" client process is one running on the system with the UPS actually plugged into a serial or USB port, and a "secondary" is drawing power from the UPS but can’t talk to it directly. See the section on UPS types for more.

## NOTIFY EVENTS
upsmon senses several events as it monitors each UPS. They are called "notify events", as they can be used to tell the users and admins about the change in status. See the additional NOTIFY-related sections below for information on customizing the delivery of these messages.

ONLINE

The UPS is back on line.

ONBATT

The UPS is on battery.

LOWBATT

The UPS battery is low (as determined by the driver).

FSD

The UPS has been commanded into the "forced shutdown" mode.

COMMOK

Communication with the UPS has been established.

COMMBAD

Communication with the UPS was just lost.

SHUTDOWN

The local system is being shut down.

REPLBATT

The UPS needs to have its battery replaced.

NOCOMM

The UPS can’t be contacted for monitoring.

NOPARENT

upsmon parent process died - shutdown impossible.

CAL

UPS calibration in progress.

NOTCAL

UPS calibration finished.

OFF

UPS administratively OFF or asleep.

NOTOFF

UPS no longer administratively OFF or asleep.

BYPASS

UPS on bypass (powered, not protecting).

NOTBYPASS

UPS no longer on bypass.

ECO

UPS in ECO or similar mode (as defined and named by vendor); other names include High Efficiency mode and Energy Saver System. For example, Eaton docs define High Efficiency mode as a sort of hardware-monitored bypass with switch-over under 10ms into Online mode in case of troubles (so what was known as Line-Interactive in the older days), which can be chosen instead of always running in a dual-conversion mode (safer, but more wasteful and with a toll on battery life). Older devices only implemented one or the other.

NOTECO

UPS no longer in ECO mode (see above).

ALARM

UPS has one or more active alarms (look at ups.alarm for details).

NOTALARM

UPS is no longer in an alarm state (no active alarms).

OVER

UPS is overloaded.

NOTOVER

UPS is no longer overloaded.

TRIM

UPS is trimming incoming voltage.

NOTTRIM

UPS is no longer trimming incoming voltage.

BOOST

UPS is boosting incoming voltage.

NOTBOOST

UPS is no longer boosting incoming voltage.

OTHER

UPS has at least one unclassified status token.

NOTOTHER

UPS has no unclassified status tokens anymore.

SUSPEND_STARTING

OS is entering sleep/suspend/hibernate mode.

SUSPEND_FINISHED

OS just finished sleep/suspend/hibernate mode, de-activating obsolete UPS readings to avoid an unfortunate shutdown.

## NOTIFY COMMAND
In upsmon.conf(5), you can configure a program called the NOTIFYCMD that will handle events that occur.

The syntax is: NOTIFYCMD "path to program"

Example:

•NOTIFYCMD "/usr/local/bin/notifyme"

Remember to wrap the path in "double quotes" if it contains any spaces. It should probably not rely on receiving any command-line arguments.

The program you run as your NOTIFYCMD can use the environment variables NOTIFYTYPE and UPSNAME to know what has happened and on which UPS. It also receives the notification message (see below) as the first (and only) argument, so you can deliver a pre-formatted message too.

Note that the NOTIFYCMD will only be called for a given event when you set the EXEC flag by using the notify flags, as detailed below.

## NOTIFY FLAGS
By default, all notify events (see above) generate a global message (wall) to all users, plus they are logged via the syslog. Except for Windows where upsmon only writes to the syslog by default. You can change this with the NOTIFYFLAG directive in the configuration file:

The syntax is: NOTIFYFLAG notifytype flags

Examples:

•NOTIFYFLAG ONLINE SYSLOG

•NOTIFYFLAG ONBATT SYSLOG+WALL

•NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC

The flags that can be set on a given notify event are:

SYSLOG

Write this message to the syslog.

WALL

Send this message to all users on the system via wall(1).

EXEC

Execute the NOTIFYCMD.

IGNORE

Don’t do anything. If you use this, don’t use any of the other flags.

You can mix these flags; for example, SYSLOG+WALL+EXEC does all three for a given event.

## NOTIFY MESSAGES
upsmon comes with default messages for each of the NOTIFY events. These can be changed with the NOTIFYMSG directive.

The syntax is: NOTIFYMSG type "message"

Examples:

•NOTIFYMSG ONLINE "UPS %s is getting line power"

•NOTIFYMSG ONBATT "Someone pulled the plug on %s"

The first instance of %s is replaced with the identifier of the UPS that generated the event. These messages are used when sending walls to the users directly from upsmon, and are also passed to the NOTIFYCMD.

Note Certain notifications, such as NOTIFY_ALARM and NOTIFY_OTHER, can accept a second instance of %s that would be replaced with the alarm text or the unrecognized token, respectively.

## POWER VALUES
The "current overall power value" is the sum of all UPSes that are currently able to supply power to the system hosting upsmon. Any UPS that is either on line or just on battery contributes to this number. If a UPS is critical (on battery and low battery) or has been put into "forced shutdown" mode, it no longer contributes.

The syntax is: MONITOR upsname powervalue username password type

A "power value" on a MONITOR line in the config file is the number of power supplies that the UPS runs on the current system.

•Normally, you only have one power supply, so it will be set to 1. Example:

•MONITOR myups@myhost 1 username mypassword primary

•On a large server with redundant power supplies, the power value for a UPS may be greater than 1. You may also have more than one of them defined. Examples for a server with four power supply modules and two UPSes (each feeding two power supplies of that server):

•MONITOR ups-alpha@myhost 2 username mypassword primary

•MONITOR ups-beta@myhost 2 username mypassword primary

•You can also set the power value for a UPS to 0 if it does not supply any power to that system. This is generally used when you want to use the upsmon notification features for a UPS even though it’s not actually powering the system that hosts this instance of the upsmon client. Don’t set this to "primary" unless you really want to power this UPS off when this instance of upsmon needs to shut down for its own reasons.

Example:

•MONITOR faraway@anotherbox 0 username mypassword secondary

The "minimum power value" is the number of power supplies that must be receiving power in order to keep this upsmon client’s computer running.

The syntax is: MINSUPPLIES value

•Typical PCs only have 1, so most users will leave this at the default. Example:

•MINSUPPLIES 1

•If you have a server or similar system with redundant power, then this value will usually be set higher. One that requires three power supplies out of 4 to be running at all times would simply set it to 3. Example:

•MINSUPPLIES 3

When the current overall healthy UPS-protected external power value drops below the minimum required power value, upsmon starts the shutdown sequence. This design allows you to lose some of your power supplies in a redundant power environment without bringing down the entire system, while still working properly for smaller systems.

## UPS CONNECTION TYPES AND UPSMON ROLES
upsmon and upsd(8) don’t always run on the same system. When they do, any UPSes that are directly attached to that upsmon host should be monitored in "primary" mode, which makes that upsmon instance take charge of that equipment, and it will wait for the "secondary" systems to disconnect before shutting down the local system. This allows the distant systems (just monitoring over the network) to shut down cleanly before upsdrvctl shutdown runs locally on the primary system and turns them all off.

When upsmon runs as a secondary, it is relying on the distant system to tell it about the state of the UPS. When that UPS goes critical (on battery and low battery), it immediately invokes the local shutdown command. This needs to happen quickly. Once all secondaries disconnect from the distant upsd(8) server, its primary-mode upsmon will start its own shutdown process. Your secondary systems must all quiesce and shut down before the primary turns off the shared power source, or filesystem damage may result.

upsmon deals with secondaries that get wedged, hang, or otherwise fail to gracefully disconnect from upsd(8) in a timely manner with the HOSTSYNC timer. During a shutdown situation, the primary upsmon will give up after this interval and it will shut down anyway. This keeps the primary from sitting there forever (which would endanger that host) if a secondary should break somehow. This defaults to 15 seconds.

If your primary system is shutting down too quickly, set the FINALDELAY interval to something greater than the default 15 seconds. Don’t set this too high, or your UPS battery may run out of power before the primary upsmon process shuts down that system. If you do need more time, consider starting the shutdown after a short time on battery, for details see the Timed Shutdowns section.

For a more technical take, please see the Shutdown Activity Workflow section.

## TIMED SHUTDOWNS
For those rare situations where the shutdown process can’t be completed between the time that low battery is signalled and the UPS actually powers off the load, use the upssched(8) helper program. You can use it along with upsmon to schedule a shutdown based on the "on battery" event. upssched can then come back to upsmon to initiate the shutdown once it has run on battery too long.

This can be complicated and messy, so stick to the default critical UPS handling if you can.

## REDUNDANT POWER SUPPLIES
If you have more than one power supply for redundant power, you may also have more than one UPS feeding your computer. upsmon can handle this. Be sure to set the UPS power values appropriately and the MINSUPPLIES value high enough so that it keeps running until it really does need to shut down.

For example, the HP NetServer LH4 by default has 3 power supplies installed, with one bay empty. It has two power cords, one per side of the box. This means that one power cord powers two power supply bays, and that you can only have two UPSes supplying power.

Connect UPS "alpha" to the cord feeding two power supplies, and UPS "beta" to the cord that feeds the third and the empty slot. Define alpha as a powervalue of 2, and beta as a powervalue of 1. Set the MINSUPPLIES to 2.

When alpha goes on battery, your current overall power value will stay at 3, as it’s still supplying power. However, once it goes critical (on battery and low battery), it will stop contributing to the current overall power value. That means the value will be 1 (beta alone), which is less than 2. That is insufficient to run the system, and upsmon will invoke the shutdown sequence.

However, if beta goes critical, subtracting its contribution will take the current overall value from 3 to 2. This is just high enough to satisfy the minimum, so the system will continue running as before. If beta returns later, it will be re-added and the current value will go back to 3. This allows you to swap out UPSes, change a power configuration, or whatever, as long as you maintain the minimum power value at all times.

## MIXED OPERATIONS
Besides being able to monitor multiple UPSes, upsmon can also monitor them as different roles. If you have a system with multiple power supplies serviced by separate UPS batteries, it’s possible to be a primary on one UPS and a secondary on the other. This usually happens when you run out of serial or USB ports and need to do the monitoring through another system nearby.

This is also complicated, especially when it comes time to power down a UPS that has gone critical but doesn’t supply the local system. You can do this with some scripting magic in your notify command script, but it’s beyond the scope of this manual.

## FORCED SHUTDOWNS
When upsmon is forced to bring down the local system, it sets the "FSD" (forced shutdown) flag on any UPSes that it is running in primary mode. This is used to synchronize secondary systems in the event that a primary which is otherwise OK needs to be brought down due to some pressing event on the UPS manager system.

You can manually invoke this mode on the system with primary-mode upsmon by starting another copy of the program with -c fsd command line argument. This is useful when you want to initiate a shutdown before the critical stage through some external means, such as upssched(8).

For a more technical take, please see the Shutdown Activity Workflow section.

Warning Please note that by design, since we require power-cycling the load and don’t want some systems to be powered off while others remain running if the "wall power" returns at the wrong moment as usual, the "FSD" flag can not be removed from the data server unless its daemon is restarted. If we do take the first step in critical mode, then we normally intend to go all the way — shut down all the servers gracefully, and power down the UPS.

Keep in mind that some UPS devices and corresponding drivers would also latch or otherwise resurface the "FSD" state again even if "wall power" is available, but the remaining battery charge is below a threshold configured as "safe" in the device (usually if you manually power on the UPS after a long power outage). This is by design of respective UPS vendors, since in such situation they can not guarantee that if a new power outage happens, their UPS would safely shut down your systems again. So it is deemed better and safer to stay dark until batteries become sufficiently charged.

When it is time to shut down, upsmon creates POWERDOWNFLAG to communicate to the operating system that the UPS should be commanded off late in the shutdown sequence. This file is removed if present when upsmon starts, so that the next normal shutdown does not cause the UPS to be turned off. (The file can’t in general be removed during shutdown because the filesystem might be read only. If the file is in a RAM-backed filesystem, the it won’t be present and the check to remove it won’t fire.)

## SIMULATING POWER FAILURES
To test a synchronized shutdown without pulling the plug on your UPS(es), you need only set the forced shutdown (FSD) flag on them. You can do this by calling upsmon again to set the flag, i.e.:

```
:; upsmon -c fsd
```

After that, the primary and the secondary will do their usual shutdown sequence as if the battery had gone critical, while you can time how long it takes for them. This is much easier on your UPS equipment, and it beats crawling under a desk to find the plug.

Note you can also use a dummy SHUTDOWNCMD setting to just report that the systems would shut down at this point, without actually disrupting their work.

For inspiration, you can see the setup done by the NUT Integration Tests suite under the tests/NIT directory in NUT sources, including references to the shutdown and notification scripts which only log the activity (you may have to configure at least a trivial NUT build and run make check-NIT-sandbox to generate some of the configuration files — or inspect the nit.sh script which pieces them together). Notably, see scripts/misc/notifyme-debug as not only a logger, but optionally a wrapper for upssched (in test runs), and clients/upssched-cmd as a sample implementation of an upssched(8) CMDSCRIPT which also focuses on logging.

Warning After such "dummy" experiments you may have to restart the NUT data server upsd to clear its "FSD" flag for the devices and clients involved, and make sure no files named by POWERDOWNFLAG option (e.g. /etc/killpower) remain on the upsmon primary systems under test.

## SHUTDOWN ACTIVITY WORKFLOW
Looking into clients/upsmon.c sources as the ultimate authority, you can find that the chain of events during a forced shutdown is. This can help make sense of the timing variables involved, and notifications sent (which you may want to handle, perhaps with upssched(8)):

•The path to shutdown activity of a host starts when its locally running upsmon client (in any role) decides the power situation is critical, e.g. by having too few "healthy" power supplies in a real outage, and/or by seeing FSD among ups.status tokens — possibly still "latched" in the upsd data server while you start a new upsmon instance, or when you call upsmon -c fsd on that system to simulate the outage;

•Such upsmon instance ends up in forceshutdown() method;

•There it loops over all UPSes it MONITOR`s as a `primary, and calls the setfsd() method for each (causing a local FSD notification, if one was not sent earlier);

•If there were no such UPSes — we are a secondary, and go into doshutdown() method immediately

•Otherwise we are a primary, and only go into doshutdown() method after first completing the sync_secondaries() method, which:

•runs an infinite loop until either there are no other persistent clients logged on to the data server (upsd) for each UPS we are a primary for, or until HOSTSYNC timeout elapses;

•it should issue a SHUTDOWN_HOSTSYNC notification if it is going to wait at all (if there were other clients seen on first loop cycle).

•Finally, in the doshutdown() method, it:

•issues a SHUTDOWN notification;

•waits for FINALDELAY;

•starts the timer for SHUTDOWNEXIT (which may be used to force upsmon process to linger after calling SHUTDOWNCMD — e.g. can be used by a secondary to block the primary from cutting power too early for some use cases, like safely parking some external machinery);

•calls the SHUTDOWNCMD (either directly in mono-process mode, or by telling the root-privileged part to do so in the common case);

•optionally linger, if SHUTDOWNEXIT is so configured;

•ultimately exit the daemon (also causes the root-privileged part to exit, by breaking the communications pipe between them).

Note that if your upsmon does split into privileged and unprivileged parts, all notifications run in the unprivileged context (your handling scripts may have to sudo explicitly if/when/where you want to do something to the system). Only SHUTDOWNCMD is called in privileged context.

## DEAD UPSES
In the event that upsmon can’t reach upsd(8), it declares that UPS "dead" after some interval controlled by DEADTIME in the upsmon.conf(5). If this happens while that UPS was last known to be on battery, it is assumed to have gone critical and no longer contributes to the overall power value.

upsmon will alert you to a UPS that can’t be contacted for monitoring with a "NOCOMM" notifier by default every 300 seconds. This can be changed with the NOCOMMWARNTIME setting.

Also upsmon normally reports polling failures for each device that are in place for each POLLFREQ loop (e.g. "Data stale" or "Driver not connected") to system log as configured. If your devices are expected to be AWOL for an extended timeframe, you can use POLLFAIL_LOG_THROTTLE_MAX to reduce the stress on syslog traffic and storage, by posting these messages only once in every several loop cycles, and when the error condition has changed or cleared. A negative value means standard behavior (log on every loop, effectively same as when max=1), and a zero value means to never repeat the message (log only on start and end/change of the failure state).

Note that this throttle only applies to one latest-active error state per monitored device.

## UPS ALARMS
UPS manufacturers and UPS drivers may implement device-specific alarms to notify the user about potentially severe conditions of the UPS. The status "ALARM" will be set on such UPS as a common denominator for the different implementations throughout the various UPS drivers and generally anytime that a "ups.alarm" variable is seen reported by the specific UPS driver.

Alarms can be acted upon by the user using the "ALARM" and "NOTALARM" notifiers, which are reported by the upsmon when the "ALARM" status occurs or disappears.

As alarms raised by the UPS are usually severe in nature, the upsmon watches a UPS in such a state more closely, bumping up the polling frequency as needed.

When connection loss occurs in such an alarm state, the upsmon will by default consider the volatile UPS as critical/dead and this may lead to false shutdowns if the actual alarm was in fact mundane in nature (e.g. caused by a HE/ECO mode). This can be changed by utilizing the ALARMCRITICAL setting within upsmon.conf.

## RELOADING NUANCES
upsmon usually gives up root powers for the process that does most of the work, including handling signals like SIGHUP to reload the configuration file. This means your upsmon.conf(5) file must be readable by the non-root account that upsmon switches to.

If you want reloads to work, upsmon must run as some user that has permissions to read the configuration file. We recommend making a new user just for this purpose, as making the file readable by "nobody" (the default user) would be a bad idea; packages typically ship with a nut or ups user to run NUT daemon services.

See the RUN_AS_USER section in upsmon.conf(5) for more on this topic.

Additionally, you can’t change the SHUTDOWNCMD or POWERDOWNFLAG definitions with a reload due to the split-process model. If you change those values, you must stop upsmon and start it back up. upsmon will warn you in the syslog if you make changes to either of those values during a reload.

## ENVIRONMENT VARIABLES
NUT_DEBUG_LEVEL sets default debug verbosity if no -D arguments were provided on command line, but does not request that the daemon runs in foreground mode.

NUT_CONFPATH is the path name of the directory that contains upsmon.conf and other configuration files. If this variable is not set, upsmon uses a built-in default, which is often /usr/local/ups/etc.

NUT_QUIET_INIT_UPSNOTIFY=true can be used to prevent daemons which can notify service management frameworks (such as systemd) about passing their lifecycle milestones from emitting such notifications (including those about lack of system support for such modern features, once per run).

NUT_QUIET_INIT_BANNER=true can be used to suppress NUT tool name and version banner. NOT recommended for services due to adverse troubleshooting impact, but may be helpful in shell profiles or scripts which process NUT tool outputs.

## FILES
upsmon.conf(5)

## SEE ALSO

### Server:
upsd(8)

### Clients:
upsc(8), upscmd(8), upsrw(8), upsmon(8)

### CGI programs:
upsset.cgi(8), upsstats.cgi(8), upsimage.cgi(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


upsrw

title: upsrw(8)

text:
# upsrw(8)

## NAME
upsrw - Network UPS Tools device/driver variable administration tool

## SYNOPSIS
upsrw [-l] ups

upsrw -h

upsrw -s variable [-u username] [-p password] [-w] [-t <timeout>] ups

## DESCRIPTION
upsrw allows you to view and change the read/write variables inside your UPS. It sends commands via the server upsd(8) to your driver, which configures the hardware for you. You must use credentials defined in upsd.users(5) file on that data server with appropriate permissions.

The list of variables that allow you to change their values is based on the capabilities of your UPS equipment. Not all models support this feature. Typically, cheaper hardware does not support any of them. Run upsrw with a UPS identifier to see what will work for you.

## OPTIONS
-s variable

Specify the variable to be changed inside the UPS. For unattended mode such as in shell scripts, use the format VAR=VALUE to specify both the variable and the value, for example:

```
-s input.transfer.high=129
```

Without this argument, upsrw will just display the list of the variables and their possible values.

Some variables are strings, and can be set to any value within the length limit. Others are enumerated types and can only be set to one of those values. Others may be within an allowed range of values. Refer to the list to know what’s available in your hardware.

-l

Just display the list of the variables and their possible values. Same as default activity without -s argument, provided for CLI similarity with other tools.

-u username

Set the NUT username for the connection to the server. This is optional, and you will be prompted for this when using the -s option if you don’t specify -u on the command line. NUT usernames are defined in upsd.users(5), and are not linked to system usernames.

-p password

Set the password to authenticate to the server. This is also optional like -u, and you will be prompted for it if necessary.

-w

Wait for the completion of setting execution by the driver and return its actual result from the device. Note that this feature requires that both upsd(8) and the driver support TRACKING (NUT version 2.8.0 or higher), or it will otherwise fail. The command will also block until an actual result is provided from the driver, or the timeout is reached (see -t).

-t seconds

Set a timeout when using -w. Defaults to 10 seconds.

ups

View or change the settings on this UPS. The format for this option is upsname[@hostname[:port]]. The default hostname is "localhost".

## COMMON OPTIONS
-h

Show the command-line help message.

-D

Raise the debugging level. Use this option multiple times for more details. Overrides the optional NUT_DEBUG_LEVEL environment variable.

-V

Show NUT version banner. More details may be available if you also export NUT_DEBUG_LEVEL=1 or greater verbosity level.

-W secs

Set the timeout for initial network connections (by default they are indefinitely non-blocking, or until the system interrupts the attempt). Overrides the optional NUT_DEFAULT_CONNECT_TIMEOUT environment variable.

## UNATTENDED MODE
If you run this program inside a shell script or similar to set variables, you will need to specify all of the information on the command line. This means using -s VAR=VALUE, -u and -p. Otherwise it will put up a prompt and your program will hang.

This is not necessary when displaying the list, as the username and password are not required for read-only mode.

Moreover, if you run this program inside a shell script or similar, you should only consider using output from stdout, not stderr.

## DIAGNOSTICS
upsrw can’t set variables on your UPS unless you provide a valid username and password. If you get "access denied" errors, make sure that your upsd.users(5) has an entry for you, and that the username you are using has permissions to SET variables.

upsrw without -w would somewhat confusingly show "OK" meaning just that the data server connection was established, and the server did not immediately reject the request due to e.g. unknown driver variable name. If you care to know the actual results, do use the -w (-t NUM) option(s) to wait for them.

## VALUE FORMAT
When using upsrw to modify a numeric float value, that values must be given using decimal (base 10) english-based representation, so using a dot, in non-scientific notation. So hexadecimal, exponents, and comma for thousands separator are forbidden.

For example: "1200.20" is valid, while "1,200.20" and "1200,20" are invalid.

## HISTORY
This program used to be called upsct2, which was ambiguous and confusing.

## SEE ALSO
upsd(8), upscmd(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/