userdbpw

title: userdbpw(8)

summary: create an encrypted password

text:
# userdbpw(8)

## NAME
userdbpw - create an encrypted password

## SYNOPSIS
userdbpw [[-md5] | [-hmac-md5] | [-hmac-sha1]] |userdb {name} set {field}

## DESCRIPTION
userdbpw enables secure entry of encrypted passwords into /etc/courier-authlib/userdb.

userdbpw reads a single line of text on standard input, encrypts it, and prints the encrypted result to standard output.

If standard input is attached to a terminal device, userdbpw explicitly issues a "Password: " prompt on standard error, and turns off echo while the password is entered.

The -md5 option is available on systems that use MD5-hashed passwords (such as systems that use the current version of the PAM library for authenticating, with MD5 passwords enabled). This option creates an MD5 password hash, instead of using the traditional crypt() function.

-hmac-md5 and -hmac-sha1 options are available only if the userdb library is installed by an application that uses a challenge/response authentication mechanism. -hmac-md5 creates an intermediate HMAC context using the MD5 hash function. -hmac-sha1 uses the SHA1 hash function instead. Whether either HMAC function is actually available depends on the actual application that installs the userdb library.

Note that even though the result of HMAC hashing looks like an encrypted password, it's really not. HMAC-based challenge/response authentication mechanisms require the cleartext password to be available as cleartext. Computing an intermediate HMAC context does scramble the cleartext password, however if its compromised, it WILL be possible for an attacker to succesfully authenticate. Therefore, applications that use challenge/response authentication will store intermediate HMAC contexts in the "pw" fields in the userdb database, which will be compiled into the userdbshadow.db database, which has group and world permissions turned off. The userdb library also requires that the cleartext userdb source for the userdb.db and userdbshadow.db databases is also stored with the group and world permissions turned off.

userdbpw is usually used together in a pipe with userdb, which reads from standard input. For example:

```
userdbpw -md5 | userdb users/john set systempw
```

or:

```
userdbpw -hmac-md5 | userdb users/john set hmac-md5pw
```

These commands set the systempw field in the record for the user john in /etc/courier-authlib/userdb/users file, and the hmac-md5pw field. Don't forget to run makeuserdb for the change to take effect.

The following command does the same thing:

```
userdb users/john set systempw=SECRETPASSWORD
```

However, this command passes the secret password as an argument to the userdb command, which can be viewed by anyone who happens to run ps(1) at the same time. Using userdbpw allows the secret password to be specified in a way that cannot be easily viewed by ps(1).

## SEE ALSO
userdb(8)[1], makeuserdb(8)[2]

## NOTES
1.

userdb(8)

[set $man.base.url.for.relative.links]/userdb.html

2.

makeuserdb(8)

[set $man.base.url.for.relative.links]/makeuserdb.html


package: courier-imap

title: courierpop3d(8)

summary: The Courier POP3 server

text:
# courierpop3d(8)

## NAME
pop3d - The Courier POP3 server

## SYNOPSIS
/usr/sbin/couriertcpd {-nodnslookup} {-stderr=syslog} {110} {/usr/sbin/pop3login} [modules...] {/usr/sbin/pop3d} {./Maildir}

## DESCRIPTION
This is a simple POP3 server for Maildirs.

Note

The couriertcpd, pop3login, and pop3d modules may be installed elsewhere than indicated here.

pop3login is usually started by couriertcpd. It already expects that a POP3 client is connected to standard input and output, presumably via a network socket. pop3login reads the POP3 userid and password, then runs the authentication modules. The remaining arguments are passed along as arguments to modules.

modules is one or more authentication modules (see the authlib(7)[1] manual page).

Each authentication modules runs the program specified by its first argument, allowing the authentication modules to be chained. The last program in the chain is pop3d , which provides the actual POP3 service. In accordance with the authentication protocol, as described in authlib(7)[1] pop3d reads file descriptor 3 to see if the userid/password has been succesfully validated. If not, pop3d terminates.

Otherwise, pop3d expects to be already running under the appropriate user and group id, with its current directory set to the account's home directory.

The first order of business is to find the account's Maildir. If the environment variable MAILDIR is set, that's where we go. That should be the pathname to the account's Maildir. The environment variable MAILDIR may be set by the authentication module. If MAILDIR is not set, pop3d uses its first argument. Usually, the default maildir is $HOME/Maildir, therefore the first argument to pop3d is "./Maildir".

## SEE ALSO
authlib(7)[1], userdb(8)[2].

## AUTHOR
Sam Varshavchik

Author

## NOTES
1.

authlib(7)

http://www.courier-mta.org/authlib.html

2.

userdb(8)

http://www.courier-mta.org/userdb.html

branch: sisyphus


imapd

title: imapd(8)

summary: The Courier IMAP server

text:
# imapd(8)

## NAME
imapd - The Courier IMAP server

## SYNOPSIS
/usr/lib/couriertcpd {couriertcpd options} {/usr/sbin/imaplogin} [modules...] {/usr/bin/imapd} {./Maildir}

/usr/bin/imapd {./Maildir}

## DESCRIPTION
imapd is the Courier IMAP server that provides IMAP access to Maildir mailboxes. Normally you don't have to worry about it, as imapd runs automatically after receiving a network connection, accompanied by the appropriate userid and password.

couriertcpd opens network ports that receive incoming IMAP connections. After an incoming network connections is established, couriertcpd runs the command specified by its first argument, which is imaplogin passing the remaining arguments to imaplogin. imaplogin reads the IMAP login userid and password, then runs the modules specified by its remaining options, which are Courier server authentication modules described in the authlib(7)[1] manual page.

The last daisy-chained command is imapd, which is the actual IMAP server, which is started from the logged-in account's home directory. The sole argument to imapd is the pathname to the default IMAP mailbox, which is usually ./Maildir. Some authentication modules are capable of specifying a different filename, by setting the MAILDIR environment variable.

imapd may also be invoked from the shell prompt, in which case it issues a PREAUTH response, then changes the current directory to either its argument, or the contents of the MAILDIR environment variable, then attempts to talk IMAP on standard input and output.

imapd implements IMAP4REV1, as defined by RFC 2060[2].

## FILES AND ENVIRONMENT VARIABLES
AUTH*

imapd examines several environment variables whose names start with AUTH - these environment variables are set by imaplogin and the authentication modules. Their absence tells imapd that it's running from the command line.

MAILDIR

MAILDIR - if defined, imapd changes its directory to the one specified by this environment variable. Otherwise imapd changes its directory to the one specified on the command line.

`pwd`/.

The current directory is assumed to be the main INBOX Maildir.

`pwd`/.folder

Maildir folders, each one containing their own tmp, new, cur, etc...

Other environment variables are initialized from the /etc/courier-imap/imapd and /etc/courier-imap/imapd-ssl configuration files. These files are loaded into the environment by the system startup script that runs couriertcpd.

### Realtime concurrent folder status updates
The Courier IMAP server always allows more than one mail client to have the same folder opened. However, when two or more clients have the same folder opened, the mail clients may not necessarily know when another client added or removed messages from the folder. The base IMAP protocol specification requires IMAP mail clients to explicitly check for any changes to the folder's contents. No provisions exists to notify the mail client immediately when the folder's contents are modified by another mail client.

The IDLE extension to the base IMAP protocol provides a delivery mechanism for notifying mail clients of changes to the mail folder's contents.

IDLE IMAP capability

IDLE must be listed in the IMAP_CAPABILITY setting in the /etc/courier-imap/imapd configuration file.

IMAP_USELOCKS

This setting in /etc/courier-imap/imapd must be enabled. This setting uses dot-lock files to synchronize updates to folder indexes between multiple IMAP clients that have the same folder opened. This setting is safe to use with NFS, as it does not use actual file locking calls, and does not require the services of the problematic NFS lock daemon.

An IMAP mail client that fully supports the IDLE protocol extension.

Of course, an IMAP client that supports the IDLE protocol extension is required. At press time the status and extent of IDLE support in most IMAP mail clients is not known.

Without IMAP_USERLOCKS there exists a small possibility that multiple mail clients will receive a slightly inconsistent folder index if both clients try to update the contents of the folder at the same time. Usually, the worst case result is that some clients will eventually end up downloading the same message twice from the server, and caching it incorrectly in the local cache (if the IMAP client caches message contents). Clearing the local message cache will quickly eliminate any residual confusion that results from this situation. Without inotify kernel interface, the Courier IMAP server will manually check for changes to the folder's contents every 60 seconds, in IDLE mode (instead of in real time).

### Verifying realtime concurrent folder status updates
Use the following procedure to verify that realtime concurrent folder status updates are properly working. It is helpful to be familiar with the IMAP protocol. If that's not the case, just be extra careful in entering the IMAP protocol commands. The following instructions describe the procedure for connecting to the IMAP server, and manually issuing IMAP protocol commands, as if they originate from an IMAP client. The following instructions use "C:" to indicate IMAP client commands that must be entered, and "S:" to indicate the expected replies from the server.

Note

The actual replies from the server may differ slightly, due to the actual server configuration, and other minor factors. The following examples have long lines wrapped for readability. Slight observed differences from the expected replies are normal, but they should still be substantively the same.

1.Prepare a test account with a couple of messages. Open two or three terminal windows. In each window, connect to the IMAP server, and enter IDLE mode:

```
S:* OK Courier-IMAP ready. Copyright 1998-2021 Double Precision, Inc.

  See COPYING for distribution information.
C:a login userid password
S:a OK LOGIN Ok.
C:a SELECT INBOX
S:* FLAGS (\Draft \Answered \Flagged \Deleted \Seen \Recent)

  * OK [PERMANENTFLAGS (\Draft \Answered \Flagged \Deleted \Seen)]

    Limited

  * 2 EXISTS

  * 0 RECENT

  * OK [UIDVALIDITY 939609418] Ok

  a OK [READ-WRITE] Ok
C:a IDLE
S:+ entering ENHANCED idle mode
```

Note

The default Courier IMAP server configuration permits a maximum of four connections from the same IP address. It may be necessary to adjust this setting in /etc/courier-imap/imapd for the duration of this test.

2.The last message from the server must be "entering ENHANCED idle mode". Otherwise, it means that some of the necessary prerequisites have not been met.

3.Open another terminal window, connect to the server, and modify the flags of one of the messages:

```
S:* OK Courier-IMAP ready. Copyright 1998-2021 Double Precision, Inc.

  See COPYING for distribution information.
C:a login userid password
S:a OK LOGIN Ok.
C:a SELECT INBOX
S:* FLAGS (\Draft \Answered \Flagged \Deleted \Seen \Recent)

  * OK [PERMANENTFLAGS (\Draft \Answered \Flagged \Deleted \Seen)]

    Limited

  * 2 EXISTS

  * 0 RECENT

  * OK [UIDVALIDITY 939609418] Ok

  a OK [READ-WRITE] Ok
C:STORE 1 +FLAGS (\Deleted)
* 1 FETCH (FLAGS (\Deleted))
a OK STORE completed.
```

4.The last command sets the \Deleted flag on the first message in the folder. Immediately after entering the last command, "* 1 FETCH (FLAGS (\Deleted))" should also appear in all other terminal windows.

5.Verify that all terminal windows reliably receive folder status updates in real time by alternatively entering the commands "a STORE 1 -FLAGS (\Deleted)" and "a STORE 1 +FLAGS (\Deleted)", to toggle the deleted flag on the first message. Observe that the message is received by all terminal windows quickly, and reliably.

6.With the \Deleted flag set on the first message, enter the EXPUNGE command, which removes the deleted message from the folder:

```
C:a EXPUNGE
S:* 1 EXPUNGE

  * 2 EXISTS

  * 0 RECENT
S:a OK EXPUNGE completed
```

The lines that begin with the "*" character should also appear in all other terminal windows (depending on the initial folder state one of the terminal windows may have a different RECENT message, which is fine).

7.Use a mail client to create and send a test message to the test account. As soon as the mail server delivers the message, the following messages should appear in every terminal window:

```
* 3 EXISTS
* 0 RECENT
* 3 FETCH (FLAGS ())
```

The numbers in these messages may be different, depending upon the initial contents of the test mail folder. One of the terminal windows should have a different RECENT count, and one of the terminal windows should include a \Recent flag in the untagged FLAGS message. These difference are acceptable; the important thing is to make sure that all terminal windows have the same EXISTS message.

## SEE ALSO
authlib(7)[1], userdb(8)[3]

## AUTHOR
Sam Varshavchik

Author

## NOTES
1.

authlib(7)

http://www.courier-mta.org/authlib.html

2.

RFC 2060

http://www.rfc-editor.org/rfc/rfc2060.txt

3.

userdb(8)

http://www.courier-mta.org/userdb.html


makeimapaccess

title: makeimapaccess(8)

summary: Build IMAP server access file

text:
# makeimapaccess(8)

## NAME
makeimapaccess - Build IMAP server access file

## SYNOPSIS
makeimapaccess

## DESCRIPTION
makeimapaccess rebuilds the contents of the /var/lib/courier-imap/imapaccess.dat database from the contents of the files in the /var/lib/courier-imap/imapaccess directory. When the imapd script starts couriertcpd, the script specifies the /var/lib/courier-imap/imapaccess.dat file to control access to the Courier mail server's IMAP daemon. The makeimapaccess script must be run before any changes in the /var/lib/courier-imap/imapaccess directory take effect.

The couriertcpd(8)[1] manual page describes the general format of access files.

### The imapaccess configuration file
The couriertcpd(8)[1] manual page describes the generic format of the access file. The access file specifies what should be done with connections from defined IP address ranges. The basic choices are to accept or reject the connection. Also, the generic format of the access file allows arbitrary environment variables to be set based on the connection's remote IP address, however the IMAP server does not use any special environment variables on its own.

## SEE ALSO
couriertcpd(8)[1].

## AUTHOR
Sam Varshavchik

Author

## NOTES
1.

couriertcpd(8)

http://www.courier-mta.org/couriertcpd.html


deliverquota

package: courier-maildrop-utils

title: deliverquota(8)

summary: deliver to a maildir with a quota

text:
# deliverquota(8)

## NAME
deliverquota - deliver to a maildir with a quota

## SYNOPSIS
deliverquota [-c] [-w percent] [-W filename] {maildir} {quota}

## DESCRIPTION
deliverquota delivers mail to a maildir taking into account any software-imposed quota on the maildir. This manually-enforced quota mechanism is described in the maildirquota(7)[1] and maildirmake(1)[2] manual pages. Instead of setting up your mail server to deliver the message directly to a maildir, configure the mail server to run the deliverquota program in order to deliver the message, and specify the location of the maildir as the argument to deliverquota.

The second argument to deliverquota is optional. If present, quota specifies a new quota setting for this maildir. Specifying quota is equivalent to running maildirmake(1)[2] with the -q option. The second argument to deliverquota is considered obsolete, and may be removed in the future.

deliverquota reads the message from standard input and delivers it to maildir. maildir may specify a path directly to a maildir folder, not the main maildir (as long as the folder was created by the maildirmake(1)[2] command.

The -c option automatically creates the maildir, and all missing parent subdirectories (as 'mkdir -p'). This option should be used with caution.

The -w N option places a warning message into the maildir if the maildir has a quota setting, and after the message was successfully delivered the maildir was at least N percent full. The warning message is copied from the file specified by the -W option, or from /etc/courier-imap/quotawarnmsg if -W was not specified. The "Date:" and "Message-Id:" headers are added to the message. The warning is repeated every 24 hours (at least), until the maildir drops below N percent full.

## RETURN CODE
deliverquota delivers the message to the maildir and terminates with exit code 0 if the message can be delivered without going over quota.

If the maildir is over its specified quota: the maildrop version of deliverquota terminates with an exit code 77 (EX_NOPERM); the Courier version of deliverquota terminates with an exit code 75 (EX_TEMPFAIL).

## SEE ALSO
maildirquota(7)[1], maildirmake(1)[2].

## AUTHOR
Sam Varshavchik

Author

## NOTES
1.

maildirquota(7)

http://www.courier-mta.org/maildirquota.html

2.

maildirmake(1)

http://www.courier-mta.org/maildirmake.html


cpufreqd

package: cpufreqd

title: cpufreqd(8)

text:
# cpufreqd(8)

## NAME
cpufreqd - intelligently monitor and manipulate CPU frequency

## SYNOPSIS
cpufreqd [-Dmhv] [-f filename] [-V verbosity]

## DESCRIPTION
cpufreqd is used to monitor the status of the system and adjust the frequency of the CPU according to the user configuration. The behaviour of the daemon is fully configurable. Logs are reported through syslogd.

## PARAMETERS
-D, --no-daemon

stay in foreground (used to debug).

-m, --manual

start in manual mode.

-f filename, --file=filename

Specify the configuration file to read. The default is /etc/cpufreqd.conf.

-h, --help

Display command line help.

-v, --version

Display the version number of the daemon.

-V, --verbosity

verbosity level from 0 (less verbose) to 7 (most verbose). Default verbosity is 4

## SIGNALS
SIGHUP

This lets cpufreqd perform a re-initialization. The configuration file (default is /etc/cpufreqd.conf) will be re-read and probes re-done. (Not yet implemented in cpufreqd-2.0)

SIGINT, SIGTERM

cpufreqd will terminate.

## EXAMPLES
/usr/sbin/cpufreqd -D

## NOTES
Some ACPI implementations are very cpu-consuming when reading the info file of

system batteries. Cpufreqd implements a simple workaround that avoids reading that file except on initialization or reinitialization. This has the effect of needing to send an HUP signal if inserting a new battery, otherwise battery measurement won't be correct.

## FILES
/sys/devices/system/cpu/cpu*/cpufreq

kernel cpu frequency interface

/proc/cpufreq

old deprecated kernel cpu frequency interface (please avoid it)

/proc/acpi

kernel power management interface (ACPI)

/proc/apm

kernel power management interface (APM)

/proc/pmu

kernel power management interface (PMU). (Not yet implemented in cpufreqd-2.0)

/etc/cpufreqd.conf

cpufreqd configuration file

## SEE ALSO
cpufreqd.conf(5),syslogd(8),cpufreqd-set(1),cpufreqd-get(1)

## BUGS
Multiple CPUs are not considered separately thus the same policy is set in every available CPU. Battery can only be specified in percent, not in minutes remaining.

## AUTHOR
George Staikos <staikos@0wned.org>

Mattia Dongili <malattia@linux.it>

Rene Rebe <rene@rocklinux.org>


turbostat

package: cpupower

title: turbostat(8)

text:
# turbostat(8)

## NAME
turbostat - Report processor frequency and idle statistics

## SYNOPSIS
turbostat [Options] command

turbostat [Options] [--interval seconds]

## DESCRIPTION
turbostat reports processor topology, frequency, idle power-state statistics, temperature and power on X86 processors. There are two ways to invoke turbostat. The first method is to supply a command, which is forked and statistics are printed in one-shot upon its completion. The second method is to omit the command, and turbostat displays statistics every 5 seconds interval. The 5-second interval can be changed using the --interval option.

Some information is not available on older processors.

### Options
Options can be specified with a single or double '-', and only as much of the option name as necessary to disambiguate it from others is necessary. Note that options are case-sensitive.

--add attributes add column with counter having specified 'attributes'. The 'location' attribute is required, all others are optional.

```
	location: {msrDDD | msr0xXXX | /sys/path... | perf/<device>/<event>}
		msrDDD is a decimal offset, eg. msr16
		msr0xXXX is a hex offset, eg. msr0x10
		/sys/path... is an absolute path to a sysfs attribute
		<device> is a perf device from /sys/bus/event_source/devices/<device> eg. cstate_core
			On Intel hybrid platforms, instead of one "cpu" perf device there are two, "cpu_core" and "cpu_atom" devices for P and E cores respectively.
			Turbostat, in this case, allow user to use "cpu" device and will automatically detect the type of a CPU and translate it to "cpu_core" and "cpu_atom" accordingly.
			For a complete example see "ADD PERF COUNTER EXAMPLE #2 (using virtual "cpu" device)".
		<event> is a perf event for given device from /sys/bus/event_source/devices/<device>/events/<event> eg. c1-residency
			perf/cstate_core/c1-residency would then use /sys/bus/event_source/devices/cstate_core/events/c1-residency
	scope: {cpu | core | package}
		sample and print the counter for every cpu, core, or package.
		default: cpu
	size: {u32 | u64 }
		MSRs are read as 64-bits, u32 truncates the displayed value to 32-bits.
		default: u64
	format: {raw | delta | percent | average}
		'raw' shows the MSR contents in hex.
		'delta' shows the difference in values during the measurement interval.
		'percent' shows the delta as a percentage of the cycles elapsed.
		'average' similar to raw, but also averaged for node/package summaries (or when using -S).
		default: delta
	name: "name_string"
		Any string that does not match a key-word above is used
		as the column header.
```

--add pmt,[attr_name=attr_value, ...] add column with a PMT (Intel Platform Monitoring Technology) counter in a similar way to --add option above, but require PMT metadata to be supplied to correctly read and display the counter. The metadata can be found in the Intel PMT XML files, hosted at https://github.com/intel/Intel-PMT. For a complete example see "ADD PMT COUNTER EXAMPLE".

```
	name="name_string"
		For column header.
	type={raw}
		'raw' shows the counter contents in hex.
		default: raw
	format={raw | delta}
		'raw' shows the counter contents in hex.
		'delta' shows the difference in values during the measurement interval.
		default: raw
	domain={cpu%u | core%u | package%u}
		'cpu' per cpu/thread counter.
		'core' per core counter.
		'package' per package counter.
		'%u' denotes id of the domain that the counter is associated with. For example core4 would mean that the counter is associated with core number 4.
	offset=%u
		'%u' offset within the PMT MMIO region.
	lsb=%u
		'%u' least significant bit within the 64 bit value read from 'offset'. Together with 'msb', used to form a read mask.
	msb=%u
		'%u' most significant bit within the 64 bit value read from 'offset'. Together with 'lsb', used to form a read mask.
	guid=%x
		'%x' hex identifier of the PMT MMIO region.
```

--cpu cpu-set limit output to system summary plus the specified cpu-set. If cpu-set is the string "core", then the system summary plus the first CPU in each core are printed -- eg. subsequent HT siblings are not printed. Or if cpu-set is the string "package", then the system summary plus the first CPU in each package is printed. Otherwise, the system summary plus the specified set of CPUs are printed. The cpu-set is ordered from low to high, comma delimited with ".." and "-" permitted to denote a range. eg. 1,2,8,14..17,21-44

--hide column do not show the specified built-in columns. May be invoked multiple times, or with a comma-separated list of column names.

--enable column show the specified built-in columns, which are otherwise disabled, by default. Currently the only built-in counters disabled by default are "usec", "Time_Of_Day_Seconds", "APIC" and "X2APIC". The column name "all" can be used to enable all disabled-by-default built-in counters.

--show column show only the specified built-in columns. May be invoked multiple times, or with a comma-separated list of column names.

--show CATEGORY --hide CATEGORY Show and hide also accept a comma-separated-list of CATEGORIES of columns: "all", "topology", "idle", "frequency", "power", "cpuidle", "hwidle", "swidle", "cache", "llc", "other". "idle" (enabled by default), includes "hwidle" and "pct_idle". "cpuidle" (default disabled) includes cpuidle software invocation counters. "swidle" includes "cpuidle" plus "pct_idle". "hwidle" includes only hardware based idle residency counters. Older versions of turbostat used the term "sysfs" for what is now "swidle".

--Dump displays the raw counter values.

--quiet Do not decode and print the system configuration header information.

--no-msr Disable all the uses of the MSR driver.

--no-perf Disable all the uses of the perf API.

--interval seconds overrides the default 5.0 second measurement interval.

--num_iterations num number of the measurement iterations.

--out output_file turbostat output is written to the specified output_file. The file is truncated if it already exists, and it is created if it does not exist.

--help displays usage for the most common parameters.

--Joules displays energy in Joules, rather than dividing Joules by time to print power in Watts.

--list display column header names available for use by --show and --hide, then exit.

--Summary limits output to a 1-line System Summary for each interval.

--TCC temperature sets the Thermal Control Circuit temperature for systems which do not export that value. This is used for making sense of the Digital Thermal Sensor outputs, as they return degrees Celsius below the TCC activation temperature.

--version displays the version.

The command parameter forks command, and upon its exit, displays the statistics gathered since it was forked.

## ROW DESCRIPTIONS
The system configuration dump (if --quiet is not used) is followed by statistics. The first row of the statistics labels the content of each column (below). The second row of statistics is the system summary line. The system summary line has a '-' in the columns for the Package, Core, and CPU. The contents of the system summary line depends on the type of column. Columns that count items (eg. IRQ) show the sum across all CPUs in the system. Columns that show a percentage show the average across all CPUs in the system. Columns that dump raw MSR values simply show 0 in the summary. After the system summary row, each row describes a specific Package/Core/CPU. Note that if the --cpu parameter is used to limit which specific CPUs are displayed, turbostat will still collect statistics for all CPUs in the system and will still show the system summary for all CPUs in the system.

## COLUMN DESCRIPTIONS
usec For each CPU, the number of microseconds elapsed during counter collection, including thread migration -- if any. This counter is disabled by default, and is enabled with "--enable usec", or --debug. On the summary row, usec refers to the total elapsed time to snapshot the procfs/sysfs and collect the counters on all cpus.

Time_Of_Day_Seconds For each CPU, the gettimeofday(2) value (seconds.subsec since Epoch) when the counters ending the measurement interval were collected. This column is disabled by default, and can be enabled with "--enable Time_Of_Day_Seconds" or "--debug". On the summary row, Time_Of_Day_Seconds refers to the timestamp following collection of counters on the last CPU.

Core processor core number. Note that multiple CPUs per core indicate support for Intel(R) Hyper-Threading Technology (HT).

CPU Linux CPU (logical processor) number. Yes, it is okay that on many systems the CPUs are not listed in numerical order -- for efficiency reasons, turbostat runs in topology order, so HT siblings appear together.

Package processor package number -- not present on systems with a single processor package.

Avg_MHz number of cycles executed divided by time elapsed. Note that this includes idle-time when 0 instructions are executed.

Busy% percent of the measurement interval that the CPU executes instructions, aka. % of time in "C0" state.

Bzy_MHz average clock rate while the CPU was not idle (ie. in "c0" state).

TSC_MHz average MHz that the TSC ran during the entire interval.

IRQ The number of interrupts serviced by that CPU during the measurement interval. The system total line is the sum of interrupts serviced across all CPUs. turbostat parses /proc/interrupts to generate this summary.

SMI The number of System Management Interrupts serviced CPU during the measurement interval. While this counter is actually per-CPU, SMI are triggered on all processors, so the number should be the same for all CPUs.

LLCkRPS Last Level Cache Thousands of References Per Second. For CPUs with an L3 LLC, this is the number of references that CPU made to the L3 (and the number of misses that CPU made to it's L2). For CPUs with an L2 LLC, this is the number of references to the L2 (and the number of misses to the CPU's L1). The system summary row shows the sum for all CPUs. In both cases, the value displayed is the actual value divided by 1000 in the interest of usually fitting into 8 columns.

LLC%hit Last Level Cache Hit Rate %. Hit Rate Percent = 100.0 * (References - Misses)/References. The system summary row shows the weighted average for all CPUs (100.0 * (Sum_References - Sum_Misses)/Sum_References).

C1, C2, C3... The number times Linux requested the C1, C2, C3 idle state during the measurement interval. The system summary line shows the sum for all CPUs. These are C-state names as exported in /sys/devices/system/cpu/cpu*/cpuidle/state*/name. While their names are generic, their attributes are processor specific. They the system description section of output shows what MWAIT sub-states they are mapped to on each system. These counters are in the "cpuidle" group, which is disabled, by default.

C1+, C2+, C3+... The idle governor idle state misprediction statistics. Inidcates the number times Linux requested the C1, C2, C3 idle state during the measurement interval, but should have requested a deeper idle state (if it exists and enabled). These statistics come from the /sys/devices/system/cpu/cpu*/cpuidle/state*/below file. These counters are in the "cpuidle" group, which is disabled, by default.

C1-, C2-, C3-... The idle governor idle state misprediction statistics. Inidcates the number times Linux requested the C1, C2, C3 idle state during the measurement interval, but should have requested a shallower idle state (if it exists and enabled). These statistics come from the /sys/devices/system/cpu/cpu*/cpuidle/state*/above file. These counters are in the "cpuidle" group, which is disabled, by default.

C1%, C2%, C3% The residency percentage that Linux requested C1, C2, C3.... The system summary is the average of all CPUs in the system. Note that these are software, reflecting what was requested. The hardware counters reflect what was actually achieved. These counters are in the "pct_idle" group, which is enabled by default.

CPU%c1, CPU%c3, CPU%c6, CPU%c7 show the percentage residency in hardware core idle states. These numbers are from hardware residency counters and are in the "hwidle" group, which is enabled, by default.

CoreTmp Degrees Celsius reported by the per-core Digital Thermal Sensor.

PkgTmp Degrees Celsius reported by the per-package Package Thermal Monitor.

CoreThr Core Thermal Throttling events during the measurement interval. Note that events since boot can be find in /sys/devices/system/cpu/cpu*/thermal_throttle/*

GFX%rc6 The percentage of time the GPU is in the "render C6" state, rc6, during the measurement interval. From /sys/class/drm/card0/power/rc6_residency_ms or /sys/class/drm/card0/gt/gt0/rc6_residency_ms or /sys/class/drm/card0/device/tile0/gtN/gtidle/idle_residency_ms depending on the graphics driver being used.

GFXMHz Instantaneous snapshot of what sysfs presents at the end of the measurement interval. From /sys/class/graphics/fb0/device/drm/card0/gt_cur_freq_mhz or /sys/class/drm/card0/gt_cur_freq_mhz or /sys/class/drm/card0/gt/gt0/rps_cur_freq_mhz or /sys/class/drm/card0/device/tile0/gtN/freq0/cur_freq depending on the graphics driver being used.

GFXAMHz Instantaneous snapshot of what sysfs presents at the end of the measurement interval. From /sys/class/graphics/fb0/device/drm/card0/gt_act_freq_mhz or /sys/class/drm/card0/gt_act_freq_mhz or /sys/class/drm/card0/gt/gt0/rps_act_freq_mhz or /sys/class/drm/card0/device/tile0/gtN/freq0/act_freq depending on the graphics driver being used.

SAM%mc6 The percentage of time the SA Media is in the "module C6" state, mc6, during the measurement interval. From /sys/class/drm/card0/gt/gt1/rc6_residency_ms or /sys/class/drm/card0/device/tile0/gtN/gtidle/idle_residency_ms depending on the graphics driver being used.

SAMMHz Instantaneous snapshot of what sysfs presents at the end of the measurement interval. From /sys/class/drm/card0/gt/gt1/rps_cur_freq_mhz or /sys/class/drm/card0/device/tile0/gtN/freq0/cur_freq depending on the graphics driver being used.

SAMAMHz Instantaneous snapshot of what sysfs presents at the end of the measurement interval. From /sys/class/drm/card0/gt/gt1/rps_act_freq_mhz or /sys/class/drm/card0/device/tile0/gtN/freq0/act_freq depending on the graphics driver being used.

Totl%C0 Weighted percentage of time that CPUs are busy. If N CPUs are busy during an interval, the percentage is N * 100%.

Any%C0 Percentage of time that at least one CPU is busy.

GFX%C0 Percentage of time that at least one GFX compute engine is busy.

CPUGFX% Percentage of time that at least one CPU is busy at the same time as at least one Graphics compute enginer is busy.

Pkg%pc2, Pkg%pc3, Pkg%pc6, Pkg%pc7 percentage residency in hardware package idle states. These numbers are from hardware residency counters.

PkgWatt Watts consumed by the whole package.

CorWatt Watts consumed by the core part of the package.

GFXWatt Watts consumed by the Graphics part of the package -- available only on client processors.

RAMWatt Watts consumed by the DRAM DIMMS -- available only on server processors.

SysWatt Watts consumed by the whole platform (RAPL PSYS).

PKG_% percent of the interval that RAPL throttling was active on the Package. Note that the system summary is the sum of the package throttling time, and thus may be higher than 100% on a multi-package system. Note that the meaning of this field is model specific. For example, some hardware increments this counter when RAPL responds to thermal limits, but does not increment this counter when RAPL responds to power limits. Comparing PkgWatt and PkgTmp to system limits is necessary.

RAM_% percent of the interval that RAPL throttling was active on DRAM.

UncMHz per-package uncore MHz, instantaneous sample.

UMHz1.0 per-package uncore MHz for pm_domain=1 and fabric_cluster=0, instantaneous sample. System summary is the average of all packages. Intel Granite Rapids systems use pm_domains 0-2 for CPUs, and 3-4 for IO, with cluster always 0. For the "--show" and "--hide" options, use "UncMHz" to operate on all UMHz*.* as a group.

## TOO MUCH INFORMATION EXAMPLE
By default, turbostat dumps all possible information -- a system configuration header, followed by columns for all counters. This is ideal for remote debugging, use the "--out" option to save everything to a text file, and get that file to the expert helping you debug.

When you are not interested in all that information, and there are several ways to see only what you want. First the "--quiet" option will skip the configuration information, and turbostat will show only the counter columns. Second, you can reduce the columns with the "--hide" and "--show" options. If you use the "--show" option, then turbostat will show only the columns you list. If you use the "--hide" option, turbostat will show all columns, except the ones you list.

To find out what columns are available for --show and --hide, the "--list" option is available. Usually, the CATEGORY names above are used to refer to groups of counters. Also, for convenience, the special string "sysfs" can be used to refer to all of the sysfs C-state counters at once:

```
sudo ./turbostat --show sysfs --quiet sleep 10
10.003837 sec
	C1	C1E	C3	C6	C7s	C1%	C1E%	C3%	C6%	C7s%
	4	21	2	2	459	0.14	0.82	0.00	0.00	98.93
	1	17	2	2	130	0.00	0.02	0.00	0.00	99.80
	0	0	0	0	31	0.00	0.00	0.00	0.00	99.95
	2	1	0	0	52	1.14	6.49	0.00	0.00	92.21
	1	2	0	0	52	0.00	0.08	0.00	0.00	99.86
	0	0	0	0	71	0.00	0.00	0.00	0.00	99.89
	0	0	0	0	25	0.00	0.00	0.00	0.00	99.96
	0	0	0	0	74	0.00	0.00	0.00	0.00	99.94
	0	1	0	0	24	0.00	0.00	0.00	0.00	99.84
```

## ONE SHOT COMMAND EXAMPLE
If turbostat is invoked with a command, it will fork that command and output the statistics gathered after the command exits. In this case, turbostat output goes to stderr, by default. Output can instead be saved to a file using the --out option. In this example, the "sleep 10" command is forked, and turbostat waits for it to complete before saving all statistics into "ts.out". Note that "sleep 10" is not part of turbostat, but is simply an example of a command that turbostat can fork. The "ts.out" file is what you want to edit in a very wide window, paste into a spreadsheet, or attach to a bugzilla entry.

```
[root@hsw]# ./turbostat -o ts.out sleep 10
[root@hsw]#
```

## PERIODIC INTERVAL EXAMPLE
Without a command to fork, turbostat displays statistics ever 5 seconds. Periodic output goes to stdout, by default, unless --out is used to specify an output file. The 5-second interval can be changed with the "-i sec" option.

```
sudo turbostat --quiet --show CPU,frequency
	Core	CPU	Avg_MHz	Busy%	Bzy_MHz	TSC_MHz	CPU%c7	UncMhz
	-	-	524	12.48	4198	3096	74.53	3800
	0	0	4	0.09	4081	3096	98.88	3800
	0	4	1	0.02	4063	3096
	1	1	2	0.06	4063	3096	99.60
	1	5	2	0.05	4070	3096
	2	2	4178	99.52	4199	3096	0.00
	2	6	3	0.08	4159	3096
	3	3	1	0.04	4046	3096	99.66
	3	7	0	0.01	3989	3096
	Core	CPU	Avg_MHz	Busy%	Bzy_MHz	TSC_MHz	CPU%c7	UncMhz
	-	-	525	12.52	4198	3096	74.54	3800
	0	0	4	0.10	4051	3096	99.49	3800
	0	4	2	0.04	3993	3096
	1	1	3	0.07	4054	3096	99.56
	1	5	4	0.10	4018	3096
	2	2	4178	99.51	4199	3096	0.00
	2	6	4	0.09	4143	3096
	3	3	2	0.06	4026	3096	99.10
	3	7	7	0.17	4074	3096
```

This example also shows the use of the --show option to show only the desired columns.

## SYSTEM CONFIGURATION INFORMATION EXAMPLE
By default, turbostat always dumps system configuration information before taking measurements. In the example above, "--quiet" is used to suppress that output. Here is an example of the configuration information:

```
turbostat version 2022.04.16 - Len Brown <lenb@kernel.org>
Kernel command line: BOOT_IMAGE=/boot/vmlinuz-5.18.0-rc6-00001-ge6891250e3b5 ...
CPUID(0): GenuineIntel 0x16 CPUID levels
CPUID(1): family:model:stepping 0x6:9e:9 (6:158:9) microcode 0xea
CPUID(0x80000000): max_extended_levels: 0x80000008
CPUID(1): SSE3 MONITOR - EIST TM2 TSC MSR ACPI-TM HT TM
CPUID(6): APERF, TURBO, DTS, PTM, HWP, HWPnotify, HWPwindow, HWPepp, No-HWPpkg, EPB
cpu7: MSR_IA32_MISC_ENABLE: 0x00850089 (TCC EIST MWAIT PREFETCH TURBO)
CPUID(7): SGX
cpu7: MSR_IA32_FEATURE_CONTROL: 0x00000005 (Locked )
CPUID(0x15): eax_crystal: 2 ebx_tsc: 258 ecx_crystal_hz: 0
TSC: 3096 MHz (24000000 Hz * 258 / 2 / 1000000)
CPUID(0x16): base_mhz: 3100 max_mhz: 4200 bus_mhz: 100
cpu7: MSR_MISC_PWR_MGMT: 0x00401cc0 (ENable-EIST_Coordination DISable-EPB DISable-OOB)
RAPL: 5825 sec. Joule Counter Range, at 45 Watts
cpu7: MSR_PLATFORM_INFO: 0x80839f1011f00
8 * 100.0 = 800.0 MHz max efficiency frequency
31 * 100.0 = 3100.0 MHz base frequency
cpu7: MSR_IA32_POWER_CTL: 0x002c005d (C1E auto-promotion: DISabled)
cpu7: MSR_TURBO_RATIO_LIMIT: 0x2728292a
39 * 100.0 = 3900.0 MHz max turbo 4 active cores
40 * 100.0 = 4000.0 MHz max turbo 3 active cores
41 * 100.0 = 4100.0 MHz max turbo 2 active cores
42 * 100.0 = 4200.0 MHz max turbo 1 active cores
cpu7: MSR_CONFIG_TDP_NOMINAL: 0x0000001f (base_ratio=31)
cpu7: MSR_CONFIG_TDP_LEVEL_1: 0x00000000 ()
cpu7: MSR_CONFIG_TDP_LEVEL_2: 0x00000000 ()
cpu7: MSR_CONFIG_TDP_CONTROL: 0x80000000 ( lock=1)
cpu7: MSR_TURBO_ACTIVATION_RATIO: 0x00000000 (MAX_NON_TURBO_RATIO=0 lock=0)
cpu7: MSR_PKG_CST_CONFIG_CONTROL: 0x1e008008 (UNdemote-C3, UNdemote-C1, demote-C3, demote-C1, locked, pkg-cstate-limit=8 (unlimited))
Uncore Frequency pkg0 die0: 800 - 3900 MHz (800 - 3900 MHz)
/dev/cpu_dma_latency: 2000000000 usec (default)
current_driver: intel_idle
current_governor: menu
current_governor_ro: menu
cpu7: POLL: CPUIDLE CORE POLL IDLE
cpu7: C1: MWAIT 0x00
cpu7: C1E: MWAIT 0x01
cpu7: C3: MWAIT 0x10
cpu7: C6: MWAIT 0x20
cpu7: C7s: MWAIT 0x33
cpu7: C8: MWAIT 0x40
cpu7: C9: MWAIT 0x50
cpu7: C10: MWAIT 0x60
cpu7: cpufreq driver: intel_pstate
cpu7: cpufreq governor: performance
cpufreq intel_pstate no_turbo: 0
cpu7: MSR_MISC_FEATURE_CONTROL: 0x00000000 (L2-Prefetch L2-Prefetch-pair L1-Prefetch L1-IP-Prefetch)
cpu0: MSR_PM_ENABLE: 0x00000001 (HWP)
cpu0: MSR_HWP_CAPABILITIES: 0x01101f53 (high 83 guar 31 eff 16 low 1)
cpu0: MSR_HWP_REQUEST: 0x00005353 (min 83 max 83 des 0 epp 0x0 window 0x0 pkg 0x0)
cpu0: MSR_HWP_INTERRUPT: 0x00000001 (EN_Guaranteed_Perf_Change, Dis_Excursion_Min)
cpu0: MSR_HWP_STATUS: 0x00000004 (No-Guaranteed_Perf_Change, No-Excursion_Min)
cpu0: EPB: 6 (balanced)
cpu0: MSR_RAPL_POWER_UNIT: 0x000a0e03 (0.125000 Watts, 0.000061 Joules, 0.000977 sec.)
cpu0: MSR_PKG_POWER_INFO: 0x00000168 (45 W TDP, RAPL 0 - 0 W, 0.000000 sec.)
cpu0: MSR_PKG_POWER_LIMIT: 0x42820800218208 (UNlocked)
cpu0: PKG Limit #1: ENabled (65.000 Watts, 64.000000 sec, clamp ENabled)
cpu0: PKG Limit #2: ENabled (65.000 Watts, 0.002441* sec, clamp DISabled)
cpu0: MSR_VR_CURRENT_CONFIG: 0x00000000
cpu0: PKG Limit #4: 0.000000 Watts (UNlocked)
cpu0: MSR_DRAM_POWER_LIMIT: 0x5400de00000000 (UNlocked)
cpu0: DRAM Limit: DISabled (0.000 Watts, 0.000977 sec, clamp DISabled)
cpu0: MSR_PP0_POLICY: 0
cpu0: MSR_PP0_POWER_LIMIT: 0x00000000 (UNlocked)
cpu0: Cores Limit: DISabled (0.000 Watts, 0.000977 sec, clamp DISabled)
cpu0: MSR_PP1_POLICY: 0
cpu0: MSR_PP1_POWER_LIMIT: 0x00000000 (UNlocked)
cpu0: GFX Limit: DISabled (0.000 Watts, 0.000977 sec, clamp DISabled)
cpu0: MSR_IA32_TEMPERATURE_TARGET: 0x00640000 (100 C) (100 default - 0 offset)
cpu0: MSR_IA32_PACKAGE_THERM_STATUS: 0x88200800 (68 C)
cpu0: MSR_IA32_PACKAGE_THERM_INTERRUPT: 0x00000003 (100 C, 100 C)
cpu7: MSR_PKGC3_IRTL: 0x0000884e (valid, 79872 ns)
cpu7: MSR_PKGC6_IRTL: 0x00008876 (valid, 120832 ns)
cpu7: MSR_PKGC7_IRTL: 0x00008894 (valid, 151552 ns)
cpu7: MSR_PKGC8_IRTL: 0x000088fa (valid, 256000 ns)
cpu7: MSR_PKGC9_IRTL: 0x0000894c (valid, 339968 ns)
cpu7: MSR_PKGC10_IRTL: 0x00008bf2 (valid, 1034240 ns)
```

The max efficiency frequency, a.k.a. Low Frequency Mode, is the frequency available at the minimum package voltage. The TSC frequency is the base frequency of the processor -- this should match the brand string in /proc/cpuinfo. This base frequency should be sustainable on all CPUs indefinitely, given nominal power and cooling. The remaining rows show what maximum turbo frequency is possible depending on the number of idle cores. Note that not all information is available on all processors.

## ADD COUNTER EXAMPLE
Here we limit turbostat to showing just the CPU number for cpu0 - cpu3. We add a counter showing the 32-bit raw value of MSR 0x199 (MSR_IA32_PERF_CTL), labeling it with the column header, "PRF_CTRL", and display it only once, after the conclusion of a 0.1 second sleep.

```
sudo ./turbostat --quiet --cpu 0-3 --show CPU --add msr0x199,u32,raw,PRF_CTRL sleep .1
0.101604 sec
CPU	  PRF_CTRL
-	0x00000000
0	0x00000c00
1	0x00000800
2	0x00000a00
3	0x00000800
```

## ADD PERF COUNTER EXAMPLE
Here we limit turbostat to showing just the CPU number for cpu0 - cpu3. We add a counter showing time spent in C1 core cstate, labeling it with the column header, "pCPU%c1", and display it only once, after the conclusion of 0.1 second sleep. We also show CPU%c1 built-in counter that should show similar values.

```
sudo ./turbostat --quiet --cpu 0-3 --show CPU,CPU%c1 --add perf/cstate_core/c1-residency,cpu,delta,percent,pCPU%c1 sleep .1
0.102448 sec
CPU     pCPU%c1 CPU%c1
-       34.89   34.89
0       45.99   45.99
1       45.94   45.94
2       23.83   23.83
3       23.84   23.84
```

## ADD PERF COUNTER EXAMPLE #2 (using virtual cpu device)
Here we run on hybrid, Meteor Lake platform. We limit turbostat to show output for just cpu0 (pcore) and cpu4 (ecore). We add a counter showing number of L3 cache misses, using virtual "cpu" device, labeling it with the column header, "VCMISS". We add a counter showing number of L3 cache misses, using virtual "cpu_core" device, labeling it with the column header, "PCMISS". This will fail on ecore cpu4. We add a counter showing number of L3 cache misses, using virtual "cpu_atom" device, labeling it with the column header, "ECMISS". This will fail on pcore cpu0. We display it only once, after the conclusion of 0.1 second sleep.

```
sudo ./turbostat --quiet --cpu 0,4 --show CPU --add perf/cpu/cache-misses,cpu,delta,VCMISS --add perf/cpu_core/cache-misses,cpu,delta,PCMISS --add perf/cpu_atom/cache-misses,cpu,delta,ECMISS sleep 5
turbostat: added_perf_counters_init_: perf/cpu_atom/cache-misses: failed to open counter on cpu0
turbostat: added_perf_counters_init_: perf/cpu_core/cache-misses: failed to open counter on cpu4
5.001207 sec
CPU	ECMISS		PCMISS		VCMISS
-	41586506	46291219	87877749
4	83173012	0		83173040
0	0		92582439	92582458
```

## ADD PMT COUNTER EXAMPLE
Here we limit turbostat to showing just the CPU number 0. We add two counters, showing crystal clock count and the DC6 residency. All the parameters passed are based on the metadata found in the PMT XML files.

For the crystal clock count, we label it with the column header, "XTAL", we set the type to 'raw', to read the number of clock ticks in hex, we set the format to 'delta', to display the difference in ticks during the measurement interval, we set the domain to 'package0', to collect it and associate it with the whole package number 0, we set the offset to '0', which is a offset of the counter within the PMT MMIO region, we set the lsb and msb to cover all 64 bits of the read 64 bit value, and finally we set the guid to '0x1a067102', that identifies the PMT MMIO region to which the 'offset' is applied to read the counter value.

For the DC6 residency counter, we label it with the column header, "Die%c6", we set the type to 'txtal_time', to obtain the percent residency value we set the format to 'delta', to display the difference in ticks during the measurement interval, we set the domain to 'package0', to collect it and associate it with the whole package number 0, we set the offset to '0', which is a offset of the counter within the PMT MMIO region, we set the lsb and msb to cover all 64 bits of the read 64 bit value, and finally we set the guid to '0x1a067102', that identifies the PMT MMIO region to which the 'offset' is applied to read the counter value.

```
sudo ./turbostat --quiet --cpu 0 --show CPU --add pmt,name=XTAL,type=raw,format=delta,domain=package0,offset=0,lsb=0,msb=63,guid=0x1a067102 --add pmt,name=Die%c6,type=txtal_time,format=delta,domain=package0,offset=120,lsb=0,msb=63,guid=0x1a067102
0.104352 sec
CPU                   XTAL      Die%c6
-       0x0000006d4d957ca7      0.00
0       0x0000006d4d957ca7      0.00
0.102448 sec
```

## INPUT
For interval-mode, turbostat will immediately end the current interval when it sees a newline on standard input. turbostat will then start the next interval. Control-C will be send a SIGINT to turbostat, which will immediately abort the program with no further processing.

## SIGNALS
SIGINT will interrupt interval-mode. The end-of-interval data will be collected and displayed before turbostat exits.

SIGUSR1 will end current interval, end-of-interval data will be collected and displayed before turbostat starts a new interval.

## NOTES
turbostat must be run as root. Alternatively, non-root users can be enabled to run turbostat this way:

\# setcap cap_sys_admin,cap_sys_rawio,cap_sys_nice=+ep path/to/turbostat

\# chmod +r /dev/cpu/*/msr

\# chmod +r /dev/cpu_dma_latency

turbostat reads hardware counters, but doesn't write them. So it will not interfere with the OS or other programs, including multiple invocations of itself.

turbostat may work poorly on Linux-2.6.20 through 2.6.29, as acpi-cpufreq periodically cleared the APERF and MPERF MSRs in those kernels.

AVG_MHz = APERF_delta/measurement_interval. This is the actual number of elapsed cycles divided by the entire sample interval -- including idle time. Note that this calculation is resilient to systems lacking a non-stop TSC.

TSC_MHz = TSC_delta/measurement_interval. On a system with an invariant TSC, this value will be constant and will closely match the base frequency value shown in the brand string in /proc/cpuinfo. On a system where the TSC stops in idle, TSC_MHz will drop below the processor's base frequency.

Busy% = MPERF_delta/TSC_delta

Bzy_MHz = TSC_delta*APERF_delta/MPERF_delta/measurement_interval

Note that these calculations depend on TSC_delta, so they are not reliable during intervals when TSC_MHz is not running at the base frequency.

Turbostat data collection is not atomic. Extremely short measurement intervals (much less than 1 second), or system activity that prevents turbostat from being able to run on all CPUS to quickly collect data, will result in inconsistent results.

The APERF, MPERF MSRs are defined to count non-halted cycles. Although it is not guaranteed by the architecture, turbostat assumes that they count at TSC rate, which is true on all processors tested to date.

## REFERENCES
Volume 3B: System Programming Guide" https://www.intel.com/products/processor/manuals/

## RUN THE LATEST VERSION
If turbostat complains that it doesn't recognize your processor, please try the latest version.

The latest version of turbostat does not require the latest version of the Linux kernel. However, some features, such as perf(1) counters, do require kernel support.

The latest turbostat release is available in the upstream Linux Kernel source tree. eg. "git pull https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git" and run make in tools/power/x86/turbostat/.

n.b. "make install" will update your system manually, but a distro update may subsequently downgrade your turbostat to an older version. For this reason, manually installing to /usr/local/bin may be what you want.

Note that turbostat/Makefile has a "make snapshot" target, which will create a tar file that can build without a local kernel source tree.

If the upstream version isn't new enough, the development tree can be found here: "git pull https://git.kernel.org/pub/scm/linux/kernel/git/lenb/linux.git turbostat"

If the development tree doesn't work, please contact the author via chat, or via email with the word "turbostat" on the Subject line.

## FILES

```
/sys/bus/event_source/devices/
/dev/cpu/*/msr
/sys/class/intel_pmt/
/sys/devices/system/cpu/
```

## SEE ALSO
perf(1), msr(4), vmstat(8)

## AUTHOR

```
Written by Len Brown <len.brown@intel.com>
```


title: x86_energy_perf_policy(8)

summary: Manage Energy vs. Performance Policy

text:
# x86_energy_perf_policy(8)

## NAME
x86_energy_perf_policy - Manage Energy vs. Performance Policy

## SYNOPSIS
x86_energy_perf_policy [ options ] [ scope ] [field value]

scope: --cpu cpu-list | --pkg pkg-list

cpu-list, pkg-list: # | #,# | #-# | all

field: --all | --epb | --hwp-epp | --hwp-min | --hwp-max | --hwp-desired

other: (--force | --hwp-enable | --turbo-enable) value)

value: # | default | performance | balance-performance | balance-power | power

## DESCRIPTION
x86_energy_perf_policy displays and updates energy-performance policy settings specific to Intel Architecture Processors. It summarizes settings available in standard Linux interfaces (eg. cpufreq), and also decodes underlying Model Specific Register (MSRs). While x86_energy_perf_policy can manage energy-performance policy using only MSR access, it prefers standard Linux kernel interfaces, when they are available.

## BACKGROUND
Policy in MSR_IA32_ENERGY_PERF_BIAS (EPB) may affect a wide range of hardware decisions, such as how aggressively the hardware enters and exits CPU idle states (C-states) and Processor Performance States (P-states). This policy hint does not replace explicit OS C-state and P-state selection. Rather, it tells the hardware how aggressively to implement those selections. Further, it allows the OS to influence energy/performance trade-offs where there is no software interface, such as in the opportunistic "turbo-mode" P-state range. Note that MSR_IA32_ENERGY_PERF_BIAS is defined per CPU, but some implementations share a single MSR among all CPUs in each processor package. On those systems, a write to EPB on one processor will be visible, and will have an effect, on all CPUs in the same processor package.

Hardware P-States (HWP) are effectively an expansion of hardware P-state control from the opportunistic turbo-mode P-state range to include the entire range of available P-states. On Broadwell Xeon, the initial HWP implementation, EPB influenced HWP. That influence was removed in subsequent generations, where it was moved to the Energy_Performance_Preference (EPP) field in a pair of dedicated MSRs -- MSR_IA32_HWP_REQUEST and MSR_IA32_HWP_REQUEST_PKG.

EPP is the most commonly managed knob in HWP mode, but MSR_IA32_HWP_REQUEST also allows the user to specify minimum-frequency for Quality-of-Service, and maximum-frequency for power-capping. MSR_IA32_HWP_REQUEST is defined per-CPU.

MSR_IA32_HWP_REQUEST_PKG has the same capability as MSR_IA32_HWP_REQUEST, but it can simultaneously set the default policy for all CPUs within a package. A bit in per-CPU MSR_IA32_HWP_REQUEST indicates whether it is over-ruled-by or exempt-from MSR_IA32_HWP_REQUEST_PKG.

MSR_HWP_CAPABILITIES shows the default values for the fields in MSR_IA32_HWP_REQUEST. It is displayed when no values are being written.

### SCOPE OPTIONS
-c, --cpu Operate on the MSR_IA32_HWP_REQUEST for each CPU in a CPU-list. The CPU-list may be comma-separated CPU numbers, with dash for range or the string "all". Eg. '--cpu 1,4,6-8' or '--cpu all'. When --cpu is used, --hwp-use-pkg is available, which specifies whether the per-cpu MSR_IA32_HWP_REQUEST should be over-ruled by MSR_IA32_HWP_REQUEST_PKG (1), or exempt from MSR_IA32_HWP_REQUEST_PKG (0).

-p, --pkg Operate on the MSR_IA32_HWP_REQUEST_PKG for each package in the package-list. The list is a string of individual package numbers separated by commas, and or ranges of package numbers separated by a dash, or the string "all". For example '--pkg 1,3' or '--pkg all'

### VALUE OPTIONS
normal | default Set a policy with a normal balance between performance and energy efficiency. The processor will tolerate minor performance compromise for potentially significant energy savings. This is a reasonable default for most desktops and servers. "default" is a synonym for "normal".

performance Set a policy for maximum performance, accepting no performance sacrifice for the benefit of energy efficiency.

balance-performance Set a policy with a high priority on performance, but allowing some performance loss to benefit energy efficiency.

balance-power Set a policy where the performance and power are balanced. This is the default.

power Set a policy where the processor can accept a measurable performance impact to maximize energy efficiency.

The following table shows the mapping from the value strings above to actual MSR values. This mapping is defined in the Linux-kernel header, msr-index.h.

```
VALUE STRING      	EPB	EPP
performance       	0	0
balance-performance	4	128
normal, default		6	128
balance-power	 	8	192
power       		15	255
```

For MSR_IA32_HWP_REQUEST performance fields (--hwp-min, --hwp-max, --hwp-desired), the value option is in units of 100 MHz, Eg. 12 signifies 1200 MHz.

### FIELD OPTIONS
-a, --all value-string Sets all EPB and EPP and HWP limit fields to the value associated with the value-string. In addition, enables turbo-mode and HWP-mode, if they were previous disabled. Thus "--all normal" will set a system without cpufreq into a well known configuration.

-B, --epb set EPB per-core or per-package. See value strings in the table above.

-d, --debug debug increases verbosity. By default x86_energy_perf_policy is silent for updates, and verbose for read-only mode.

-P, --hwp-epp set HWP.EPP per-core or per-package. See value strings in the table above.

-m, --hwp-min request HWP to not go below the specified core/bus ratio. The "default" is the value found in IA32_HWP_CAPABILITIES.min.

-M, --hwp-max request HWP not exceed a the specified core/bus ratio. The "default" is the value found in IA32_HWP_CAPABILITIES.max.

-D, --hwp-desired request HWP 'desired' frequency. The "normal" setting is 0, which corresponds to 'full autonomous' HWP control. Non-zero performance values request a specific performance level on this processor, specified in multiples of 100 MHz.

-w, --hwp-window specify integer number of microsec in the sliding window that HWP uses to maintain average frequency. This parameter is meaningful only when the "desired" field above is non-zero. Default is 0, allowing the HW to choose.

## OTHER OPTIONS
-f, --force writes the specified values without bounds checking.

-U, --hwp-use-pkg (0 | 1), when used in conjunction with --cpu, indicates whether the per-CPU MSR_IA32_HWP_REQUEST should be overruled (1) or exempt (0) from per-Package MSR_IA32_HWP_REQUEST_PKG settings. The default is exempt.

-H, --hwp-enable enable HardWare-P-state (HWP) mode. Once enabled, system RESET is required to disable HWP mode.

-t, --turbo-enable enable (1) or disable (0) turbo mode.

-v, --version print version and exit.

If no request to change policy is made, the default behavior is to read and display the current system state, including the default capabilities.

## WARNING
This utility writes directly to Model Specific Registers. There is no locking or coordination should this utility be used to modify HWP limit fields at the same time that intel_pstate's sysfs attributes access the same MSRs.

Note that --hwp-desired and --hwp-window are considered experimental. Future versions of Linux reserve the right to access these fields internally -- potentially conflicting with user-space access.

## EXAMPLE

```
# sudo x86_energy_perf_policy
cpu0: EPB 6
cpu0: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
cpu0: HWP_CAP: low 1 eff 8 guar 27 high 35
cpu1: EPB 6
cpu1: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
cpu1: HWP_CAP: low 1 eff 8 guar 27 high 35
cpu2: EPB 6
cpu2: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
cpu2: HWP_CAP: low 1 eff 8 guar 27 high 35
cpu3: EPB 6
cpu3: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
cpu3: HWP_CAP: low 1 eff 8 guar 27 high 35
```

## NOTES
x86_energy_perf_policy runs only as root.

## FILES

```
EPB: /sys/devices/system/cpu/cpu*/power/energy_perf_bias
EPP: /sys/devices/system/cpu/cpu*/cpufreq/energy_performance_preference
MSR: /dev/cpu/*/msr
```

## SEE ALSO

```
msr(4)
Intel(R) 64 and IA-32 Architectures Software Developer's Manual
```

## AUTHORS

```
Len Brown
```


cracklib-check

package: cracklib-utils

title: cracklib-check(8)

summary: Check passwords using libcrack2

text:
# cracklib-check(8)

## NAME
cracklib-check - Check passwords using libcrack2

## SYNOPSIS
cracklib-check [-h|--no-echo]

## DESCRIPTION
cracklib-check takes a list of passwords from stdin and checks them via libcrack2's FascistCheck(3) sub routine.

## OPTIONS
--no-echo

Don't echo the password which is ok to the terminal.

-h, --help

Print help explaining the command line options.

## RESULT
cracklib-check prints each checked password and the corresponding result of FascistCheck(3) to stdout. The password and the result are separated by a colon. When --no-echo is specified, prints only the result if password is ok.

## SEE ALSO
FascistCheck(3)

## AUTHOR
This man page was written by Jan Dittberner <jandd@debian.org> for the Debian GNU/Linux System (but may be used by others).


cracklib-format

title: cracklib-format(8)

summary: cracklib dictionary utilities

text:
# cracklib-format(8)

## NAME
cracklib-format, cracklib-packer, cracklib-unpacker - cracklib dictionary utilities

## SYNOPSIS
cracklib-format file ...

cracklib-packer cracklib_dictpath

cracklib-unpacker cracklib_dictpath

## DESCRIPTION
cracklib-format takes a list of text files each containing a list of words, one per line, It lowercases all words, removes control characters, and sorts the lists. It outputs the cleaned up list to standard output. The text files may be optionally compressed with gzip(1).

If you supply massive amounts of text to cracklib-format you must have enough free space available for use by the sort(1) command. If you do not have 20Mb free in /var/tmp (or whatever temporary area your sort(1) command uses), have a look at the /usr/sbin/cracklib-format program which is a sh(1) program. You can usually tweak the sort(1) command to use any large area of disk you desire, by use of the -T option. cracklib-format has a hook for this.

cracklib-packer reads from standard input a list of sorted and cleaned words and creates a database in the directory and prefix given by the command line argument cracklib_dictpath. Three files are created with the suffixes of .hwm, .pwd, and .pwi. These three files are in the format that the FascistCheck(3) subroutine, cracklib-unpacker(8), and cracklib-check(8), utilities understand. The number of words read and written are printed on stdout(3).

cracklib-unpacker reads from the database in the directory and prefix given by the command line argument cracklib_dictpath and outputs on standard output the list of words that make up the database.

The database is in a binary format generated by the utilities cracklib-format(8) and cracklib-packer(8). On a Debian system the database is located in the directory /var/cache/cracklib/cracklib_dict and is generated daily with the program /etc/cron.daily/cracklib. The location is also defined in the header file crack.h using the constant CRACKLIB_DICTPATH though none of the subroutines in the cracklib libraries have this location hardcoded into their implementations.

## FILES
/var/cache/cracklib/cracklib_dict.[hwm|pwd|pwi]

cracklib dictionary database files used by utilities.

/etc/cron.daily/cracklib

cracklib daily cron program to rebuild the cracklib dictionary database.

/etc/cracklib/cracklib.conf

cracklib configuration file used by the cracklib daily cron program to rebuild the cracklib dictionary database.

/usr/include/crack.h

cracklib header file defining the subroutine FascistCheck(3) and the constant CRACKLIB_DICTPATH used to compile in the location of the cracklib dictionary database for these utilities.

/usr/sbin/cracklib-format

cracklib shell script to create initial list of words for dictionary database.

## SEE ALSO
FascistCheck(3), cracklib-check(8), update-cracklib(8), create-cracklib-dict(8)

/usr/share/doc/libcrack2/libcrack2.html

/usr/share/doc/cracklib-runtime/cracklib-runtime.html

## AUTHOR
cracklib2 is written by Alec Muffett <alecm@crypto.dircon.co.uk>. Manual added by Jean Pierre LeJacq <jplejacq@quoininc.com>.


cracklib-update

title: cracklib-update(8)

summary: Regenerate cracklib dictionary

text:
# cracklib-update(8)

## NAME
update-cracklib - Regenerate cracklib dictionary

## SYNOPSIS
update-cracklib

## DESCRIPTION
update-cracklib builds a compressed and accumulated version of wordlists stored in the directories given in cracklib's configuration file /etc/cracklib/cracklib.conf. Programs using cracklib2 need this database to be of any use.

By default this script is called by cron every day.

## RESULT
update-cracklib prints out two numbers: the number of words read from the ASCII dictionaries and the number of words eventually written into the cracklib database; if no error occurred, these should be equal.

0 is returned on success, otherwise an error message is printed to standard error and -1 is returned.

## FILES
/etc/cracklib/cracklib.conf

shell script that sets cracklib_dictpath_src which must be a space separated list of source dictionary files.

## SEE ALSO
cracklib(3), crack_mkdict(8)

## AUTHOR
This program and manual page was written by Martin Pitt <martin@piware.de> for the Debian GNU/Linux System (but may be used by others).


create-cracklib-dict

title: create-cracklib-dict(8)

summary: Check passwords using libcrack2

text:
# create-cracklib-dict(8)

## NAME
create-cracklib-dict - Check passwords using libcrack2

## SYNOPSIS
create-cracklib-dict wordlist ...

## DESCRIPTION
create-cracklib-dict takes one or more word list files as arguments and converts them into cracklib dictionaries for use by password checking programs. The results are placed in the default compiled-in dictionary location.

If you wish to store the dictionary in a different location, use the cracklib-format and cracklib-packer commands directly.

## SEE ALSO
cracklib-format(8), cracklib-packer(8), cracklib-check(8),

## AUTHOR
This man page was written by Jan Dittberner <jandd@debian.org> for the Debian GNU/Linux System (but may be used by others).


crash

package: crash

title: crash(8)

text:
# crash(8)

## NAME
crash - Analyze Linux crash dump data or a live system

## SYNOPSIS
crash [OPTION]... NAMELIST MEMORY-IMAGE[@ADDRESS] (dumpfile form)

crash [OPTION]... [NAMELIST] (live system form)

## DESCRIPTION
Crash is a tool for interactively analyzing the state of the Linux system while it is running, or after a kernel crash has occurred and a core dump has been created by the netdump, diskdump, LKCD, kdump, xendump kvmdump or VMware facilities. It is loosely based on the SVR4 UNIX crash command, but has been significantly enhanced by completely merging it with the gdb(1) debugger. The marriage of the two effectively combines the kernel-specific nature of the traditional UNIX crash utility with the source code level debugging capabilities of gdb(1).

In the dumpfile form, both a NAMELIST and a MEMORY-IMAGE argument must be entered. In the live system form, the NAMELIST argument must be entered if the kernel's vmlinux file is not located in a known location, such as the /usr/lib/debug/lib/modules/<kernel-version> directory.

The crash utility has also been extended to support the analysis of dumpfiles generated by a crash of the Xen hypervisor. In that case, the NAMELIST argument must be that of the xen-syms binary. Live system analysis is not supported for the Xen hypervisor.

The crash utility command set consists of common kernel core analysis tools such as kernel stack back traces of all processes, source code disassembly, formatted kernel structure and variable displays, virtual memory data, dumps of linked-lists, etc., along with several commands that delve deeper into specific kernel subsystems. Appropriate gdb commands may also be entered, which in turn are passed on to the gdb module for execution. If desired, commands may be placed in either a $HOME/.crashrc file and/or in a .crashrc file in the current directory. During initialization, the commands in $HOME/.crashrc are executed first, followed by those in the ./.crashrc file.

The crash utility is designed to be independent of Linux version dependencies. When new kernel source code impacts the correct functionality of crash and its command set, the utility will be updated to recognize new kernel code changes, while maintaining backwards compatibility with earlier releases.

## OPTIONS
NAMELIST

This is a pathname to an uncompressed kernel image (a vmlinux file), or a Xen hypervisor image (a xen-syms file) which has been compiled with the "-g" option. If using the dumpfile form, a vmlinux file may be compressed in either gzip or bzip2 formats.

MEMORY-IMAGE[@ADDRESS]

A kernel core dump file created by the netdump, diskdump, LKCD kdump, xendump kvmdump or VMware facilities. If a MEMORY-IMAGE argument is not entered, the session will be invoked on the live system, which typically requires root privileges because of the device file used to access system RAM. By default, /dev/crash will be used if it exists. If it does not exist, then /dev/mem will be used; but if the kernel has been configured with CONFIG_STRICT_DEVMEM, then /proc/kcore will be used. It is permissible to explicitly enter /dev/crash, /dev/mem or /proc/kcore.

An @ADDRESS value must be appended to the MEMORY-IMAGE if the dumpfile is a raw RAM dumpfile that has no header information describing the file contents. Multiple MEMORY-IMAGE@ADDRESS ordered pairs may be entered, with each dumpfile containing a contiguous block of RAM, where the ADDRESS value is the physical start address of the block expressed in hexadecimal. The physical address value(s) will be used to create a temporary ELF header in /var/tmp, which will only exist during the crash session. If a raw RAM dumpile represents a live memory source, such as that specified by the QEMU mem-path argument of a memory-backend-file object, then "live:" must be prepended to the MEMORY-IMAGE name.

As VMware facility, the crash utility is able to process VMware VM memory dump generated by VM suspend or guest core dump. In that case, .vmss or .guest file should be used as a MEMORY-IMAGE and .vmem file must be located in the same folder.

mapfile

If the NAMELIST file is not the same kernel that is running (live system form), or the kernel that was running when the system crashed (dumpfile form), then the System.map file of the original kernel should be entered on the command line.

-h [option]

--help [option]

Without an option argument, display a crash usage help message. If the option argument is a crash command name, the help page for that command is displayed. If it is the string "input", a page describing the various crash command line input options is displayed. If it is the string "output", a page describing command line output options is displayed. If it is the string "all", then all of the possible help messages are displayed. After the help message is displayed, crash exits.

-s

Silently proceed directly to the "crash>" prompt without displaying any version, GPL, or crash initialization data during startup, and by default, runtime command output is not passed to any scrolling command.

-i file

Execute the command(s) contained in file prior to displaying the "crash>" prompt for interactive user input.

-d num

Set the internal debug level. The higher the number, the more debugging data will be printed when crash initializes and runs.

-S

Use /boot/System.map as the mapfile.

-e vi | emacs

Set the readline(3) command line editing mode to "vi" or "emacs". The default editing mode is "vi".

-f

Force the usage of a compressed vmlinux file if its original name does not start with "vmlinux".

-k

Indicate that the NAMELIST file is an LKCD "Kerntypes" debuginfo file.

-g [namelist]

Determine if a vmlinux or xen-syms namelist file contains debugging data.

-t

Display the system-crash timestamp and exit.

-L

Attempt to lock all of its virtual address space into memory by calling mlockall(MCL_CURRENT|MCL_FUTURE) during initialization. If the system call fails, an error message will be displayed, but the session continues.

-c tty-device

Open the tty-device as the console used for debug messages.

-p page-size

If a processor's page size cannot be determined by the dumpfile, and the processor default cannot be used, use page-size.

-o filename

Only used with the MEMORY-IMAGE@ADDRESS format for raw RAM dumpfiles, specifies a filename of a new ELF vmcore that will be created and used as the dumpfile. It will be saved to allow future use as a standalone vmcore, replacing the original raw RAM dumpfile.

-m option=value

--machdep option=value

Pass an option and value pair to machine-dependent code. These architecture-specific option/pairs should only be required in very rare circumstances:

```
X86_64:

  phys_base=<physical-address>

  irq_eframe_link=<value>

  irq_stack_gap=<value>

  max_physmem_bits=<value>

  kernel_image_size=<value>

  vm=orig       (pre-2.6.11 virtual memory address ranges)

  vm=2.6.11     (2.6.11 and later virtual memory address ranges)

  vm=xen        (Xen kernel virtual memory address ranges)

  vm=xen-rhel4  (RHEL4 Xen kernel virtual address ranges)

  vm=5level     (5-level page tables)

  page_offset=<PAGE_OFFSET-value>
PPC64:

  vm=orig

  vm=2.6.14     (4-level page tables)
IA64:

  phys_start=<physical-address>

  init_stack_size=<size>

  vm=4l         (4-level page tables)
ARM:

  phys_base=<physical-address>
ARM64:

  phys_offset=<physical-address>

  kimage_voffset=<kimage_voffset-value>

  max_physmem_bits=<value>

  vabits_actual=<value>
X86:

  page_offset=<CONFIG_PAGE_OFFSET-value>
```

-x

Automatically load extension modules from a particular directory. If a directory is specified in the CRASH_EXTENSIONS shell environment variable, then that directory will be used. Otherwise /usr/lib64/crash/extensions (64-bit architectures) or /usr/lib/crash/extensions (32-bit architectures) will be used; if they do not exist, then the ./extensions directory will be used.

--active

Track only the active task on each cpu.

--buildinfo

Display the crash binary's build date, the user ID of the builder, the hostname of the machine where the build was done, the target architecture, the version number, and the compiler version.

--memory_module modname

Use the modname as an alternative kernel module to the crash.ko module that creates the /dev/crash device.

--memory_device device

Use device as an alternative device to the /dev/crash, /dev/mem or /proc/kcore devices.

--log dumpfile

Dump the contents of the kernel log buffer. A kernel namelist argument is not necessary, but the dumpfile must contain the VMCOREINFO data taken from the original /proc/vmcore ELF header. Note: this option is deprecated and will no longer work for kernel(>=v5.10).

--no_kallsyms

Do not use kallsyms-generated symbol information contained within kernel module object files.

--no_modules

Do not access or display any kernel module related information.

--no_ikconf

Do not attempt to read configuration data that was built into kernels configured with CONFIG_IKCONFIG.

--no_data_debug

Do not verify the validity of all structure member offsets and structure sizes that it uses.

--no_kmem_cache

Do not initialize the kernel's slab cache infrastructure, and commands that use kmem_cache-related data will not work.

--no_elf_notes

Do not use the registers from the ELF NT_PRSTATUS notes saved in a compressed kdump header for backtraces.

--kmem_cache_delay

Delay the initialization of the kernel's slab cache infrastructure until it is required by a run-time command.

--readnow

Pass this flag to the embedded gdb module, which will override its two-stage strategy that it uses for reading symbol tables from the NAMELIST.

--smp

Specify that the system being analyzed is an SMP kernel.

-v

--version

Display the version of the crash utility, the version of the embedded gdb module, GPL information, and copyright notices.

--cpus number

Specify the number of cpus in the SMP system being analyzed.

--osrelease dumpfile

Display the OSRELEASE vmcoreinfo string from a kdump dumpfile header.

--build-id dumpfile

Display the BUILD-ID vmcoreinfo string from a kdump dumpfile header. Note: this option only works for kernel (>=v5.9); otherwise it prints "unknown" and exits with non-zero status.

--hyper

Force the session to be that of a Xen hypervisor.

--p2m_mfn pfn

When a Xen Hypervisor or its dom0 kernel crashes, the dumpfile is typically analyzed with either the Xen hypervisor or the dom0 kernel. It is also possible to analyze any of the guest domU kernels if the pfn_to_mfn_list_list pfn value of the guest kernel is passed on the command line along with its NAMELIST and the dumpfile.

--xen_phys_start physical-address

Supply the base physical address of the Xen hypervisor's text and static data for older xendump dumpfiles that did not pass that information in the dumpfile header.

--zero_excluded

If the makedumpfile(8) facility has filtered a compressed kdump dumpfile to exclude various types of non-essential pages, or has marked a compressed or ELF kdump dumpfile as incomplete due to an ENOSPC or other error during its creation, any attempt to read missing pages will fail. With this flag, reads from any of those pages will return zero-filled memory.

--no_panic

Do not attempt to find the task that was running when the kernel crashed. Set the initial context to that of the "swapper" task on cpu 0.

--more

Use /bin/more as the command output scroller, overriding the default of /usr/bin/less and any settings in either ./.crashrc or $HOME/.crashrc.

--less

Use /usr/bin/less as the command output scroller, overriding any settings in either ./.crashrc or $HOME/.crashrc.

--hex

Set the default command output radix to 16, overriding the default radix of 10, and any radix settings in either ./.crashrc or $HOME/.crashrc.

--dec

Set the default command output radix to 10, overriding any radix settings in either ./.crashrc or $HOME/.crashrc. This is the default radix setting.

--CRASHPAGER

Use the output paging command defined in the CRASHPAGER shell environment variable, overriding any settings in either ./.crashrc or $HOME/.crashrc.

--no_scroll

Do not pass run-time command output to any scrolling command.

--no_strip

Do not strip cloned kernel text symbol names.

--no_crashrc

Do not execute the commands in either $HOME/.crashrc or ./.crashrc.

--mod directory

When loading the debuginfo data of kernel modules with the mod -S command, search for their object files in directory instead of in the standard location.

--src directory

Search for the kernel source code in directory instead of in the standard location that is compiled into the debuginfo data.

--kaslr offset|auto

If an x86, x86_64, s390x or loongarch64 kernel was configured with CONFIG_RANDOMIZE_BASE, the offset value is equal to the difference between the symbol values compiled into the vmlinux file and their relocated KASLR values. If set to auto, the KASLR offset value will be automatically calculated.

--reloc size

When analyzing live x86 kernels that were configured with a CONFIG_PHYSICAL_START value that is larger than its CONFIG_PHYSICAL_ALIGN value, then it will be necessary to enter a relocation size equal to the difference between the two values.

--hash count

Set the number of internal hash queue heads used for list gathering and verification. The default count is 32768.

--max-malloc-bufs size

Set the value of MAX_MALLOC_BUFS to size. The minimum allowed value is 3072.

--minimal

Bring up a session that is restricted to the log, dis, rd, sym, eval, set and exit commands. This option may provide a way to extract some minimal/quick information from a corrupted or truncated dumpfile, or in situations where one of the several kernel subsystem initialization routines would abort the crash session.

--kvmhost [32|64]

When examining an x86 KVM guest dumpfile, this option specifies that the KVM host that created the dumpfile was an x86 (32-bit) or an x86_64 (64-bit) machine, overriding the automatically determined value.

--kvmio <size>

override the automatically-calculated KVM guest I/O hole size.

--offline [show|hide]

Show or hide command output that is related to offline cpus. The default setting is show.

## COMMANDS
Each crash command generally falls into one of the following categories:

Symbolic display

Displays of kernel text/data, which take full advantage of the power of gdb to format and display data structures symbolically.

System state

The majority of crash commands consist of a set of "kernel-aware" commands, which delve into various kernel subsystems on a system-wide or per-task basis.

Utility functions

A set of useful helper commands serving various purposes, some simple, others quite powerful.

Session control

Commands that control the crash session itself.

The following alphabetical list consists of a very simple overview of each crash command. However, since individual commands often have several options resulting in significantly different output, it is suggested that the full description of each command be viewed by executing crash -h <command>, or during a crash session by simply entering help command.

*

"pointer to" is shorthand for either the struct or union commands. It displays the contents of a kernel structure or union.

alias

creates a single-word alias for a command.

ascii

displays an ascii chart or translates a numeric value into its ascii components.

bpf

provides information on currently-loaded eBPF programs and maps.

bt

displays a task's kernel-stack backtrace. If it is given the -a option, it displays the stack traces of the active tasks on all CPUs. It is often used with the foreach command to display the backtraces of all tasks with one command.

btop

translates a byte value (physical offset) to its page number.

dev

displays data concerning the character and block device assignments, I/O port usage, I/O memory usage, and PCI device data.

dis

disassembles memory, either entire kernel functions, from a location for a specified number of instructions, or from the start of a function up to a specified memory location.

eval

evaluates an expression or numeric type and displays the result in hexadecimal, decimal, octal and binary.

exit

causes crash to exit.

extend

dynamically loads or unloads crash shared object extension modules.

files

displays information about open files in a context.

foreach

repeats a specified command for the specified (or all) tasks in the system.

fuser

displays the tasks using the specified file or socket.

gdb

passes its argument to the embedded gdb module. It is useful for executing gdb commands that have the same name as crash commands.

help

alone displays the command menu; if followed by a command name, a full description of a command, its options, and examples are displayed. Its output is far more complete and useful than this man page.

ipcs

displays data about the System V IPC facilities.

irq

displays data concerning interrupt request numbers and bottom-half interrupt handling.

kmem

displays information about the use of kernel memory.

list

displays the contents of a linked list.

log

displays the kernel log_buf contents in chronological order.

mach

displays data specific to the machine type.

mod

displays information about the currently installed kernel modules, or adds or deletes symbolic or debugging information about specified kernel modules.

mount

displays information about the currently-mounted filesystems.

net

display various network related data.

p

passes its arguments to the gdb "print" command for evaluation and display.

ps

displays process status for specified, or all, processes in the system.

pte

translates the hexadecimal contents of a PTE into its physical page address and page bit settings.

ptob

translates a page frame number to its byte value.

ptov

translates a hexadecimal physical address into a kernel virtual address.

q

is an alias for the "exit" command.

rd

displays the contents of memory, with the output formatted in several different manners.

repeat

repeats a command indefinitely, optionally delaying a given number of seconds between each command execution.

runq

displays the tasks on the run queue.

sbitmapq

dumps the contents of the sbitmap_queue structure and the used bits in the bitmap. Also, it shows the dump of a structure array associated with the sbitmap_queue.

search

searches a range of user or kernel memory space for given value.

set

either sets a new context, or gets the current context for display.

sig

displays signal-handling data of one or more tasks.

struct

displays either a structure definition or the contents of a kernel structure at a specified address.

swap

displays information about each configured swap device.

sym

translates a symbol to its virtual address, or a static kernel virtual address to its symbol -- or to a symbol-plus-offset value, if appropriate.

sys

displays system-specific data.

task

displays the contents of a task_struct.

tree

displays the contents of a red-black tree or a radix tree.

timer

displays the timer queue entries, both old- and new-style, in chronological order.

union

is similar to the struct command, except that it works on kernel unions.

vm

displays basic virtual memory information of a context.

vtop

translates a user or kernel virtual address to its physical address.

waitq

walks the wait queue list displaying the tasks which are blocked on the specified wait queue.

whatis

displays the definition of structures, unions, typedefs or text/data symbols.

wr

modifies the contents of memory on a live system. It can only be used if /dev/mem is the device file being used to access system RAM, and should obviously be used with great care.

When crash is invoked with a Xen hypervisor binary as the NAMELIST, the command set is slightly modified. The *, alias, ascii, bt, dis, eval, exit, extend, gdb, help, list, log, p, pte, rd, repeat, search, set, struct, sym, sys, union, whatis, wr and q commands are the same as above. The following commands are specific to the Xen hypervisor:

domain

displays the contents of the domain structure for selected, or all, domains.

doms

displays domain status for selected, or all, domains.

dumpinfo

displays Xen dump information for selected, or all, cpus.

pcpus

displays physical cpu information for selected, or all, cpus.

vcpus

displays vcpu status for selected, or all, vcpus.

## FILES
.crashrc

Initialization commands. The file can be located in the user's HOME directory and/or the current directory. Commands found in the .crashrc file in the HOME directory are executed before those in the current directory's .crashrc file.

## ENVIRONMENT
EDITOR

Command input is read using readline(3). If EDITOR is set to emacs or vi then suitable keybindings are used. If EDITOR is not set, then vi is used. This can be overridden by set vi or set emacs commands located in a .crashrc file, or by entering -e emacs on the crash command line.

CRASHPAGER

If CRASHPAGER is set, its value is used as the name of the program to which command output will be sent. If not, then command output is sent to /usr/bin/less -E -X by default.

CRASH_MODULE_PATH

Specifies an alternative directory tree to search for kernel module object files.

CRASH_EXTENSIONS

Specifies a directory containing extension modules that will be loaded automatically if the -x command line option is used.

## NOTES
If crash does not work, look for a newer version: kernel evolution frequently makes crash updates necessary.

The command set scroll off will cause output to be sent directly to the terminal rather than through a paging program. This is useful, for example, if you are running crash in a window of emacs.

## AUTHOR
Dave Anderson <anderson@redhat.com> wrote crash.

Jay Fenlason <fenlason@redhat.com> and Dave Anderson <anderson@redhat.com> wrote this man page.

## SEE ALSO
The help command within crash provides more complete and accurate documentation than this man page.

https://github.com/crash-utility - the home page of the crash utility.

netdump(8), gdb(1), makedumpfile(8)


crda

package: crda

title: crda(8)

text:
# crda(8)

## NAME
crda - send to the kernel a wireless regulatory domain for a given ISO / IEC 3166 alpha2

## SYNOPSIS

crda

## Description
crda is the Linux wireless central regulatory domain agent. crda is intended to be used by udev scripts and should not be run manually unless debugging udev scripts. crda is triggered to run by the kernel by sending a udev event upon a new regulatory domain change. Regulatory domain changes are triggered by the wireless kernel subsystem (upon initialization and on reception of country IEs), wireless drivers, or userspace (see iw ). Upon a regulatory domain change the kernel sends a udev change event for the regulatory platform. The kernel ignores regulatory domains sent to it if it does not expect them. The regulatory domain is read by crda from the regulatory.bin file.

## RSA Digital Signature
If built with openssl or gcrypt support crda will have embedded into it an RSA digital signature which will prevent it from reading corrupted or non-authored regulatory.bin files. Authorship is respected by the RSA public key packed into crda. This specific crda package has been built with RSA public keys from John Linville (the Linux wireless kernel maintainer) and Seth Forshee (the wireless regulatory databse maintainer) and as such will only read regulatory.bin files signed by one of them. For further information see the regulatory.bin man page.

## UDEV RULE
A udev regulatory rule must be put in place in order to receive and parse udev events from the kernel in order to get udev to call crda with the passed ISO / IEC 3166 alpha2 country code. An example udev rule which can be used (usually in /lib/udev/rules.d/85-regulatory.rules ):

KERNEL=="regulatory*", ACTION=="change", SUBSYSTEM=="platform", RUN+="/sbin/crda"

## Environment variable
Set the COUNTRY environment variable with a specific ISO / IEC 3166 alpha2 country code and then run crda without arguments. This will send a regulatory domain for that alpha2 to the kernel.

## SEE ALSO
iw(8) regulatory.bin(5)

http://wireless.kernel.org/en/developers/Regulatory/


regdbdump

title: regdbdump(8)

text:
# regdbdump(8)

## NAME
regdbdump - parse and print out regulatory rules file

## SYNOPSIS

regdbdump <path-to-regulatory.bin>

## Description
regdbdump can be used to parse the regulatory.bin file, the Linux wireless regulatory database used by crda, and print out its contents in human readable format. regdbdump will return non zero if the digital signature regdbdump was built with cannot verify the signature of the regulatory database. Should this happen unintentionally chances are your regulatory.bin file is corrupted or has been tampered with.

## SEE ALSO
regulatory.bin(5) crda(8) iw(8)

http://wireless.kernel.org/en/developers/Regulatory/


title: createrepo_c(8)

text:
# createrepo_c(8)

## NAME
createrepo_c - Create rpm-md format (xml-rpm-metadata) repository

## SYNOPSIS
createrepo_c [options] <directory>

## DESCRIPTION
Uses rpm packages from <directory> to create repodata.

If compiled with libmodulemd support modular metadata inside <directory> identified by the patterns below and all their compressed variants are automatically collected, merged and added to the repodata.

The patterns are:

- *.modulemd.yaml (recommended file name: N:S:V:C:A.modulemd.yaml)

- *.modulemd-defaults.yaml (recommended file name: N.modulemd-defaults.yaml)

- modules.yaml (recommended way of importing multiple documents at once)

## OPTIONS

### -V --version
Show program's version number and exit.

### -q --quiet
Run quietly.

### -v --verbose
Run verbosely.

### -x --excludes PACKAGE_NAME_GLOB
Path patterns to exclude, can be specified multiple times. The patterns are matched against relative paths to RPMs. Note that the feature uses g_pattern_match() function, not glob(), for semantic differences see https://developer.gnome.org/glib/stable/glib-Glob-style-pattern-matching.html

### --basedir BASEDIR
Basedir for path to directories.

### -u --baseurl URL
Optional base URL location for all files.

### -g --groupfile GROUPFILE
Path to groupfile to include in metadata.

### -s --checksum CHECKSUM_TYPE
Choose the checksum type used in repomd.xml and for packages in the metadata. The default is now sha256.

### -p --pretty
Make sure all xml generated is formatted (default)

### -p --no-pretty
Minify the generated xml content. On average this reduces compressed size by 2%.

### -d --database
DEPRECATED: Generate sqlite databases for use with yum.

### --no-database
Do not generate sqlite databases in the repository.

### --update
If metadata already exists in the outputdir and an rpm is unchanged (based on file size and mtime) since the metadata was generated, reuse the existing metadata rather than recalculating it. In the case of a large repository with only a few new or modified rpms this can significantly reduce I/O and processing time.

### --update-md-path
Existing metadata from this path are loaded and reused in addition to those present in the outputdir (works only with --update). Can be specified multiple times.

### --skip-stat
Skip the stat() call on a --update, assumes if the filename is the same then the file is still the same (only use this if you're fairly trusting or gullible).

### --split
Run in split media mode. Rather than pass a single directory, take a set of directories corresponding to different volumes in a media set. Meta data is created in the first given directory

### -i --pkglist FILENAME
Specify a text file which contains the complete list of files to include in the repository from the set found in the directory. File format is one package per line, no wildcards or globs.

### -n --includepkg PACKAGE
Specify pkgs to include on the command line. Takes urls as well as local paths.

### --recycle-pkglist
Useful only with --update. Read the list of packages from old metadata, and reuse it instead of (perhaps expensive) directory traversal. This doesn't collide with explicitly selected packages by --pkglist or --includepkg, such packages are appended to the recycled list. This option is useful for I/O optimal repo modifications (package removal by --exclude, and additions with --pkglist).

### -o --outputdir URL
Optional output directory.

### -S --skip-symlinks
Ignore symlinks of packages.

### --changelog-limit NUM
Only import the last N changelog entries, from each rpm, into the metadata.

### --unique-md-filenames
Include the file's checksum in the metadata filename, helps HTTP caching (default).

### --simple-md-filenames
Do not include the file's checksum in the metadata filename.

### --retain-old-md NUM
Specify NUM to 0 to remove all repodata present in old repomd.xml or any other positive number to keep all old repodata. Use --compatibility flag to get the behavior of original createrepo: Keep around the latest (by timestamp) NUM copies of the old repodata (works only for primary, filelists, other and their DB variants).

### --distro DISTRO
Distro tag and optional cpeid: --distro'cpeid,textname'.

### --content CONTENT_TAGS
Tags for the content in the repository.

### --repo REPO_TAGS
Tags to describe the repository itself.

### --revision REVISION
User-specified revision for this repository.

### --set-timestamp-to-revision
Set timestamp fields in repomd.xml and last modification times of created repodata to a value given with --revision. This requires --revision to be a timestamp formatted in 'date +%s' format.

### --read-pkgs-list READ_PKGS_LIST
Output the paths to the pkgs actually read useful with --update.

### --workers
Number of workers to spawn to read rpms.

### --xz
Use xz for repodata compression.

### --compress-type COMPRESSION_TYPE
Which compression type to use. Supported compressions are: bz2, gz, zck, zstd, xz.

### --general-compress-type COMPRESSION_TYPE
Which compression type to use (even for primary, filelists and other xml).

### --zck
Generate zchunk files as well as the standard repodata.

### --zck-dict-dir ZCK_DICT_DIR
Directory containing compression dictionaries for use by zchunk

### --keep-all-metadata
Keep all additional metadata (not primary, filelists and other xml or sqlite files, nor their compressed variants) from source repository during update (default).

### --discard-additional-metadata
Discard all additional metadata (not primary, filelists and other xml or sqlite files, nor their compressed variants) from source repository during update.

### --compatibility
Enforce maximal compatibility with classical createrepo (Changes --retain-old-md behavior, defaults to Gzip for compression).

### --retain-old-md-by-age AGE
During --update, remove all files in repodata/ which are older then the specified period of time. (e.g. '2h', '30d', ...). Available units (m - minutes, h - hours, d - days)

### -c --cachedir CACHEDIR.
Set path to cache dir

### --local-sqlite
Gen sqlite DBs locally (into a directory for temporary files). Sometimes, sqlite has a trouble to gen DBs on a NFS mount, use this option in such cases. This option could lead to a higher memory consumption if TMPDIR is set to /tmp or not set at all, because then the /tmp is used and /tmp dir is often a ramdisk.

### --cut-dirs NUM
Ignore NUM of directory components in location_href during repodata generation

### --location-prefix PREFIX
Append this prefix before location_href in output repodata

### --repomd-checksum CHECKSUM_TYPE
Checksum type to be used in repomd.xml

### --error-exit-val
Exit with retval 2 if there were any errors during processing (option deprecated, on by default)

### --ignore-lock
Expert (risky) option: Ignore an existing .repodata/. (Remove the existing .repodata/ and create an empty new one to serve as a lock for other createrepo instances. For the repodata generation, a different temporary dir with the name in format .repodata.time.microseconds.pid/ will be used). NOTE: Use this option on your own risk! If two createrepos run simultaneously, then the state of the generated metadata is not guaranteed - it can be inconsistent and wrong.