NetworkManager-dispatcher

title: NetworkManager-dispatcher(8)

text:
# NetworkManager-dispatcher(8)

## NAME
NetworkManager-dispatcher - Dispatch user scripts for NetworkManager

## SYNOPSIS
NetworkManager [OPTIONS...]

## DESCRIPTION
NetworkManager-dispatcher service is a D-Bus activated service that runs user provided scripts upon certain changes in NetworkManager.

NetworkManager-dispatcher will execute scripts in the /{etc,usr/lib}/NetworkManager/dispatcher.d directory or subdirectories in alphabetical order in response to network events. Files in /etc take precedence over identically-named files in /usr/lib. Each script should be a regular executable file owned by root. Furthermore, it must not be writable by group or other, and not setuid.

Each script receives two arguments, the first being the interface name of the device an operation just happened on, and second the action. For device actions, the interface is the name of the kernel interface suitable for IP configuration. Thus it is either VPN_IP_IFACE, DEVICE_IP_IFACE, or DEVICE_IFACE, as applicable. For the hostname action the device name is always "none". For connectivity-change and dns-change it is empty.

The actions are:

pre-up

The interface is connected to the network but is not yet fully activated. Scripts acting on this event must be placed or symlinked into the /etc/NetworkManager/dispatcher.d/pre-up.d directory, and NetworkManager will wait for script execution to complete before indicating to applications that the interface is fully activated.

up

The interface has been activated.

pre-down

The interface will be deactivated but has not yet been disconnected from the network. Scripts acting on this event must be placed or symlinked into the /etc/NetworkManager/dispatcher.d/pre-down.d directory, and NetworkManager will wait for script execution to complete before disconnecting the interface from its network. Note that this event is not emitted for forced disconnections, like when carrier is lost or a wireless signal fades. It is only emitted when there is an opportunity to cleanly handle a network disconnection event.

down

The interface has been deactivated.

vpn-pre-up

The VPN is connected to the network but is not yet fully activated. Scripts acting on this event must be placed or symlinked into the /etc/NetworkManager/dispatcher.d/pre-up.d directory, and NetworkManager will wait for script execution to complete before indicating to applications that the VPN is fully activated.

vpn-up

A VPN connection has been activated.

vpn-pre-down

The VPN will be deactivated but has not yet been disconnected from the network. Scripts acting on this event must be placed or symlinked into the /etc/NetworkManager/dispatcher.d/pre-down.d directory, and NetworkManager will wait for script execution to complete before disconnecting the VPN from its network. Note that this event is not emitted for forced disconnections, like when the VPN terminates unexpectedly or general connectivity is lost. It is only emitted when there is an opportunity to cleanly handle a VPN disconnection event.

vpn-down

A VPN connection has been deactivated.

hostname

The system hostname has been updated. Use gethostname(2) to retrieve it. The interface name (first argument) is empty and no environment variable is set for this action.

dhcp4-change

The DHCPv4 lease has changed (renewed, rebound, etc).

dhcp6-change

The DHCPv6 lease has changed (renewed, rebound, etc).

connectivity-change

The network connectivity state has changed (no connectivity, went online, etc).

reapply

The connection was reapplied on the device.

dns-change

The DNS configuration has changed. This action is raised even if NetworkManager is configured to not manage resolv.conf (for example, via dns=none). In such case, the dispatch script can discover the DNS configuration provided by currently active connections by looking at file /run/NetworkManager/resolv.conf

device-add

This action is called when a connection of type generic has the generic.device-handler property set. The property indicates the name of a dispatcher script to be executed in directory /{etc,usr/lib}/NetworkManager/dispatcher.d/device. Note that differently from other actions, only one script is executed. The script needs to perform any action needed to create the device for the generic connection. On successful termination, the script returns zero. Otherwise, it returns a non-zero value to indicate an error. The script can return values to NetworkManager by writing to standard output; each line should contain a key name followed by the equal sign '=' and a key value. The keys understood at the moment are:

IFINDEX

Indicates the interface index of the interface created by the script. This key is required when the script succeeds; if it is not set, the activation will fail. The key is ignored in case of script failure.

ERROR

Specifies an error message indicating the cause of the script failure. It is ignored when the script succeeds.

Since the dispatcher service captures stdout for parsing those keys, anything written to stdout will not appear in the dispatcher service journal log. Use stderr if you want to print messages to the journal (for example, for debugging). Only the first 8KiB of stdout are considered and among those, only the first 64 lines; the rest is ignored.

device-delete

This action is the counterpart of device-add and is called to delete the device for a generic connection. All the aspects described for device-add also apply to this action, with the only exception that key IFINDEX is ignored. It is not necessary to delete the kernel link in the handler because NetworkManager already does that; therefore the action is useful for any additional cleanup needed.

The environment contains more information about the interface and the connection. The following variables are available for the use in the dispatcher scripts:

NM_DISPATCHER_ACTION

The dispatcher action like "up" or "dhcp4-change", identical to the first command line argument. Since NetworkManager 1.12.0.

CONNECTION_UUID

The UUID of the connection profile.

CONNECTION_ID

The name (ID) of the connection profile.

CONNECTION_DBUS_PATH

The NetworkManager D-Bus path of the connection.

CONNECTION_FILENAME

The backing file name of the connection profile (if any).

CONNECTION_EXTERNAL

If "1", this indicates that the connection describes a network configuration created outside of NetworkManager.

DEVICE_IFACE

The interface name of the control interface of the device. Depending on the device type, this differs from DEVICE_IP_IFACE. For example for ADSL devices, this could be 'atm0' or for WWAN devices it might be 'ttyUSB0'.

DEVICE_IP_IFACE

The IP interface name of the device. This is the network interface on which IP addresses and routes will be configured.

IP4_ADDRESS_N

The IPv4 address in the format "address/prefix gateway", where N is a number from 0 to (# IPv4 addresses - 1). gateway item in this variable is deprecated, use IP4_GATEWAY instead.

IP4_NUM_ADDRESSES

The variable contains the number of IPv4 addresses the script may expect.

IP4_GATEWAY

The gateway IPv4 address in traditional numbers-and-dots notation.

IP4_ROUTE_N

The IPv4 route in the format "address/prefix next-hop metric", where N is a number from 0 to (# IPv4 routes - 1).

IP4_NUM_ROUTES

The variable contains the number of IPv4 routes the script may expect.

IP4_NAMESERVERS

The variable contains a space-separated list of the DNS servers.

IP4_DOMAINS

The variable contains a space-separated list of the search domains.

DHCP4_<dhcp-option-name>

If the connection used DHCP for address configuration, the received DHCP configuration is passed in the environment using standard DHCP option names, prefixed with "DHCP4_", like "DHCP4_HOST_NAME=foobar".

IP6_<name> and DHCP6_<name>

The same variables as for IPv4 are available for IPv6, but the prefixes are IP6_ and DHCP6_ instead.

CONNECTIVITY_STATE

The network connectivity state, which can take the values defined by the NMConnectivityState type, from the org.freedesktop.NetworkManager D-Bus API: UNKNOWN, NONE, PORTAL, LIMITED or FULL. Note: this variable will only be set for connectivity-change actions.

In case of VPN, VPN_IP_IFACE is set, and IP4_*, IP6_* variables with VPN prefix are exported too, like VPN_IP4_ADDRESS_0, VPN_IP4_NUM_ADDRESSES.

The content of the user setting for the connection being activated is also passed via environment variables. Each key is stored in a variable with name CONNECTION_USER_ concatenated with the encoding of the key name. The encoding works as follows:

•lowercase letters become uppercase

•uppercase letters are prefixed with an underscore

•numbers do not change

•a dot is replaced with a double underscore

•any other character is encoded with an underscore followed by its 3-digit octal representation

For example, key test.foo-Bar2 is stored in a variable named CONNECTION_USER_TEST__FOO_055_BAR2.

Dispatcher scripts are run one at a time, but asynchronously from the main NetworkManager process, and will be killed if they run for too long. If your script might take arbitrarily long to complete, you should spawn a child process and have the parent return immediately. Scripts that are symbolic links pointing inside the /etc/NetworkManager/dispatcher.d/no-wait.d/ directory are run immediately, without waiting for the termination of previous scripts, and in parallel. Also beware that once a script is queued, it will always be run, even if a later event renders it obsolete. (Eg, if an interface goes up, and then back down again quickly, it is possible that one or more "up" scripts will be run after the interface has gone down.)

## BUGS
Please report any bugs you find in NetworkManager at the NetworkManager issue tracker[1].

## SEE ALSO
NetworkManager home page[2], NetworkManager(8),

## NOTES
1.

NetworkManager issue tracker

https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues

2.

NetworkManager home page

https://networkmanager.dev


NetworkManager-wait-online.service

package: NetworkManager-daemon

title: NetworkManager-wait-online.service(8)

summary: Wait for the network to come online

text:
# NetworkManager-wait-online.service(8)

## NAME
NetworkManager-wait-online.service - Wait for the network to come online

## DESCRIPTION
The NetworkManager-wait-online service is a oneshot systemd service that delays reaching the network-online target until NetworkManager reports that the startup is completed on the D-Bus.

When the system boots, for example, remote mounts defined in /etc/fstab, require that the network is up. For this, these systemd units contain the After=network-online.target setting to order themselves after this target. NetworkManager-wait-online ensures that the network-online target is reached only after the network is available.

Optimally, all services on the host react dynamically to network changes and systemd services do not need to be configured to start after reaching the network-online target. In this case, NetworkManager-wait-online.service has no effect and does not delay the boot time. On the other hand, if you encounter a long boot time due to the delay of NetworkManager-wait-online, investigate the services that require network access and fix them.

Except for the time out value in the NetworkManager-wait-online.service unit, you cannot configure this service. Instead, settings in NetworkManager and the connection profiles affect the behavior:

•Startup is not complete as long as NetworkManager profiles are in an activating state. During boot, NetworkManager starts profiles with the connection.autoconnect=yes setting. If activation fails, NetworkManager retries the activation depending on the value of the connection.autoconnect-retries setting. NetworkManager reports startup complete when all profiles and devices are either activated or in a disconnect state and no further events are expected.

•When a device reaches the activate state depends on its configuration. For example, with a profile that has both IPv4 and IPv6 enabled, by default, NetworkManager considers the device as fully activated already when only one of the address families is ready. The ipv4.may-fail and ipv6.may-fail settings control this behavior. Additionally, the following settings influence when the two address families complete: ipv4.required-timeout, ipv6.required-timeout, ipv4.dhcp-timeout, and ipv6.ra-timeout. For details, see nm-settings-nmcli(5).

•NetworkManager cannot set IP addresses on bridge and bond devices that have ports that do not auto-activate. Because of this configuration error, NetworkManager-wait-online blocks until the service reaches its timeout value.

•Dispatcher scripts for the pre-up event run at a late stage during activation of a profile. These scripts block the activation for when NetworkManager considers the profile fully activated. For details, see NetworkManager-dispatcher(8).

•The property connection.wait-activation-delay adds an additional delay during activation and delays startup complete. This setting works around certain cases where a device is known to not be ready for a certain amount of time.

•The property connection.wait-device-timeout in the connection profiles cause a delay until the waiting devices appear. This is useful if the driver takes a longer time to detect the networking interfaces. This setting is similar to the connection.gateway-ping-timeout property.

•With Wi-Fi devices, NetworkManager needs to wait for the first scan result to know which networks are available. That adds a delay.

•With Ethernet devices, NetworkManager waits for the carrier until the value in [device*].carrier-wait-timeout is reached. This is because some devices take a long time to detect the carrier. Consequently, booting with cable unplugged, unnecessarily delays NetworkManager-wait-online.service.

## BUGS
Please report any bugs in NetworkManager at the NetworkManager issue tracker[1].

## SEE ALSO
NetworkManager home page[2], NetworkManager(8), nm-online(1), the network-online.target description in systemd.special(7)

## NOTES
1.

NetworkManager issue tracker

https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues

2.

NetworkManager home page

https://networkmanager.dev

branch: sisyphus


nm-initrd-generator

title: nm-initrd-generator(8)

text:
# nm-initrd-generator(8)

## NAME
nm-initrd-generator - early boot NetworkManager configuration generator

## SYNOPSIS
nm-initrd-generator [OPTIONS...] -- [CMDLINE...]

## DESCRIPTION
nm-initrd-generator scans the command line for options relevant to network configuration and creates configuration files for an early instance of NetworkManager run from the initial ramdisk during early boot.

## OPTIONS
-c | --connections-dir path

Output connection directory.

-p | --persistent-connections-dir path

Persistent connection directory. If it exists, rd.neednet will not cause a default connection to be generated in absence of other options.

-i | --initrd-data-dir path

Output directory for initrd data (e.g. hostname).

-d | --sysfs-dir path

The sysfs mount point.

-r | --run-config-dir path

Output directory for config files.

-s | --stdout

Dump connections to standard output. Useful for debugging.

CMDLINE

The options that appear on the kernel command line. The following options are recognized: ip

rd.route

bridge

bond

team

vlan

ib.pkey

bootdev

nameserver

net.ifnames

rd.peerdns

rd.iscsi.ibft

rd.nvmf.nonbft

rd.bootif

rd.neednet

rd.ethtool

rd.net.dns

rd.net.dns-backend

rd.net.dns-resolve-mode

rd.net.timeout.dhcp

rd.net.dhcp.client-id

rd.net.dhcp.retry

rd.net.dhcp.vendor-class

rd.net.dhcp.dscp

rd.net.timeout.carrier

rd.znet

rd.znet_ifname

BOOTIF

Please consult the dracut.cmdline(7) manual for the documentation of the precise format of the values supported.

## DIFFERENCES FROM THE NETWORK-LEGACY DRACUT MODULE
nm-initrd-generator generates a set of connections that are then configured by the NetworkManager instance running in the initrd. There are some differences in behavior compared to the network-legacy dracut module:

•When an interface is configured with a static address and a gateway, the network-legacy module waits that the gateway responds to arping requests before proceeding, while NetworkManager doesn't.

•network-legacy configures interfaces one by one in the order in which they are announced by udev. If multiple interfaces specify a hostname (from command line or from DHCP), the one from the last interface activated wins. With NetworkManager, hostnames from command line have higher precedence over ones from DHCP, and the last that appears in the command line wins.

•NetworkManager supports the ib.pkey=PARENT.PKEY argument to set up an Infiniband partition on IPoIB parent device PARENT using the specified partition key PKEY. The partition key must be in hexadecimal notation without leading "0x", for example "ib.pkey=ib0.8004".

•NetworkManager supports the rd.ethtool=INTERFACE:AUTONEG:SPEED kernel command line option to set up ethtool NIC configuration parameters AUTONEG and SPEED. The INTERFACE being configured must be specified, and the other parameters are optional and can be left blank. When SPEED is set, duplex mode is automatically set to 'full'. INTERFACE accepts string values, AUTONEG accepts boolean values (true and false / on or off / 0 or 1), and SPEED accepts positive integer values.

•NetworkManager supports the rd.net.dns-backend=VALUE kernel command line option to configure the DNS processing mode. See the description of the "dns" key in the "main section" paragraph of NetworkManager.conf(5). For example: rd.net.dns-backend=systemd-resolved, rd.net.dns-backend=dnsconfd

•NetworkManager supports the rd.net.dns=SERVER kernel command line option to configure a global (non interface-specific) DNS server. The option can be specified multiple time to add more than one server. Each server can be specified as a plain IP or as an URI according to the description in the "global-dns-domains sections" paragraph of NetworkManager.conf(5). For example: rd.net.dns=2001:db8::1, rd.net.dns=dns+tls://192.0.2.0, rd.net.dns=dns+tls://[2001:db8::2]:5353#example.org. In addition, it supports configuring the "resolve-mode" key in the global DNS configuration via the rd.net.dns-resolve-mode command line option.

•NetworkManager supports the rd.net.dhcp.dscp={CS0|CS4|CS6} kernel command line option to set a specific DSCP (TOS) value in the IP header of DHCP messages.

•NetworkManager supports the rd.net.dhcp.client-id=interface:client-id kernel command line option to set a specific DHCPv4 client identifier for the given interface. The client-id can be specified either as a sequence of bytes in hexadecimal format separated by dashes, or as the character '@' followed by a non-empty string. When using the second format, NetworkManager prepends a zero byte to the given string, according to section 9.14 of RFC 2132. See the "ipv4.dhcp-client-id" section of nm-settings-nmcli(5) for more details. Examples: rd.net.dhcp.client-id=eth0:01-52-54-00-45-87-42, rd.net.dhcp.client-id=enp1s0:@example.com.

## EXIT STATUS
nm-initrd-generator exits with status 0. It ignores unrecognized options and prints an error message if it encounters a malformed option.

## SEE ALSO
dracut.cmdline(7), NetworkManager(8), nm-settings-nmcli(5).


accton

package: acct

title: accton(8)

summary: turns process accounting on or off

text:
# accton(8)

## NAME
accton - turns process accounting on or off

## SYNOPSIS
accton

[OPTION] on|off|filename

accton

[ -V | --version ] [ -h | --help ]

## DESCRIPTION
accton filename turns on process accounting.

## OPTIONS
-V, --version

Print the version number of accton to standard output and quit.

-h, --help

Prints the usage string and default locations of system files to standard output and exits.

on

Turns on process accounting using the default accounting file name.

off

Turns off process accounting.

## FILES
acct

The system wide process accounting file. See acct(5) for further details.

## AUTHOR
The GNU accounting utilities were written by Noel Cragg <noel@gnu.ai.mit.edu>. The man page was adapted from the accounting texinfo page by Susan Kleinmann <sgk@sgk.tiac.net>.

## SEE ALSO
ac(1), last(1), lastcomm(1), acct(2), acct(5), sa(8).


dump-acct

title: dump-acct(8)

text:
# dump-acct(8)

## NAME
dump-acct - print an acct file in human-readable format.

## SYNOPSIS
dump-acct [-r|--reverse] [-R|--raw] [--format] version] [--byteswap] [--ahz] hertz] [-n|--num recs] [-h|--help] [ files]

## DESCRIPTION
dump-acct filename prints a list of all executed processes. This list is written by the kernel which must be compiled with BSD process accounting enabled (Debian kernel image have it already enabled). It must be started with accton(5). Note that on Debian systems, this is ensured via the init script /etc/init.d/acct.

All fields are separated by vertical line. Fields are: command, version, user time, system time, effective time, uid, gid, memory, io, pid, ppid, time. User, system and effective times are ticks per second. One tick is usually 1/50 of a second. The time field shows the start time of the process.

The --raw switch, as well as the --format, --byteswap, and --ahz can be used as a handy format converter.

## OPTIONS
-h, --help

Prints the usage string and default locations of system files to standard output and exits.

-n, --num recs

Number of lines to print.

-r, --reverse

Start printing from last records.

-R, --raw

Print raw records, not human-readable.

--format version

Use specified format version to display records.

--byteswap

Swap bytes endianness when reading records.

--ahz

Use specified units of time to display data from other kernel versions and architectures.

## FILES
acct

The system wide process accounting file. See acct(5) for further details.

## SEE ALSO
acct(5), ac(8).

## AUTHOR
The GNU accounting utilities were written by Noel Cragg <noel@gnu.ai.mit.edu>.

This manual page was written by Ognyan Kulev <ogi@fmi.uni-sofia.bg> and updated by Daniel Baumann <daniel@debian.org> and Mathieu Trudel <mathieu.tl@gmail.com> for the Debian project (but may be used by others).


dump-utmp

title: dump-utmp(8)

text:
# dump-utmp(8)

## NAME
dump-utmp - print a utmp file in human-readable format

## SYNOPSIS
dump-utmp [-hrR] [-n <recs>] <files>

[--num <recs>] [--raw] [--reverse] [--help]

## OPTIONS
The following options are supported:

-h, --help

Print a help message and the default location of the process accounting file and exit.

-r, --reverse

Print the output in reverse order.

-R, --raw

The records will be printed without any parsing.

-n, --num NUMRECS

Display only the first NUMRECS number of records.

## SEE ALSO
accton (8), lastcomm (1), utmp (5)


sa

title: sa(8)

summary: summarizes accounting information

text:
# sa(8)

## NAME
sa - summarizes accounting information

## SYNOPSIS
sa

[ -a | --list-all-names ]

[ -b | --sort-sys-user-div-calls ]

[ -c | --percentages ] [ -d | --sort-avio ]

[ -D | --sort-tio ] [ -f | --not-interactive ]

[ -i | --dont-read-summary-files ]

[ -j | --print-seconds ] [ -k | --sort-cpu-avmem ]

[ -K | --sort-ksec ] [ -l | --separate-times ]

[ -m | --user-summary ] [ -n | --sort-num-calls ]

[ -p | --show-paging ] [ -P | --show-paging-avg ]

[ -r | --reverse-sort ] [ -s | --merge ]

[ -t | --print-ratio ] [ -u | --print-users ]

[ -v num | --threshold num ] [ --sort-real-time ]

[ --debug ] [ -V | --version ] [ -h | --help ]

[ --other-usracct-file filename ]

[ --other-savacct-file filename ]

[ [ --other-acct-file ] filename ] [ --ahz hz ]

## DESCRIPTION
sa summarizes information about previously executed commands as recorded in the acct file. In addition, it condenses this data into a summary file named savacct which contains the number of times the command was called and the system resources used. The information can also be summarized on a per-user basis; sa will save this information into a file named usracct.

If no arguments are specified, sa will print information about all of the commands in the acct file.

If called with a file name as the last argument, sa will use that file instead of the system's default acct file.

By default, sa will sort the output by sum of user and system time. If command names have unprintable characters, or are only called once, sa will sort them into a group called `***other'. If more than one sorting option is specified, the list will be sorted by the one specified last on the command line.

The output fields are labeled as follows:

cp

sum of system and user CPU time in minutes (unless -j or --print-seconds is specified)

re

elapsed time in minutes (unless -j or --print-seconds is specified)

k

CPU time averaged core usage, in 1k units

avio

average number of I/O operations per execution

tio

total number of I/O operations

k*sec

CPU storage integral (kilo-core seconds)

u

user CPU time in minutes (unless -j or --print-seconds is specified)

s

system CPU time in minutes (unless -j or --print-seconds is specified)

Note that these column titles do not appear in the first row of the table, but after each numeric entry (as units of measurement) in every row. For example, you might see `79.29re', meaning 79.29 minutes or seconds of elapsed time.

An asterisk will appear after the name of commands that forked but didn't do exec.

GNU sa takes care to implement a number of features not found in other versions. For example, most versions of sa don't pay attention to flags like `--print-seconds' and `--sort-num-calls' when combined with the `--user-summary' or `--print-users' flags. GNU sa pays attention to these flags if they are applicable. Also, MIPS' sa stores the average memory use as a short rather than a double, resulting in some round-off errors. GNU sa uses double the whole way through.

## OPTIONS
The availability of these program options depends on your operating system. In specific, the members that appear in the struct acct of your system's process accounting header file (usually acct.h) determine which flags will be present. For example, if your system's struct acct doesn't have the `ac_mem' field, the installed version of sa will not support the `--sort-cpu-avmem', `--sort-ksec', `-k', or `-K' options.

In short, all of these flags may not be available on your machine.

-a, --list-all-names

Force sa not to sort those command names with unprintable characters and those used only once into the ***other group.

-b, --sort-sys-user-div-calls

Sort the output by the sum of user and system time divided by the number of calls.

-c, --percentages

Print percentages of total time for the command's user, system, and real time values.

-d, --sort-avio

Sort the output by the average number of disk I/O operations.

-D, --sort-tio

Print and sort the output by the total number of disk I/O operations.

-f, --not-interactive

When using the `--threshold' option, assume that all answers to interactive queries will be affirmative.

-i, --dont-read-summary-files

Don't read the information in the system's default savacct file.

-j, --print-seconds

Instead of printing total minutes for each category, print seconds per call.

-k, --sort-cpu-avmem

Sort the output by CPU time averaged memory usage.

-K, --sort-ksec

Print and sort the output by the CPU-storage integral.

-l, --separate-times

Print separate columns for system and user time; usually the two are added together and listed as `cp'.

-m, --user-summary

Print the number of processes and number of CPU minutes on a per-user basis.

-n, --sort-num-calls

Sort the output by the number of calls. This is the default sorting method.

-p, --show-paging

Print the number of minor and major pagefaults and swaps.

-P, --show-paging-avg

Print the number of minor and major pagefaults and swaps divided by the number of calls.

-r, --reverse-sort

Sort output items in reverse order.

-s, --merge

Merge the summarized accounting data into the summary files savacct and usracct.

-t, --print-ratio

For each entry, print the ratio of real time to the sum of system and user times. If the sum of system and user times is too small to report, `*ignore*' will appear in this field.

-u, --print-users

For each command in the accounting file, print the userid and command name. After printing all entries, quit. *Note*: this flag supersedes all others.

-v num, --threshold num

Print commands which were executed num times or fewer and await a reply from the terminal. If the response begins with `y', add the command to the `**junk**' group.

--separate-forks

It really doesn't make any sense to me that the stock version of sa separates statistics for a particular executable depending on whether or not that command forked. Therefore, GNU sa lumps this information together unless this option is specified.

--sort-real-time

Sort the output by the real time field.

--debug

Print verbose internal information.

-V, --version

Print the version number of sa.

-h, --help

Prints the usage string and default locations of system files to standard output and exits.

--other-usracct-file filename

Write summaries by user ID to filename rather than the system's default usracct file.

--other-savacct-file filename

Write summaries by command name to filename rather than the system's default savacct file.

--other-acct-file filename

Read from the file filename instead of the system's default pacct file.

--ahz hz

Use this flag to tell the program what AHZ should be (in hertz). This option is useful if you are trying to view an acct file created on another machine which has the same byte order and file format as your current machine, but has a different value for AHZ.

## FILES
acct

The raw system wide process accounting file. See acct(5) for further details.

savacct

A summary of system process accounting sorted by command.

usracct

A summary of system process accounting sorted by user ID.

## BUGS
There is not yet a wide experience base for comparing the output of GNU sa with versions of sa in many other systems. The problem is that the data files grow big in a short time and therefore require a lot of disk space.

## AUTHOR
The GNU accounting utilities were written by Noel Cragg <noel@gnu.ai.mit.edu>. The man page was adapted from the accounting texinfo page by Susan Kleinmann <sgk@sgk.tiac.net>.

## SEE ALSO
ac(1), last(1), lastcomm(1), acct(5), accton(8).


acmed

package: acmed

title: acmed(8)

summary: ACME client daemon

text:
# acmed(8)

## NAME
acmed — ACME client daemon

## SYNOPSIS
acmed

[-c|--config FILE] [-f|--foreground] [-h|--help] [--log-stderr] [--log-syslog] [--log-level LEVEL] [--no-pid-file] [--pid-file FILE] [--root-cert FILE] [-V|--version]

## DESCRIPTION
acmed is an Automatic Certificate Management Environment (ACME) client daemon which can automatically request and renew X.509 security certificates from various Certification Authorities (CA).

The options are as follows:

-c, --config FILE

Specify an alternative configuration file.

-f, --foreground

Runs in the foreground

-h, --help

Prints help information

--log-stderr

Prints log messages to the standard error output

--log-syslog

Sends log messages via syslog

--log-level LEVEL

Specify the log level. Possible values: error, warn, info, debug and trace.

--no-pid-file

Do not create any PID file

--pid-file FILE

Specifies the location of the PID file

--root-cert FILE

Add a root certificate to the trust store. This option can be used multiple times.

-V, --version

Prints version information

## FILES
/etc/acmed/acmed.toml

Default acmed configuration file.

## SEE ALSO
acmed.toml(5), tacd(8)

## STANDARDS

- R. Barnes, J. Hoffman-Andrews, D. McCarney, and J. Kasten, Automatic Certificate Management Environment (ACME), RFC 8555, March 2019.

- R.B. Shoemaker, Automated Certificate Management Environment (ACME) TLS Application-Layer Protocol Negotiation (ALPN) Challenge Extension, RFC 8737, February 2020.

- R.B. Shoemaker, Automated Certificate Management Environment (ACME) IP Identifier Validation Extension, RFC 8738, February 2020.

## AUTHORS
Rodolphe Bréard ⟨rodolphe@breard.tf⟩


tacd

title: tacd(8)

summary: TLS-ALPN Challenge Daemon

text:
# tacd(8)

## NAME
tacd — TLS-ALPN Challenge Daemon

## SYNOPSIS
tacd

[-e|--acme-ext STRING] [--acme-ext-file FILE] [--crt-digest STRING] [--crt-signature-alg STRING] [-d|--domain STRING] [--domain-file STRING] [-f|--foreground] [-h|--help] [-l|--listen host:port] [--log-stderr] [--log-syslog] [--log-level LEVEL] [--no-pid-file] [--pid-file FILE] [-V|--version]

## DESCRIPTION
tacd is a server that will listen to incoming Transport Layer Security (TLS) connections and, if the acme-tls/1 protocol has been declared during the Application-Layer Protocol Negotiation (ALPN), present a self-signed certificate in order to attempt to solve the TLS-ALPN-01 challenge. It then drops the connection.

In order to generate the self-signed certificate, it is required to specify both the domain name to validate and the acmeIdentifier extension. If one of those values is not specified using the available options, it is read from the standard input. When reading from the standard input, a new line character is expected at the end. In the case both values needs to be read from the standard input, the domain name is read first, then the acmeIdentifier extension.

The options are as follows:

-e, --acme-ext STRING

The acmeIdentifier extension to set in the self-signed certificate.

--acme-ext-file FILE

File from which is read the acmeIdentifier extension to set in the self-signed certificate.

--crt-digest STRING

Set the certificate's digest algorithm. Possible values are:

- sha256

- sha384

- sha512

--crt-signature-alg STRING

Set the certificate's signature algorithm. Possible values depends on the cryptographic library support and can be listed using the --help flag.

-d, --domain STRING

The domain that is being validated.

--domain-file STRING

File from which is read the domain that is being validated.

-f, --foreground

Runs in the foreground.

-h, --help

Prints help information.

-i, --listen host:port | unix:path

Specifies the host and port combination or the unix socket to listen on.

--log-stderr

Prints log messages to the standard error output.

--log-syslog

Sends log messages via syslog.

--log-level LEVEL

Specify the log level. Possible values: error, warn, info, debug and trace.

--no-pid-file

Do not create any PID file

--pid-file FILE

Specifies the location of the PID file.

-V, --version

Prints version information.

## SEE ALSO
acmed.toml(5)

## STANDARDS
R.B. Shoemaker, Automated Certificate Management Environment (ACME) TLS Application-Layer Protocol Negotiation (ALPN) Challenge Extension, RFC 8737, February 2020.

## AUTHORS
Rodolphe Bréard ⟨rodolphe@breard.tf⟩


package: acpid

title: acpi_listen(8)

summary: ACPI event listener

text:
# acpi_listen(8)

## NAME
acpi_listen - ACPI event listener

## SYNOPSIS
acpi_listen [options]

## DESCRIPTION
acpid is the system-wide ACPI event catcher. acpi_listen is a simple shell-friendly tool which connects to acpid and listens for events. When an event occurs, acpi_listen will print it on stdout.

## OPTIONS
-c, --count events

Receive up to a maximum number of ACPI events, then exit.

-s, --socketfile filename

This option changes the name of the UNIX domain socket which acpid opens. Default is /run/acpid.socket.

-t, --time seconds

Listen for the specified time in seconds, before exiting.

-v, --version

Print version information and exit.

-h, --help

Show help and exit.

## FILES
/run/acpid.socket

## BUGS
There are no known bugs. To file bug reports, see AUTHORS below.

## SEE ALSO
acpid(8)

## AUTHORS
Ted Felix (www.tedfelix.com)

Tim Hockin <thockin@hockin.org>

Luca Capello <luca@pca.it>


acpid

title: acpid(8)

text:
# acpid(8)

## NAME
acpid - Advanced Configuration and Power Interface event daemon

## SYNOPSIS
acpid [options]

## DESCRIPTION
acpid is designed to notify user-space programs of ACPI events. acpid should be started during the system boot, and will run as a background process, by default. It will open an events file (/proc/acpi/event by default) and attempt to read whole lines which represent ACPI events. If the events file does not exist, acpid will attempt to connect to the Linux kernel via the input layer and netlink. When an ACPI event is received from one of these sources, acpid will examine a list of rules, and execute the rules that match the event. acpid will ignore all incoming ACPI events if a lock file exists (/var/lock/acpid by default).

Rules are defined by simple configuration files. acpid will look in a configuration directory (/etc/acpi/events by default), and parse all regular files with names that consist entirely of upper and lower case letters, digits, underscores, and hyphens (similar to run-parts(8)) that do not begin with a period ('.') or end with a tilde (~). Each file must define two things: an event and an action. Any blank lines, or lines where the first character is a hash ('#') are ignored. Extraneous lines are flagged as warnings, but are not fatal. Each line has three tokens: the key, a literal equal sign, and the value. The key can be up to 63 characters, and is case-insensitive (but whitespace matters). The value can be up to 511 characters, and is case and whitespace sensitive.

The event value is a regular expression (see regcomp(3)), against which events are matched.

The action value is a commandline, which will be invoked via /bin/sh whenever an event matching the rule in question occurs. The commandline may include shell-special characters, and they will be preserved. The only special characters in an action value are "%" escaped. The string "%e" will be replaced by the literal text of the event for which the action was invoked. This string may contain spaces, so the commandline must take care to quote the "%e" if it wants a single token. The string "%%" will be replaced by a literal "%". All other "%" escapes are reserved, and will cause a rule to not load.

This feature allows multiple rules to be defined for the same event (though no ordering is guaranteed), as well as one rule to be defined for multiple events. To force acpid to reload the rule configuration, send it a SIGHUP.

The pseudo-action <drop> causes the event to be dropped completely and no further processing undertaken; clients connecting via the UNIX domain socket (see below) will not be notified of the event. This may be useful on some machines, such as certain laptops which generate spurious battery events at frequent intervals. The name of this pseudo-action may be redefined with a commandline option.

In addition to rule files, acpid also accepts connections on a UNIX domain socket (/run/acpid.socket by default). Any application may connect to this socket. Once connected, acpid will send the text of all ACPI events to the client. The client has the responsibility of filtering for messages about which it cares. acpid will not close the client socket except in the case of a SIGHUP or acpid exiting.

For faster startup, this socket can be passed in as stdin so that acpid need not create the socket. In addition, if a socket is passed in as stdin, acpid will not daemonize. It will be run in foreground. This behavior is provided to support systemd(1).

acpid will log all of its activities, as well as the stdout and stderr of any actions, to syslog.

All the default files and directories can be changed with commandline options.

## OPTIONS
-c, --confdir directory

This option changes the directory in which acpid looks for rule configuration files. Default is /etc/acpi/events.

-C, --clientmax number

This option changes the maximum number of non-root socket connections which can be made to the acpid socket. Default is 256.

-d, --debug

This option increases the acpid debug level by one.

-e, --eventfile filename

This option changes the event file from which acpid reads events. Default is /proc/acpi/event.

-n, --netlink

This option forces acpid to use the Linux kernel input layer and netlink interface for ACPI events.

-f, --foreground

This option keeps acpid in the foreground by not forking at startup, and makes it log to stderr instead of syslog.

-l, --logevents

This option tells acpid to log information about all events and actions.

-L, --lockfile filename

This option changes the lock file used to stop event processing. Default is /var/lock/acpid.

-g, --socketgroup groupname

This option changes the group ownership of the UNIX domain socket to which acpid publishes events.

-m, --socketmode mode

This option changes the permissions of the UNIX domain socket to which acpid publishes events. Default is 0666.

-s, --socketfile filename

This option changes the name of the UNIX domain socket which acpid opens. Default is /run/acpid.socket.

-S, --nosocket

This option tells acpid not to open a UNIX domain socket. This overrides the -s option, and negates all other socket options.

-p, --pidfile filename

This option tells acpid to use the specified file as its pidfile. If the file exists, it will be removed and over-written. Default is /run/acpid.pid.

-r, --dropaction action

This option defines the pseudo-action which tells acpid to abort all processing of an event, including client notifications. Default is <drop>.

-t, --tpmutefix

This option enables special handling of the mute button for certain ThinkPad models with mute LEDs that get out of sync with the mute state when the mute button is held down. With this option, the mute button will generate the following events in sync with the number of presses (and, by extension, the state of the LED):

button/mute MUTE (key pressed) K

button/mute MUTE (key released) K

-v, --version

Print version information and exit.

-h, --help

Show help and exit.

## EXAMPLE
This example will shut down your system if you press the power button.

Create a file named /etc/acpi/events/power that contains the following:

event=button/power

action=/etc/acpi/power.sh "%e"

Then create a file named /etc/acpi/power.sh that contains the following:

/sbin/shutdown -h now "Power button pressed"

Now, when acpid is running, a press of the power button will cause the rule in /etc/acpi/events/power to trigger the script in /etc/acpi/power.sh. The script will then shut down the system.

## TROUBLESHOOTING
acpid is a simple program that runs scripts in response to ACPI events from the kernel. When there's trouble, the problem is rarely with acpid itself. The following are some suggestions for finding the most common sources of ACPI-related problems.

When troubleshooting acpid, it is important to be aware that other parts of a system might be handling ACPI events. systemd(1) is capable of handling the power switch and various other events that are commonly handled by acpid. See the description of HandlePowerKey in logind.conf(5) for more. Some window managers also take over acpid's normal handling of the power button and other events.

kacpimon(8) can be used to verify that the expected ACPI events are coming in. See the man page for kacpimon(8) for the proper procedure. If the events aren't coming in, you've probably got a kernel driver issue.

If the expected events are coming in, then you'll need to check and see if your window manager is responsible for handling these events. Some are, some aren't. (E.g. in Ubuntu 14.04 (Unity/GNOME), there are settings for the laptop lid in the System Settings > Power > "When the lid is closed" fields.) If your window manager is responsible for handling the problematic event, and you've got it configured properly, then you may have a window manager issue.

Lastly, take a look in /etc/acpi/events (see above). Is there a configuration file in there for the event in question (e.g. /etc/acpi/events/lidbtn for laptop lid open/close events)? Is it properly connected to a script (e.g. /etc/acpi/lid.sh)? Is that script working? It's not unusual for an acpid script to check and see if there is a window manager running, then do nothing if there is. This means it is up to the window manager to handle this event.

## DEPENDENCIES
acpid should work on any linux kernel released since 2003.

## FILES
/proc/acpi/event

/dev/input/event*

/etc/acpi/

/run/acpid.socket

/run/acpid.pid

/var/lock/acpid

## BUGS
There are no known bugs. To file bug reports, see PROJECT WEBSITE below.

## SEE ALSO
regcomp(3) sh(1) socket(2) connect(2) init(1) systemd(1) acpi_listen(8) kacpimon(8)

## PROJECT WEBSITE
http://sourceforge.net/projects/acpid2/

## AUTHORS
Ted Felix <ted@tedfelix.com>

Tim Hockin <thockin@hockin.org>

Andrew Henroid


kacpimon

title: kacpimon(8)

summary: Kernel ACPI Event Monitor

text:
# kacpimon(8)

## NAME
kacpimon - Kernel ACPI Event Monitor

## SYNOPSIS
kacpimon

## DESCRIPTION
kacpimon is a monitor program that connects to three sources of ACPI events:

1. /proc/acpi/event

2. netlink

3. the input layer (/dev/input/event*)

kacpimon then reports on what it sees while it is connected.

Use kacpimon to make sure your kernel is sending acpi-related events via the three sources mentioned above.

Since both acpid(8) and kacpimon connect to the same sources, be sure to stop acpid(8) before running kacpimon. If you are using upstart(7), use initctl(8) to stop acpid(8). If you are using systemd(1), use systemctl(1) to stop acpid(8). If you aren't using either of those, you can try killall(1) to stop acpid(8).

Be sure to run kacpimon as root or else it won't be able to open /proc/acpi/event or the input layer:

sudo kacpimon

If you want to pipe the output of kacpimon to a file, be sure to use the "Esc" key to exit rather than Ctrl-C. Using Ctrl-C will cause output to be lost.

## FILES
/proc/acpi/event

kernel ACPI event file

/dev/input/event*

input layer event files

## SEE ALSO
acpi_listen(8), acpid(8)

## AUTHOR
Ted Felix <www.tedfelix.com>

## TODO
- Make kacpimon something that actually gets installed?

## LICENSE
kacpimon - Kernel ACPI Event Monitor

Copyright (C) 2009-2013 Ted Felix (www.tedfelix.com)

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Or visit www.gnu.org.


adcli

package: adcli

title: adcli(8)

text:
# adcli(8)

## NAME
adcli - Tool for performing actions on an Active Directory domain

## SYNOPSIS
adcli info domain.example.com

adcli join domain.example.com

adcli update

adcli testjoin

adcli create-user [--domain=domain.example.com] user

adcli delete-user [--domain=domain.example.com] user

adcli passwd-user [--domain=domain.example.com] user

adcli create-group [--domain=domain.example.com] user

adcli delete-group [--domain=domain.example.com] user

adcli add-member [--domain=domain.example.com] group user or computer...

adcli remove-member [--domain=domain.example.com] group user...

adcli preset-computer [--domain=domain.example.com] computer...

adcli reset-computer [--domain=domain.example.com] computer

adcli delete-computer [--domain=domain.example.com] computer

adcli show-computer [--domain=domain.example.com] computer

adcli create-msa [--domain=domain.example.com]

## GENERAL OVERVIEW
adcli is a command line tool that can perform actions in an Active Directory domain. Among other things it can be used to join a computer to a domain.

See the various sub commands below. The following global options can be used:

-D, --domain=domain

The domain to connect to. If a domain is not specified, then the domain part of the local computer's host name is used.

-R, --domain-realm=REALM

Kerberos realm for the domain. If not specified, then the upper cased domain name is used.

-S, --domain-controller=server

Connect to a specific domain controller. If not specified, then an appropriate domain controller is automatically discovered.

--use-ldaps

Connect to the domain controller with LDAPS. By default the LDAP port is used and SASL GSS-SPNEGO or GSSAPI is used for authentication and to establish encryption. This should satisfy all requirements set on the server side and LDAPS should only be used if the LDAP port is not accessible due to firewalls or other reasons. Please note that the place where CA certificates can be found to validate the AD DC certificates must be configured in the OpenLDAP configuration file, e.g. /etc/openldap/ldap.conf. As an alternative it can be specified with the help of an environment variable, e.g.

```
$ LDAPTLS_CACERT=/path/to/ad_dc_ca_cert.pem adcli join --use-ldaps -D domain.example.com
...
```

Please see ldap.conf(5) for details.

-C

Use the default Kerberos credential cache to authenticate with the domain.

--login-ccache[=ccache_name]

Use the specified Kerberos credential cache to authenticate with the domain. If no credential cache is specified, the default Kerberos credential cache will be used. Credential caches of type FILE can be given with the path to the file. For other credential cache types, e.g. DIR, KEYRING or KCM, the type must be specified explicitly together with a suitable identifier. Please note that since the ccache_name is optional the =(equal) sign is mandatory. If = is missing the parameter is treated as optionless extra argument. How this is handled depends on the specific sub-command.

-U, --login-user=User

Use the specified user account to authenticate with the domain. If not specified, then the name 'Administrator' will be used.

--no-password

Don't show prompts for or read a password from input.

-W, --prompt-password

Prompt for a password if necessary. This is the default.

--stdin-password

Read a password from stdin input instead of prompting for a password.

-v, --verbose

Run in verbose mode with debug output.

## QUERYING DOMAIN INFORMATION
adcli info displays discovered information about an Active Directory domain or an Active Directory domain controller.

```
$ adcli info domain.example.com
...
```

```
$ adcli info --domain-controller=dc.domain.example.com
...
```

adcli info will output as much information as it can about the domain. The information is designed to be both machine and human readable. The command will exit with a non-zero exit code if the domain does not exist or cannot be reached.

To show domain info for a specific domain controller use the --domain-controller option to specify which domain controller to query.

Use the --verbose option to show details of how the domain is discovered and queried. Many of the global options, in particular authentication options, are not usable with the adcli info command.

## JOINING THE LOCAL MACHINE TO A DOMAIN
adcli join creates a computer account in the domain for the local machine, and sets up a keytab for the machine. It does not configure an authentication service (such as sssd).

```
$ adcli join domain.example.com
Password for Administrator:
```

In addition to the global options, you can specify the following options to control how this operation is done.

-N, --computer-name=computer

The short non-dotted name of the computer account that will be created in the domain. If not specified, then the first portion of the --host-fqdn is used.

-O, --domain-ou=OU=xxx

The full distinguished name of the OU in which to create the computer account. If not specified, then the computer account will be created in a default location.

-H, --host-fqdn=host

Override the local machine's fully qualified domain name. If not specified, the local machine's hostname will be retrieved via gethostname(). If gethostname() only returns a short name getaddrinfo() with the AI_CANONNAME hint is called to expand the name to a fully qualified domain name.

-K, --host-keytab=/path/to/keytab

Specify the path to the host keytab where host credentials will be written after a successful join operation. If not specified, the default location will be used, usually /etc/krb5.keytab.

--login-type={computer|user}

Specify the type of authentication that will be performed before creating the machine account in the domain. If set to 'computer', then the computer must already have a preset account in the domain. If not specified and none of the other --login-xxx arguments have been specified, then will try both 'computer' and 'user' authentication.

--os-name=name

Set the operating system name on the computer account. The default depends on where adcli was built, but is usually something like 'linux-gnu'.

--os-service-pack=pack

Set the operating system service pack on the computer account. Not set by default.

--os-version=version

Set the operating system version on the computer account. Not set by default.

--description=description

Set the description attribute on the computer account. Not set by default.

--service-name=service

Additional service name for a Kerberos principal to be created on the computer account. This option may be specified multiple times.

--user-principal=host/name@REALM

Set the userPrincipalName field of the computer account to this Kerberos principal. If you omit the value for this option, then a principal will be set in the form of host/host.example.com@REALM

--one-time-password

Specify a one time password for a preset computer account. This is equivalent to using --login-type=computer and providing a password as input.

--trusted-for-delegation=yes|no|true|false

Set or unset the TRUSTED_FOR_DELEGATION flag in the userAccountControl attribute to allow or not allow that Kerberos tickets can be forwarded to the host.

--dont-expire-password=yes|no|true|false

Set or unset the DONT_EXPIRE_PASSWORD flag in the userAccountControl attribute to indicate if the machine account password should expire or not. By default adcli will set this flag while joining the domain which corresponds to the default behavior of Windows clients. Please note that if the password will expire (--dont-expire-password=false) a renewal mechanism has to be enabled on the client to not loose the connectivity to AD if the password expires.

--add-service-principal=service/hostname

Add a service principal name. In contrast to the --service-name the hostname part can be specified as well in case the service should be accessible with a different host name as well.

--setattr=name=value

Add the LDAP attribute name with the given value to the new LDAP host object. This option can be used multiple times to add multiple different attributes. Multi-value attributes are currently not supported. Please note that the account used to join the domain must have the required privileges to add the given attributes. Some attributes might have constraints with respect to syntax and allowed values which must be met as well. Attributes managed by other adcli options cannot be set with this option.

--show-details

After a successful join print out information about join operation. This is output in a format that should be both human and machine readable.

--show-password

After a successful join print out the computer machine account password. This is output in a format that should be both human and machine readable.

--add-samba-data

After a successful join add the domain SID and the machine account password to the Samba specific databases by calling Samba's net utility. Please note that Samba's net requires some settings in smb.conf to create the database entries correctly. Most important here is currently the workgroup option, see smb.conf(5) for details.

--samba-data-tool=/path/to/net

If Samba's net cannot be found at /usr/bin/net, this option can be used to specific an alternative location with the help of an absolute path.

--ldap-passwd

Use LDAP add/mod operations to set the machine account password instead of Kerberos. This might help in some situations where Kerberos fails or is unreliable. But please note that 'Change password' or 'Reset password' permissions or similar might be needed to make the LDAP operation work. Additionally there will be no read-only domain controller (RODC) support as there is with Kerberos.

If supported on the AD side the msDS-supportedEncryptionTypes attribute will be set as well. Either the current value or the default list of AD's supported encryption types filtered by the permitted encryption types of the client's Kerberos configuration are written.

## UPDATING THE MACHINE ACCOUNT PASSWORD AND OTHER ATTRIBUTES
adcli update updates the password of the computer account on the domain controller for the local machine, write the new keys to the keytab and removes older keys. It keeps the previous key on purpose because AD will need some time to replicate the new key to all DCs hence the previous key might still be used.

```
$ adcli update
```

If used with a credential cache, other attributes of the computer account can be changed as well if the principal has sufficient privileges.

```
$ kinit Administrator
$ adcli update --login-ccache=/tmp/krbcc_123
```

In addition to the global options, you can specify the following options to control how this operation is done.

-N, --computer-name=computer

The short non-dotted name of the computer account that will be created in the domain. If not specified, it will be retrieved from the keytab entries.

-H, --host-fqdn=host

The local machine's fully qualified domain name. If not specified, the local machine's hostname will be retrieved from the keytab entries.

-K, --host-keytab=/path/to/keytab

Specify the path to the host keytab where current host credentials are stored and the new ones will be written to. If not specified, the default location will be used, usually /etc/krb5.keytab.

--os-name=name

Set the operating system name on the computer account. Not set by default.

--os-service-pack=pack

Set the operating system service pack on the computer account. Not set by default.

--os-version=version

Set the operating system version on the computer account. Not set by default.

--description=description

Set the description attribute on the computer account. Not set by default.

--service-name=service

Additional service name for a Kerberos principal to be created on the computer account. This option may be specified multiple times.

--user-principal=host/name@REALM

Set the userPrincipalName field of the computer account to this Kerberos principal.

--computer-password-lifetime=lifetime

Only update the password of the computer account if it is older than the lifetime given in days. By default the password is updated if it is older than 30 days.

--trusted-for-delegation=yes|no|true|false

Set or unset the TRUSTED_FOR_DELEGATION flag in the userAccountControl attribute to allow or not allow that Kerberos tickets can be forwarded to the host.

--dont-expire-password=yes|no|true|false

Set or unset the DONT_EXPIRE_PASSWORD flag in the userAccountControl attribute to indicate if the machine account password should expire or not. By default adcli will set this flag while joining the domain which corresponds to the default behavior of Windows clients. Please note that if the password will expire (--dont-expire-password=false) a renewal mechanism has to be enabled on the client to not loose the connectivity to AD if the password expires.

--account-disable=yes|no|true|false

Set or unset the ACCOUNTDISABLE flag in the userAccountControl attribute to disable or enable the computer account.

--add-service-principal=service/hostname

Add a service principal name. In contrast to the --service-name the hostname part can be specified as well in case the service should be accessible with a different host name as well.

--remove-service-principal=service/hostname

Remove a service principal name from the keytab and the AD host object.

--setattr=name=value

Add the LDAP attribute name with the given value to the LDAP host object. This option can be used multiple times to add multiple different attributes. Multi-value attributes are currently not supported. Please note that the account used to update the host object must have the required privileges to modify the given attributes. Some attributes might have constraints with respect to syntax and allowed values which must be met as well. Attributes managed by other adcli options cannot be set with this option.

--delattr=name

Remove the LDAP attribute name from the LDAP host object. This option can be used multiple times to remove multiple different attributes. Please note that the account used to update the host object must have the required privileges to delete the given attributes. Attributes managed by other adcli options cannot be removed.

--show-details

After a successful join print out information about join operation. This is output in a format that should be both human and machine readable.

--add-samba-data

After a successful join add the domain SID and the machine account password to the Samba specific databases by calling Samba's net utility. Please note that Samba's net requires some settings in smb.conf to create the database entries correctly. Most important here is currently the workgroup option, see smb.conf(5) for details.

Note that if the machine account password is not older than 30 days, you have to pass --computer-password-lifetime=0 to force the update.

--samba-data-tool=/path/to/net

If Samba's net cannot be found at /usr/bin/net, this option can be used to specific an alternative location with the help of an absolute path.

--ldap-passwd

Use LDAP add/mod operations to set the machine account password instead of Kerberos. This might help in some situations where Kerberos fails or is unreliable. But please note that 'Change password' or 'Rest password' permissions or similar might be needed to make the LDAP operation work. Additionally there will be no read-only domain controller (RODC) support as there is with Kerberos.

If supported on the AD side the msDS-supportedEncryptionTypes attribute will be set as well. Either the current value or the default list of AD's supported encryption types filtered by the permitted encryption types of the client's Kerberos configuration are written.

## TESTING IF THE MACHINE ACCOUNT PASSWORD IS VALID
adcli testjoin uses the current credentials in the keytab and tries to authenticate with the machine account to the AD domain. If this works the machine account password and the join are still valid. If it fails the machine account password or the whole machine account have to be refreshed with adcli join or adcli update.

```
$ adcli testjoin
```

Only the global options not related to authentication are available, additionally you can specify the following options to control how this operation is done.

-K, --host-keytab=/path/to/keytab

Specify the path to the host keytab where current host credentials are stored and the new ones will be written to. If not specified, the default location will be used, usually /etc/krb5.keytab.

## CREATING A USER
adcli create-user creates a new user account in the domain.

```
$ adcli create-user Fry --domain=domain.example.com \
	--display-name="Philip J. Fry" --mail=fry@domain.example.com
```

In addition to the global options, you can specify the following options to control how the user is created.

--display-name="Name"

Set the displayName attribute of the new created user account.

-O, --domain-ou=OU=xxx

The full distinguished name of the OU in which to create the user account. If not specified, then the computer account will be created in a default location.

--mail=email@domain.com

Set the mail attribute of the new created user account. This attribute may be specified multiple times.

--unix-home=/home/user

Set the unixHomeDirectory attribute of the new created user account, which should be an absolute path to the user's home directory.

--unix-gid=111

Set the gidNumber attribute of the new created user account, which should be the user's numeric primary group id.

--unix-shell=/bin/shell

Set the loginShell attribute of the new created user account, which should be a path to a valid shell.

--unix-uid=111

Set the uidNumber attribute of the new created user account, which should be the user's numeric primary user id.

--nis-domain=nis_domain

Set the msSFU30NisDomain attribute of the new created user account, which should be the user's NIS domain is the NIS/YP service of Active Directory's Services for Unix (SFU) are used. This is needed to let the 'UNIX attributes' tab of older Active Directory versions show the set UNIX specific attributes. If not specified adcli will try to determine the NIS domain automatically if needed.

## DELETING A USER
adcli delete-user deletes a user account from the domain.

```
$ adcli delete-user Fry --domain=domain.example.com
```

The various global options can be used.

## (RE)SETTING THE PASSWORD OF A USER WITH AN ADMINISTRATIVE ACCOUNT
adcli passwd-user sets or resets the password of user account. The administrative account used for this operation must have privileges to set a password.

```
$ adcli passwd-user Fry --domain=domain.example.com
```

The various global options can be used.

## CREATING A GROUP
adcli create-group creates a new group in the domain.

```
$ adcli create-group Pilots --domain=domain.example.com \
	--description="Group for all pilots"
```

In addition to the global options, you can specify the following options to control how the group is created.

--description="text"

Set the description attribute of the new created group.

-O, --domain-ou=OU=xxx

The full distinguished name of the OU in which to create the group. If not specified, then the group will be created in a default location.

## DELETING A GROUP
adcli delete-group deletes a group from the domain.

```
$ adcli delete-group Pilots --domain=domain.example.com
```

The various global options can be used.

## ADDING A MEMBER TO A GROUP
adcli add-member adds one or more users to a group in the domain. The group is specified first, and then the various users or computers to be added. You must use dollar sign for computer account (computername$)

```
$ adcli add-member --domain=domain.example.com Pilots Leela Scruffy
$ adcli add-member --domain=domain.example.com servers srv-smb$
```

The various global options can be used.

## REMOVING A MEMBER FROM A GROUP
adcli remove-member removes a user from a group in the domain. The group is specified first, and then the various users to be removed.

```
$ adcli remove-member --domain=domain.example.com Pilots Scruffy
```

The various global options can be used.

## PRESET COMPUTER ACCOUNTS
adcli preset-computer pre-creates one or more computer accounts in the domain for machines to later use when joining the domain. By doing this machines can join using a one time password or automatically without a password.

```
$ adcli preset-computer --domain=domain.example.com \
	host1.example.com host2
Password for Administrator:
```

If the computer names specified contain dots, then they are treated as fully qualified host names, otherwise they are treated as short computer names. The computer accounts must not already exist.

In addition to the global options, you can specify the following options to control how this operation is done.

-O, --domain-ou=OU=xxx

The full distinguished name of the OU in which to create the computer accounts. If not specified, then the computer account will be created in a default location.

--one-time-password

Specify a one time password to use when presetting the computer accounts. If not specified, then a default password will be used, which allows for later automatic joins.

--os-name=name

Set the operating system name on the computer account. The default depends on where adcli was built, but is usually something like 'linux-gnu'.

--os-service-pack=pack

Set the operating system service pack on the computer account. Not set by default.

--os-version=version

Set the operating system version on the computer account. Not set by default.

--service-name=service

Additional service name for a Kerberos principal to be created on the computer account. This option may be specified multiple times.

--user-principal

Set the userPrincipalName field of the computer account to this Kerberos principal in the form of host/host.example.com@REALM

## RESET COMPUTER ACCOUNT
adcli reset-computer resets a computer account in the domain. If the appropriate machine is currently joined to the domain, then its membership will be broken. The account must already exist.

```
$ adcli reset-computer --domain=domain.example.com host2
```

If the computer names specified contain dots, then they are treated as fully qualified host names, otherwise they are treated as short computer names.

In addition to the global options, you can specify the following options to control how this operation is done.

--login-type={computer|user}

Specify the type of authentication that will be performed before creating the machine account in the domain. If set to 'computer', then the computer must already have a preset account in the domain. If not specified and none of the other --login-xxx arguments have been specified, then will try both 'computer' and 'user' authentication.

## DELETE COMPUTER ACCOUNT
adcli delete-computer deletes a computer account in the domain. The account must already exist.

```
$ adcli delete-computer --domain=domain.example.com host2
Password for Administrator:
```

If the computer name contains a dot, then it is treated as fully qualified host name, otherwise it is treated as short computer name.

If no computer name is specified, then the host name of the computer adcli is running on is used, as returned by gethostname().

The various global options can be used.

## SHOW COMPUTER ACCOUNT ATTRIBUTES
adcli show-computer show the computer account attributes stored in AD. The account must already exist.

```
$ adcli show-computer --domain=domain.example.com host2
Password for Administrator:
```

If the computer name contains a dot, then it is treated as fully qualified host name, otherwise it is treated as short computer name.

If no computer name is specified, then the host name of the computer adcli is running on is used, as returned by gethostname().

The various global options can be used.

## CREATE A MANAGED SERVICE ACCOUNT
adcli create-msa creates a managed service account (MSA) in the given Active Directory domain. This is useful if a computer should not fully join the Active Directory domain but LDAP access is needed. A typical use case is that the computer is already joined an Active Directory domain and needs access to another Active Directory domain in the same or a trusted forest where the host credentials from the joined Active Directory domain are not valid, e.g. there is only a one-way trust.

```
$ adcli create-msa --domain=domain.example.com
Password for Administrator:
```

The managed service account, as maintained by adcli, cannot have additional service principals names (SPNs) associated with it. An SPN is defined within the context of a Kerberos service which is tied to a machine account in Active Directory. Since a machine can be joined to a single Active Directory domain, managed service account in a different Active Directory domain will not have the SPNs that otherwise are part of another Active Directory domain's machine.

Since it is expected that a client will most probably join to the Active Directory domain matching its DNS domain the managed service account will be needed for a different Active Directory domain and as a result the Active Directory domain name is a mandatory option. If called with no other options adcli create-msa will use the short hostname with an additional random suffix as computer name to avoid name collisions.

LDAP attribute sAMAccountName has a limit of 20 characters. However, machine account's NetBIOS name must be at most 16 characters long, including a trailing '$' sign. Since it is not expected that the managed service accounts created by adcli will be used on the NetBIOS level the remaining 4 characters can be used to add uniqueness. Managed service account names will have a suffix of 3 random characters from number and upper- and lowercase ASCII ranges appended to the chosen short host name, using '!' as a separator. For a host with the shortname 'myhost', a managed service account will have a common name (CN attribute) 'myhost!A2c' and a NetBIOS name (sAMAccountName attribute) will be 'myhost!A2c$'. A corresponding Kerberos principal in the Active Directory domain where the managed service account was created would be 'myhost!A2c$@DOMAIN.EXAMPLE.COM'.

A keytab for the managed service account is stored into a file specified with -K option. If it is not specified, the file is named after the default keytab file, with lowercase Active Directory domain of the managed service account as a suffix. On most systems it would be /etc/krb5.keytab with a suffix of 'domain.example.com', e.g. /etc/krb5.keytab.domain.example.com.

adcli create-msa can be called multiple times to reset the password of the managed service account. To identify the right account with the random component in the name the corresponding principal is read from the keytab. If the keytab got deleted adcli will try to identify an existing managed service account with the help of the fully-qualified name, if this fails a new managed service account will be created.

The managed service account password can be updated with

```
$ adcli update --domain=domain.example.com --host-keytab=/etc/krb5.keytab.domain.example.com
```

and the managed service account can be deleted with

```
$ adcli delete-computer --domain=domain.example.com 'myhost!A2c'
```

In addition to the global options, you can specify the following options to control how this operation is done.

-N, --computer-name=computer

The short non-dotted name of the managed service account that will be created in the Active Directory domain. The long option name --computer-name is kept to underline the similarity with the same option of the other sub-commands. If not specified, then the first portion of the --host-fqdn or its default is used with a random suffix.

-O, --domain-ou=OU=xxx

The full distinguished name of the OU in which to create the managed service account. If not specified, then the managed service account will be created in a default location.

-H, --host-fqdn=host

Override the local machine's fully qualified DNS domain name. If not specified, the local machine's hostname will be retrieved via gethostname(). If gethostname() only returns a short name getaddrinfo() with the AI_CANONNAME hint is called to expand the name to a fully qualified DNS domain name.

-K, --host-keytab=/path/to/keytab

Specify the path to the host keytab where credentials of the managed service account will be written after a successful creation. If not specified, the default location will be used, usually /etc/krb5.keytab with the lower-cased Active Directory domain name added as a suffix e.g. /etc/krb5.keytab.domain.example.com.

--show-details

After a successful creation print out information about the created object. This is output in a format that should be both human and machine readable.

--show-password

After a successful creation print out the managed service account password. This is output in a format that should be both human and machine readable.

## DELEGATED PERMISSIONS
It is common practice in AD to not use an account from the Domain Administrators group to join a machine to a domain but use a dedicated account which only has permissions to join a machine to one or more OUs in the Active Directory tree. Giving the needed permissions to a single account or a group in Active Directory is called Delegation. A typical example on how to configured Delegation can be found in the Delegation section of the blog post Who can add workstation to the domain[1].

When using an account with delegated permissions with adcli basically the same applies as well. However some aspects are explained here in a bit more details to better illustrate different concepts of Active Directory and to make it more easy to debug permissions issues during the join. Please note that the following is not specific to adcli but applies to all applications which would like to modify certain properties or objects in Active Directory with an account with limited permissions.

First, as said in the blog post it is sufficient to have "Create computer object" permissions to join a computer to a domain. But this would only work as expected if the computer object does not exist in Active Directory before the join. Because only when a new object is created Active Directory does not apply additional permission checks on the attributes of the new computer object. This means the delegated user can add any kind of attribute with any value to a new computer object also long as they meet general constraints like e.g. that the attribute must be defined in the schema and is allowed in a objectclass of the object, the value must match the syntax defined in the schema or that the sAMAccountName must be unique in the domain.

If you want to use the account with delegated permission to remove computer objects in Active Directory (adcli delete-computer) you should of course make sure that the account has "Delete computer object" permissions.

If the computer object already exists the "Create computer object" permission does not apply anymore since now an existing object must be modified. Now permissions on the individual attributes are needed. e.g. "Read and write Account Restrictions" or "Reset Password". For some attributes Active Directory has two types of permissions the plain "Read and Write" permissions and the "Validated Write" permissions. For the latter case there are two specific permissions relevant for adcli, namely

•Validated write to DNS host name

•Validated write to service principal name

Details about the validation of the values can be found in the "Validated Writes" section of [MS-ADTS], especially dNSHostName[2] and servicePrincipalName[3]. To cut it short for "Validated write to DNS host name" the domain part of the fully-qualified hostname must either match the domain name of the domain you want to join to or must be listed in the msDS-AllowedDNSSuffixes attribute. And for "Validated write to service principal name" the hostname part of the service principal name must match the name stored in dNSHostName or some other attributes which are not handled by adcli. This also means that dNSHostName cannot be empty or only contain a short name if the service principal name should contain a fully-qualified name.

To summarize, if you only have validated write permissions you should make sure the domain part of the hostname matches the domain you want to join or use the --host-fqdn with a matching name.

The plain read write permissions do not run additional validations but the attribute values must still be in agreement with the general constraints mentioned above. If the computer object already exists adcli might need the following permissions which are also needed by Windows clients to modify existing attributes:

•Reset Password

•Read and write Account Restrictions

•Read and (validated) write to DNS host name

•Read and (validated) write to service principal name

additionally adcli needs

•Read and write msDS-supportedEncryptionTypes

This is added for security reasons to avoid that Active Directory stores Kerberos keys with (potentially weaker) encryption types than the client supports since Active Directory is often configured to still support older (weaker) encryption types for compatibility reasons.

All other attributes are only set or modified on demand, i.e. adcli must be called with an option the would set or modify the given attribute. In the following the attributes adcli can modify together with the required permissions are listed:

•userPrincipalName

•Read/Write userPrincipal Name

•msDS-supportedEncryptionTypes

•Read/Write msDS-SupportedEncryptionTypes

•dNSHostName

•Read/Write dNSHostName

•Read and write DNS host name attributes

•Validated write to DNS host name

•servicePrincipalName

•Read/Write servicePrincipalName

•Validated write to service principal name

•operatingSystem

•Read/Write Operating System

•operatingSystemVersion

•Read/Write Operating System Version

•operatingSystemServicePack

•Read/Write operatingSystemServicePack

•userAccountControl

•Read/Write userAccountControl

•description

•Read/Write Description

For the management of users and groups (adcli create-user, adcli delete-user, adcli create-group, adcli delete-group) the same applies only for different types of objects, i.e. users and groups. Since currently adcli only supports the creation and the removal of user and group objects it is sufficient to have the "Create/Delete User objects" and "Create/Delete Group objects" permissions.

If you want to manage group members as well (adcli add-member, adcli remove-member) "Read/Write Members" permissions are needed as well.

Depending on the version of Active Directory the "Delegation of Control Wizard" might offer some shortcuts for common task like e.g.

•Create, delete and manage user accounts

•Create, delete and manage groups

•Modify the membership of a group

The first 2 shortcuts will provided full access to user and group objects which, as explained above, is more than currently is needed. After using those shortcut it is a good idea to verify in the "Security" tab in the "Properties" of the related Active Directory container that the assigned permissions meet the expectations.

## BUGS
Please send bug reports to either the distribution bug tracker or the upstream bug tracker at https://bugs.freedesktop.org/enter_bug.cgi?product=realmd&component=adcli

## SEE ALSO
realmd(8), net(8), sssd(8)

Further details available in the realmd online documentation at http://www.freedesktop.org/software/realmd/

## NOTES
1.

Who can add workstation to the domain

https://docs.microsoft.com/en-us/archive/blogs/dubaisec/who-can-add-workstation-to-the-domain

2.

dNSHostName

https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-adts/5c578b15-d619-408d-ba17-380714b89fd1

3.

servicePrincipalName

https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-adts/28ca4eca-0e0b-4666-9175-a37ccb8edada


adjtimex

package: adjtimex

title: adjtimex(8)

text:
# adjtimex(8)

## NAME
adjtimex - display or set the kernel time variables

## SYNOPSIS
adjtimex [option]...

## DESCRIPTION
This program gives you raw access to the kernel time variables. Anyone may print out the time variables, but only the superuser may change them.

Your computer has two clocks - the "hardware clock" that runs all the time, and the system clock that runs only while the computer is on. Normally, "hwclock --hctosys" should be run at startup to initialize the system clock. The system clock has much better precision (approximately 1 usec), but the hardware clock probably has better long-term stability. There are three basic strategies for managing these clocks.

For a machine connected to the Internet, or equipped with a precision oscillator or radio clock, the best way is to regulate the system clock with ntpd(8). The kernel will automatically update the hardware clock every eleven minutes.

In addition, hwclock(8) can be used to approximately correct for a constant drift in the hardware clock. In this case, "hwclock --adjust" is run occasionally. hwclock notes how long it has been since the last adjustment, and nudges the hardware clock forward or back by the appropriate amount. The user needs to set the time with "hwclock --set" several times over the course of a few days so hwclock can estimate the drift rate. During that time, ntpd should not be running, or else hwclock will conclude the hardware clock does not drift at all. After you have run "hwclock --set" for the last time, it's okay to start ntpd. Then, "hwclock --systohc" should be run when the machine is shut down. (To see why, suppose the machine runs for a week with ntpd, is shut down for a day, is restarted, and "hwclock --adjust" is run by a startup script. It should only correct for one day's worth of drift. However, it has no way of knowing that ntpd has been adjusting the hardware clock, so it bases its adjustment on the last time hwclock was run.)

For a standalone or intermittently connected machine, where it's not possible to run ntpd, you may use adjtimex instead to correct the system clock for systematic drift.

There are several ways to estimate the drift rate. If your computer can be connected to the net, you might run ntpd for at least several hours and run "adjtimex --print" to learn what values of tick and freq it settled on. Alternately, you could estimate values using as a reference the CMOS clock (see the --compare and --adjust switches), another host (see --host and --review), or some other source of time (see --watch and --review). You could then add a line to rc.local invoking adjtimex, or configure /etc/init.d/adjtimex or /etc/default/adjtimex, to set those parameters each time you reboot.

## OPTIONS
Options may be introduced by either - or --, and unique abbreviations may be used.

Here is a summary of the options, grouped by type. Explanations follow.

Get/Set Kernel Time Parameters

-p --print -t --tick val -f newfreq --frequency newfreq -o val --offset val -s adjustment --singleshot adjustment -S status --status status -m val -R --reset --maxerror val -e val --esterror val -T val --timeconstant val -a[count] --adjust[=count]

Estimate Systematic Drifts

-c[count] --compare[=count] -i tim --interval tim -l file --log file -h timeserver --host timeserver -w --watch -r[file] --review[=file] -u --utc -d --directisa -n --nointerrupt

Informative Output

--help -v --version -V --verbose

-p, --print

Print the current values of the kernel time variables. NOTE: The time is "raw", and may be off by up to one timer tick (10 msec). "status" gives the value of the time_status variable in the kernel. For Linux 1.0 and 1.2 kernels, the value is as follows:

```
      0   clock is synchronized (so the kernel should

          periodically set the CMOS clock to match the

          system clock)

      1   inserting a leap second at midnight

      2   deleting a leap second at midnight

      3   leap second in progress

      4   leap second has occurred

      5   clock not externally synchronized (so the

          kernel should leave the CMOS clock alone)
```

For Linux kernels 2.0 through 2.6, the value is a sum of these:

```
      1   PLL updates enabled

      2   PPS freq discipline enabled

      4   PPS time discipline enabled

      8   frequency-lock mode enabled

     16   inserting leap second

     32   deleting leap second

     64   clock unsynchronized

    128   holding frequency

    256   PPS signal present

    512   PPS signal jitter exceeded

   1024   PPS signal wander exceeded

   2048   PPS signal calibration error

   4096   clock hardware fault
```

-t val, --tick val

Set the number of microseconds that should be added to the system time for each kernel tick interrupt. For a kernel with USER_HZ=100, there are supposed to be 100 ticks per second, so val should be close to 10000. Increasing val by 1 speeds up the system clock by about 100 ppm, or 8.64 sec/day. tick must be in the range 900000/USER_HZ...1100000/USER_HZ. If val is rejected by the kernel, adjtimex will determine the acceptable range through trial and error and print it. (After completing the search, it will restore the original value.)

-f newfreq, --frequency newfreq

Set the system clock frequency offset to newfreq. newfreq can be negative or positive, and gives a much finer adjustment than the --tick switch. When USER_HZ=100, the value is scaled such that newfreq = 65536 speeds up the system clock by about 1 ppm, or .0864 sec/day. Thus, all of these are about the same:

```
     --tick  9995 --frequency  32768000

     --tick 10000 --frequency   6553600

     --tick 10001 --frequency         0

     --tick 10002 --frequency  -6553600

     --tick 10005 --frequency -32768000
```

To see the acceptable range for newfreq, use --print and look at "tolerance", or try an illegal value (e.g. --tick 0).

-s adj, --singleshot adj

Slew the system clock by adj usec. (Its rate is changed temporarily by about 1 part in 2000.)

-o adj, --offset adj

Add a time offset of adj usec. The kernel code adjusts the time gradually by adj, notes how long it has been since the last time offset, and then adjusts the frequency offset to correct for the apparent drift. adj must be in the range -512000...512000.

-S status, --status status

Set kernel system clock status register to value status. Look here above at the --print switch section for the meaning of status, depending on your kernel.

-R, --reset

Reset clock status after setting a clock parameter. For early Linux kernels, using the adjtimex(2) system call to set any time parameter the kernel think the clock is synchronized with an external time source, so it sets the kernel variable time_status to TIME_OK. Thereafter, at 11 minute intervals, it will adjust the CMOS clock to match. We prevent this "eleven minute mode" by setting the clock, because that has the side effect of resetting time_status to TIME_BAD. We try not to actually change the clock setting. Kernel versions 2.0.40 and later apparently don't need this. If your kernel does require it, use this option with: -t -T -t -e -m -f -s -o -c -r.

-m val, --maxerror val

Set maximum error (usec).

-e val, --esterror val

Set estimated error (usec). The maximum and estimated error are not used by the kernel. They are merely made available to user processes via the adjtimex(2) system call.

-T val, --timeconstant val

Set phase locked loop (PLL) time constant. val determines the bandwidth or "stiffness" of the PLL. The effective PLL time constant will be a multiple of (2^val). For room-temperature quartz oscillators, David Mills recommends the value 2, which corresponds to a PLL time constant of about 900 sec and a maximum update interval of about 64 sec. The maximum update interval scales directly with the time constant, so that at the maximum time constant of 6, the update interval can be as large as 1024 sec. Values of val between zero and 2 give quick convergence; values between 2 and 6 can be used to reduce network load, but at a modest cost in accuracy.

-c[count], --compare[=count]

Periodically compare the system clock with the CMOS clock. After the first two calls, print values for tick and frequency offset that would bring the system clock into approximate agreement with the CMOS clock. CMOS clock readings are adjusted for systematic drift using using the correction in /etc/adjtime — see hwclock(8). The interval between comparisons is 10 seconds, unless changed by the --interval switch. The optional argument is the number of comparisons. (If the argument is supplied, the "=" is required.) If the CMOS clock and the system clock differ by more than six minutes, adjtimex will try shifting the time from the CMOS clock by some multiple of one hour, up to plus or minus 13 hours in all. This should allow correct operation, including logging, if the --utc switch was used when the CMOS clock is set to local time (or vice-versa), or if summer time has started or stopped since the CMOS clock was last set.

-a[count], --adjust[=count]

By itself, same as --compare, except the recommended values are actually installed after every third comparison. With --review, the tick and frequency are set to the least-squares estimates. (In the latter case, any count value is ignored.)

--force-adjust

Override the sanity check that prevents changing the clock rate by more than 500 ppm.

-i tim, --interval tim

Set the interval in seconds between clock comparisons for the --compare and --adjust options.

-u, --utc

The CMOS clock is set to UTC (universal time) rather than local time.

-d, --directisa

To read the CMOS clock accurately, adjtimex usually accesses the clock via the /dev/rtc device driver of the kernel, and makes use of its CMOS update-ended interrupt to detect the beginning of seconds. It will also try /dev/rtc0 (for udev), /dev/misc/rtc (for the obsolete devfs) and possibly others. When the /dev/rtc driver is absent, or when the interrupt is not available, adjtimex can sometimes automatically fallback to a direct access method. This method detects the start of seconds by polling the update-in-progress (UIP) flag of the CMOS clock. You can force this direct access to the CMOS chip with the --directisa switch. Note that the /dev/rtc interrupt method is more accurate, less sensible to perturbations due to system load, cleaner, cheaper, and is generally better than the direct access method. It is advisable to not use the --directisa switch, unless the CMOS chip or the motherboard don't properly provide the necessary interrupt.

-n, --nointerrupt

Force immediate use of busywait access method, without first waiting for the interrupt timeout.

-l[file], --log[=file]

Save the current values of the system and CMOS clocks, and optionally a reference time, to file (default /var/log/clocks.log). The reference time is taken from a network timeserver (see the --host switch) or supplied by the user (see the --watch switch).

-h timeserver, --host timeserver

Use ntpdate to query the given timeserver for the current time. This will fail if timeserver is not running a Network Time Protocol (NTP) server, or if that server is not synchronized. Implies --log.

-w, --watch

Ask for a keypress when the user knows the time, then ask what that time was, and its approximate accuracy. Implies --log.

-r[file], --review[=file]

Review the clock log file (default /var/log/clocks.log) and estimate, if possible, the rates of the CMOS and system clocks. Calculate least-squares rates using all suitable log entries. Suggest corrections to adjust for systematic drift. With --adjust, the frequency and tick are set to the suggested values. (The CMOS clock correction is not changed.)

-V, --verbose

Increase verbosity.

--help

Print the program options.

-v, --version

Print the program version.

## EXAMPLES
If your system clock gained 8 seconds in 24 hours, you could set the tick to 9999, and then it would lose 0.64 seconds a day (that is, 1 tick unit = 8.64 seconds per day). To correct the rest of the error, you could set the frequency offset to (2^16)*0.64/.0864 = 485452. Thus, putting the following in rc.local would approximately correct the system clock:

```
     adjtimex  --tick 9999  --frequency 485452
```

## NOTES
adjtimex adjusts only the system clock — the one that runs while the computer is powered up. To set or regulate the CMOS clock, see hwclock(8).

## AUTHORS
Steven S. Dick <ssd at nevets.oau.org>, Jim Van Zandt <jrv at comcast.net>.

## SEE ALSO
date(1L), gettimeofday(2), settimeofday(2), hwclock(8), ntpdate(8), ntpd(8), /usr/src/linux/include/linux/timex.h, /usr/src/linux/include/linux/sched.h, /usr/src/linux/kernel/time.c, /usr/src/linux/kernel/sched.c