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.

branch: sisyphus


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)


numatop

package: numatop

title: numatop(8)

text:
# numatop(8)

## NAME
numatop - a tool for memory access locality characterization and analysis.

## SYNOPSIS
numatop [-s] [-l] [-f] [-d]

numatop [-h]

## DESCRIPTION
This manual page briefly documents the numatop command.

Most modern systems use a Non-Uniform Memory Access (NUMA) design for multiprocessing. In NUMA systems, memory and processors are organized in such a way that some parts of memory are closer to a given processor, while other parts are farther from it. A processor can access memory that is closer to it much faster than the memory that is farther from it. Hence, the latency between the processors and different portions of the memory in a NUMA machine may be significantly different.

numatop is an observation tool for runtime memory locality characterization and analysis of processes and threads running on a NUMA system. It helps the user to characterize the NUMA behavior of processes and threads and to identify where the NUMA-related performance bottlenecks reside. The tool uses hardware performance counter sampling technologies and associates the performance data with Linux system runtime information to provide real-time analysis in production systems. The tool can be used to:

A) Characterize the locality of all running processes and threads to identify those with the poorest locality in the system.

B) Identify the "hot" memory areas, report average memory access latency, and provide the location where accessed memory is allocated. A "hot" memory area is where process/thread(s) accesses are most frequent. numatop has a metric called "ACCESS%" that specifies what percentage of memory accesses are attributable to each memory area.

Note: numatop records only the memory accesses which have latencies greater than a predefined threshold (128 CPU cycles).

C) Provide the call-chain(s) in the process/thread code that accesses a given hot memory area.

D) Provide the call-chain(s) when the process/thread generates certain counter events (RMA/LMA/IR/CYCLE). The call-chain(s) helps to locate the source code that generates the events.

RMA: Remote Memory Access.

LMA: Local Memory Access.

IR: Instruction Retired.

CYCLE: CPU cycles.

E) Provide per-node statistics for memory and CPU utilization. A node is: a region of memory in which every byte has the same distance from each CPU.

F) Show, using a user-friendly interface, the list of processes/threads sorted by some metrics (by default, sorted by CPU utilization), with the top process having the highest CPU utilization in the system and the bottom one having the lowest CPU utilization. Users can also use hotkeys to resort the output by these metrics: RMA, LMA, RMA/LMA, CPI, and CPU%.

RMA/LMA: ratio of RMA/LMA.

CPI: CPU cycle per instruction.

CPU%: CPU utilization.

numatop is a GUI tool that periodically tracks and analyzes the NUMA activity of processes and threads and displays useful metrics. Users can scroll up/down by using the up or down key to navigate in the current window and can use several hot keys shown at the bottom of the window, to switch between windows or to change the running state of the tool. For example, hotkey 'R' refreshes the data in the current window.

Below is a detailed description of the various display windows and the data items that they display:

[WIN1 - Monitoring processes and threads]:

Get the locality characterization of all processes. This is the first window upon startup, it's numatop's "Home" window. This window displays a list of processes. The top process has the highest system CPU utilization (CPU%), while the bottom process has the lowest CPU% in the system. Generally, the memory-intensive process is also CPU-intensive, so the processes shown in this window are sorted by CPU% by default. The user can press hotkeys '1', '2', '3', '4', or '5' to resort the output by "RMA", "LMA", "RMA/LMA", "CPI", or "CPU%".

[KEY METRICS]:

RMA(K): number of Remote Memory Access (unit is 1000).

RMA(K) = RMA / 1000;

LMA(K): number of Local Memory Access (unit is 1000).

LMA(K) = LMA / 1000;

RMA/LMA: ratio of RMA/LMA.

CPI: CPU cycles per instruction.

CPU%: system CPU utilization (busy time across all CPUs).

[HOTKEY]:

Q: Quit the application.

H: WIN1 refresh.

R: Refresh to show the latest data.

I: Switch to WIN2 to show the normalized data.

N: Switch to WIN11 to show the per-node statistics.

1: Sort by RMA.

2: Sort by LMA.

3: Sort by RMA/LMA.

4: Sort by CPI.

5: Sort by CPU%

[WIN2 - Monitoring processes and threads (normalized)]:

Get the normalized locality characterization of all processes.

[KEY METRICS]:

RPI(K): RMA normalized by 1000 instructions.

RPI(K) = RMA / (IR / 1000);

LPI(K): LMA normalized by 1000 instructions.

LPI(K) = LMA / (IR / 1000);

Other metrics remain the same.

[HOTKEY]:

Q: Quit the application.

H: Switch to WIN1.

B: Back to previous window.

R: Refresh to show the latest data.

N: Switch to WIN11 to show the per-node statistics.

1: Sort by RPI.

2: Sort by LPI.

3: Sort by RMA/LMA.

4: Sort by CPI.

5: Sort by CPU%

[WIN3 - Monitoring the process]:

Get the locality characterization with node affinity of a specified process.

[KEY METRICS]:

NODE: the node ID.

CPU%: per-node CPU utilization.

Other metrics remain the same.

[HOTKEY]:

Q: Quit the application.

H: Switch to WIN1.

B: Back to previous window.

R: Refresh to show the latest data.

N: Switch to WIN11 to show the per-node statistics.

L: Show the latency information.

C: Show the call-chain.

[WIN4 - Monitoring all threads]:

Get the locality characterization of all threads in a specified process.

[KEY METRICS]:

CPU%: per-CPU CPU utilization.

Other metrics remain the same.

[HOTKEY]:

Q: Quit the application.

H: Switch to WIN1.

B: Back to previous window.

R: Refresh to show the latest data.

N: Switch to WIN11 to show the per-node statistics.

[WIN5 - Monitoring the thread]:

Get the locality characterization with node affinity of a specified thread.

[KEY METRICS]:

CPU%: per-CPU CPU utilization.

Other metrics remain the same.

[HOTKEY]:

Q: Quit the application.

H: Switch to WIN1.

B: Back to previous window.

R: Refresh to show the latest data.

N: Switch to WIN11 to show the per-node statistics.

L: Show the latency information.

C: Show the call-chain.

[WIN6 - Monitoring memory areas]:

Get the memory area use with the associated accessing latency of a specified process/thread.

[KEY METRICS]:

ADDR: starting address of the memory area.

SIZE: size of memory area (K/M/G bytes).

ACCESS%: percentage of memory accesses are to this memory area.

LAT(ns): the average latency (nanoseconds) of memory accesses.

DESC: description of memory area (from /proc/<pid>/maps).

[HOTKEY]:

Q: Quit the application.

H: Switch to WIN1.

B: Back to previous window.

R: Refresh to show the latest data.

A: Show the memory access node distribution.

C: Show the call-chain when process/thread accesses the memory area.

[WIN7 - Memory access node distribution overview]:

Get the percentage of memory accesses originated from the process/thread to each node.

[KEY METRICS]:

NODE: the node ID.

ACCESS%: percentage of memory accesses are to this node.

LAT(ns): the average latency (nanoseconds) of memory accesses to this node.

[HOTKEY]:

Q: Quit the application.

H: Switch to WIN1.

B: Back to previous window.

R: Refresh to show the latest data.

[WIN8 - Break down the memory area into physical memory on node]:

Break down the memory area into the physical mapping on node with the associated accessing latency of a process/thread.

[KEY METRICS]:

NODE: the node ID.

Other metrics remain the same.

[HOTKEY]:

Q: Quit the application.

H: Switch to WIN1.

B: Back to previous window.

R: Refresh to show the latest data.

[WIN9 - Call-chain when process/thread generates the event ("RMA"/"LMA"/"CYCLE"/"IR")]:

Determine the call-chains to the code that generates "RMA"/"LMA"/"CYCLE"/"IR".

[KEY METRICS]:

Call-chain list: a list of call-chains.

[HOTKEY]:

Q: Quit the application.

H: Switch to WIN1.

B: Back to the previous window.

R: Refresh to show the latest data.

1: Locate call-chain when process/thread generates "RMA"

2: Locate call-chain when process/thread generates "LMA"

3: Locate call-chain when process/thread generates "CYCLE" (CPU cycle)

4: Locate call-chain when process/thread generates "IR" (Instruction Retired)

[WIN10 - Call-chain when process/thread access the memory area]:

Determine the call-chains to the code that references this memory area. The latency must be greater than the predefined latency threshold (128 CPU cycles).

[KEY METRICS]:

Call-chain list: a list of call-chains.

Other metrics remain the same.

[HOTKEY]:

Q: Quit the application.

H: Switch to WIN1.

B: Back to previous window.

R: Refresh to show the latest data.

[WIN11 - Node Overview]:

Show the basic per-node statistics for this system

[KEY METRICS]:

MEM.ALL: total usable RAM (physical RAM minus a few reserved bits and the kernel binary code).

MEM.FREE: sum of LowFree + HighFree (overall stat) .

CPU%: per-node CPU utilization.

Other metrics remain the same.

[WIN12 - Information of Node N]:

Show the memory use and CPU utilization for the selected node.

[KEY METRICS]:

CPU: array of logical CPUs which belong to this node.

CPU%: per-node CPU utilization.

MEM active: the amount of memory that has been used more recently and is not usually reclaimed unless absolute necessary.

MEM inactive: the amount of memory that has not been used for a while and is eligible to be swapped to disk.

Dirty: the amount of memory waiting to be written back to the disk.

Writeback: the amount of memory actively being written back to the disk.

Mapped: all pages mapped into a process.

[HOTKEY]:

Q: Quit the application.

H: Switch to WIN1.

B: Back to previous window.

R: Refresh to show the latest data.

## OPTIONS
The following options are supported by numatop:

-s sampling_precision

normal: balance precision and overhead (default)

high: high sampling precision (high overhead)

low: low sampling precision, suitable for high load system

-l log_level

Specifies the level of logging in the log file. Valid values are:

1: unknown (reserved for future use)

2: all

-f log_file

Specifies the log file where output will be written. If the log file is not writable, the tool will prompt "Cannot open '<file name>' for writting.".

-d dump_file

Specifies the dump file where the screen data will be written. Generally the dump file is used for automated test. If the dump file is not writable, the tool will prompt "Cannot open <file name> for dump writing."

-h Displays the command's usage.

-t duration

Specifies run time duration in seconds.

## EXAMPLES
Example 1: Launch numatop with high sampling precision

numatop -s high

Example 2: Write all warning messages in /tmp/numatop.log

numatop -l 2 -o /tmp/numatop.log

Example 3: Dump screen data in /tmp/dump.log

numatop -d /tmp/dump.log

## EXIT STATUS
0: successful operation.

Other value: an error occurred.

## USAGE
You must have root privileges to run numatop.

Or set -1 in /proc/sys/kernel/perf_event_paranoid

Note: The perf_event_paranoid setting has security implications and a non-root user probably doesn't have authority to access /proc. It is highly recommended that the user runs numatop as root.

## VERSION
numatop requires a patch set to support PEBS Load Latency functionality in the kernel. The patch set has not been integrated in 3.8. Probably it will be integrated in 3.9. The following steps show how to get and apply the patch set.

1. git clone git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git

2. cd tip

3. git checkout perf/x86

4. build kernel as usual

numatop supports the Intel Xeon processors: 5500-series, 6500/7500-series, 5600 series, E7-x8xx-series, and E5-16xx/24xx/26xx/46xx-series. Note: CPU microcode version 0x618 or 0x70c or later is required on E5-16xx/24xx/26xx/46xx-series. It also supports IBM Power8, Power9, Power10 and Power11 processors.


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/