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:

http://www.tuxera.com/community/

## 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, iterleave 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 an 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 an 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 ] [ --interleave nodes ] [ --preferred node ] [ --membind nodes ] [ --cpunodebind nodes ] [ --physcpubind cpus ] [ --localalloc ] [--] command {arguments ...}

numactl --show

numactl --hardware

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 specifed 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.

--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 specifed 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

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.

--show, -s

Show NUMA policy settings of the current process.

--hardware, -H

Show inventory of available nodes on the system.

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

This policy is 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, --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 an shared memory segment with numeric ID id

--shm shmkeyfile

Create or use an 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 --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=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 --interleave=all --shm /tmp/shmkey Interleave all of the sysv shared memory region 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 an 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: example lightweight UPS client

text:
# upsc(8)

## NAME
upsc - example lightweight UPS client

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

upsc ups [variable]

upsc -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
-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 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 may be useful in shell scripts to save an additional pipe into grep.

## 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 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 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
upsd(8)

## INTERNET RESOURCES
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


upscmd

title: upscmd(8)

text:
# upscmd(8)

## NAME
upscmd - UPS administration program for instant commands

## SYNOPSIS
upscmd -h

upscmd -l ups

upscmd [-u username] [-p password] ups command

## DESCRIPTION
upscmd allows you to invoke "instant commands" in your UPS hardware. 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
-h

Display the help message.

-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.

ups

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

## 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.

## BUGS
There is currently no way to tell the user when the driver requires confirmation to invoke a command such as load.off. Similarly, there is not yet a way to tell the user if a command succeeds or fails.

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: http://www.networkupstools.org/


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
-h

Display the help message.

-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 "%"

%TIME format%

Insert the time with strftime formatting

%ETIME%

Insert the number of seconds, ala time_t. This is now a 10 digit number.

%HOST%

insert the local hostname

%UPSHOST%

insert the host of the UPS being monitored

%PID%

insert the pid of upslog

%VAR varname%

insert the value of variable varname

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%
```

-i interval

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

-l logfile

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

-s ups

Monitor this UPS. The format for this option is upsname[@hostname[:port]]. The default hostname is "localhost".

-u username

If started as root, upsmon 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", which is less than ideal.

## 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 USR1 signal 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 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.

## 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: http://www.networkupstools.org/


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

upsmon [-D] [-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 (slave or master).

## OPTIONS
-h

Display the help message.

-c command

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

shutdown all master 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.

-D

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

-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. 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 configure time with configure --with-user=.... Typically this is nobody, but other 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.

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

```
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". 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 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.

The type set in that section must also match the type here-- master or slave. In general, a master process is one running on the system with the UPS actually plugged into a serial port, and a slave 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.

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

NOTIFYCMD "path to program"

NOTIFYCMD "/usr/local/bin/notifyme"

Remember to wrap the path in "quotes" if it contains any spaces.

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 preformatted 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, 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. You can change this with the NOTIFYFLAG directive in the configuration file:

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. "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.

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.

## 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.

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.

MONITOR upsname powervalue username password type

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

MONITOR myups@myhost 1 username mypassword master

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.

MONITOR ups-alpha@myhost 2 username mypassword master

MONITOR ups-beta@myhost 2 username mypassword master

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 running the system that hosts upsmon. Don’t set this to "master" unless you really want to power this UPS off when this instance of upsmon needs to shut down for its own reasons.

MONITOR faraway@anotherbox 0 username mypassword slave

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

MINSUPPLIES value

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

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 to be running at all times would simply set it to 3.

MINSUPPLIES 3

When the current overall power value drops below the minimum 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 TYPES
upsmon and upsd(8) don’t always run on the same system. When they do, any UPSes that are directly attached to the upsmon host should be monitored in "master" mode. This makes upsmon take charge of that equipment, and it will wait for slaves to disconnect before shutting down the local system. This allows the distant systems (monitoring over the network) to shut down cleanly before upsdrvctl shutdown runs and turns them all off.

When upsmon runs as a slave, 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 it disconnects from the distant upsd(8) server, the master upsmon will start its own shutdown process. Your slaves must all shut down before the master turns off the power or filesystem damage may result.

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

If your master 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 master upsmon process shuts down that system.

## 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 master on one and a slave on the other. This usually happens when you run out of serial 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 master mode. This is used to synchronize slaves in the event that a master UPS that is otherwise OK needs to be brought down due to some pressing event on the master.

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

## 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.

## 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(8) 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. I recommend making a new user just for this purpose, as making the file readable by "nobody" (the default user) would be a bad idea.

See the RUN_AS_USER section in upsmon.conf(8) 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.

## 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 master and the slaves will do their usual shutdown sequence as if the battery had gone critical. This is much easier on your UPS equipment, and it beats crawling under a desk to find the plug.

## 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: http://www.networkupstools.org/


upsrw

title: upsrw(8)

summary: UPS variable administration tool

text:
# upsrw(8)

## NAME
upsrw - UPS variable administration tool

## SYNOPSIS
upsrw ups

upsrw -h

upsrw -s variable [-u username] [-p password] 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.

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
-h

Display the help message.

-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.

-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.

ups

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

## 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.

## 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 forbiden. 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: http://www.networkupstools.org/


upssched

title: upssched(8)

text:
# upssched(8)

## NAME
upssched - Timer helper for scheduling events from upsmon

## SYNOPSIS
upssched

Note upssched should be run from upsmon(8) via the NOTIFYCMD. You should never run it directly during normal operations.

## DESCRIPTION
upssched was created to allow users to execute programs at times relative to events being monitored by upsmon(8). The original purpose was to allow for a shutdown to occur after some fixed period on battery, but there are other uses that are possible.

## INTEGRATION
upssched needs to be called as the NOTIFYCMD in your upsmon.conf(5). It determines what is happening based on the UPSNAME and NOTIFYTYPE environment variables. You should never have to deal with them directly.

Set the EXEC flag on the events that you want to see in upssched. For example, to make sure that upssched hears about ONLINE, ONBATT and LOWBATT events, the flags would look like this:

```
NOTIFYFLAG ONLINE EXEC
NOTIFYFLAG ONBATT EXEC
NOTIFYFLAG LOWBATT EXEC
```

If you also want to continue writing to the syslog, just add it in:

```
NOTIFYFLAG ONLINE SYSLOG+EXEC
NOTIFYFLAG ONBATT SYSLOG+EXEC
NOTIFYFLAG LOWBATT SYSLOG+EXEC
```

For a full list of notify flags, see the upsmon(8) documentation.

## CONFIGURATION
See upssched.conf(5) for information on configuring this program.

## EARLY SHUTDOWNS
To shut down the system early, define a timer that starts due to an ONBATT condition. When it triggers, make your CMDSCRIPT call your shutdown routine. It should finish by calling upsmon -c fsd so that upsmon gets to shut down the slaves in a controlled manner.

Be sure you cancel the timer if power returns (ONLINE).

## DEBOUNCING EVENTS
If your UPS goes on and off battery frequently, you can use this program to reduce the number of pager messages that are sent out. Rather than sending pages directly from upsmon(8), use a short timer here. If the timer triggers with the UPS still on battery, then send the page. If the power returns before then, the timer can be cancelled and no page is necessary.

## BACKGROUND
This program was written primarily to fulfill the requests of users for the early shutdown scenario. The "outboard" design of the program (relative to upsmon) was intended to reduce the load on the average system. Most people don’t have the requirement of shutting down after N seconds on battery, since the usual OB+LB testing is sufficient.

This program was created separately so those people don’t have to spend CPU time and RAM on something that will never be used in their environments.

The design of the timer handler is also geared towards minimizing impact. It will come and go from the process list as necessary. When a new timer is started, a process will be forked to actually watch the clock and eventually start the CMDSCRIPT. When a timer triggers, it is removed from the queue. Cancelling a timer will also remove it from the queue. When no timers are present in the queue, the background process exits.

This means that you will only see upssched running when one of two things is happening:

•There’s a timer of some sort currently running

•upsmon just called it, and you managed to catch the brief instance

The final optimization handles the possibility of trying to cancel a timer when there are none running. If the timer daemon isn’t running, there are no timers to cancel, and furthermore there is no need to start a clock-watcher. So, it skips that step and exits sooner.

## FILES
upssched.conf(5)

## SEE ALSO
upsmon(8)

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


upsimage.cgi

package: nut-cgi

title: upsimage.cgi(8)

summary: Image\-generating helper for upsstats.cgi

text:
# upsimage.cgi(8)

## NAME
upsimage.cgi - Image-generating helper for upsstats.cgi

## SYNOPSIS
upsimage.cgi

Note As a CGI program, this should be invoked through your web server. If you run it from the command line, it will either complain about unauthorized access or spew a PNG at you.

## DESCRIPTION
upsimage.cgi generates the graphical bars that make up the right side of the page generated by upsstats.cgi(8). These represent the current battery charge, utility voltage, and UPS load where available.

The images are in PNG format, and are created by linking to Boutell’s excellent gd library.

## ACCESS CONTROL
upsstats will only talk to upsd(8) servers that have been defined in your hosts.conf(5). If it complains about "Access to that host is not authorized", check that file first.

## FILES
hosts.conf(5)

## SEE ALSO
upsd(8), upsstats.cgi(8)

### Internet resources:
The gd home page: http://libgd.bitbucket.org

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


upsset.cgi

title: upsset.cgi(8)

summary: Web\-based UPS administration program

text:
# upsset.cgi(8)

## NAME
upsset.cgi - Web-based UPS administration program

## SYNOPSIS
upsset.cgi

Note As a CGI program, this should be invoked through your web server. If you run it from the command line, it will sit there until you give it input resembling a POST request.

## DESCRIPTION
upsset.cgi lets you access many administrative functions within the UPS software from your web browser. You can change settings and invoke instant commands where available.

## CHANGING SETTINGS
Some UPS hardware allows you to change certain variables to other values. To see what’s available, pick a UPS from the chooser and select "settings", then select "View" to update the page.

You should see a list of items with the descriptions on the left side and the possible options or input spaces on the right. After changing something, be sure to "Save changes" to update the values in your UPS.

If your UPS doesn’t support any read/write variables, there will be nothing to do on this page.

Setting values in read/write variables can also be done from the command line with upsrw(8).

## INSTANT COMMANDS
Some UPS hardware also has provisions for performing certain actions at the user’s command. These include battery tests, battery calibration, front panel tests (beep!) and more. To access this section, do as above, but pick "Commands" as the function.

If your UPS supports any instant commands, they will be listed in a chooser widget. Pick the one you like and "Issue command" to make it happen.

Note some dangerous commands like "Turn off load" may not happen right away. This is a feature, not a bug.

The apcsmart driver and some others require that you send this command twice within a short window in order to make it happen. This is to keep you from accidentally killing your systems by picking the wrong one.

To actually turn off the load, you have to send the command once, then send it again after 3 seconds elapse but before 15 seconds pass. If you do it too quickly or slowly, you have to wait at least 3 seconds but not 15 seconds again.

You can also invoke instant commands from the command line with upscmd(8).

## ACCESS CONTROL
upsset will only talk to upsd(8) servers that have been defined in your hosts.conf(8). If it complains about "Access to that host is not authorized", check your hosts.conf first.

## SECURITY
upsset will not run until you convince it that your CGI directory has been secured. This is due to the possibility of someone using upsset to try password combinations against your upsd(8) server.

See the example upsset.conf file for more information on how you do this. The short explanation is—if you can’t lock it down, don’t try to run it.

## FILES
hosts.conf(5), upsset.conf(5)

## SEE ALSO

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


upsstats.cgi

title: upsstats.cgi(8)

summary: Web\-based UPS status viewer

text:
# upsstats.cgi(8)

## NAME
upsstats.cgi - Web-based UPS status viewer

## SYNOPSIS
upsstats.cgi

Note As a CGI program, this should be invoked through your web server. If you run it from the command line, it will either complain about unauthorized access or spew a bunch of HTML at you.

## DESCRIPTION
upsstats.cgi uses template files to build web pages containing status information from UPS hardware. It can repeat sections of those template files to monitor several UPSes simultaneously, or focus on a single UPS.

These templates can also include references to upsimage.cgi(8) for graphical displays of battery charge levels, voltage readings, and the UPS load.

## ACCESS CONTROL
upsstats will only talk to upsd(8) servers that have been defined in your hosts.conf(5). If it complains that "Access to that host is not authorized", check that file first.

## TEMPLATES
The web page that is displayed is actually a template containing commands to upsstats which are replaced by status information. The default file used for the overview is upsstats.html.

When monitoring a single UPS, the file displayed is upsstats-single.html.

The format of these files, including the possible commands, is documented in upsstats.html(5).

## FILES
hosts.conf(5), upsstats.html(5), upsstats-single.html

## SEE ALSO
upsimage.cgi(8)

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


nut-ipmipsu

package: nut-driver-ipmi

title: nut-ipmipsu(8)

text:
# nut-ipmipsu(8)

## NAME
nut-ipmipsu - Driver for IPMI Power Supply Units (PSU)

## SYNOPSIS
nut-ipmipsu -h

nut-ipmipsu -a PSU_NAME [OPTIONS]

Note This driver is experimental, and still a work-in-progress. Feedback is encouraged.

Note This man page only documents the hardware-specific features of the nut-ipmipsu driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
This driver should support a wide range of PSUs through local IPMI interface.

nut-ipmipsu currently use the GNU FreeIPMI project, for IPMI implementation.

## EXTRA ARGUMENTS
This driver doesn’t support any optional settings.

## INSTALLATION
This driver is not built by default. You can build it by using "configure --with-ipmi=yes".

You also need to give proper permissions on the local IPMI device file (/dev/ipmi0 for example) to allow the NUT user to access it.

An udev rules file (nut-ipmipsu.rules) is provided and automatically installed on udev enabled system. This file is generally installed in /etc/udev/rules.d/ or /lib/udev/rules.d/ on newer systems, to address the permission settings problem. For more information, refer to nut/scripts/udev/README.

## INSTANT COMMANDS
This driver doesn’t support any instant commands.

## IMPLEMENTATION
The "port" value is used to identify the PSU. For instance, to target FRU 0x2, use the following in ups.conf:

```
[pdu]

        driver = nut-ipmipsu

        port = id2
```

This driver will report various information related to a PSU, including:

•manufacturer, model, serial and part numbers,

•nominal voltage and frequency,

•actual current and voltage,

•status of the PSU:

•OL means that the PSU is present and providing power,

•OFF means that the PSU is present but not providing power (power cable removed),

•stale (no data) means that the PSU is not present (ie physically removed).

Here is an example output for a Dell r610 server:

```
device.mfr: DELL
device.mfr.date: 01/05/11 - 08:51:00
device.model: PWR SPLY,717W,RDNT
device.part: 0RN442A01
device.serial: CN179721130031
device.type: psu
driver.name: nut-ipmipsu
driver.parameter.pollinterval: 2
driver.parameter.port: id2
driver.version: 2.6.1-3139M
driver.version.data: IPMI PSU driver
driver.version.internal: 0.01
input.current: 0.20
input.frequency.high: 63
input.frequency.low: 47
input.voltage: 232.00
input.voltage.maximum: 264
input.voltage.minimum: 90
ups.id: 2
ups.realpower.nominal: 717
ups.status: OL
ups.voltage: 12
```

## AUTHOR
Arnaud Quette <arnaud.quette@free.fr>

## SEE ALSO

### The core driver:
nutupsdrv(8)

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

GNU FreeIPMI home page: http://www.gnu.org/software/freeipmi/


snmp-ups

package: nut-driver-snmp

title: snmp-ups(8)

summary: Multi\-MIB Driver for SNMP UPS equipment

text:
# snmp-ups(8)

## NAME
snmp-ups - Multi-MIB Driver for SNMP UPS equipment

## NOTE
This man page only documents the hardware-specific features of the snmp-ups driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
The snmp-ups driver automatically detects and supports a wide range of devices by loading various MIBS:

ietf

UPS that is RFC 1628 (UPS MIB) compliant, e.g. MGE UPS SYSTEMS, Liebert, perhaps others (default)

mge

MGE UPS SYSTEMS and MGE Office Protection Systems devices with SNMP cards (ref 66062, 66045, 66074 and 66244)

apcc

APC AP9605, AP9606, AP9617, and AP9618 APC network management cards, as well as any others supporting the APC POWERNET MIB

netvision

Socomec Sicon UPS with Netvision Web/SNMP management card/external box

pw

Powerware devices with ConnectUPS SNMP cards

pxgx_ups

Eaton devices with Power Xpert Gateway UPS Card

aphel_genesisII

Eaton Powerware ePDU Monitored

aphel_revelation

Eaton Powerware ePDU Managed

raritan

Various Raritan PDUs

baytech

Various BayTech PDUs

cpqpower

HP/Compaq AF401A management card, perhaps others

cyberpower

Cyberpower RMCARD201. Should also support RMCARD100 (net version), RMCARD202 and RMCARD301

huawei

Huawei UPS5000-E, perhaps others

## EXTRA ARGUMENTS
This driver supports the following optional settings in the ups.conf(5):

mibs=name

Set MIB compliance (default=auto, allowed entries: refer to SUPPORTED HARDWARE above). With "auto", the driver will try a select set of SNMP objects until it finds one that the device responds to. Note that since NUT 2.6.2, snmp-ups has a new method that uses sysObjectID (which is a pointer to the prefered MIB of the device) to detect supported devices. This renders void the use of "mibs" option.

community=name

Set community name (default = public). Note that a RW community name is required to change UPS settings (as for a powerdown).

snmp_version=version

Set SNMP version (default = v1, allowed: v2c, v3)

snmp_retries=retries

Specifies the number of Net-SNMP retries to be used in the requests (default=5)

snmp_timeout=timeout

Specifies the Net-SNMP timeout in seconds between retries (default=1)

pollfreq=value

Set polling frequency in seconds, to reduce network flow (default=30)

notransferoids

Disable the monitoring of the low and high voltage transfer OIDs in the hardware. This will remove input.transfer.low and input.transfer.high from the list of variables. This should only be used on APCC Symmetra equipment which has strangeness in the three-phase power reporting.

secLevel=value

Set the securityLevel used for SNMPv3 messages (default=noAuthNoPriv, allowed: authNoPriv,authPriv)

secName=value

Set the securityName used for authenticated SNMPv3 messages (no default)

authPassword=value

Set the authentication pass phrase used for authenticated SNMPv3 messages (no default)

privPassword=value

Set the privacy pass phrase used for encrypted SNMPv3 messages (no default)

authProtocol=value

Set the authentication protocol (MD5 or SHA) used for authenticated SNMPv3 messages (default=MD5)

privProtocol=value

Set the privacy protocol (DES or AES) used for encrypted SNMPv3 messages (default=DES)

## REQUIREMENTS
You will need to install the Net-SNMP package from http://www.net-snmp.org/ before building this driver.

SNMP v3 also requires OpenSSL support from http://www.openssl.org.

## LIMITATIONS

### Shutdown
The shutdown sequence should be tested before relying on NUT to send a shutdown command to the UPS. The problem is that the host network stack may have been torn down by the time the driver is invoked to send the shutdown command. The driver attempts to send shutdown.return, shutdown.reboot, and load.off.delay commands to the UPS in sequence, stopping after the first supported command.

## INSTALLATION
This driver is only built if the Net-SNMP development files are present at configuration time. You can also force it to be built by using configure --with-snmp=yes before calling make.

## EXAMPLES
The hostname of the UPS is specified with the "port" value in ups.conf:

```
[snmpv1]

        driver = snmp-ups

        port = snmp-ups.example.com

        community = public

        snmp_version = v1

        pollfreq = 15

        desc = "Example SNMP v1 device"
```

```
[snmpv3]

        driver = snmp-ups

        port = 166.99.224.132

        snmp_version = v3

        secLevel = authPriv

        secName = mysecurityname

        authPassword = myauthenticationpassphrase

        privPassword = myprivatepassphrase

        desc = "Example SNMP v3 device, with the highest security level"
```

## AUTHORS
Arnaud Quette, Dmitry Frolov

## SEE ALSO

### The core driver:
nutupsdrv(8)

### NUT SNMP Protocols Library
Available at: http://www.networkupstools.org/protocols/snmp/

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


package: nut-server

title: al175(8)

text:
# al175(8)

## NAME
al175 - Driver for Eltek UPS models with AL175 alarm module

## NOTE
This man page only documents the hardware-specific features of the al175 driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
The al175 driver is known to work with the following UPSes:

```
Eltek MPSU4000 with AL175 alarm module
```

It may also work with other UPSes equiped with AL175 alarm module, but they have not been tested.

AL175 have to be configured to operate in COMLI mode. See documentation supplied with your hardware on how to do it.

## EXTRA ARGUMENTS
This driver does not support any extra settings in the ups.conf(5).

## INSTANT COMMANDS
This driver supports some extra commands (see upscmd(8)):

test.battery.start

Start a battery test.

test.battery.stop

Stop a battery test.

## VARIABLES
Besides status, this driver reads UPS state into following variables:

•ups.test.result

•output.voltage.nominal

•output.current

•battery.voltage.nominal

•battery.current

•battery.temperature

•input.transfer.boost.low

## KNOWN ISSUES AND BUGS
•Shutdown is not supported. FIXME

•The driver was reworked to meet the project code quality criteria, without testing on real hardware. Some bugs may have crept in.

## AUTHOR
Kirill Smelkov <kirr@mns.spb.ru>

## SEE ALSO

### The core driver:
nutupsdrv(8)

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