pcsd

title: pcsd(8)

text:
# pcsd(8)

## NAME
pcsd - pacemaker/corosync configuration system daemon

## SYNOPSIS
pcsd

pcsd --version [--full]

## DESCRIPTION
Daemon for controlling and configuring pacemaker/corosync clusters via pcs.

--version

Print pcsd version information. List pcsd capabilities if --full is specified.

## ENVIRONMENT

### Network and SSL/TLS Settings
PCSD_BIND_ADDR=<string>

List of IP addresses pcsd should bind to delimited by ',' character.

PCSD_PORT=<string>

Port on which pcsd should be available.

PCSD_SSL_OPTIONS=<string>

SSL/TLS options delimited by ',' character. This is usually used to set SSL/TLS protocols accepted by pcsd. List of valid options can be obtained by running: ruby -e 'require "openssl"; puts OpenSSL::SSL.constants.grep /^OP_/'

PCSD_SSL_CIPHERS=<string>

SSL/TLS ciphers accepted by pcsd.

### Web UI Settings
PCSD_SESSION_LIFETIME=<integer>

Web UI session lifetime in seconds.

### Proxy Settings
See ENVIRONMENT section in curl(1) man page for more details.

https_proxy=<string>, HTTPS_PROXY=<string>

Proxy server address for node to node communication.

all_proxy=<string>, ALL_PROXY=<string>

Proxy server address for node to node communication.

no_proxy=<string>, NO_PROXY=<string>

List of hostnames for which proxy is not used.

### Miscellaneous Settings
PCSD_DEBUG=<boolean>

Set to true for advanced pcsd debugging information.

PCSD_RESTART_AFTER_REQUESTS=<integer>

Number of requests after which the Ruby server will be restarted to reduce memory footprint. To disable restarts, set 0, other numbers lower than 50 are interpreted as 50. Invalid values are ignored and the default (200) is set instead.

## FILES
All files described in this section are located in /var/lib/pcsd/. They are not meant to be edited manually unless said otherwise.

### cfgsync_ctl
This JSON file controls pcsd and cluster configuration files synchronization across cluster nodes which pcsd is doing automatically in the background. This file can be safely edited manually.

Example:

{

"file_backup_count": 50,

"thread_disabled": false,

"thread_interval": 600,

"thread_interval_previous_not_connected": 60,

"thread_paused_until": 1487780453

}

file_backup_count

How many backup files should be kept for each synchronized file.

thread_disabled

Set this to true to completely disable the synchronization.

thread_interval

How often in seconds should pcsd ask other nodes if the synchronized files have changed.

thread_interval_previous_not_connected

How often in seconds should pcsd ask other nodes if the synchronized files have changed if during the previous attempt pcsd was unable to connect to at least two nodes.

thread_paused_until

Disable the synchronization until the set unix timestamp.

### known-hosts
This JSON file stores information about hosts known to the local pcsd which are used to login to remote instances of pcsd. Stored information include host addresses, pcsd ports and authentication tokens.

### pcs_settings.conf
This JSON file contains web UI and cluster configuration such as clusters managed from web UI and cluster permissions.

### pcs_users.conf
This JSON file stores authentication tokens accepted by local instance of pcsd.

### pcsd.cookiesecret
Web UI cookie secret.

### pcsd.crt, pcsd.key
These files contain pcsd server certificate and private key.

## SEE ALSO
pcs(8) pcs_snmp_agent(8)

curl(1)

branch: sisyphus


pcscd

package: pcsc-lite

title: pcscd(8)

summary: PC/SC Smart Card Daemon

text:
# pcscd(8)

## NAME
pcscd - PC/SC Smart Card Daemon

## SYNOPSIS
pcscd

[-acfTdeCvHSI] [--apdu] [--config dir] [--foreground] [--color] [--debug] [--info] [--error] [--critical] [--force-reader-polling] [-t number] [--max-thread number] [-s number] [--max-card-handle-per-thread number] [-r number] [--max-card-handle-per-reader number] [--version] [--hotplug] [--reader-name-no-serial] [--reader-name-no-interface] [--disable-polkit]

pcscd

-h

pcscd

--help

## OPTIONS
-a, --apdu

log APDUs and SW using the debug method (see --debug).

-c, --config dir

Specifies the directory dir as an alternate location for /etc/reader.conf.d/. The argument can also be a single configuration file (for backward compatibility).

-f, --foreground

Runs pcscd in the foreground and sends log messages to stderr instead of syslog(3).

-T, --color

force use of colored logs.

-d, --debug

use the lowest log level. Any log message of this level or above will be sent to stderr or syslog(3) depending on the use of --foreground.

--info

use info log level. This is the default log level.

-e, --error

use error log level.

-C, --critical

use critical log level.

The log levels are ordered as: debug < info < error < critical. Use a log level l will log this level and all the levels above it.

--force-reader-polling

ignore the IFD_GENERATE_HOTPLUG reader capability

-t, --max-thread number

maximum number of threads (default 200). This is the maximum number of clients (SCardEstablishContext) that pcscd can handle.

-s, --max-card-handle-per-thread number

maximum number of card handle per thread (default: 200). This is the maximum number of card handle (SCardConnect) per client (SCardEstablishContext).

-r, --max-card-handle-per-reader number

maximum number of card handle per reader (default: 200) This is the maximum number of card handle (SCardConnect) per reader.

-h, --help

Displays information about the pcscd command line

-v, --version

Displays the program version number

-H, --hotplug

Ask pcscd to re-read the /etc/reader.conf.d/my_reader.conf files to detect added or removed non-USB readers (serial or PCMCIA).

-x, --auto-exit

pcscd will quit after 60 seconds of inactivity after the release of the last PC/SC context. This is used when pcscd is started on demand by systemd.

-S, --reader-name-no-serial

Do not include the USB serial number in the reader name.

-I, --reader-name-no-interface

Do not include the USB interface name in the reader name.

--disable-polkit

Ignore polkit rules. All accesses are allowed.

## DESCRIPTION
pcscd is the daemon program for pcsc-lite. It is a resource manager that coordinates communications with smart card readers and smart cards and cryptographic tokens that are connected to the system.

It allows applications to access smart cards and readers using the WinSCard API but without knowing details of the card or reader.

pcscd coordinates the loading of drivers for card readers.

## SERIAL SMART CARD READER DRIVERS
Smart card reader drivers are placed in the /usr/lib64/pcsc/drivers directory. Each driver is simply an .so file. pcscd locates the driver using the /etc/reader.conf.d/my_reader.conf files. See the reader.conf(5) manual page for more information.

Some drivers are available at https://muscle.apdu.fr/musclecard.com/drivers.html.

## USB SMART CARD READER DRIVERS
USB smart card reader drivers are located in /usr/lib64/pcsc/drivers directory as a bundle. You shall NOT add a USB driver in a /etc/reader.conf.d/my_reader.conf file.

## CONFIGURATION FILE
It is possible to set arguments that will be used by pcscd with the configuration file /etc/default/pcscd For example you can increase the debug level using:

```
PCSCD_ARGS=--debug
```

Or set environment variables like:

```
PCSCLITE_FILTER_IGNORE_READER_NAMES="Twin"
PCSCLITE_FILTER_EXTEND_READER_NAMES=" $HOSTNAME"
```

See https://blog.apdu.fr/posts/2021/08/pcsc-lite-configuration-using/ for more details.

## UDEV USB READER FILTERING (LINUX ONLY)
If udev support is enabled, setting the udev property PCSCLITE_IGNORE=1 on a USB device will cause that reader to be ignored. For example to ignore any reader attached to USB port 3 of bus 1, add the following to a foobar.rules file in the /etc/udev/rules.d/ directory:

```
ACTION!="remove|unbind", SUBSYSTEM=="usb", KERNEL=="1-3", ENV{PCSCLITE_IGNORE}="1"
```

## FILES
/etc/default/pcscd : daemon configuration file

/etc/reader.conf.d/* : Serial reader configuration files

/run/pcscd/pcscd.pid : process id of the running pcscd

/usr/lib64/pcsc/drivers/ : directory containing bundles for USB drivers

## SEE ALSO
reader.conf(5), syslog(3), udev(7)

## AUTHORS
David Corcoran <corcoran@musclecard.com> and Ludovic Rousseau <ludovic.rousseau@free.fr>


pdbv

package: pdbv

title: pdbv(8)

text:
# pdbv(8)

## NAME
pdbv - generate a (X)HTML view of the dpkg or rpm database

## SYNOPSIS
pdbv [options]

## DESCRIPTION
This manual page documents the pdbv command. The program generates a navigable view of the dpkg or rpm database of the system it is invoked on. The resulting (X)HTML output can be viewed with a browser.

It starts to look for a file named /etc/pdbv/pdbvrc then for files named $HOME/.pdbvrc and $HOME/.pdbvrc2. Finally it uses command line arguments.

## OPTIONS
The programs follows the usual GNU command line syntax, with long options starting with two dashes (`-'). A summary of options is included below.

-d, --dir=/path

Output directory. A directory called pdbv will be created in there.

--xhtml

Generate XHTML output (default).

--listing=type

Type of listing : basic, group (by section/group), date, all. (this option applies to xhtml/html output) (missing in pdbv 2.0.x)

--light

Run faster but generate a less polished output. For instance, links will not be created from urls and emails. You should not use this option unless pdbv take more than a minute to run.

-f, --force

Update all entries, even if they seem up-to-date.

--debug

Print out debug messages, use warnings.

--cron=delay

Run only if the cron delay specified on the command line is equal to the cron delay specified in the configuration file. This option is used in /etc/cron.d/pdbv

-h, --help

Show summary of options.

--version

Show version of program.

## SEE ALSO
dpkg(8), rpm(8).

## AUTHORS
Mathieu Roy <yeupou@gnu.org>, Paulo Miguel Peralta Ferreira <pmpf@ist.utl.pt>, Federico Montesino Pouzols <fedemp@suidzer0.org>, Arkadiusz Lipiec <A.Lipiec@elka.pw.edu.pl>, Florian M. Weps <fmw@debian.org>.

This manual page was written by Florian M. Weps, for the Debian GNU/Linux system (but may be used by others).


pdnsd

package: pdnsd

title: pdnsd(8)

summary: dns proxy daemon

text:
# pdnsd(8)

## NAME
pdnsd - dns proxy daemon

## SYNOPSIS
pdnsd [-h] [-V] [-s] [-d] [-g] [-t] [-p file] [-vn] [-mxx] [-c file] [-4] [-6] [-a]

This man page is an extract of the documentation of pdnsd. For complete, current documentation, refer to the HTML (or plain text) documentation (which you can find in the doc/ subdirectory of the source or in a standard documentation directory, typically /usr/share/doc/pdnsd/ if you are using a binary package).

## DESCRIPTION
pdnsd is a IPv6 capable proxy domain name server (DNS) which saves the contents of its DNS cache to the disk on exit.

## OPTIONS
-4

enables IPv4 support. IPv6 support is automatically disabled (should it be available). On by default.

-6

enables IPv6 support. IPv4 support is automatically disabled (should it be available). Off by default.

-a

With this option, pdnsd will try to detect automatically if the system supports IPv6, and fall back to IPv4 otherwise.

-V or --version

Print version information and exit.

-c FILE or --config-file=FILE

specifies that configuration is to be read from FILE. Default is /etc/pdnsd.conf.

-d or --daemon

Start pdnsd in daemon mode (as a background process).

-g or --debug

Print some debug messages on the console or to the file pdnsd.debug in your cache directory (in daemon mode).

-h or --help

Print an option summary and exit.

-i PREFIX or --ipv4_6_prefix=PREFIX

specifies the prefix pdnsd uses (when running in IPv6 mode) to map IPv4 addresses in the configuration file to IPv6 addresses. Must be a valid IPv6 address. Default is ::ffff:0.0.0.0

-p FILE

writes the pid the server runs as to the specified filename. Works only in daemon mode.

--pdnsd-user

Print the user pdnsd will run as and exit.

-s or --status

enables the status control socket. Either this option should be passed to the command line or status_ctl=on; should be specified in the config file if you want to use pdnsd-ctl(8) to control pdnsd at runtime.

-t or --tcp

enables the TCP server thread. pdnsd will then serve TCP and UDP queries.

-vn

sets the verbosity of pdnsd. n is a numeric argument between 0 (normal operation) to 3 (many messages for debugging).

-mxx

sets the query method pdnsd uses. Possible values for xx are:

uo - pdnsd will use UDP only. This is the fastest method, and should be supported by all name servers on the Internet.

to - pdnsd will use TCP only. TCP queries usually take more time than UDP queries, but are more secure against certain attacks, where an attacker tries to guess your query id and to send forged answers. TCP queries are not supported by some name servers.

tu - pdnsd will try to use TCP, and will fall back to UDP if its connection is refused or times out.

ut - pdnsd will try to use UDP, and will repeat the query using TCP if the UDP reply was truncated (i.e. the tc bit is set). This is the behaviour recommended by the DNS standards.

Additionally, "no" can be prepended to the --status, --daemon, --debug and --tcp options (e.g. --notcp) to reverse their effect.

## USAGE
pdnsd is usually run from a startup script. For pdnsd to work, You need to:-

1. Tell your system to use pdnsd as the primary DNS server by modifying /etc/resolv.conf.

2. Tell pdnsd to use an authentic source for DNS records, by including the IP addresses of one or more DNS servers, usually your ISP's DNS servers, in /etc/pdnsd.conf.

For this, put the following line in your /etc/resolv.conf

nameserver 127.0.0.X

where X can be any number. (I use 3). Comment out all other entries. You should put the same value in the server_ip= line in global section of /etc/pdnsd.conf.

If you want to use pdnsd as the DNS server for a small local network, you should use the IP address or name of the interface connected to this network instead of 127.0.0.X.

To tell pdnsd where to get DNS information from, add the following lines in /etc/pdnsd.conf:-

server {

label= "myisp";

ip=123.456.789.001,123.456.789.002;

proxy_only=on;

timeout=10;

}

Note the opening and closing braces. Add more such server sections for each set of DNS servers you want pdnsd to query. Of course the configuration options shown here are just examples. More examples can be found in /etc/pdnsd.conf.sample or the pdnsd.conf in the documentation directory. See the pdnsd.conf(5) man page for all the possible options and their exact meaning.

If you use a dial up connection, remember that ppp scripts usually replace /etc/resolv.conf when connection with the ISP is established. You need to configure ppp (or whatever you use to establish a connection) so that /etc/resolv.conf is not replaced every time a connection is established. Read the documentation for the scripts run when your network comes up.

If you use pppconfig, specify `none' in the `nameservers' option in the `advanced' tab. If you use multiple ISPs, you should do this for each connection/account.

If you use multiple ISPs, you should tell pdnsd which DNS servers have become available by calling pdnsd-ctl, the pdnsd control utility, in a script (e.g. /etc/ppp/ip-up when you use pppd) that is run when the connection is established. If the addresses of the DNS servers are obtained through some type of dynamic configuration protocol (e.g. pppd with the usepeerdns option or a DHCP client), you can pass the DNS server addresses as an extra argument to pdnsd-ctl to configure pdnsd at run time. See the pdnsd-ctl(8) man page for details.

## FILES
/etc/pdnsd.conf is the pdnsd configuration file. The file format and configuration options are described in the pdnsd.conf(5) man page. You can find examples of almost all options in /etc/pdnsd.conf.sample.

/var/cache/pdnsd/pdnsd.cache

/var/cache/pdnsd/pdnsd.status is the status control socket, which must be enabled before you can use pdnsd-ctl.

/etc/init.d/pdnsd (the name and location of the start-up script may be different depending on your distribution.)

/etc/resolv.conf

/etc/defaults/pdnsd contains additional parameters or options which may be passed to pdnsd at boot time. This saves the hassle of fiddling with initscripts (not available on all distributions).

## BUGS
The verbosity option -vn presently does not seem to have much effect on the amount of debug output.

Report any remaining bugs to the authors.

## CONFORMING TO
pdnsd should comply with RFCs 1034 and 1035. As of version 1.0.0, RFC compliance has been improved and pdnsd is now believed (or hoped?) to be fully RFC compatible. It completely follows RFC 2181 (except for one minor issue in the FreeBSD port, see the documentation).

It does NOT support the following features, of which most are marked optional, experimental or obsolete in these RFCs:

• Inverse queries

• Status queries

• Completion queries

• Namespaces other than IN (Internet)

• AXFR and IXFR queries (whole zone transfers); since pdnsd does not maintain zones, that should not violate the standard

The following record types, that are extensions to the original DNS standard, are supported if given as options at compile time. (if you do not need them, you do not need to compile support for them into pdnsd and save cache and executable space):

• RP (responsible person, RFC 1183)

• AFSDB (AFS database location, RFC 1183)

• X25 (X25 address, RFC 1183)

• ISDN (ISDN number/address, RFC 1183)

• RT (route through, RFC 1183)

• NSAP (Network Service Access Protocol address , RFC 1348)

• PX (X.400/RFC822 mapping information, RFC 1995)

• GPOS (geographic position, deprecated)

• AAAA (IPv6 address, RFC 1886)

• LOC (location, RFC 1876)

• EID (Nimrod EID)

• NIMLOC (Nimrod locator)

• SRV (service record, RFC 2782)

• ATMA (ATM address)

• NAPTR (URI mapping, RFC 2168)

• KX (key exchange, RFC 2230)

## SEE ALSO
pdnsd-ctl(8), pdnsd.conf(5), pppconfig(8), resolv.conf(5)

More documentation is available in the doc/ subdirectory of the source, or in /usr/share/doc/pdnsd/ if you are using a binary package.

## AUTHORS
pdnsd was originally written by Thomas Moestl, <tmoestl@gmx.net>, and was extensively revised by Paul A. Rombouts <p.a.rombouts@home.nl> (for versions 1.1.8b1-par and later).

Several others have contributed to pdnsd; see files in the source or /usr/share/doc/pdnsd/ directory.

This man page was written by Mahesh T. Pai <paivakil@yahoo.co.in> using the documents in /usr/share/docs/pdnsd/ directory for Debian, but can be used on other distributions too.

Last revised: 22 Jul 2007 by Paul A. Rombouts.

## COPYRIGHT
This man page is a part of the pdnsd package, and may be distributed in original or modified form under terms of the GNU General Public License, as published by the Free Software Foundation; either version 3, or (at your option) any later version.

You can find a copy of the GNU GPL in the file COPYING in the source or the /usr/share/common-licenses/ directory if you are using a Debian system.


pdnsd-ctl

title: pdnsd-ctl(8)

summary: controls pdnsd

text:
# pdnsd-ctl(8)

## NAME
pdnsd-ctl - controls pdnsd

## SYNOPSIS
pdnsd-ctl [-c sockpath] [-q] command [arguments]

## DESCRIPTION
pdnsd-ctl controls pdnsd, a proxy dns server with permanent caching. Note that the status control socket must be enabled (by specifying an option on the pdnsd command line or in the configuration file) before you can use pdnsd-ctl.

-c sockpath

Set the control socket path to sockpath (must match pdnsd setting). This is only necessary if the directory differs from the default specified at compile time.

-q

Be quiet unless output is specified by the command or something goes wrong.

## COMMANDS
help [no arguments]

Print a command summary.

version [no arguments]

Print version and license info.

status [no arguments]

Print a description of pdnsd's cache status, thread status and configuration. Also shows which remote name servers are assumed to be available.

server (index|label) (up|down|retest) [dns1[,dns2[,...]]]

Set the status of the servers with the given index or label to up or down, or force a retest. The index is assigned in the order of definition in pdnsd.conf starting with 0. Use the status command to view the indexes. You can specify all instead of an index to perform the action for all servers registered with pdnsd.

An optional third argument can be given consisting of a list of IP addresses separated by commas or white-space characters. This list will replace the addresses of name servers used by pdnsd for the given server section. This feature is useful for run-time configuration of pdnsd with dynamic DNS data in scripts called by ppp or DHCP clients. The last argument may also be an empty string, which causes existing IP addresses to be removed and the corresponding server section to become inactive.

record name (delete|invalidate)

Delete or invalidate the records of the given domain name if it is in the cache. Invalidation means that the records are marked as timed out, and will be reloaded if possible. For local records (i.e., records that were given in the config file using a rr section, records read from a hosts-style file and records added using pdnsd-ctl), invalidation has no effect. Deletion will work, though.

source fn owner [ttl] [(on|off)] [noauth]

Load a hosts-style file. Works like using the pdnsd source configuration section. Owner and ttl are used as in the source section. ttl has a default of 900 (it does not need to be specified). The next to last argument corresponds to the serve_aliases option, and is off by default. noauth is used to make the domains non-authoritative (this is similar to setting authrec=off in the config file, please consult the pdnsd.conf(5) man page for what that means). fn is the name of the file, which must be readable by pdnsd.

add a addr name [ttl] [noauth]

add aaaa addr name [ttl] [noauth]

add ptr host name [ttl] [noauth]

add cname host name [ttl] [noauth]

add mx host name pref [ttl] [noauth]

Add a record of the given type to the pdnsd cache, replacing existing records for the same name and type. The 2nd argument corresponds to the value of the option in the rr section that is named like the first argument. The addr argument may be a list of IP addresses, separated by commas or white space. The ttl is optional, the default is 900 seconds. noauth is used to make the domains non-authoritative (this is similar to setting authrec=off in the config file, please consult the pdnsd.conf(5) man page for what that means). If you want no other record than the newly added in the cache, do pdnsd-ctl record name delete before adding records.

neg name [type] [ttl]

Add a negatively cached record to pdnsd's cache, replacing existing records for the same name and type. If no type is given, the whole domain is cached negatively. For negatively cached records, errors are immediately returned on a query, without querying other servers first. The ttl is optional, the default is 900 seconds.

config filename

Reload pdnsd's configuration file.

The config file must be owned by the uid that pdnsd had when it was started, and be readable by pdnsd's run_as uid. If no file name is specified, the config file used at start-up is reloaded. Note that some configuration changes, like the port or IP address pdnsd listens on, cannot be made this way and you will receive an error message. In these cases, you will have to restart pdnsd instead.

include filename

Parse an include file.

The include file may contain the same type of sections as a config file, expect for global and server sections, which are not allowed. This command can be used to add data to the cache without reconfiguring pdnsd.

eval string

Parse a string as if part of an include file.

The string should hold one or more complete configuration sections, but no global and server sections, which are not allowed. If multiple strings are given, they will be joined using newline chars and parsed together.

empty-cache [[+|-]name ...]

Delete all entries in the cache matching include/exclude rules.

If no arguments are provided, the cache is completely emptied, freeing all existing entries. Note that this also removes local records, as defined by the config file. To restore local records, run "pdnsd-ctl config" immediately afterwards.

If one or more arguments are provided, these are interpreted as include/exclude names. If an argument starts with a '+' the name is to be included. If an argument starts with a '-' it is to be excluded. If an argument does not begin with '+' or '-', a '+' is assumed. If the domain name of a cache entry ends in one of the names in the list, the first match will determine what happens. If the matching name is to be included, the cache entry is deleted, otherwise it remains. If there are no matches, the default action is not to delete.

dump [name]

Print information stored in the cache about name. If name begins with a dot and is not the root domain, information about the names in the cache ending in name (including name without the leading dot) will be printed. If name is not specified, information about all the names in the cache will be printed.

list-rrtypes [no arguments]

List available rr types for the neg command. Note that those are only used for the neg command, not for add!

## BUGS
If you pipe the output of dump command through an application that reads only part of the output and then blocks (such as more or less), pdnsd threads trying to add new entries to the cache will be suspended until the pipe is closed. It is preferable to capture the output in a file in such a case.

Report any remaining bugs to the authors.

## AUTHORS
Thomas Moestl <tmoestl@gmx.net>

Paul A. Rombouts <p.a.rombouts@home.nl> (for versions 1.1.8b1-par and later)

Last revised: 04 Sep 2008 by Paul A. Rombouts.

## SEE ALSO
pdnsd(8), pdnsd.conf(5)


bitesize

package: perf-tools

title: bitesize(8)

text:
# bitesize(8)

## NAME
bitesize - show disk I/O size as a histogram. Uses Linux perf_events.

## SYNOPSIS
bitesize [-h] [-b buckets] [seconds]

## DESCRIPTION
This can be used to characterize the distribution of block device (disk) I/O sizes. To study block device I/O in more detail, see iosnoop(8).

This uses multiple counting tracepoints with different filters, one for each histogram bucket. While this is summarized in-kernel, the use of multiple tracepoints does add addiitonal overhead, which is more evident if you add more buckets. In the future this functionality will be available in an efficient way in the kernel, and this tool can be rewritten.

## REQUIREMENTS
Linux perf_events: add linux-tools-common, run "perf", then add any additional packages it requests. This also requires the block:block_rq_issue tracepoint, which should already be available in recent kernels.

## OPTIONS
-h

Usage message.

-b buckets

Specify a list of bucket points for the histogram as a string (eg, "10 500 1000"). The histogram will include buckets for less-than the minimum, and greater-than-or-equal-to the maximum. If a single value is specified, two statistics only are gathered: for less-than and for greater-than-or-equal-to. The overhead is relative to the number of buckets, so only specifying a single value costs the lowest overhead.

seconds

Number of seconds to trace. If not specified, this runs until Ctrl-C.

## EXAMPLES
Trace read() syscalls until Ctrl-C, and show histogram of requested size:

\# bitesize syscalls:sys_enter_read count

## FIELDS
Kbytes

Kbyte range of the histogram bucket.

I/O

Number of I/O that occurred in this range while tracing.

Distribution

ASCII histogram representation of the I/O column.

## OVERHEAD
While the counts are performed in-kernel, there is one tracepoint used per histogram bucket, so the overheads are higher than usual (relative to the number of buckets) than function counting using perf stat. The lowest overhead is when -b is used to specify one bucket only, bifurcating statistics.

## SOURCE
This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
iosnoop(8), iolatency(8), iostat(1)


cachestat

title: cachestat(8)

text:
# cachestat(8)

## NAME
cachestat - Measure page cache hits/misses. Uses Linux ftrace.

## SYNOPSIS
cachestat [-Dht] [interval]

## DESCRIPTION
This tool provides basic cache hit/miss statistics for the Linux page cache.

Its current implementation uses Linux ftrace dynamic function profiling to create custom in-kernel counters, which is a workaround until such counters can be built-in to the kernel. Specifically, four kernel functions are counted:

mark_page_accessed() for measuring cache accesses

mark_buffer_dirty() for measuring cache writes

add_to_page_cache_lru() for measuring page additions

account_page_dirtied() for measuring page dirties

It is possible that these functions have been renamed (or are different logically) for your kernel version, and this script will not work as-is. This was written for a Linux 3.13 kernel, and tested on a few others versions. This script is a sandcastle: the kernel may wash some away, and you'll need to rebuild.

This program's implementation can be improved in the future when other kernel capabilities are made available. If you need a more reliable tool now, then consider other tracing alternatives (eg, SystemTap). This tool is really a proof of concept to see what ftrace can currently do.

WARNING: This uses dynamic tracing of kernel functions, and could cause kernel panics or freezes. Test, and know what you are doing, before use. It also traces cache activity, which can be frequent, and cost some overhead. The statistics should be treated as best-effort: there may be some error margin depending on unusual workload types.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
CONFIG_FUNCTION_PROFILER, which you may already have enabled and available on recent kernels, and awk.

## OPTIONS
-D

Include extra fields for debug purposes (see script).

-h

Print usage message.

-t

Include timestamps in units of seconds.

interval

Output interval in seconds. Default is 1.

## EXAMPLES
Show per-second page cache statistics:

\# cachestat

## FIELDS
TIME

Time, in HH:MM:SS.

HITS

Number of page cache hits (reads). Each hit is for one memory page (the size depends on your processor architecture; commonly 4 Kbytes). Since this tool outputs at a timed interval, this field indicates the cache hit rate.

MISSES

Number of page cache misses (reads from storage I/O). Each miss is for one memory page. Cache misses should be causing disk I/O. Run iostat(1) for correlation (although the miss count and size by the time disk I/O is issued can differ due to I/O subsystem merging).

DIRTIES

Number of times a page in the page cache was written to and thus "dirtied". The same page may be counted multiple times per interval, if it is written to multiple times. This field gives an indication of how much cache churn there is, caused by applications writing data.

RATIO

The ratio of cache hits to total cache accesses (hits + misses), as a percentage.

BUFFERS_MB

Size of the buffer cache, for disk I/O. From /proc/meminfo.

CACHED_MB

Size of the page cache, for file system I/O. From /proc/meminfo.

## OVERHEAD
This tool currently uses ftrace function profiling, which provides efficient in-kernel counters. However, the functions profiled are executed frequently, so the overheads can add up. Test and measure before use. My own testing showed around a 2% loss in application performance while this tool was running.

## SOURCE
This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
iostat(1), iosnoop(8)


execsnoop

title: execsnoop(8)

text:
# execsnoop(8)

## NAME
execsnoop - trace process exec() with arguments. Uses Linux ftrace.

## SYNOPSIS
execsnoop [-hrt] [-a argc] [-d secs] [name]

## DESCRIPTION
execsnoop traces process execution, showing PID, PPID, and argument details if possible.

This traces exec() from the fork()->exec() sequence, which means it won't catch new processes that only fork(). With the -r option, it will also catch processes that re-exec. It makes a best-effort attempt to retrieve the program arguments and PPID; if these are unavailable, 0 and "[?]" are printed respectively. There is also a limit to the number of arguments printed (by default, 8), which can be increased using -a.

This implementation is designed to work on older kernel versions, and without kernel debuginfo. It works by dynamic tracing an execve kernel function to read the arguments from the %si register. The stub_execve() function is tried first, and then the do_execve() function. The sched:sched_process_fork tracepoint, is used for the PPID. Tracing registers and kernel functions is an unstable technique, and this tool may not work for some kernels or platforms.

This program is a workaround that should be improved in the future when other kernel capabilities are made available. If you need a more reliable tool now, then consider other tracing alternatives (eg, SystemTap). This tool is really a proof of concept to see what ftrace can currently do.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
FTRACE and KPROBE CONFIG, sched:sched_process_fork tracepoint, and either the stub_execve() or do_execve() kernel function. You may already have these on recent kernels. And awk.

## OPTIONS
-a argc

Maximum number of arguments to show. The default is 8, and the maximum allowed is 16. If execsnoop thinks it has truncated the argument list, an ellipsis "[...]" will be shown.

-d seconds

Duration to trace, in seconds. This also uses in-kernel buffering.

-h

Print usage message.

-r

Include re-exec()s.

-t

Include timestamps in units of seconds.

name

Only show processes that match this name. Partials and regular expressions are allowed, as this is filtered in user space by awk.

## EXAMPLES
Trace all new processes and arguments (if possible):

\# execsnoop

Trace all new process names containing the text "http":

\# execsnoop http

## FIELDS
TIMEs

Time of the exec(), in seconds.

PID

Process ID.

PPID

Parent process ID, if this was able to be read. If it wasn't, 0 is printed.

ARGS

Command line arguments, if these were able to be read. If they aren't able to be read, "[?]" is printed (which would be due to a limitation in this tools implementation, since this is workaround for older kernels; if you need reliable argument tracing, use a different tracer). They will be truncated to the argc limit, and an ellipsis "[...]" may be printed if execsnoop is aware of the truncation.

## OVERHEAD
This reads and processes exec() events in user space as they occur. Since the rate of exec() is expected to be low (< 500/s), the overhead is expected to be small or negligible.

## SOURCE
This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
top(1)


funccount

title: funccount(8)

text:
# funccount(8)

## NAME
funccount - count kernel function calls matching specified wildcards. Uses Linux ftrace.

## SYNOPSIS
funccount [-hT] [-i secs] [-d secs] [-t top] funcstring

## DESCRIPTION
This tool is a quick way to determine which kernel functions are being called, and at what rate. It uses ftrace function profiling capabilities.

WARNING: This uses dynamic tracing of (what can be many) kernel functions, and could cause kernel panics or freezes. Test, and know what you are doing, before use.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
CONFIG_FUNCTION_PROFILER, which you may already have enabled and available on recent kernels, and awk.

## OPTIONS
-d seconds Total duration of the trace.

-h

Print usage message.

-i seconds

Print an interval summary every so many seconds.

-t top

Print top number of entries only.

-T

Include timestamp on each summary.

funcstring

A function name to trace, which may include file glob style wildcards ("*") at the beginning or ending of a string only. Eg, "vfs*" means match "vfs" followed by anything.

## EXAMPLES
Count every kernel function beginning with "bio_", until Ctrl-C is hit:

\# funccount 'bio_*'

Count every "tcp_*" kernel function, and print a summary every one second, five in total:

\# funccount -i 1 -d 5 'tcp_*'

Count every "ext4*" kernel function, and print the top 20 when Ctrl-C is hit:

\# funccount -t 20 'ext4*'

## FIELDS
FUNC

Kernel function name.

COUNT

Number of times this function was called during the tracing interval.

## OVERHEAD
This uses the ftrace profiling framework, which does in-kernel counts, lowering the overhead (compared to tracing each event).

## SOURCE
This is from the perf-tools collection:

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
functrace(8)


funcgraph

title: funcgraph(8)

text:
# funcgraph(8)

## NAME
funcgraph - trace kernel function graph, showing child function calls and times. Uses Linux ftrace.

## SYNOPSIS
funcgraph [-aCDhHPtT] [-m maxdepth] [-p PID] [-L TID] [-d secs] funcstring

## DESCRIPTION
This is an exploratory tool that shows the graph of child function calls for a given kernel function. This can cost moderate overhead to execute, and should only be used to understand kernel behavior before using other, lower overhead tools. This is a proof of concept using Linux ftrace capabilities on older kernels.

The output format is the same as the ftrace function graph trace format, described in the kernel source under Documentation/trace/ftrace.txt. Note that the output may be shuffled when different CPU buffers are read; check the CPU column for changes, or include timestamps (-t) and post sort.

The "-d duration" mode leaves the trace data in the kernel buffer, and only reads it at the end. If the trace data is large, beware of exhausting buffer space (/sys/kernel/debug/tracing/buffer_size_kb) and losing data.

Also beware of feedback loops: tracing tcp* functions over an ssh session, or writing ext4* functions to an ext4 file system. For the former, tcp trace data could be redirected to a file (as in the usage message). For the latter, trace to the screen or a different file system.

WARNING: This uses dynamic tracing of kernel functions, and could cause kernel panics or freezes. Test, and know what you are doing, before use. Also see the OVERHEAD section.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
FTRACE CONFIG, which you may already have enabled and available on recent kernels.

## OPTIONS
-a

All info. Same as -HPt. (But no -T, which isn't available in older kernels.)

-C

Function durations measure on-CPU time only (exclude sleep time).

-d seconds

Set the duration of tracing, in seconds. Trace output will be buffered and printed at the end. This also reduces overheads by buffering in-kernel, instead of printing events as they occur. The ftrace buffer has a fixed size per-CPU (see /sys/kernel/debug/tracing/buffer_size_kb). If you think events are missing, try increasing that size.

-D

Do not show function duration times.

-h

Print usage message.

-H

Print column headers.

-m

Max depth to trace functions. By default, unlimited (0). This feature is only available for newer Linux kernel versions.

-p PID

Only trace kernel functions when this process ID is on-CPU.

-L TID

Only trace kernel functions when this thread ID is on-CPU.

-P

Show process names and process IDs with every line of output.

-t

Show timestamps on every line of output.

-T

Tail mode: decorate function return lines with the name of the function. This option may not be available for older kernels.

funcstring

A function name to trace, which may include file glob style wildcards ("*") at the beginning or ending of a string only. Eg, "vfs*" means match "vfs" followed by anything. Since the output is verbose, you probably only want to trace single functions, and not use wildcards.

## EXAMPLES
Trace calls to do_nanosleep(), showing child functions and durations:

\# funcgraph do_nanosleep

Same as above, but include column headers:

\# funcgraph -H do_nanosleep

Same as above, but include timestamps and process names as well:

\# funcgraph -HtP do_nanosleep

Trace all vfs_read() kernel function calls, and child functions, for PID 198 only:

\# funcgraph -p 198 vfs_read

Trace all vfs_read() kernel function calls, and child functions, for 1 second then write to a file.

\# funcgraph -d 1 vfs_read > out

## FIELDS
The output format depends on the kernel version, and headings can be printed using -H. The format is the same as the ftrace function trace format, described in the kernel source under Documentation/trace/ftrace.txt.

Typical fields are:

TIME

(Shown with -t.) Time of event, in seconds.

CPU

The CPU this event occurred on.

TASK/PID

(Shown with -P.) The process name (which could include dashes), a dash, and the process ID.

DURATION

Elapsed time during the function call, inclusive of children. This is also inclusive of sleep time, unless -C is used. The time is either displayed on the return of a function ("}"), or for a leaf function (no children), on the same line. If the trace output begins with some returns that lack entries, their durations may not be trusted. This is usually only the case for the first dozen or so lines.

FUNCTION CALLS

Entries and returns from kernel functions.

## OVERHEAD
This tool causes moderate to high overheads. Use with caution for exploratory purposes, then switch to lower overhead techniques based on findings. It's expected that the kernel will run at least 50% slower while this tool is running -- even while no output is being generated. This is because ALL kernel functions are traced, and filtered based on the function of interest. When output is generated, it can generate many lines quickly depending on the traced event. Such data will cause performance overheads. This also works without buffering by default, printing function events as they happen (uses trace_pipe), context switching and consuming CPU to do so. If needed, you can try the "-d secs" option, which buffers events instead, reducing overhead. If you think the buffer option is losing events, try increasing the buffer size (buffer_size_kb).

It's a good idea to use funccount(8) first, which is lower overhead, to help you select which functions you may want to trace using funcgraph(8).

## SOURCE
This is from the perf-tools collection:

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
funccount(8), functrace(8), kprobe(8)


funcslower

title: funcslower(8)

text:
# funcslower(8)

## NAME
funcslower - trace kernel functions slower than a threshold (microseconds). Uses Linux ftrace.

## SYNOPSIS
funcslower [-aChHPt] [-p PID] [-L TID] [-d secs] funcstring latency_us

## DESCRIPTION
This uses the Linux ftrace function graph profiler to time kernel functions and filter them based on a latency threshold. Latency outliers can be studied this way, confirming their presence, duration, and rate. This tool is a proof of concept using Linux ftrace capabilities on older kernels.

The output format is based on the ftrace function graph trace format, described in the kernel source under Documentation/trace/ftrace.txt. Use the -H option to print column headings. Note that the output may be shuffled when different CPU buffers are read; check the CPU column for changes, or include timestamps (-t) and post sort.

WARNING: This uses dynamic tracing of kernel functions, and could cause kernel panics or freezes. Test, and know what you are doing, before use.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
FTRACE function graph, which you may already have enabled and available on recent kernels. And awk.

## OPTIONS
-a

All info. Same as -HPt.

-C

Function durations measure on-CPU time only (exclude sleep time).

-d seconds

Set the duration of tracing, in seconds. Trace output will be buffered and printed at the end. This also reduces overheads by buffering in-kernel, instead of printing events as they occur. The ftrace buffer has a fixed size per-CPU (see /sys/kernel/debug/tracing/buffer_size_kb). If you think events are missing, try increasing that size.

-h

Print usage message.

-H

Print column headers.

-p PID

Only trace kernel functions when this process ID is on-CPU.

-L TID

Only trace kernel functions when this thread ID is on-CPU.

-P

Show process names and process IDs with every line of output.

-t

Show timestamps on every line of output.

funcstring

A function name to trace, which may include file glob style wildcards ("*") at the beginning or ending of a string only. Eg, "vfs*" means match "vfs" followed by anything. Since the output is verbose, you probably only want to trace single functions, and not use wildcards.

latency_us

Minimum function duration to trace, in units of microseconds. This is filtered in-kernel.

## EXAMPLES
Trace calls to vfs_read(), showing events slower than 10 ms:

\# funcslower vfs_read 10000

Same as above, but include column headers, event timestamps, and process names:

\# funcslower -HPt vfs_read 10000

Trace slow vfs_read()s for PID 198 only:

\# funcslower -p 198 vfs_read 10000

## FIELDS
The output format depends on the kernel version, and headings can be printed using -H. The format is the same as the ftrace function trace format, described in the kernel source under Documentation/trace/ftrace.txt.

Typical fields are:

TIME

(Shown with -t.) Time of event, in seconds.

CPU

The CPU this event occurred on.

TASK/PID

(Shown with -P.) The process name (which could include dashes), a dash, and the process ID.

DURATION

Elapsed time during the function call, inclusive of children. This is also inclusive of sleep time, unless -C is used.

FUNCTION CALLS

Kernel function returns.

## OVERHEAD
OVERHEADS: Timing and filtering is performed in-kernel context, costing lower overheads than post-processing in user space. If you trace frequent events (eg, pick a common function and a low threshold), you might want to try the "-d secs" option, which buffers events in-kernel instead of printing them live.

It's a good idea to start with a high threshold (eg, "100000" for 100 ms) then to decrease it. If you start low instead, you may start printing too many events.

## SOURCE
This is from the perf-tools collection:

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
funccount(8), functrace(8), funcgraph(8), kprobe(8)


functrace

title: functrace(8)

text:
# functrace(8)

## NAME
functrace - trace kernel function calls matching specified wildcards. Uses Linux ftrace.

## SYNOPSIS
functrace [-hH] [-p PID] [-L TID] [-d secs] funcstring

## DESCRIPTION
This tool provides a quick way to capture the execution of kernel functions, showing basic details including as the process ID, timestamp, and calling function.

WARNING: This uses dynamic tracing of (what can be many) kernel functions, and could cause kernel panics or freezes. Test, and know what you are doing, before use.

Also beware of feedback loops: tracing tcp* functions over an ssh session, or writing ext4* functions to an ext4 file system. For the former, tcp trace data could be redirected to a file (as in the usage message). For the latter, trace to the screen or a different file system.

SEE ALSO: kprobe(8), which can dynamically trace a single function call or return, and examine CPU registers and return values.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
FTRACE CONFIG, which you may already have enabled and available on recent kernels.

## OPTIONS
-d seconds

Set the duration of tracing, in seconds. Trace output will be buffered and printed at the end. This also reduces overheads by buffering in-kernel, instead of printing events as they occur. The ftrace buffer has a fixed size per-CPU (see /sys/kernel/debug/tracing/buffer_size_kb). If you think events are missing, try increasing that size.

-h

Print usage message.

-H

Print column headers.

-p PID

Only trace kernel functions when this process ID is on-CPU.

-L TID

Only trace kernel functions when this thread ID is on-CPU.

funcstring

A function name to trace, which may include file glob style wildcards ("*") at the beginning or ending of a string only. Eg, "vfs*" means match "vfs" followed by anything.

## EXAMPLES
Trace calls to do_nanosleep():

\# functrace do_nanosleep

Trace calls to all kernel functions ending in "*sleep":

\# functrace '*sleep'

Trace all "vfs*" kernel function calls for PID 198:

\# functrace -p 198 'vfs*'

Trace all "tcp*" kernel function calls, and output to a file until Ctrl-C:

\# functrace 'tcp*' > out

Trace all "tcp*" kernel function calls, output to a file, for 1 second (buffered):

\# functrace -d 1 'tcp*' > out

## FIELDS
The output format depends on the kernel version, and headings can be printed using -H. The format is the same as the ftrace function trace format, described in the kernel source under Documentation/trace/ftrace.txt.

Typical fields are:

TASK-PID

The process name (which could include dashes), a dash, and the process ID.

CPU#

The CPU ID, in brackets.

||||

Kernel state flags. For example, on Linux 3.16 these are for irqs-off, need-resched, hardirq/softirq, and preempt-depth.

TIMESTAMP

Time of event, in seconds.

FUNCTION

Kernel function name.

## OVERHEAD
This can generate a lot of trace data quickly, depending on the frequency of the traced events. Such data will cause performance overheads. This also works without buffering by default, printing function events as they happen (uses trace_pipe), context switching and consuming CPU to do so. If needed, you can try the "-d secs" option, which buffers events instead, reducing overhead. If you think the buffer option is losing events, try increasing the buffer size (buffer_size_kb).

It's a good idea to use funccount(8) first, which is lower overhead, to help you select which functions you may want to trace using functrace(8).

## SOURCE
This is from the perf-tools collection:

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
funccount(8), kprobe(8)


iolatency

title: iolatency(8)

text:
# iolatency(8)

## NAME
iolatency - summarize block device I/O latency as a histogram. Uses Linux ftrace.

## SYNOPSIS
iolatency [-hQT] [-d device] [-i iotype] [interval [count]]

## DESCRIPTION
This shows the distribution of latency, allowing modes and latency outliers to be identified and studied. For more details of block device I/O, use iosnoop(8).

This is a proof of concept tool using ftrace, and involves user space processing and related overheads. See the OVERHEAD section.

NOTE: Due to the way trace buffers are switched per interval, there is the possibility of losing a small number of I/O (usually less than 1%). The summary therefore shows the general distribution, but may be slightly incomplete. If 100% of I/O must be studied, use iosnoop(8) and post-process. Also note that I/O may be missed when the trace buffer is full: see the interval section in OPTIONS.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
FTRACE CONFIG, and the tracepoints block:block_rq_issue and block:block_rq_complete, which you may already have enabled and available on recent Linux kernels. And awk.

## OPTIONS
-d device

Only show I/O issued by this device. (eg, "202,1"). This matches the DEV column in the iolatency output, and is filtered in-kernel.

-i iotype

Only show I/O issued that matches this I/O type. This matches the TYPE column in the iolatency output, and wildcards ("*") can be used at the beginning or end (only). Eg, "*R*" matches all reads. This is filtered in-kernel.

-h

Print usage message.

-Q

Include block I/O queueing time. This uses block I/O queue insertion as the start tracepoint (block:block_rq_insert), instead of block I/O issue (block:block_rq_issue).

-T

Include timestamps with each summary output.

interval

Interval between summary histograms, in seconds. During the interval, trace output will be buffered in-kernel, which is then read and processed for the summary. This buffer has a fixed size per-CPU (see /sys/kernel/debug/tracing/buffer_size_kb). If you think events are missing, try increasing that size (the bufsize_kb setting in iolatency). With the default setting (4 Mbytes), I'd expect this to happen around 50k I/O per summary.

count

Number of summaries to print.

## EXAMPLES
Default output, print a summary of block I/O latency every 1 second:

\# iolatency

Include block I/O queue time:

iolatency -Q

Print 5 x 1 second summaries:

\# iolatency 1 5

Trace reads only:

\# iolatency -i '*R*'

Trace I/O issued to device 202,1 only:

\# iolatency -d 202,1

## FIELDS
>=(ms)

Latency was greater than or equal-to this value, in milliseconds.

<(ms)

Latency was less than this value, in milliseconds.

I/O

Number of block device I/O in this latency range, during the interval.

Distribution

ASCII histogram representation of the I/O column.

## OVERHEAD
Block device I/O issue and completion events are traced and buffered in-kernel, then processed and summarized in user space. There may be measurable overhead with this approach, relative to the block device IOPS.

The overhead may be acceptable in many situations. If it isn't, this tool can be reimplemented in C, or using a different tracer (eg, perf_events, SystemTap, ktap.)

## SOURCE
This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
iosnoop(8), iostat(1)


iosnoop

title: iosnoop(8)

text:
# iosnoop(8)

## NAME
iosnoop - trace block I/O events as they occur. Uses Linux ftrace.

## SYNOPSIS
iosnoop [-hQst] [-d device] [-i iotype] [-p pid] [-n name] [duration]

## DESCRIPTION
iosnoop prints block device I/O events as they happen, with useful details such as PID, device, I/O type, block number, I/O size, and latency.

This traces disk I/O at the block device interface, using the block: tracepoints. This can help characterize the I/O requested for the storage devices and their resulting performance. I/O completions can also be studied event-by-event for debugging disk and controller I/O scheduling issues.

NOTE: Use of a duration buffers I/O, which reduces overheads, but this also introduces a limit to the number of I/O that will be captured. See the duration section in OPTIONS.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
FTRACE CONFIG, and the tracepoints block:block_rq_insert, block:block_rq_issue, and block:block_rq_complete, which you may already have enabled and available on recent Linux kernels. And awk.

## OPTIONS
-d device

Only show I/O issued by this device. (eg, "202,1"). This matches the DEV column in the iosnoop output, and is filtered in-kernel.

-i iotype

Only show I/O issued that matches this I/O type. This matches the TYPE column in the iosnoop output, and wildcards ("*") can be used at the beginning or end (only). Eg, "*R*" matches all reads. This is filtered in-kernel.

-p PID

Only show I/O issued by this PID. This filters in-kernel. Note that I/O may be issued indirectly; for example, as the result of a memory allocation, causing dirty buffers (maybe from another PID) to be written to storage. With the -Q option, the identified PID is more accurate, however, LATms now includes queueing time (see the -Q option).

-n name

Only show I/O issued by processes with this name. Partial strings and regular expressions are allowed. This is a post-filter, so all I/O is traced and then filtered in user space. As with PID, this includes indirectly issued I/O, and -Q can be used to improve accuracy (see the -Q option).

-h

Print usage message.

-Q

Use block I/O queue insertion as the start tracepoint (block:block_rq_insert), instead of block I/O issue (block:block_rq_issue). This makes the following changes: COMM and PID are more likely to identify the origin process, as are -p PID and -n name; STARTs shows queue insert; and LATms shows I/O time including time spent on the block I/O queue.

-s

Include a column for the start time (issue time) of the I/O, in seconds. If the -Q option is used, this is the time the I/O is inserted on the block I/O queue.

-t

Include a column for the completion time of the I/O, in seconds.

duration

Set the duration of tracing, in seconds. Trace output will be buffered and printed at the end. This also reduces overheads by buffering in-kernel, instead of printing events as they occur. The ftrace buffer has a fixed size per-CPU (see /sys/kernel/debug/tracing/buffer_size_kb). If you think events are missing, try increasing that size (the bufsize_kb setting in iosnoop). With the default setting (4 Mbytes), I'd expect this to happen around 50k I/O.

## EXAMPLES
Default output, print I/O activity as it occurs:

\# iosnoop

Buffer for 5 seconds (lower overhead) and write to a file:

\# iosnoop 5 > outfile

Trace based on block I/O queue insertion, showing queueing time:

\# iosnoop -Q

Trace reads only:

\# iosnoop -i '*R*'

Trace I/O issued to device 202,1 only:

\# iosnoop -d 202,1

Include I/O start and completion timestamps:

\# iosnoop -ts

Include I/O queueing and completion timestamps:

\# iosnop -Qts

Trace I/O issued when PID 181 was on-CPU only:

\# iosnoop -p 181

Trace I/O queued when PID 181 was on-CPU (more accurate), and include queue time:

\# iosnoop -Qp 181

## FIELDS
COMM

Process name (command) for the PID that was on-CPU when the I/O was issued, or inserted if -Q is used. See PID. This column is truncated to 12 characters.

PID

Process ID which was on-CPU when the I/O was issued, or inserted if -Q is used. This will usually be the process directly requesting I/O, however, it may also include indirect I/O. For example, a memory allocation by this PID which causes dirty memory from another PID to be flushed to disk.

TYPE

Type of I/O. R=read, W=write, M=metadata, S=sync, A=readahead, F=flush or FUA (force unit access), D=discard, E=secure, N=null (not RWFD).

DEV

Storage device ID.

BLOCK

Disk block for the operation (location, relative to this device).

BYTES

Size of the I/O, in bytes.

LATms

Latency (time) for the I/O, in milliseconds.

## OVERHEAD
By default, iosnoop works without buffering, printing I/O events as they happen (uses trace_pipe), context switching and consuming CPU to do so. This has a limit of about 10,000 IOPS (depending on your platform), at which point iosnoop will be consuming 1 CPU. The duration mode uses buffering, and can handle much higher IOPS rates, however, the buffer has a limit of about 50,000 I/O, after which events will be dropped. You can tune this with bufsize_kb, which is per-CPU. Also note that the "-n" option is currently post-filtered, so all events are traced.

The overhead may be acceptable in many situations. If it isn't, this tool can be reimplemented in C, or using a different tracer (eg, perf_events, SystemTap, ktap.)

## SOURCE
This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
iolatency(8), iostat(1), lsblk(8)


killsnoop

title: killsnoop(8)

text:
# killsnoop(8)

## NAME
killsnoop - trace kill() syscalls with process and signal details. Uses Linux ftrace.

## SYNOPSIS
killsnoop [-hst] [-d secs] [-p pid] [-n name]

## DESCRIPTION
This traces kill() syscalls, showing which process killed which pid and returns the returncode (0 for success, -1 for error).

This implementation is designed to work on older kernel versions, and without kernel debuginfo. It works by dynamic tracing of the return value of kill() and associating it with the previous kill() syscall return. This approach is kernel version specific, and may not work on your version. It is a workaround, and proof of concept for ftrace, until more kernel tracing functionality is available.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
FTRACE and KPROBE CONFIG, syscalls:sys_enter_kill and syscalls:sys_exit_kill kernel tracepoints (you may already have these on recent kernels) and awk.

## OPTIONS
-d secs

Set the duration of tracing, in seconds. Trace output will be buffered and printed at the end. This also reduces overheads by buffering in-kernel, instead of printing events as they occur. The ftrace buffer has a fixed size per-CPU (see /sys/kernel/debug/tracing/buffer_size_kb). If you think events are missing, try increasing that size.

-h

Print usage message.

-n name

Only show processes matching this process name. Partial strings and regular expressions are allowed. This is post-filtered using awk.

-p PID

Only trace this process ID. This is filtered in-kernel.

-s

Use human readable signal names, instead of signal numbers.

-t

Include timestamps, in seconds.

## EXAMPLES
Trace all kill() syscalls with details:

\# killsnoop

Trace kill() syscalls with readable signal names, and times:

\# killsnoop -st

Track kill() syscalls for processes named "httpd":

\# killsnoop -n httpd

## FIELDS
TIMEs

Time of open() completion, in units of seconds.

COMM

Process name (if known) of the process that issued the signal.

PID

Process ID that issued the signal.

TPID

Target PID for the signal.

SIGNAL

Signal number sent to the target process, or name if -s is used.

RETURN

Return status: 0 for success, -1 for failure.

## OVERHEAD
This reads and kill() syscalls as they occur. For high rates of kills (> 500/s), the overhead may begin to be measurable, however, the rate is unlikely to get this high. And if it is: you should investigate why. Test yourself. You can also use the -d mode to buffer output, reducing overheads.

## SOURCE
This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Martin Probst

## SEE ALSO
tpoint(8), execsnoop(8), opensnoop(8)


kprobe

title: kprobe(8)

text:
# kprobe(8)

## NAME
kprobe - trace a given kprobe definition. Kernel dynamic tracing. Uses Linux ftrace.

## SYNOPSIS
kprobe [-FhHsv] [-d secs] [-p PID] [-L TID] kprobe_definition [filter]

## DESCRIPTION
This will create, trace, then destroy a given kprobe definition. See Documentation/trace/kprobetrace.txt in the Linux kernel source for the syntax of a kprobe definition, and "kprobe -h" for examples. With this tool, the probe alias is optional (it will become to kprobe:<funcname> if not specified).

WARNING: This uses dynamic tracing of kernel functions, and could cause kernel panics or freezes, depending on the function traced. Test in a lab environment, and know what you are doing, before use.

Also beware of feedback loops: tracing tcp functions over an ssh session, or writing ext4 functions to an ext4 file system. For the former, tcp trace data could be redirected to a file (as in the usage message). For the latter, trace to the screen or a different file system.

SEE ALSO: functrace(8), which can perform basic tracing (event only) of multiple kernel functions using wildcards.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
FTRACE and KPROBES CONFIG, which you may already have enabled and available on recent kernels.

## OPTIONS
-F

Force. Trace despite warnings. By default the specified kernel function must exist in the available_filter_functions file. This option overrides this check. This might expose you to more unsafe functions, which could cause kernel panics or freezes when traced.

-d seconds

Set the duration of tracing, in seconds. Trace output will be buffered and printed at the end. This also reduces overheads by buffering in-kernel, instead of printing events as they occur. The ftrace buffer has a fixed size per-CPU (see /sys/kernel/debug/tracing/buffer_size_kb). If you think events are missing, try increasing that size.

-h

Print usage message.

-H

Print column headers.

-s

Print kernel stack traces after each event.

-v

Show the kprobe format file only (do not trace), identifying possible variables for use in a custom filter.

-p PID

Only trace kernel functions when this process ID is on-CPU.

-L TID

Only trace kernel functions when this thread ID is on-CPU.

kprobe_definition

A full kprobe definition, as documented by Documentation/trace/kprobetrace.txt in the Linux kernel source. Note that the probe alias name is optional with kprobe(8), and if not specified, the tracepoint will become kprobe:<funcname>. See the EXAMPLES section.

filter

An ftrace filter definition.

## EXAMPLES
These examples may need modification to match your kernel version's function names and platform's register usage. If using platform specific registers becomes too painful in practice, consider a kernel debuginfo-based tracer, which can trace variables names instead. For example, perf_events.

Trace do_sys_open() entry:

\# kprobe p:do_sys_open

Trace do_sys_open() return:

\# kprobe r:do_sys_open

Trace do_sys_open() return value:

\# kprobe 'r:do_sys_open $retval'

Trace do_sys_open() return value, with a custom probe alias "myopen":

\# kprobe 'r:myopen do_sys_open $retval'

Trace do_sys_open() file mode:

\# kprobe 'p:myopen do_sys_open mode=%cx:u16'

Trace do_sys_open() file mode for PID 81:

\# kprobe -p 81 'p:myopen do_sys_open mode=%cx:u16'

Trace do_sys_open() with filename string:

\# kprobe 'p:myopen do_sys_open filename=+0(%si):string'

Trace do_sys_open() for filenames ending in "stat":

\# kprobe 'p:myopen do_sys_open fn=+0(%si):string' 'fn ~ "*stat" '

Trace tcp_retransmit_skb() and show kernel stack traces, showing the path that led to it (can help explain why):

\# kprobe -s 'p:myprobe tcp_retransmit_skb'

## FIELDS
The output format depends on the kernel version, and headings can be printed using -H. The format is the same as the ftrace function trace format, described in the kernel source under Documentation/trace/ftrace.txt.

Typical fields are:

TASK-PID

The process name (which could include dashes), a dash, and the process ID.

CPU#

The CPU ID, in brackets.

||||

Kernel state flags. For example, on Linux 3.16 these are for irqs-off, need-resched, hardirq/softirq, and preempt-depth.

TIMESTAMP

Time of event, in seconds.

FUNCTION

Kernel function name.

## OVERHEAD
This can generate a lot of trace data quickly, depending on the frequency of the traced events. Such data will cause performance overheads. This also works without buffering by default, printing function events as they happen (uses trace_pipe), context switching and consuming CPU to do so. If needed, you can try the "-d secs" option, which buffers events instead, reducing overhead. If you think the buffer option is losing events, try increasing the buffer size (buffer_size_kb).

It's a good idea to use funccount(8) first, which is lower overhead, to help you select which functions you may want to trace using kprobe(8).

## SOURCE
This is from the perf-tools collection:

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
functrace(8), funccount(8)


opensnoop

title: opensnoop(8)

text:
# opensnoop(8)

## NAME
opensnoop - trace open() syscalls with file details. Uses Linux ftrace.

## SYNOPSIS
opensnoop [-htx] [-d secs] [-p pid] [-L tid] [-n name] [filename]

## DESCRIPTION
This traces open() syscalls, showing the file name (pathname) and returned file descriptor number (or -1, for error).

This implementation is designed to work on older kernel versions, and without kernel debuginfo. It works by dynamic tracing of the return value of getname() as a string, and associating it with the following open() syscall return. This approach is kernel version specific, and may not work on your version. It is a workaround, and proof of concept for ftrace, until more kernel tracing functionality is available.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
FTRACE and KPROBE CONFIG, the syscalls:sys_exit_open tracepoint, and the getname() kernel function. You may already have these enabled and available on recent Linux kernels. And awk.

## OPTIONS
-d secs

Set the duration of tracing, in seconds. Trace output will be buffered and printed at the end. This also reduces overheads by buffering in-kernel, instead of printing events as they occur. The ftrace buffer has a fixed size per-CPU (see /sys/kernel/debug/tracing/buffer_size_kb). If you think events are missing, try increasing that size.

-h

Print usage message.

-n name

Only show processes matching this process name. Partial strings and regular expressions are allowed. This is post-filtered using awk.

-p PID

Only trace this process ID. This is filtered in-kernel.

-L TID

Only trace this thread ID. This is filtered in-kernel.

-t

Include timestamps, in seconds.

-x

Only print failed open()s.

filename

Only show open()s which match this filename. Partial strings and regular expressions are allowed. This is post-filtered using awk.

## EXAMPLES
Trace all open() syscalls with details:

\# opensnoop

Only trace open()s for PID 81:

\# opensnoop -p 81

Trace failed open() syscalls:

\# opensnoop -x

Trace open() syscalls for filenames containing "conf":

\# opensnoop conf

Trace open() syscalls for filenames ending in "log":

\# opensnoop 'log$'

## FIELDS
TIMEs

Time of open() completion, in units of seconds.

COMM

Process name (if known).

PID

Process ID.

FD

File descriptor. If this is a successful open, the file descriptor number is shown. If this is unsuccessful, -1 is shown. Numbers beginning with 0x are hexadecimal.

FILE

Filename (pathname) used by the open() syscall.

## OVERHEAD
This reads and open() syscalls and getname() kernel functions as they occur. For high rates of opens (> 500/s), the overhead may begin to be measurable. Test yourself. You can use the -d mode to buffer output, reducing overheads.

## SOURCE
This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
execsnoop(8), strace(1)


perf-stat-hist

title: perf-stat-hist(8)

text:
# perf-stat-hist(8)

## NAME
perf-stat-hist - histogram summary of tracepoint values. Uses Linux perf_events.

## SYNOPSIS
perf-stat-hist [-h] [-b buckets|-P power] [-m max] tracepoint variable [seconds]

## DESCRIPTION
This is a proof-of-concept showing in-kernel histograms using Linux perf_events (aka the "perf" command), on older kernels where perf_events does not have this native capability.

These histograms show the distribution of variable, allowing details including multiple modes and outliers to be studied.

This uses multiple counting tracepoints with different filters, one for each histogram bucket. While this is summarized in-kernel, the use of multiple tracepoints does add addiitonal overhead. Hopefully, in the future this this functionality will be provided in an efficient way from perf_events itself, at which point this tool can be deleted or rewritten.

## REQUIREMENTS
Linux perf_events: add linux-tools-common, run "perf", then add any additional packages it requests. Also uses awk.

## OPTIONS
-h

Usage message.

-b buckets

Specify a list of bucket points for the histogram as a string (eg, "10 500 1000"). The histogram will include buckets for less-than the minimum, and greater-than-or-equal-to the maximum. If a single value is specified, two statistics only are gathered: for less-than and for greater-than-or-equal-to. The overhead is relative to the number of buckets, so only specifying a single value costs the lowest overhead.

-P power

Power for power-of histogram. By default, a power-of-4 histogram is created. This and the -b option are exclusive.

-m max

Max value for power-of histograms.

tracepoint

Tracepoint specification. Eg, syscalls:sys_enter_read.

variable

The tracepoint variable name to summarize. To see what are available, cat the format file under /sys/kernel/debug/tracing/events/*/*/format.

seconds

Number of seconds to trace. If not specified, this runs until Ctrl-C.

## EXAMPLES
Trace read() syscalls until Ctrl-C, and show histogram of requested size:

\# perf-stat-hist syscalls:sys_enter_read count

Trace read() syscall completions until Ctrl-C, and show histogram of successful returned size:

\# perf-stat-hist syscalls:sys_exit_read ret

Trace read() return sizes for 10 seconds, showing histogram:

\# perf-stat-hist syscalls:sys_exit_read ret 10

Trace network transmits until Ctrl-C, and show histogram of packet size:

\# perf-stat-hist net:net_dev_xmit len

Trace read() return sizes, using a power-of-10 histogram:

perf-stat-hist -P 10 syscalls:sys_exit_read ret

Trace read() return sizes, using a power-of-2 histogram, and a max of 1024:

perf-stat-hist -P 2 -m 1024 syscalls:sys_exit_read ret

Trace read() return sizes, using the specified bucket points:

perf-stat-hist -b "10 50 100 5000" syscalls:sys_exit_read ret

Trace read() return sizes, and bifurcate statistics by the value 10:

perf-stat-hist -b 10 syscalls:sys_exit_read ret

## FIELDS
Range

Range of the histogram bucket, in units of the variable specified.

Count

Number of occurrences (tracepoint events) of the variable in this range.

Distribution

ASCII histogram representation of the Count column.

## OVERHEAD
While the counts are performed in-kernel, there is one tracepoint used per histogram bucket, so the overheads are higher than usual (relative to the number of buckets) than function counting using perf stat. The lowest overhead is when -b is used to specify one bucket only, bifurcating statistics.

## SOURCE
This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
perf(1)


reset-ftrace

title: reset-ftrace(8)

text:
# reset-ftrace(8)

## NAME
reset-ftrace - reset state of ftrace, disabling all tracing. Written for Linux ftrace.

## SYNOPSIS
reset-ftrace [-fhq]

## DESCRIPTION
This resets the state of various ftrace files, and shows the before and after state.

This may only be of use to ftrace hackers who, in the process of developing ftrace software, often get the subsystem into a partially active state, and would like a quick way to reset state. Check the end of this script for the actually files reset, and add more if you need.

WARNING: Only use this if and when you are sure that there are no other active ftrace sessions on your system, as otherwise it will kill them.

## REQUIREMENTS
FTRACE CONFIG.

## OPTIONS
-f

Force. If the ftrace lock file exists (/var/tmp/.ftrace-lock), delete it.

-h

Print usage message.

-q

Quiet. Run, but don't print any output.

## EXAMPLES
Reset various ftrace files:

\# reset-ftrace

## SOURCE
This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
perf(1)


syscount

title: syscount(8)

text:
# syscount(8)

## NAME
syscount - count system calls. Uses Linux perf_events.

## SYNOPSIS
syscount [-chv] [-t top] {-p PID|-d seconds|command}

## DESCRIPTION
This is a proof-of-concept using perf_events capabilities for older kernel versions, that lack custom in-kernel aggregations. Once they exist, this script can be substantially rewritten and improved (lower overhead).

## REQUIREMENTS
Linux perf_events: add linux-tools-common, run "perf", then add any additional packages it requests. Also needs awk.

## OPTIONS
-c

Show counts by syscall name. This mode (without -v) uses in-kernel counts, which have lower overhead than the default mode.

-h

Usage message.

-v

Verbose: include PID.

-p PID

Trace this process ID only.

-d seconds

Duration of trace in seconds.

command

Run and trace this command.

## EXAMPLES
Trace and summarize syscalls by process name:

\# syscount

Trace and summarize syscalls by syscall name (lower overhead):

\# syscount -c

Trace for 5 seconds, showing by process name:

\# syscount -d 5

Trace PID 932 only, and show by syscall name (lower overhead):

\# syscount -cp 923

Execute the """ls""" command, and show by syscall name:

\# syscount -c ls

## FIELDS
PID

Process ID.

COMM

Process command name.

SYSCALL

Syscall name.

COUNT

Number of syscalls during tracing.

## OVERHEAD
Modes that report syscall names only (-c, -cp PID, -cd secs) have lower overhead, since they use in-kernel counts. Other modes which report process IDs (-cv) or process names (default) create a perf.data file for post processing, and you will see messages about it doing this. Beware of the file size (test for short durations, or use -c to see counts based on in-kernel counters), and gauge overheads based on the perf.data size.

Note that this script delibrately does not pipe perf record into perf script, which would avoid perf.data, because it can create a feedback loop where the perf script syscalls are recorded. Hopefully there will be a fix for this in a later perf version, so perf.data can be skipped, or other kernel features to aggregate by process name in-kernel directly (eg, via eBPF, ktap, or SystemTap).

## SOURCE
This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
iosnoop(8), iolatency(8), iostat(1)


tcpretrans

title: tcpretrans(8)

text:
# tcpretrans(8)

## NAME
tcpretrans - show TCP retransmits, with address and other details. Uses Linux ftrace.

## SYNOPSIS
tcpretrans [-hsp]

## DESCRIPTION
This traces TCP retransmits that are sent by the system tcpretrans is executed from, showing address, port, and TCP state information, and sometimes the PID (although usually not, since retransmits are usually sent by the kernel on timeout events). To keep overhead low, only tcp_retransmit_skb() kernel calls are traced (this does not trace every packet).

This was written as a proof of concept for ftrace, for older Linux systems, and without kernel debuginfo. It uses dynamic tracing of tcp_retransmit_skb(), and reads /proc/net/tcp for socket details. Its use of dynamic tracing and CPU registers is an unstable platform-specific workaround, and may require modifications to work on different kernels and platforms. This would be better written using a tracer such as SystemTap, and will likely be rewritten in the future when certain tracing features are added to the Linux kernel.

When -l is used, this also uses dynamic tracing of tcp_send_loss_probe() and a register.

Currently only IPv4 is supported, on x86_64. If you try this on a different architecture, you'll likely need to adjust the register locations (search for %di).

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
FTRACE and KPROBE CONFIG, tcp_retransmit_skb() kernel function. You may have these already have these on recent kernels. And Perl. TCP tail loss probes were added in Linux 3.10.

## OPTIONS
-h

Print usage message.

-s

Include kernel stack traces.

-l

Include TCP tail loss probes.

## EXAMPLES
Trace TCP retransmits

\# tcpretrans

TIME

Time of retransmit (may be rounded up to the nearest second).

PID

Process ID that was on-CPU. This is less useful than it might sound, as it may usually be 0, for the kernel, for timer-based retransmits.

LADDR

Local address.

LPORT

Local port.

--

Packet type: "R>" for retransmit, and "L>" for tail loss probe.

RADDR

Remote address.

RPORT

Remote port.

STATE

TCP session state.

## OVERHEAD
The CPU overhead is relative to the rate of TCP retransmits, and is designed to be low as this does not examine every packet. Once per second the /proc/net/tcp file is read, and a buffer of retransmit trace events is retrieved from the kernel and processed.

## SOURCE
This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
tcpdump(1)


tpoint

title: tpoint(8)

text:
# tpoint(8)

## NAME
tpoint - trace a given tracepoint. Static tracing. Uses Linux ftrace.

## SYNOPSIS
tpoint [-hHsv] [-d secs] [-p PID] [-L TID] tracepoint [filter]

tpoint -l

## DESCRIPTION
This will enable a given tracepoint, print events, then disable the tracepoint when the program ends. This is like a simple version of the "perf" command for printing live tracepoint events only. Wildcards are currently not supported. If for any reason tpoint(8) is insufficient, use the more powerful perf command for tracing tracepoints instead.

Beware of feedback loops: tracing tcp functions over an ssh session, or writing ext4 events to an ext4 file system. For the former, tcp trace data could be redirected to a file (as in the usage message). For the latter, trace to the screen or a different file system.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
FTRACE CONFIG and tracepoints, which you may already have enabled and available on recent kernels.

## OPTIONS
-d seconds

Set the duration of tracing, in seconds. Trace output will be buffered and printed at the end. This also reduces overheads by buffering in-kernel, instead of printing events as they occur. The ftrace buffer has a fixed size per-CPU (see /sys/kernel/debug/tracing/buffer_size_kb). If you think events are missing, try increasing that size.

-h

Print usage message.

-H

Print column headers.

-l

List tracepoints only.

-s

Print kernel stack traces after each event.

-v

Show the tpoint format file only (do not trace), identifying possible variables for use in a custom filter.

-p PID

Only trace kernel functions when this process ID is on-CPU.

-L TID

Only trace kernel functions when this thread ID is on-CPU.

tracepoint

A tracepoint name. Eg, block:block_rq_issue. See the EXAMPLES section.

filter

An ftrace filter definition.

## EXAMPLES
List tracepoints containing "open":

\# tpoint -l | grep open

Trace open() syscall entry:

\# tpoint syscalls:sys_enter_open

Trace open() syscall entry, showing column headers:

\# tpoint -H syscalls:sys_enter_open

Trace block I/O issue:

\# tpoint block:block_rq_issue

Trace block I/O issue with stack traces:

\# tpoint -s block:block_rq_issue

## FIELDS
The output format depends on the kernel version, and headings can be printed using -H. The format is the same as the ftrace function trace format, described in the kernel source under Documentation/trace/ftrace.txt.

Typical fields are:

TASK-PID

The process name (which could include dashes), a dash, and the process ID.

CPU#

The CPU ID, in brackets.

||||

Kernel state flags. For example, on Linux 3.16 these are for irqs-off, need-resched, hardirq/softirq, and preempt-depth.

TIMESTAMP

Time of event, in seconds.

FUNCTION

Kernel function name.

## OVERHEAD
This can generate a lot of trace data quickly, depending on the frequency of the traced events. Such data will cause performance overheads. This also works without buffering by default, printing function events as they happen (uses trace_pipe), context switching and consuming CPU to do so. If needed, you can try the "-d secs" option, which buffers events instead, reducing overhead. If you think the buffer option is losing events, try increasing the buffer size (buffer_size_kb).

Before using tpoint(8), you can use perf_events to count the rate of events for the tracepoint of interest, to gauge overhead. For example:

perf stat -e block:block_rq_issue -a sleep 5

That counts the occurrences of the block:block_rq_issue tracepoint for 5 seconds.

Also consider using perf_events, which manages buffers differently and more efficiently, for higher frequency applications.

## SOURCE
This is from the perf-tools collection:

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
functrace(8), funccount(8), perf(1)


uprobe

title: uprobe(8)

text:
# uprobe(8)

## NAME
uprobe - trace a given uprobe definition. User-level dynamic tracing. Uses Linux ftrace. EXPERIMENTAL.

## SYNOPSIS
uprobe [-FhHsv] [-d secs] [-p PID] [-L TID] {-l target | uprobe_definition [filter]}

## DESCRIPTION
This will create, trace, then destroy a given uprobe definition. See Documentation/trace/uprobetracer.txt in the Linux kernel source for the syntax of a uprobe definition, and "uprobe -h" for examples. With this tool, the probe alias is optional (it will default to something meaningful).

WARNING: This uses dynamic tracing of user-level functions, using some relatively new kernel code. I have seen this cause target processes to fail, either entering endless spin loops or crashing on illegal instructions. I believe newer kernels (post 4.0) are relatively safer, but use caution. Test in a lab environment, and know what you are doing, before use. Also consider other (more developed) user-level tracers (perf_events, LTTng, etc.).

Use extreme caution with the raw address mode: eg, "p:libc:0xbf130". uprobe does not check for instruction alignment, so tracing the wrong address (eg, mid-way through a multi-byte instruction) will corrupt the target's memory. Other tracers (eg, perf_events with debuginfo) check alignment.

Also beware of widespread tracing that interferes with the operation of the system, eg, tracing libc:malloc, which by-default will trace _all_ processes.

I wrote this because I kept testing different custom uprobes at the command line, and wanted a way to automate the steps. For generic user-level tracing, use perf_events directly.

Since this uses ftrace, only the root user can use this tool.

## REQUIREMENTS
REQUIREMENTS: FTRACE and UPROBE CONFIG, which you may already have on recent kernel versions, file(1), ldconfig(8), objdump(1), and some version of awk. Also, currently only executes on Linux 4.0+ (see WARNING) unless -F is used.

## OPTIONS
-F

Force. Trace despite kernel version warnings. Use on older kernels may expose you to (since fixed) bugs, which can lock up or crash target processes, which could also lock up the entire system. Test in a lab environment before use, and consider other more developed user-level tracers (perf_events, LTTng, etc.).

-d seconds

Set the duration of tracing, in seconds. Trace output will be buffered and printed at the end. This also reduces overheads by buffering in-kernel, instead of printing events as they occur. The ftrace buffer has a fixed size per-CPU (see /sys/kernel/debug/tracing/buffer_size_kb). If you think events are missing, try increasing that size.

-h

Print usage message.

-H

Print column headers.

-s

Print user-level stack traces after each event. These are currently printed in hex, and need post-processing to see user-level symbols (eg, addr2line; I should automate that).

-v

Show the uprobe format file only (do not trace), identifying possible variables for use in a custom filter.

-p PID

Only trace user-level functions when this process ID is on-CPU.

-L TID

Only trace user-level functions when this thread ID is on-CPU.

uprobe_definition

A full uprobe definition, as documented by Documentation/trace/uprobetracer.txt in the Linux kernel source. Note that the probe alias name is optional with uprobe(8), and if not specified, it will default to something meaningful. See the EXAMPLES section.

filter

An ftrace filter definition.

## EXAMPLES
These examples may need modification to match your target software function names and platform's register usage. If using platform specific registers becomes too painful in practice, consider a debuginfo-based tracer, which can trace variables names instead (eg, perf_events).

trace readline() calls in all running "bash" executables:

\# uprobe p:bash:readline

trace readline() with explicit executable path:

\# uprobe p:/bin/bash:readline

trace the return of readline() with return value as a string:

\# uprobe 'r:bash:readline +0($retval):string'

trace sleep() calls in all running libc shared libraries:

\# uprobe p:libc:sleep

trace sleep() with register %di (x86):

\# uprobe 'p:libc:sleep %di'

trace this address (use caution: must be instruction aligned):

\# uprobe p:libc:0xbf130

trace gettimeofday() for PID 1182 only:

\# uprobe -p 1182 p:libc:gettimeofday

trace the return of fopen() only when it returns NULL:

\# uprobe 'r:libc:fopen file=$retval' 'file == 0'

## FIELDS
The output format depends on the kernel version, and headings can be printed using -H. The format is the same as the ftrace function trace format, described in the kernel source under Documentation/trace/ftrace.txt.

Typical fields are:

TASK-PID

The process name (which could include dashes), a dash, and the process ID.

CPU#

The CPU ID, in brackets.

||||

Kernel state flags. For example, on Linux 3.16 these are for irqs-off, need-resched, hardirq/softirq, and preempt-depth.

TIMESTAMP

Time of event, in seconds.

FUNCTION

User-level function name.

## OVERHEAD
This can generate a lot of trace data quickly, depending on the frequency of the traced events. Such data will cause performance overheads. This also works without buffering by default, printing function events as they happen (uses trace_pipe), context switching and consuming CPU to do so. If needed, you can try the "-d secs" option, which buffers events instead, reducing overhead. If you think the buffer option is losing events, try increasing the buffer size (buffer_size_kb).

If you find a use for uprobe(8) where the overhead is prohibitive, consider the same enabling using perf_events where overhead should be reduced.

## SOURCE
This is from the perf-tools collection:

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
kprobe(8)


photorec

package: photorec

title: photorec(8)

text:
# photorec(8)

## NAME
photorec - Recover lost files from harddisk, digital camera and cdrom

## SYNOPSIS
photorec [/log] [/debug] [/d recup_dir] [device|image.dd|image.e01]

photorec /version

## DESCRIPTION

PhotoRec is file data recovery software designed to recover lost files including video, documents and archives from Hard Disks and CDRom and lost pictures (Photo Recovery) from digital camera memory. PhotoRec ignores the filesystem and goes after the underlying data, so it'll work even if your media's filesystem is severely damaged or formatted. PhotoRec is safe to use, it will never attempt to write to the drive or memory support you are about to recover lost data from.

For more information on how to use, please visit the wiki pages on www.cgsecurity.org

## OPTIONS
/log

create a photorec.log file

/debug

add debug information

## SEE ALSO
testdisk(8), fdisk(8).

## AUTHOR
PhotoRec 7.2, Data Recovery Utility, February 2024

Christophe GRENIER <grenier@cgsecurity.org>

https://www.cgsecurity.org


title: php-fpm8.2.32(8)

summary: PHP FastCGI Process Manager 'PHP-FPM'

text:
# php-fpm8.2.32(8)

## NAME
php7-fpm - PHP FastCGI Process Manager 'PHP-FPM'

## SYNOPSIS
php8.2-fpm [options]

## DESCRIPTION
PHP is a widely-used general-purpose scripting language that is especially suited for Web development and can be embedded into HTML. This is a variant of PHP that will run in the background as a daemon, listening for CGI requests. Output is logged to /var/log/php8.2-fpm.log.

Most options are set in the configuration file. The configuration file is /etc/php-fpm.conf. By default, php8.2-fpm will respond to CGI requests listening on localhost http port 9000. Therefore php7-fpm expects your webserver to forward all requests for '.php' files to port 9000 and you should edit your webserver configuration file appropriately.

## OPTIONS
-C

Do not chdir to the script's directory

--php-ini path|file

-c path|file

Look for php.ini file in the directory path or use the specified file

--no-php-ini

-n

No php.ini file will be used

--define foo[=bar]

-d foo[=bar]

Define INI entry foo with value bar

-e

Generate extended information for debugger/profiler

--help

-h

This help

--info

-i

PHP information and configuration

--modules

-m

Show compiled in modules

--version

-v

Version number

--prefix path

-p

Specify alternative prefix path (the default is /usr)

--pid file

-g

Specify the PID file location.

--fpm-config file

-y

Specify alternative path to FastCGI process manager configuration file (the default is /etc/fpm/php8.2-fpm.conf)

--test

-t

Test FPM configuration file and exit If called twice (-tt), the configuration is dumped before exiting.

--daemonize

-D

Force to run in background and ignore daemonize option from configuration file.

--nodaemonize

-F

Force to stay in foreground and ignore daemonize option from configuration file.

--force-stderr

-O

Force output to stderr in nodaemonize even if stderr is not a TTY.

--allow-to-run-as-root

-R

Allow pool to run as root (disabled by default)

## FILES
php8.2-fpm.conf

The configuration file for the php7-fpm daemon.

php.ini

The standard php configuration file.

## EXAMPLES
For any unix systems which use init.d for their main process manager, you should use the init script provided to start and stop the php8.2-fpm daemon.

sudo /etc/init.d/php8.2-fpm start

For any unix systems which use systemd for their main process manager, you should use the unit file provided to start and stop the php8.2-fpm daemon.

sudo systemctl start php8.2-fpm.service

If your installation has no appropriate init script, launch php8.2-fpm with no arguments. It will launch as a daemon (background process) by default. The file /var/run/php8.2-fpm.pid determines whether php8.2-fpm is already up and running. Once started, php8.2-fpm then responds to several POSIX signals:

SIGINT,SIGTERM immediate termination SIGQUIT graceful stop

SIGUSR1 re-open log file

SIGUSR2 graceful reload of all workers + reload of fpm conf/binary

## TIPS
The PHP-FPM CGI daemon will work well with most popular webservers, including Apache2, lighttpd and nginx.

## SEE ALSO
The PHP-FPM website:

http://php-fpm.org

For a more or less complete description of PHP look here:

http://www.php.net/manual/

A nice introduction to PHP by Stig Bakken can be found here:

http://www.zend.com/zend/art/intro.php

## BUGS
You can view the list of known bugs or report any new bug you found at:

https://github.com/php/php-src/issues

## AUTHORS
PHP-FPM SAPI was written by Andrei Nigmatulin. The mailing-lists are highload-php-en (English) and highload-php-ru (Russian).

The PHP Group: Thies C. Arntzen, Stig Bakken, Andi Gutmans, Rasmus Lerdorf, Sam Ruby, Sascha Schumann, Zeev Suraski, Jim Winstead, Andrei Zmievski.

A List of active developers can be found here:

http://www.php.net/credits.php

And last but not least PHP was developed with the help of a huge amount of contributors all around the world.

## VERSION INFORMATION
This manpage describes php8.2-fpm, version @PHP_VERSION@.

## COPYRIGHT
Copyright © The PHP Group

Copyright (c) 2007-2009, Andrei Nigmatulin

This source file is subject to version 3.01 of the PHP license, that is bundled with this package in the file LICENSE, and is available through the world-wide-web at the following url:

https://www.php.net/license/3_01.txt

If you did not receive a copy of the PHP license and are unable to obtain it through the world-wide-web, please send a note to license@php.net so we can mail you a copy immediately.