avahi-autoipd.action

title: avahi-autoipd.action(8)

summary: avahi-autoipd action script

text:
# avahi-autoipd.action(8)

## NAME
avahi-autoipd.action - avahi-autoipd action script

## SYNOPSIS
/etc/avahi/avahi-autoipd.action

## DESCRIPTION
avahi-autoipd.action is the action script that is called whenever an IP address has been acquired by avahi-autoipd or when it detected an IP address conflict. The script should add or remove the specified address from the specified network interface.

## PARAMETERS
argv[1] An event string: one of BIND, CONFLICT, UNBIND or STOP. If BIND is passed an IP address has been successfully acquired and the script shall add it to the network interface. If CONFLICT is passed avahi-autopid detected a IP address on the local network, the action script should remove the configured IP address. If UNBIND is passed the IP address should be removed from the interface, too, because a routable address has been configured to the interface by some other program. If STOP is passed the avahi-autoipd is being shutdown and the action script should remove the IP address. In short: on BIND the address should be added to the interface, on CONFLICT, UNBIND or STOP it should be removed.

argv[2] The network interface name.

argv[3] An IP address from the IPv4LL range.

## AUTHORS
The Avahi Developers <avahi (at) lists (dot) freedesktop (dot) org>; Avahi is available from http://avahi.org/

## SEE ALSO
avahi-autoipd(8), dhclient-script(8), ip(8), ifconfig(8)

## COMMENTS
This man page was written using xml2man(1) by Oliver Kurth.


avahi-daemon

package: avahi-daemon

title: avahi-daemon(8)

summary: The Avahi mDNS/DNS-SD daemon

text:
# avahi-daemon(8)

## NAME
avahi-daemon - The Avahi mDNS/DNS-SD daemon

## SYNOPSIS
avahi-daemon [options]

avahi-daemon --kill

avahi-daemon --reload

avahi-daemon --check

## DESCRIPTION
The Avahi mDNS/DNS-SD daemon implements Apple's Zeroconf architecture (also known as "Rendezvous" or "Bonjour"). The daemon registers local IP addresses and static services using mDNS/DNS-SD and provides two IPC APIs for local programs to make use of the mDNS record cache the avahi-daemon maintains. First there is the so called "simple protocol" which is used exclusively by avahi-dnsconfd (a daemon which configures unicast DNS servers using server info published via mDNS) and nss-mdns (a libc NSS plugin, providing name resolution via mDNS). Finally there is the D-Bus interface which provides a rich object oriented interface to D-Bus enabled applications.

Upon startup avahi-daemon interprets its configuration file /etc/avahi/avahi-daemon.conf and reads XML fragments from /etc/avahi/services/*.service which may define static DNS-SD services. If you enable publish-resolv-conf-dns-servers in avahi-daemon.conf the file /etc/resolv.conf will be read, too.

## OPTIONS
-f | --file= FILE

Specify the configuration file to read. (default: /etc/avahi/avahi-daemon.conf)

-D | --daemonize

Daemonize after startup. Implies --syslog.

-s | --syslog

Log to syslog instead of STDERR. Implied by --daemonize.

--debug

Increase verbosity to debug level.

--no-rlimits

Don't enforce resource limits as specified in the configuration file. (See setrlimit(2) for more information)

--no-drop-root

Don't drop root privileges after startup and don't require daemon to be started as root. We recommend not to use this option.

--no-chroot

Don't chroot(2) the daemon. This option is only available when compiled with chroot() support.

--no-proc-title

Don't change the process name while running. Unless this option is specified avahi-daemon will reflect its current state and the selected host name in the process title.

-k | --kill

Kill an already running avahi-daemon. (equivalent to sending a SIGTERM)

-r | --reload

Tell an already running avahi-daemon to reread /etc/resolv.conf (in case you enabled publish-resolv-conf-dns-servers in avahi-daemon.conf) the files from /etc/avahi/services/. Please note that this will not reload the /etc/avahi/avahi-daemon.conf. (equivalent to sending a SIGHUP)

-c | --check

Return 0 as return code when avahi-daemon is already running.

-h | --help

Show help

-v | --version

Show version information

## FILES
/etc/avahi/avahi-daemon.conf: the default configuration file for avahi-daemon, avahi-daemon.conf(5) for more information.

/etc/avahi/hosts: additional static hostname mappings to publish in mDNS, see avahi.hosts(5) for more information.

/etc/avahi/services/*.service: static service definitions, see avahi.service(5) for more information.

## SIGNALS
SIGINT, SIGTERM: avahi-daemon will shutdown. (Same as --kill).

SIGHUP: avahi-daemon will reload unicast DNS server data from /etc/resolv.conf and static service definitions from /etc/avahi/services/. (Same as --reload)

SIGUSR1: avahi-daemon will dump local and remote cached resource record data to syslog.

## AUTHORS
The Avahi Developers <avahi (at) lists (dot) freedesktop (dot) org>; Avahi is available from http://avahi.org/

## SEE ALSO
avahi-daemon.conf(5), avahi.hosts(5), avahi.service(5), avahi-dnsconfd(8), avahi-set-host-name(1)

http://avahi.org/wiki/AvahiAndUnicastDotLocal documents the problems when using Avahi in a unicast DNS zone .local.

## COMMENTS
This man page was written using xml2man(1) by Oliver Kurth.


avahi-dnsconfd

package: avahi-dnsconfd

title: avahi-dnsconfd(8)

text:
# avahi-dnsconfd(8)

## NAME
avahi-dnsconfd - Unicast DNS server from mDNS/DNS-SD configuration daemon

## SYNOPSIS
avahi-dnsconfd [options]

avahi-dnsconfd --kill

avahi-dnsconfd --refresh

avahi-dnsconfd --check

## DESCRIPTION
avahi-dnsconfd connects to a running avahi-daemon and runs the script /etc/avahi/avahi-dnsconfd.action for each unicast DNS server that is announced on the local LAN. This is useful for configuring unicast DNS servers in a DHCP-like fashion with mDNS.

## OPTIONS
-D | --daemonize

Daemonize after startup and redirect log messages to syslog.

-s | --syslog

Log to syslog instead of STDERR. Implied by --daemonize.

-k | --kill

Kill an already running avahi-dnsconfd. (equivalent to sending a SIGTERM)

-r | --refresh

Tell an already running avahi-dnsconfd to refresh the DNS server data. (equivalent to sending a SIGHUP)

-c | --check

Return 0 as return code when avahi-dnsconfd is already running.

-h | --help

Show help

-v | --version

Show version information

## FILES
/etc/avahi/avahi-dnsconfd.action: the script to run when a DNS server is found or removed.

## SIGNALS
SIGINT, SIGTERM: avahi-dnsconfd will shutdown. This is issued by passing --kill to avahi-daemon.

SIGHUP: avahi-dnsconfd will refresh the DNS server data.

## AUTHORS
The Avahi Developers <avahi (at) lists (dot) freedesktop (dot) org>; Avahi is available from http://avahi.org/

## SEE ALSO
avahi-daemon(8), avahi-dnsconfd.action(8)

## COMMENTS
This man page was written using xml2man(1) by Oliver Kurth.


avahi-dnsconfd.action

title: avahi-dnsconfd.action(8)

summary: avahi-dnsconfd action script

text:
# avahi-dnsconfd.action(8)

## NAME
avahi-dnsconfd.action - avahi-dnsconfd action script

## SYNOPSIS
/etc/avahi/avahi-dnsconfd.action

## DESCRIPTION
avahi-dnsconfd.action is the action script that is called whenever a new unicast DNS server is found or removed by avahi-dnsconfd. The default script as shipped with avahi patches /etc/resolv.conf to reflect the changed unicast DNS server configuration.

## PARAMETERS
argv[1] Contains the character "+" if the DNS server is new, "-" when it shall be removed from the DNS server list.

argv[2] The IP address of the DNS server.

argv[3] Numerical network interface number this DNS server was found on.

argv[4] Numerical protocol number this DNS server was found on. (usually 2 for IPv4 and 10 for IPv6)

## ENVIRONMENT
AVAHI_INTERFACE Contains the textual interface name the corresponds with argv[3]. (e.g. "eth0")

AVAHI_INTERFACE_DNS_SERVERS Contains a list of all DNS servers that avahi-dnsconfd found on the interface $AVAHI_INTERFACE, separated by spaces.

AVAHI_DNS_SERVERS Contains a list of all DNS server that avahi-dnsconfd found on all interfaces, separated by spaces.

## AUTHORS
The Avahi Developers <avahi (at) lists (dot) freedesktop (dot) org>; Avahi is available from http://avahi.org/

## SEE ALSO
avahi-dnsconfd(8), avahi-daemon(8)

## COMMENTS
This man page was written using xml2man(1) by Oliver Kurth.


bacula-fd

title: bacula-fd(8)

summary: Bacula's File Daemon

text:
# bacula-fd(8)

## NAME
bacula-fd - Bacula's File Daemon

## SYNOPSIS
bacula-fd [options]

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

Bacula's File Daemon acts as the interface between the Bacula network backup system and the filesystems to be backed up: it is responsible for reading/writing/verifying the files to be backup'd/verified/restored. Network transfer can optionally be compressed.

## OPTIONS
-c file

Specify the configuration file to use.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output.

-T

Send debug messages to the trace file.

-f

Run in foreground (for debugging).

-g group

Set the group/gid to run as.

-k

Keep readall permission when dropping privileges.

-m

Print kaboom output (for debugging).

-P

Do not create a PID file.

-s

No signals (for debugging).

-t

Test the configuration file and report errors.

-u user

Set the username/uid to run as.

-v

Set verbose mode.

-?

Show version and usage of program.

## SEE ALSO
bacula-dir(8), bacula-sd(8).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


bacula

title: bacula(8)

summary: The Network Backup Solution

text:
# bacula(8)

## NAME
Bacula - The Network Backup Solution

## SYNOPSIS
bacula-dir - Director

bacula-fd - File daemon or Client

bacula-sd - Storage daemon

bconsole - Console to control Bacula

## DESCRIPTION
Bacula is a set of computer programs that permits you (or the system administrator) to manage backup, recovery, and verification of computer data across a network of computers of different kinds. In technical terms, it is a network Client/Server based backup program. Bacula is relatively easy to use and efficient, while offering many advanced storage management features that make it easy to find and recover lost or damaged files. Due to its modular design, Bacula is scalable from small single computer systems to systems consisting of hundreds of computers located over a large network.

Bacula Director service consists of the program that supervises all the backup, restore, verify and archive operations. The system administrator uses the Bacula Director to schedule backups and to recover files. For more details see the Director Services Daemon Design Document in the Bacula Developer's Guild. The Director runs as a daemon or a service (i.e. in the background).

Bacula Console services is the program that allows the administrator or user to communicate with the Bacula Director (see above). Currently, the Bacula Console is available in two versions. The first and simplest is to run the Console program in a shell window (i.e. TTY interface). Most system administrators will find this completely adequate. The second version is a Qt 4.2 GUI interface named bat that has more features than the bconsole program.

Bacula File services (or Client program) is the software program that is installed on the machine to be backed up. It is specific to the operating system on which it runs and is responsible for providing the file attributes and data when requested by the Director. The File services are also responsible for the file system dependent part of restoring the file attributes and data during a recovery operation. For more details see the File Services Daemon Design Document in the Bacula Developer's Guide. This program runs as a daemon on the machine to be backed up, and in some of the documentation, the File daemon is referred to as the Client (for example in Bacula's configuration file). In addition to Unix/Linux File daemons, there is a Windows File daemon (normally distributed in binary format). The Windows File daemon runs on all currently known Windows versions (2K, 2003, XP, and Vista).

Bacula Storage services consist of the software programs that perform the storage and recovery of the file attributes and data to the physical backup media or volumes. In other words, the Storage daemon is responsible for reading and writing your tapes (or other storage media, e.g. files). For more details see the Storage Services Daemon Design Document in the Bacula Developer's Guide. The Storage services runs as a daemon on the machine that has the backup device (usually a tape drive).

Catalog services are comprised of the software programs responsible for maintaining the file indexes and volume databases for all files backed up. The Catalog services permit the System Administrator or user to quickly locate and restore any desired file. The Catalog services sets Bacula apart from simple backup programs like tar and bru, because the catalog maintains a record of all Volumes used, all Jobs run, and all Files saved, permitting efficient restoration and Volume management. Bacula currently supports three different databases, MySQL, PostgreSQL, and SQLite3, one of which must be chosen when building Bacula.

## OPTIONS
See the HTML/PDF documentation at:

<http://www.bacula.org>

for details of the command line options.

## CONFIGURATION
Each daemon has its own configuration file which must be tailored for each particular installation. Please see the HTML/PDF documentation for the details.

## SEE ALSO
The HTML manual installed on your system (typically found in

/usr/share/doc/bacula-<version>) or the online manual at:

<http://www.bacula.org>

## BUGS
See <http://bugs.bacula.org>

## AUTHOR
Kern Sibbald

### Current maintainer
Kern Sibbald

### Contributors
An enormous list of past and former persons who have devoted their time and energy to this project -- thanks. See the AUTHORS file in the main Bacula source directory.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


bconsole

title: bconsole(8)

summary: Bacula's management Console

text:
# bconsole(8)

## NAME

bconsole - Bacula's management Console

## SYNOPSIS
bconsole [options]

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

## OPTIONS
-D dir

Select a Director.

-l

List defined Directors.

-c config

Specify configuration file.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output.

-n

No conio (for scripting).

-s

No signals (for debugging).

-u nn

Set command execution timeout to nn seconds.

-t

Test the configuration file and report errors.

-?

Show version and usage of program.

## SEE ALSO
bacula-dir(8), bls(1), bextract(1).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


btraceback

title: btraceback(8)

summary: wrapper script around gdb and bsmtp

text:
# btraceback(8)

## NAME

btraceback - wrapper script around gdb and bsmtp

## SYNOPSIS
btraceback /path/to/binary pid

## DESCRIPTION
btraceback is a wrapper shell script around the gdb debugger (or dbx on Solaris systems) and bsmtp, provided for debugging purposes.

## USAGE
btraceback is called by the exception handlers of the Bacula daemons during a crash. It can also be called interactively to view the current state of the threads belonging to a process, but this is not recommended unless you are trying to debug a problem (see below).

## NOTES
In order to work properly, debugging symbols must be available to the debugger on the system, and gdb, or dbx (on Solaris systems) must be available in the $PATH.

If the Director or Storage daemon runs under a non-root uid, you will probably need to be modify the btraceback script to elevate privileges for the call to gdb/dbx, to ensure it has the proper permissions to debug when called by the daemon.

Although Bacula's use of btraceback within its exception handlers is always safe, manual or interactive use of btraceback is subject to the same risks than live debugging of any program, which means it could cause Bacula to crash under rare and abnormal circumstances. Consequently we do not recommend manual use of btraceback in production environments unless it is required for debugging a problem.

## ENVIRONMENT
btracback relies on $PATH to find the debugger.

## FILES
/usr/lib/bacula/btraceback

The script itself.

/usr/sbin/btraceback

symbolic link to /usr/lib/bacula/btraceback

/etc/bacula/scripts/btraceback.gdb

the GDB command batch used to output a stack trace

## AUTHOR
This manual page was written by Lucas B. Cohen <lbc@members.fsf.org>

## SEE ALSO
bsmtp(1) This man page document is released under the BSD 2-Clause license.


bacula-dir

title: bacula-dir(8)

summary: Bacula Director

text:
# bacula-dir(8)

## NAME
bacula-dir - Bacula Director

## SYNOPSIS
bacula-dir [options]

## DESCRIPTION
This manual page documents briefly the bacula-dir command.

Bacula's Director Daemon acts as the controller of the network backup system: it is responsible for scheduling and coordinating backups across the network.

## OPTIONS
-c file

Specify the configuration file to use.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output.

-T

Send debug messages to the trace file.

-f

Run in foreground (for debugging).

-g group

Set the group/gid to run as.

-m

Print kaboom output (for debugging).

-P

Do not create a PID file.

-r job

Run <job>.

-s

No signals (for debugging).

-t

Test the configuration file and report errors.

-u user

Set the username/uid to run as.

-v

Set verbose mode.

-?

Show version and usage of program.

## TCP-WRAPPERS CONFIGURATION
Tcpwrappers looks for the service name of the bacula daemons in hosts.allow , and the service names of these daemons is configured to be different from the binary. The service names are configured to be %hostname%-%component% rather than bacula-dir (As defined in the bacula-dir.conf.in file)

So the hosts.allow entry has to match %hostname%-%component% (servername-dir for example) instead of bacula-%component%

WARNING: This means that if the hosts.allow file has the entry:

bacula-dir: ALL

you will not be able to run bconsole to connect to the local director!

The entry would have to read:

server-dir: ALL

and this will allow the console to connect to the director. (The process running is bacula-dir.)

## SEE ALSO
bacula-fd(8), bacula-sd(8).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


bcopy

title: bcopy(8)

summary: Bacula's 'Copy from tape'

text:
# bcopy(8)

## NAME

bcopy - Bacula's 'Copy from tape'

## SYNOPSIS
bcopy [options] input-archive output-archive

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

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-b bootstrap

Specify a bootstrap file.

-c config

Specify configuration file.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output.

-i input

Specify input Volume names (separated by '|')

-o output

Specify output Volume names (separated by '|')

-p

Proceed in spite of I/O errors.

-w directory

Specify working directory (default /tmp).

-v

Set verbose mode.

## SEE ALSO
bls(1), bextract(1).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


bregex

title: bregex(8)

summary: Bacula's 'regex' engine

text:
# bregex(8)

## NAME

bregex - Bacula's 'regex' engine

## SYNOPSIS
bregex [options] -f <data-file>

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

This program can be useful for testing regex expressions to be applied against a list of filenames.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output

-f <data-file>

The data-file is a filename that contains lines of data to be matched (or not) against one or more patterns. When the program is run, it will prompt you for a regular expression pattern, then apply it one line at a time against the data in the file. Each line that matches will be printed preceded by its line number. You will then be prompted again for another pattern.

-n

Print lines that do not match

-l

Suppress lines numbers.

## SEE ALSO
regex(7)

## AUTHOR
This manual page was written by Bruno Friedmann <bruno@ioda-net.ch>. This man page document is released under the BSD 2-Clause license.


bscan

title: bscan(8)

summary: Bacula's 'Scan tape'

text:
# bscan(8)

## NAME

bscan - Bacula's 'Scan tape'

## SYNOPSIS
bscan [options] bacula-archive

## DESCRIPTION
The purpose of bscan is to read (scan) a Bacula Volume and to recreate or update the database contents with the information found on the Volume. This is done in a non-destructive way. This permits restoring database entries that have been lost by pruning, purging, deleting, or a database corruption problem.

Normally, it should not be necessary to run the bscan command because the database is self maintaining, and most corrupted databases can be repaired by the tools provided by the database vendors. In addition, if you have maintained bootstrap files during backups, you should be able to recover all your data from the bootstrap file without needed an up to date catalog.

bscan command.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-b bootstrap

Specify a bootstrap file.

-c config

Specify configuration file.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output.

-m

Update media info in database.

-D

Specify the driver database name (default: NULL)

-n name

Specify the database name (default: bacula)

-u username

Specify database username (default: bacula)

-P password

Specify database password (default: none)

-h host

Specify database host (default: NULL)

-t port

Specify database port (default: 0)

-p

Proceed in spite of I/O errors.

-r

List records.

-s

Synchronize or store in Database.

-S

Show scan progress periodically.

-v

Verbose output mode.

-V volume

Specify volume names (separated by '|')

-w dir

Specify working directory (default from conf file)

## SEE ALSO
bls(8), bextract(8).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>, for the Debian GNU/Linux system (but may be used by others).

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


bwild

title: bwild(8)

summary: Bacula's 'wildcard' engine

text:
# bwild(8)

## NAME

bwild - Bacula's 'wildcard' engine

## SYNOPSIS
bwild [options] -f <data-file>

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

This is a simple program that will allow you to test wild-card expressions against a file of data.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output

-f <data-file>

The data-file is a filename that contains lines of data to be matched (or not) against one or more patterns. When the program is run, it will prompt you for a wild-card pattern, then apply it one line at a time against the data in the file. Each line that matches will be printed preceded by its line number. You will then be prompted again for another pattern.

Enter an empty line for a pattern to terminate the program. You can print only lines that do not match by using the -n option, and you can suppress printing of line numbers with the -l option.

-n

Print lines that do not match

-l

Suppress lines numbers.

-i

use case insensitive match.

## SEE ALSO
fnmatch(3)

## AUTHOR
This manual page was written by Bruno Friedmann <bruno@ioda-net.ch>. This man page document is released under the BSD 2-Clause license.


dbcheck

title: dbcheck(8)

text:
# dbcheck(8)

## NAME

dbcheck - Bacula's Catalog Database Check/Clean program

## SYNOPSIS
dbcheck [options] working-directory bacula-database user password [dbhost] [dbport]

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

dbcheck will not repair your database if it is broken. Please see your vendor's instructions for fixing broken database.

dbcheck is a simple program that will search for logical inconsistencies in the Bacula tables in your database, and optionally fix them. It is a database maintenance routine, in the sense that it can detect and remove unused rows, but it is not a database repair routine. To repair a database, see the tools furnished by the database vendor. Normally dbcheck should never need to be run, but if Bacula has crashed or you have a lot of Clients, Pools, or Jobs that you have removed, it could be useful.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-b

If specified, dbcheck will run in batch mode, and it will proceed to examine and fix (if -f is set) all programmed inconsistency checks. By default, dbcheck will enter interactive mode (see below).

-C catalog

catalog name in the director conf file.

-c config

If the -c option is given with the Director's conf file, there is no need to enter any of the command line arguments, in particular the working directory as dbcheck will read them from the file.

-B

print catalog configuration and exit.

-d nn

set debug level to nn.

-dt

print timestamp in debug output.

-f

If specified, dbcheck will repair (fix) the inconsistencies it finds. Otherwise, it will report only.

-v

Set verbose mode.

## INTERACTIVE MODE
In interactive mode dbcheck will prompt with the following:

Hello, this is the database check/correct program. Please select the function you want to perform.

1) Toggle modify database flag

2) Toggle verbose flag

3) Repair bad Filename records

4) Repair bad Path records

5) Eliminate duplicate Filename records

6) Eliminate duplicate Path records

7) Eliminate orphaned Jobmedia records

8) Eliminate orphaned File records

9) Eliminate orphaned Path records

10) Eliminate orphaned Filename records

11) Eliminate orphaned FileSet records

12) Eliminate orphaned Client records

13) Eliminate orphaned Job records

14) Eliminate all Admin records

15) Eliminate all Restore records

16) All (3-15)

17) Quit Select function number:

By entering 1 or 2, you can toggle the modify database flag (-f option) and the verbose flag (-v). It can be helpful and reassuring to turn off the modify database flag, then select one or more of the consistency checks (items 3 through 9) to see what will be done, then toggle the modify flag on and re-run the check.

The inconsistencies examined are the following:

Duplicate filename records. This can happen if you accidentally run two

copies of Bacula at the same time, and they are both adding filenames

simultaneously. It is a rare occurrence, but will create an

inconsistent database. If this is the case, you will receive error

messages during Jobs warning of duplicate database records. If you are

not getting these error messages, there is no reason to run this check.

Repair bad Filename records. This checks and corrects filenames that have

a trailing slash. They should not.

Repair bad Path records. This checks and corrects path names that do not

have a trailing slash. They should.

Duplicate path records. This can happen if you accidentally run two copies

of Bacula at the same time, and they are both adding filenames

simultaneously. It is a rare occurrence, but will create an

inconsistent database. See the item above for why this occurs and how

you know it is happening.

Orphaned JobMedia records. This happens when a Job record is deleted

(perhaps by a user issued SQL statement), but the corresponding JobMedia

record (one for each Volume used in the Job) was not deleted. Normally,

this should not happen, and even if it does, these records generally do

not take much space in your database. However, by running this check,

you can eliminate any such orphans.

Orphaned File records. This happens when a Job record is deleted (perhaps

by a user issued SQL statement), but the corresponding File record (one

for each Volume used in the Job) was not deleted. Note, searching for

these records can be very time consuming (i.e. it may take hours) for a

large database. Normally this should not happen as Bacula takes care to

prevent it. Just the same, this check can remove any orphaned File

records. It is recommended that you run this once a year since orphaned

File records can take a large amount of space in your database. You

might want to ensure that you have indexes on JobId, FilenameId, and

PathId for the File table in your catalog before running this command.

Orphaned Path records. This condition happens any time a directory is

deleted from your system and all associated Job records have been

purged. During standard purging (or pruning) of Job records, Bacula

does not check for orphaned Path records. As a consequence, over a

period of time, old unused Path records will tend to accumulate and use

space in your database. This check will eliminate them. It is

recommended that you run this check at least once a year.

Orphaned Filename records. This condition happens any time a file is

deleted from your system and all associated Job records have been

purged. This can happen quite frequently as there are quite a large

number of files that are created and then deleted. In addition, if you

do a system update or delete an entire directory, there can be a very

large number of Filename records that remain in the catalog but are no

longer used.

During standard purging (or pruning) of Job records, Bacula does not

check for orphaned Filename records. As a consequence, over a period of

time, old unused Filename records will accumulate and use space in your

database. This check will eliminate them. It is strongly recommended

that you run this check at least once a year, and for large database

(more than 200 Megabytes), it is probably better to run this once every

6 months.

Orphaned Client records. These records can remain in the database long

after you have removed a client.

Orphaned Job records. If no client is defined for a job or you do not run

a job for a long time, you can accumulate old job records. This option

allow you to remove jobs that are not attached to any client (and thus

useless).

All Admin records. This command will remove all Admin records,

regardless of their age.

All Restore records. This command will remove all Restore records,

regardless of their age.

By the way, I personally run dbcheck only where I have messed up my database due to a bug in developing Bacula code, so normally you should never need to run dbcheck inspite of the recommendations given above, which are given so that users don't waste their time running dbcheck too often.

## SEE ALSO
bls(1), bextract(1).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


bacula-sd

title: bacula-sd(8)

summary: Bacula's Storage Daemon

text:
# bacula-sd(8)

## NAME
bacula-sd - Bacula's Storage Daemon

## SYNOPSIS
bacula-sd [options]

## DESCRIPTION
This manual page documents briefly the bacula-sd command.

Bacula's Storage Daemon acts as the interface between the Bacula network backup system and a tape drive/autochanger or filesystem where the backups will be stored.

## OPTIONS
-c file

Specify the configuration file to use.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output.

-T

Send debug messages to the trace file.

-f

Run in foreground (for debugging).

-g group

Set the group/gid to run as.

-P

Do not create a PID file.

-p

Proceed in spite of I/O errors

-m

Print kaboom output (for debugging)

-s

No signals (for debugging).

-t

Test the configuration file and report errors.

-u user

Set the username/uid to run as.

-v

Set verbose mode.

-?

Show version and usage of program.

## SEE ALSO
bacula-dir(8), bacula-fd(8).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


bextract

title: bextract(8)

summary: Bacula's 'Extract from tape'

text:
# bextract(8)

## NAME

bextract - Bacula's 'Extract from tape'

## SYNOPSIS
bextract [options] bacula-archive-device-name output-directory

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

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-b bootstrap

Specify a bootstrap file.

-c config

Specify configuration file.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output.

-e file

Specify exclude list.

-i file

Specify include list.

-p

Proceed in spite of I/O errors.

-t

Read data from volume, do not write anything

-v

Set verbose mode.

-V volume-name

Specify volume names.

## SEE ALSO
bls(1), bextract(1).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


bls

title: bls(8)

summary: Bacula's 'Tape LS'

text:
# bls(8)

## NAME

bls - Bacula's 'Tape LS'

## SYNOPSIS
bls [options] <device-name>

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

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-b bootstrap

Specify a bootstrap file.

-c config

Specify configuration file.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output

-e <file>

Specify exclude list file.

-i <file>

Specify include list file.

-j

List jobs.

-k

List blocks.

(no -j or -k option)

List saved files

-L

Dump label.

-p

Proceed in spite of errors.

-V volumes

Specify volume names (separated by '|').

-v

Set verbose mode.

## SEE ALSO
bscan(8), bextract(8).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


btape

title: btape(8)

summary: Bacula's Tape interface test program

text:
# btape(8)

## NAME

btape - Bacula's Tape interface test program

## SYNOPSIS
btape [options] device-name

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

## OPTIONS
A summary of options is included below.

-?

Show summary of options and commands.

-b bootstrap

Specify a bootstrap file.

-c config

Specify configuration file.

-d nn

Set debug level to nn.

-p

Proceed inspite of I/O errors.

-s

No signals (for debugging).

-v

Set verbose mode.

## COMMANDS
autochanger

test autochanger

bsf

backspace file

bsr

backspace record

cap

list device capabilities

clear

clear tape errors

eod

go to end of Bacula data for append

eom

go to the physical end of medium

fill

fill tape, write onto second volume

unfill

read filled tape

fsf

forward space a file

fsr

forward space a record

help

print this reference

label

write a Bacula label to the tape

load

load a tape

quit

quit btape

rawfill

use write() to fill tape

readlabel

read and print the Bacula tape label

rectest

test record handling functions

rewind

rewind the tape

scan

read() tape block by block to EOT and report

scanblocks

Bacula read block by block to EOT and report

status

print tape status

test

General test Bacula tape functions

weof

write an EOF on the tape

wr

write a single Bacula block

rr

read a single record

rb

read a single bacula block

qfill

quick fill command

## SEE ALSO
bscan(1), bextract(1).

## AUTHOR
This manual page was written by Jose Luis Tallon <jltallon@adv-solutions.net>.

## COPYRIGHT
This man page document is released under the BSD 2-Clause license.


bacula-fd

title: bacula-fd(8)

summary: Bacula's File Daemon


bacula

title: bacula(8)

summary: The Network Backup Solution


bconsole

title: bconsole(8)

summary: Bacula's management Console


btraceback

title: btraceback(8)

summary: wrapper script around gdb and bsmtp


bacula-dir

title: bacula-dir(8)

summary: Bacula Director


bcopy

title: bcopy(8)

summary: Bacula's 'Copy from tape'


bregex

title: bregex(8)

summary: Bacula's 'regex' engine


bscan

title: bscan(8)

summary: Bacula's 'Scan tape'


bwild

title: bwild(8)

summary: Bacula's 'wildcard' engine


dbcheck

title: dbcheck(8)

summary: Bacula's Catalog Database Check/Clean program


bacula-sd

title: bacula-sd(8)

summary: Bacula's Storage Daemon


bextract

title: bextract(8)

summary: Bacula's 'Extract from tape'


bls

title: bls(8)

summary: Bacula's 'Tape LS'


btape

title: btape(8)

summary: Bacula's Tape interface test program


bacula-fd

title: bacula-fd(8)

summary: Bacula's File Daemon


bacula

title: bacula(8)

summary: The Network Backup Solution


bconsole

title: bconsole(8)

summary: Bacula's management Console


btraceback

title: btraceback(8)

summary: wrapper script around gdb and bsmtp


bacula-dir

title: bacula-dir(8)

summary: Bacula Director


bcopy

title: bcopy(8)

summary: Bacula's 'Copy from tape'


bregex

title: bregex(8)

summary: Bacula's 'regex' engine


bscan

title: bscan(8)

summary: Bacula's 'Scan tape'


bwild

title: bwild(8)

summary: Bacula's 'wildcard' engine


dbcheck

title: dbcheck(8)


bacula-sd

title: bacula-sd(8)

summary: Bacula's Storage Daemon


bextract

title: bextract(8)

summary: Bacula's 'Extract from tape'


bls

title: bls(8)

summary: Bacula's 'Tape LS'


btape

title: btape(8)

summary: Bacula's Tape interface test program


bbconsjson

title: bbconsjson(8)

summary: Bacula's JSON configuration export tool

text:
# bbconsjson(8)

## NAME

bbconsjson - Bacula's JSON configuration export tool

## SYNOPSIS
bbconsjson [options]

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

This is a simple program that will allow you to dump the Bacula Console configuration in JSON format.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output

-r <res>

Get resource type

-n <name>

Get resource name

-l <dirs>

Get only directives matching dirs (use with -r)

-D

Get only data

-R

Do not apply JobDefs to Job

-c <file>

Set configuration file to file

-d <nn>

Set debug level to <nn>

-dt

Print timestamp in debug output

-t

Read configuration and exit

-s

Output in show text format

-v

Verbose user messages

## AUTHOR
This manual page was written by Eric Bollengier <eric@baculasystems.com>. This man page document is released under the BSD 2-Clause license.


bdirjson

title: bdirjson(8)

summary: Bacula's JSON configuration export tool

text:
# bdirjson(8)

## NAME

bdirjson - Bacula's JSON configuration export tool

## SYNOPSIS
bdirjson [options]

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

This is a simple program that will allow you to dump the Bacula Director configuration in JSON format.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output

-r <res>

Get resource type

-n <name>

Get resource name

-l <dirs>

Get only directives matching dirs (use with -r)

-D

Get only data

-R

Do not apply JobDefs to Job

-c <file>

Set configuration file to file

-d <nn>

Set debug level to <nn>

-dt

Print timestamp in debug output

-t

Read configuration and exit

-s

Output in show text format

-v

Verbose user messages

## AUTHOR
This manual page was written by Eric Bollengier <eric@baculasystems.com>. This man page document is released under the BSD 2-Clause license.


bfdjson

title: bfdjson(8)

summary: Bacula's JSON configuration export tool

text:
# bfdjson(8)

## NAME

bfdjson - Bacula's JSON configuration export tool

## SYNOPSIS
bfdjson [options]

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

This is a simple program that will allow you to dump the Bacula File Daemon configuration in JSON format.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output

-r <res>

Get resource type

-n <name>

Get resource name

-l <dirs>

Get only directives matching dirs (use with -r)

-D

Get only data

-R

Do not apply JobDefs to Job

-c <file>

Set configuration file to file

-d <nn>

Set debug level to <nn>

-dt

Print timestamp in debug output

-t

Read configuration and exit

-s

Output in show text format

-v

Verbose user messages

## AUTHOR
This manual page was written by Eric Bollengier <eric@baculasystems.com>. This man page document is released under the BSD 2-Clause license.


bsdjson

title: bsdjson(8)

summary: Bacula's JSON configuration export tool

text:
# bsdjson(8)

## NAME

bsdjson - Bacula's JSON configuration export tool

## SYNOPSIS
bsdjson [options]

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

This is a simple program that will allow you to dump the Bacula Storage Daemon configuration in JSON format.

## OPTIONS
A summary of options is included below.

-?

Show version and usage of program.

-d nn

Set debug level to nn.

-dt

Print timestamp in debug output

-r <res>

Get resource type

-n <name>

Get resource name

-l <dirs>

Get only directives matching dirs (use with -r)

-D

Get only data

-R

Do not apply JobDefs to Job

-c <file>

Set configuration file to file

-d <nn>

Set debug level to <nn>

-dt

Print timestamp in debug output

-t

Read configuration and exit

-s

Output in show text format

-v

Verbose user messages

## AUTHOR
This manual page was written by Eric Bollengier <eric@baculasystems.com>. This man page document is released under the BSD 2-Clause license.


bcache-status

package: bcache-status

title: bcache-status(8)

summary: Display useful bcache statistics

text:
# bcache-status(8)

## NAME
bcache-status - Display useful bcache statistics

## SYNOPSIS
bcache-status [ --help ] [ -f ] [ -h ] [ -d ] [ -t ] [ -a ] [ -r ] [ -s ] [ -g ]

## DESCRIPTION
This command displays useful bcache statistics in a convenient way.

## OPTIONS
---help

Print help message and exit.

-f, --five-minute

Print the last five minutes of stats.

-h, --hour

Print the last hour of stats.

-d, --day

Print the last day of stats.

-t, --total

Print total stats.

-a, --all

Print all stats.

-r, --reset-stats

Reset stats after printing them.

-s, --sub-status

Print subdevice status.

-g, --gc

Invoke GC before printing status (root only).


bcache-super-show

package: bcache-tools

title: bcache-super-show(8)

summary: Print the bcache superblock

text:
# bcache-super-show(8)

## NAME
bcache-super-show - Print the bcache superblock

## SYNOPSIS
bcache-super-show [ -f] device

## OPTIONS
-f

Keep going if the superblock crc is invalid


make-bcache

title: make-bcache(8)

summary: create a cache device

text:
# make-bcache(8)

## NAME
make-bcache - create a cache device

## SYNOPSIS
make-bcache [ -U UUID ] [ -b bucket-size ] device

## OPTIONS
-C

Create a cache

-B

Create a backing device (kernel functionality not yet implemented)

-U UUID

Create a cache device with the specified UUID

-b bucket-size

Specifies the bucket size. Allocation is done in terms of buckets, and cache hits are counted per bucket; thus a smaller bucket size will give better cache utilization, but poorer write performance. The bucket size is intended to be equal to the size of your SSD's erase blocks, which seems to be 128k-512k for most SSDs. Must be a power of two; accepts human readable units. Defaults to 128k.


probe-bcache

title: probe-bcache(8)

summary: probe a bcache device

text:
# probe-bcache(8)

## NAME
probe-bcache - probe a bcache device

## SYNOPSIS
probe-bcache [ -o udev ] device

## OPTIONS
-o

return UUID in udev style for invocation by udev rule as IMPORT{program}

## USAGE
Return UUID if device identified as bcache-formatted.

Only necessary until support for the bcache superblock is included in blkid; in the meantime, provides just enough functionality for a udev script to create the /dev/disk/by-uuid symlink.


bcc-argdist

package: bcc-tools

title: bcc-argdist(8)

text:
# bcc-argdist(8)

## NAME
argdist - Trace a function and display a histogram or frequency count of its parameter values. Uses Linux eBPF/bcc.

## SYNOPSIS
argdist [-h] [-p PID] [-z STRING_SIZE] [-i INTERVAL] [-d DURATION] [-n COUNT] [-v] [-T TOP] [-H specifier] [-C specifier] [-I header]

## DESCRIPTION
argdist attaches to function entry and exit points, collects specified parameter values, and stores them in a histogram or a frequency collection that counts the number of times a parameter value occurred. It can also filter parameter values and instrument multiple entry points at once.

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-p PID

Trace only functions in the process PID.

-z STRING_SIZE

When collecting string arguments (of type char*), collect up to STRING_SIZE characters. Longer strings will be truncated.

-i INTERVAL

Print the collected data every INTERVAL seconds. The default is 1 second.

-d DURATION

Total duration of trace in seconds.

-n NUMBER

Print the collected data COUNT times and then exit.

-v

Display the generated BPF program, for debugging purposes.

-T TOP

When collecting frequency counts, display only the top TOP entries.

-H specifiers, -C specifiers

One or more probe specifications that instruct argdist which functions to probe, which parameters to collect, how to aggregate them, and whether to perform any filtering. See SPECIFIER SYNTAX below.

-I header

One or more header files that should be included in the BPF program. This enables the use of structure definitions, enumerations, and constants that are available in these headers. You should provide the same path you would include in the BPF program, e.g. 'linux/blkdev.h' or 'linux/time.h'. Note: in many cases, argdist will deduce the necessary header files automatically.

## SPECIFIER SYNTAX
The general specifier syntax is as follows:

{p,r,t,u}:{[library],category}:function(signature)[:type[,type...]:expr[,expr...][:filter]][#label]

{p,r,t,u}

Probe type - "p" for function entry, "r" for function return, "t" for kernel tracepoint, "u" for USDT probe; -H for histogram collection, -C for frequency count. Indicates where to place the probe and whether the probe should collect frequency count information, or aggregate the collected values into a histogram. Counting probes will collect the number of times every parameter value was observed, whereas histogram probes will collect the parameter values into a histogram. Only integral types can be used with histogram probes; there is no such limitation for counting probes.

[library]

Library containing the probe. Specify the full path to the .so or executable file where the function to probe resides. Alternatively, you can specify just the lib name: for example, "c" refers to libc. If no library name is specified, the kernel is assumed.

category

The category of the kernel tracepoint. For example: net, sched, block.

function(signature)

The function to probe, and its signature. The function name must match exactly for the probe to be placed. The signature, on the other hand, is only required if you plan to collect parameter values based on that signature. For example, if you only want to collect the first parameter, you don't have to specify the rest of the parameters in the signature. When capturing kernel tracepoints, this should be the name of the event, e.g. net_dev_start_xmit. The signature for kernel tracepoints should be empty. When capturing USDT probes, this should be the name of the probe, e.g. reloc_complete. The signature for USDT probes should be empty.

[type[,type...]]

The type(s) of the expression(s) to capture. This is the type of the keys in the histogram or raw event collection that are collected by the probes.

[expr[,expr...]]

The expression(s) to capture. These are the values that are assigned to the histogram or raw event collection. You may use the parameters directly, or valid C expressions that involve the parameters, such as "size % 10". Tracepoints may access a special structure called "args" that is formatted according to the tracepoint format (which you can obtain using tplist). For example, the block:block_rq_complete tracepoint can access args->nr_sector. USDT probes may access the arguments defined by the tracing program in the special arg1, arg2, ... variables. To obtain their types, use the tplist tool. Return probes can use the argument values received by the function when it was entered, through the $entry(paramname) special variable. Return probes can also access the function's return value in $retval, and the function's execution time in nanoseconds in $latency. Note that adding the $latency or $entry(paramname) variables to the expression will introduce an additional probe at the function's entry to collect this data, and therefore introduce additional overhead.

[filter]

The filter applied to the captured data. Only parameter values that pass the filter will be collected. This is any valid C expression that refers to the parameter values, such as "fd == 1 && length > 16". The $entry, $retval, and $latency variables can be used here as well, in return probes. The filter expression may also use the STRCMP pseudo-function to compare a predefined string to a string argument. For example: STRCMP("test.txt", file). The order of arguments is important: the first argument MUST be a quoted literal string, and the second argument can be a runtime string.

[label]

The label that will be displayed when printing the probed values. By default, this is the probe specifier.

## EXAMPLES
Print a histogram of allocation sizes passed to kmalloc:

\# argdist -H 'p::__kmalloc(u64 size):u64:size'

Print a count of how many times process 1005 called malloc with an allocation size of 16 bytes:

\# argdist -p 1005 -C 'p:c:malloc(size_t size):size_t:size:size==16'

Snoop on all strings returned by gets():

\# argdist -C 'r:c:gets():char*:$retval'

Print a histogram of read sizes that were longer than 1ms:

\# argdist -H 'r::__vfs_read(void *file, void *buf, size_t count):size_t:$entry(count):$latency > 1000000'

Print frequency counts of how many times writes were issued to a particular file descriptor number, in process 1005:

\# argdist -p 1005 -C 'p:c:write(int fd):int:fd'

Print a histogram of error codes returned by read() in process 1005:

\# argdist -p 1005 -H 'r:c:read()'

Print a histogram of buffer sizes passed to write() across all processes, where the file descriptor was 1 (STDOUT):

\# argdist -H 'p:c:write(int fd, const void *buf, size_t count):size_t:count:fd==1'

Count fork() calls in libc across all processes, grouped by pid:

\# argdist -C 'p:c:fork():int:$PID;fork per process'

Print histogram of number of sectors in completing block I/O requests:

\# argdist -H 't:block:block_rq_complete():u32:nr_sector'

Aggregate interrupts by interrupt request (IRQ):

\# argdist -C 't:irq:irq_handler_entry():int:irq'

Print the functions used as thread entry points and how common they are:

\# argdist -C 'u:pthread:pthread_start():u64:arg2' -p 1337

Print histograms of sleep() and nanosleep() parameter values:

\# argdist -H 'p:c:sleep(u32 seconds):u32:seconds' -H 'p:c:nanosleep(struct timespec *req):long:req->tv_nsec'

Spy on writes to STDOUT performed by process 2780, up to a string size of 120 characters:

\# argdist -p 2780 -z 120 -C 'p:c:write(int fd, char* buf, size_t len):char*:buf:fd==1'

Group files being read from and the read sizes from __vfs_read:

\# argdist -C 'p::__vfs_read(struct file *file, void *buf, size_t count):char*,size_t:file->f_path.dentry->d_iname,count:file->f_path.dentry->d_iname[0]!=0'

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Sasha Goldshtein


bcc-bashreadline

title: bcc-bashreadline(8)

text:
# bcc-bashreadline(8)

## NAME
bashreadline - Print entered bash commands system wide. Uses Linux eBPF/bcc.

## SYNOPSIS
bashreadline [-h] [-s SHARED]

## DESCRIPTION
bashreadline traces the return of the readline() function using uprobes, to show the bash commands that were entered interactively, system wide. The entered command may fail: this is just showing what was entered.

This program is also a basic example of eBPF/bcc and uprobes.

This makes use of a Linux 4.4 feature (bpf_perf_event_output()); for kernels older than 4.4, see the version under tools/old, which uses an older mechanism

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-s

Specify the location of libreadline.so shared library when you failed to run the script directly with error: "Exception: could not determine address of symbol ´readline´". Default value is /lib/libreadline.so.

## EXAMPLES
Trace bash commands system wide:

\# bashreadline

## FIELDS
TIME

Time of the command (HH:MM:SS).

PID

Process ID of the bash shell.

COMMAND

Entered command.

## OVERHEAD
As the rate of interactive bash commands is expected to be very low (<<100/s), the overhead of this program is expected to be negligible.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
opensnoop(8)


bcc-bindsnoop

title: bcc-bindsnoop(8)

summary: Trace bind() system calls.

text:
# bcc-bindsnoop(8)

## NAME
bindsnoop - Trace bind() system calls.

## SYNOPSIS
bindsnoop.py [-h] [-w] [-t] [-p PID] [-P PORT] [-E] [-U] [-u UID] [--count] [--cgroupmap MAP] [--mntnsmap MNTNSMAP]

## DESCRIPTION
bindsnoop reports socket options set before the bind call that would impact this system call behavior.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS:
Show help message and exit:

-h, --help

Include timestamp on output:

-t, --timestamp

Wider columns (fit IPv6):

-w, --wide

Trace this PID only:

-p PID, --pid PID

Comma-separated list of ports to trace:

-P PORT, --port PORT

Trace cgroups in this BPF map:

--cgroupmap MAP

Trace mount namespaces in this BPF map:

--mntnsmap MNTNSMAP

Include errors in the output:

-E, --errors

Include UID on output:

-U, --print-uid

Trace this UID only:

-u UID, --uid UID

Count binds per src ip and port:

--count

## EXAMPLES:
Trace all IPv4 and IPv6 bind()s

bindsnoop

Include timestamps

bindsnoop -t

Trace PID 181

bindsnoop -p 181

Trace port 80

bindsnoop -P 80

Trace port 80 and 81

bindsnoop -P 80,81

Include UID

bindsnoop -U

Trace UID 1000

bindsnoop -u 1000

Report bind errors

bindsnoop -E

Count bind per src ip

bindsnoop --count

Trace IPv4 and IPv6 bind system calls and report socket options that would impact bind call behavior:

SOL_IP IP_FREEBIND F....

SOL_IP IP_TRANSPARENT .T...

SOL_IP IP_BIND_ADDRESS_NO_PORT ..N..

SOL_SOCKET SO_REUSEADDR ...R.

SOL_SOCKET SO_REUSEPORT ....r

SO_BINDTODEVICE interface is reported as "IF" index

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Pavel Dubovitsky

## SEE ALSO
tcpaccept(8)


bcc-biolatency

title: bcc-biolatency(8)

text:
# bcc-biolatency(8)

## NAME
biolatency - Summarize block device I/O latency as a histogram.

## SYNOPSIS
biolatency [-h] [-F] [-T] [-Q] [-m] [-D] [interval [count]]

## DESCRIPTION
biolatency traces block device I/O (disk I/O), and records the distribution of I/O latency (time). This is printed as a histogram either on Ctrl-C, or after a given interval in seconds.

The latency of disk I/O operations is measured from when requests are issued to the device up to completion. A -Q option can be used to include time queued in the kernel.

This tool uses in-kernel eBPF maps for storing timestamps and the histogram, for efficiency.

This works by tracing various kernel blk_*() functions using dynamic tracing, and will need updating to match any changes to these functions.

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h Print usage message.

-T

Include timestamps on output.

-m

Output histogram in milliseconds.

-D

Print a histogram per disk device.

-F

Print a histogram per set of I/O flags.

-j

Print a histogram dictionary

interval

Output interval, in seconds.

count

Number of outputs.

## EXAMPLES
Summarize block device I/O latency as a histogram:

\# biolatency

Print 1 second summaries, 10 times:

\# biolatency 1 10

Print 1 second summaries, using milliseconds as units for the histogram, and

include timestamps on output: # biolatency -mT 1

Include OS queued time in I/O time:

\# biolatency -Q

Show a latency histogram for each disk device separately:

\# biolatency -D

Show a latency histogram in a dictionary format:

\# biolatency -j

## FIELDS
usecs

Microsecond range

msecs

Millisecond range

count

How many I/O fell into this range

distribution

An ASCII bar chart to visualize the distribution (count column)

## OVERHEAD
This traces kernel functions and maintains in-kernel timestamps and a histogram, which are asynchronously copied to user-space. This method is very efficient, and the overhead for most storage I/O rates (< 10k IOPS) should be negligible. If you have a higher IOPS storage environment, test and quantify the overhead before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
biosnoop(8)


bcc-biolatpcts

title: bcc-biolatpcts(8)

text:
# bcc-biolatpcts(8)

## NAME
biolatpcts - Monitor IO latency distribution of a block device.

## SYNOPSIS
biolatpcts [-h] [-i INTERVAL] [-w which] [-p PCT,...] [-j] [-v] DEV

## DESCRIPTION
biolatpcts traces block device I/O (disk I/O) of the specified device, and calculates and prints the completion latency distribution percentiles per IO type periodically. Example:

\# biolatpcts /dev/nvme0n1

nvme0n1 p1 p5 p10 p16 p25 p50 p75 p84 p90 p95 p99 p100

read 95us 175us 305us 515us 895us 985us 995us 1.5ms 2.5ms 3.5ms 4.5ms 10ms

write 5us 5us 5us 15us 25us 135us 765us 855us 885us 895us 965us 1.5ms

discard 5us 5us 5us 5us 135us 145us 165us 205us 385us 875us 1.5ms 2.5ms

flush 5us 5us 5us 5us 5us 5us 5us 5us 5us 1.5ms 4.5ms 5.5ms

[...]

biolatpcts prints a number of pre-set latency percentiles in tabular form every three seconds. The interval can be changed with the -i option.

The latency is measured between issue to the device and completion. The starting point can be changed with the -w option.

Any number of percentiles can be specified using the -p option. The input percentile string is used verbatim in the output to ease machine consumption.

-j option enables json output. The result for each interval is printed on a single line.

This tool works by tracing blk_account_io_done() with kprobe and bucketing the completion latencies into percpu arrays. It may need updating to match the changes to the function.

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

## REQUIREMENTS
CONFIG_BPF, CONFIG_KPROBES and bcc.

## OPTIONS
-h Print usage message.

-i INTERVAL, --interval INTERVAL

Report interval. (default: 3)

-w {from-rq-alloc,after-rq-alloc,on-device}, --which {from-rq-alloc,after-rq-alloc,on-device}

Which latency to measure. (default: on-device)

-p PCT,..., --pcts PCT,...

Percentiles to calculate. (default: 1,5,10,16,25,50,75,84,90,95,99,100)

-j, --json

Output in json.

-v, --verbose

Enable debug output.

DEV

Target block device. /dev/DEVNAME, DEVNAME or MAJ:MIN.

## EXAMPLES
Print sda's I/O latency percentiles every second

\# biolatpcts -i 1 sda

Print nvme0n1's all-9 I/O latency percentiles in json every second

\# biolatpcts -p 99,99.9,99.99,99.999 -j -i 1 /dev/nvme0n1

## OVERHEAD
This traces kernel functions and maintains in-kernel per-cpu latency buckets, which are asynchronously copied to user-space. This method is very efficient, and the overhead for most storage I/O rates should be negligible. If you have an extremely high IOPS storage device, test and quantify the overhead before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Tejun Heo

## SEE ALSO
biolatency(8), biosnoop(8)


bcc-biosnoop

title: bcc-biosnoop(8)

text:
# bcc-biosnoop(8)

## NAME
biosnoop - Trace block device I/O and print details incl. issuing PID.

## SYNOPSIS
biosnoop [-hQ]

## DESCRIPTION
This tools traces block device I/O (disk I/O), and prints a one-line summary for each I/O showing various details. These include the latency from the time of issue to the device to its completion, and the PID and process name from when the I/O was first created (which usually identifies the responsible process).

This uses in-kernel eBPF maps to cache process details (PID and comm) by I/O request, as well as a starting timestamp for calculating I/O latency.

This works by tracing various kernel blk_*() functions using dynamic tracing, and will need updating to match any changes to these functions.

This makes use of a Linux 4.4 feature (bpf_perf_event_output()); for kernels older than 4.4, see the version under tools/old, which uses an older mechanism

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-Q

Include a column showing the time spent quueued in the OS.

## EXAMPLES
Trace all block device I/O and print a summary line per I/O:

\# biosnoop

## FIELDS
TIME(s)

Time of the I/O completion, in seconds since the first I/O was seen.

COMM

Cached process name, if present. This usually (but isn't guaranteed) to identify the responsible process for the I/O.

PID

Cached process ID, if present. This usually (but isn't guaranteed) to identify the responsible process for the I/O.

DISK

Disk device name.

T

Type of I/O: R = read, W = write. This is a simplification.

SECTOR

Device sector for the I/O.

BYTES

Size of the I/O, in bytes.

QUE(ms)

Time the I/O was queued in the OS before being issued to the device, in milliseconds.

LAT(ms)

Time for the I/O (latency) from the issue to the device, to its completion, in milliseconds.

## OVERHEAD
Since block device I/O usually has a relatively low frequency (< 10,000/s), the overhead for this tool is expected to be negligible. For high IOPS storage systems, test and quantify before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

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


bcc-biotop

title: bcc-biotop(8)

summary: Block device (disk) I/O by process top.

text:
# bcc-biotop(8)

## NAME
biotop - Block device (disk) I/O by process top.

## SYNOPSIS
biotop [-h] [-C] [-r MAXROWS] [interval] [count]

## DESCRIPTION
This is top for disks.

This traces block device I/O (disk I/O), and prints a per-process summary every interval (by default, 1 second). The summary is sorted on the top disk consumers by throughput (Kbytes). The PID and process name shown are measured from when the I/O was first created, which usually identifies the responsible process.

For efficiency, this uses in-kernel eBPF maps to cache process details (PID and comm) by I/O request, as well as a starting timestamp for calculating I/O latency, and the final summary.

This works by tracing various kernel blk_*() functions using dynamic tracing, and will need updating to match any changes to these functions.

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-C

Don't clear the screen.

-r MAXROWS

Maximum number of rows to print. Default is 20.

interval

Interval between updates, seconds.

count

Number of interval summaries.

## EXAMPLES
Summarize block device I/O by process, 1 second screen refresh:

\# biotop

Don't clear the screen:

\# biotop -C

5 second summaries, 10 times only:

\# biotop 5 10

## FIELDS
loadavg:

The contents of /proc/loadavg

PID

Cached process ID, if present. This usually (but isn't guaranteed) to identify the responsible process for the I/O.

COMM

Cached process name, if present. This usually (but isn't guaranteed) to identify the responsible process for the I/O.

D

Direction: R == read, W == write. This is a simplification.

MAJ

Major device number.

MIN

Minor device number.

DISK

Disk device name.

I/O

Number of I/O during the interval.

Kbytes

Total Kbytes for these I/O, during the interval.

AVGms

Average time for the I/O (latency) from the issue to the device, to its completion, in milliseconds.

## OVERHEAD
Since block device I/O usually has a relatively low frequency (< 10,000/s), the overhead for this tool is expected to be low or negligible. For high IOPS storage systems, test and quantify before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## INSPIRATION
top(1) by William LeFebvre

## SEE ALSO
biosnoop(8), biolatency(8), iostat(1)


bcc-bitesize

title: bcc-bitesize(8)

summary: Summarize block device I/O size as a histogram \- Linux eBPF/bcc.

text:
# bcc-bitesize(8)

## NAME
bitesize - Summarize block device I/O size as a histogram - Linux eBPF/bcc.

## SYNOPSIS
bitesize

## DESCRIPTION
Show I/O distribution for requested block sizes, by process name.

This works by tracing block:block_rq_issue and prints a historgram of I/O size.

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## EXAMPLES
Count I/O size per process until Ctrl-C is hit:

\# bitesize

## FIELDS
Kbtes

Size in kilobytes of range

count

How many I/O fell into this range

distribution

An ASCII bar chart to visualize the distribution (count column)

## OVERHEAD
This traces a block I/O tracepoint to update a histogram, which is asynchronously copied to user-space. This method is very efficient, and the overhead for most storage I/O rates (< 10k IOPS) should be negligible. If you have a higher IOPS storage environment, test and quantify the overhead before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Allan McAleavy

## SEE ALSO
https://github.com/brendangregg/systemtap-lwtools/blob/master/disk/bitesize-nd.stp


bcc-bpflist

title: bcc-bpflist(8)

text:
# bcc-bpflist(8)

## NAME
bpflist - Display processes currently using BPF programs and maps.

## SYNOPSIS
bpflist [-v]

## DESCRIPTION
This tool displays processes currently using BPF programs and maps, and optionally also kprobes and uprobes on the system. This is useful to understand which BPF programs are loaded on the system.

Currently, for lack of a better alternative, this tool pipes into 'ls' and parses its output to snoop for BPF file descriptors in all running processes. In the future, when BPF accounting is provided by the kernel, this tool should use these accounting features.

Only the root user can use this tool, because it accesses debugfs.

## REQUIREMENTS
bcc, debugfs

## OPTIONS
-h Print usage message.

-v

Count kprobes and uprobes as well as BPF programs. Repeating verbose mode twice also prints the kprobe and uprobe definitions in addition to counting them.

## EXAMPLES
Display processes currently using BPF programs:

\# bpflist

Also count kprobes and uprobes:

\# bpflist -v

## FIELDS
PID

Process ID.

COMM

Process comm.

TYPE

The type of the data displayed: BPF program, BPF map, kprobe, or uprobe.

COUNT

The number of items of this type that belong to the specified process.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Sasha Goldshtein


bcc-bps

title: bcc-bps(8)

text:
# bcc-bps(8)

## NAME
bps - List all BPF programs. 'ps' for BPF programs.

## SYNOPSIS
bps [bpf-prog-id]

## DESCRIPTION
bps lists all BPF programs loaded into the kernel. It is similar to the ps command but for the BPF programs.

Each loaded bpf program is identified by an unique integer (i.e. bpf-prog-id or simply BID). If a bpf-prog-id is specified, the maps used by bpf-prog-id will also be listed.

## EXAMPLES
List all BPF programs loaded into the kernel:

bps

Show the details and maps of BID 6:

bps 6

## BPF PROGRAM FIELDS
BID

BPF program ID. It ends with '-' if it is not jitted.

TYPE

The type of a BPF program. e.g. kprobe, tracepoint, xdp...etc.

UID

The user ID that loaded the BPF program.

\#MAPS

Total number of maps used by a BPF program.

LoadTime

When was the BPF program loaded?

NAME

The name of a BPF program. The user space library (like bcc ) usually uses the C function name of the original BPF's source code as the program name. It could be empty if the user space did not provide a name.

## BPF MAP FIELDS
MID

BPF map ID.

TYPE

The type of a BPF map. e.g. hash, array, stack trace...etc.

FLAGS

The flags used to create the BP map.

KeySz

The key size of a BPF map.

ValueSz

The value size of a BPF map.

MaxEnts

The maximum number of entries of a map.

NAME

The name of a BPF map. The user space library (like bcc ) usually uses the C variable name of the BPF map as its name. It could be empty if the user space did not provide a name.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Martin Lau


bcc-btrfsdist

title: bcc-btrfsdist(8)

text:
# bcc-btrfsdist(8)

## NAME
btrfsdist - Summarize btrfs operation latency. Uses Linux eBPF/bcc.

## SYNOPSIS
btrfsdist [-h] [-T] [-N] [-d] [interval] [count]

## DESCRIPTION
This tool summarizes time (latency) spent in common btrfs file operations: reads, writes, opens, and syncs, and presents it as a power-of-2 histogram. It uses an in-kernel eBPF map to store the histogram for efficiency.

Since this works by tracing the btrfs_file_operations interface functions, it will need updating to match any changes to these functions.

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-T

Don't include timestamps on interval output.

-m

Output in milliseconds.

-p PID

Trace this PID only.

## EXAMPLES
Trace btrfs operation time, and print a summary on Ctrl-C:

\# btrfsdist

Trace PID 181 only:

\# btrfsdist -p 181

Print 1 second summaries, 10 times:

\# btrfsdist 1 10

1 second summaries, printed in milliseconds

\# btrfsdist -m 1

## FIELDS
msecs

Range of milliseconds for this bucket.

usecs

Range of microseconds for this bucket.

count

Number of operations in this time range.

distribution

ASCII representation of the distribution (the count column).

## OVERHEAD
This adds low-overhead instrumentation to btrfs writes and fsyncs, as well as all system reads and opens (due to the current implementation of the btrfs_file_operations interface). Particularly, all reads and writes from the file system cache will incur extra overhead while tracing. Such reads and writes can be very frequent (depending on the workload; eg, 1M/sec), at which point the overhead of this tool may become noticeable. Measure and quantify before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
btrfsslower(8)


bcc-btrfsslower

title: bcc-btrfsslower(8)

text:
# bcc-btrfsslower(8)

## NAME
btrfsslower - Trace slow btrfs file operations, with per-event details.

## SYNOPSIS
btrfsslower [-h] [-j] [-p PID] [min_ms] [-d DURATION]

## DESCRIPTION
This tool traces common btrfs file operations: reads, writes, opens, and syncs. It measures the time spent in these operations, and prints details for each that exceeded a threshold.

WARNING: See the OVERHEAD section.

By default, a minimum millisecond threshold of 10 is used. If a threshold of 0 is used, all events are printed (warning: verbose).

Since this works by tracing the btrfs_file_operations interface functions, it will need updating to match any changes to these functions.

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-p PID Trace this PID only.

min_ms

Minimum I/O latency (duration) to trace, in milliseconds. Default is 10 ms.

-d DURATION

Total duration of trace in seconds.

## EXAMPLES
Trace synchronous file reads and writes slower than 10 ms:

\# btrfsslower

Trace slower than 1 ms:

\# btrfsslower 1

Trace slower than 1 ms, and output just the fields in parsable format (csv):

\# btrfsslower -j 1

Trace all file reads and writes (warning: the output will be verbose):

\# btrfsslower 0

Trace slower than 1 ms, for PID 181 only:

\# btrfsslower -p 181 1

Trace for 10 seconds only:

\# btrfsslower -d 10

## FIELDS
TIME(s)

Time of I/O completion since the first I/O seen, in seconds.

COMM

Process name.

PID

Process ID.

T

Type of operation. R == read, W == write, O == open, S == fsync.

OFF_KB

File offset for the I/O, in Kbytes.

BYTES

Size of I/O, in bytes.

LAT(ms)

Latency (duration) of I/O, measured from when it was issued by VFS to the filesystem, to when it completed. This time is inclusive of block device I/O, file system CPU cycles, file system locks, run queue latency, etc. It's a more accurate measure of the latency suffered by applications performing file system I/O, than to measure this down at the block device interface.

FILENAME

A cached kernel file name (comes from dentry->d_name.name).

ENDTIME_us

Completion timestamp, microseconds (-j only).

OFFSET_b

File offset, bytes (-j only).

LATENCY_us

Latency (duration) of the I/O, in microseconds (-j only).

## OVERHEAD
This adds low-overhead instrumentation to btrfs writes and fsyncs, as well as all system reads and opens (due to the current implementation of the btrfs_file_operations interface). Particularly, all reads and writes from the file system cache will incur extra overhead while tracing. Such reads and writes can be very frequent (depending on the workload; eg, 1M/sec), at which point the overhead of this tool may become noticeable. Measure and quantify before use. If this continues to be a problem, consider switching to a tool that prints in-kernel summaries only, such as btrfsdist(8).

Note that the overhead of this tool should be less than fileslower(8), as this tool targets btrfs functions only, and not all file read/write paths (which can include socket I/O).

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
btrfsdist(8), biosnoop(8), funccount(8), fileslower(8)


bcc-cachestat

title: bcc-cachestat(8)

text:
# bcc-cachestat(8)

## NAME
cachestat - Statistics for linux page cache hit/miss ratios. Uses Linux eBPF/bcc.

## SYNOPSIS
cachestat [-T] [interval [count]]

## DESCRIPTION
This traces four kernel functions and prints per-second summaries. This can be useful for general workload characterization, and looking for patterns in operation usage over time.

This works by tracing kernel page cache functions using dynamic tracing, and will need updating to match any changes to these functions. Edit the script to customize which functions are traced.

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## EXAMPLES
Print summaries every second:

\# cachestat

Print summaries every second with timestamp:

\# cachestat -T

Print output every five seconds, three times:

\# cachestat 5 3

Print output with timestamp every five seconds, three times:

\# cachestat -T 5 3

## FIELDS
TIME

Timestamp.

HITS

Number of page cache hits.

MISSES

Number of page cache misses.

DIRTIES

Number of dirty pages added to the page cache.

HITRATIO

The hit ratio as a percentage.

READ_HIT%

Read hit percent of page cache usage.

WRITE_HIT%

Write hit percent of page cache usage.

BUFFERS_MB

Buffers size taken from /proc/meminfo.

CACHED_MB

Cached amount of data in current page cache taken from /proc/meminfo.

## OVERHEAD
This traces various kernel page cache functions and maintains in-kernel counts, which are asynchronously copied to user-space. While the rate of operations can be very high (>1G/sec) we can have up to 34% overhead, this is still a relatively efficient way to trace these events, and so the overhead is expected to be small for normal workloads. Measure in a test environment.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Allan McAleavy

## SEE ALSO
https://github.com/brendangregg/perf-tools/blob/master/fs/cachestat


bcc-cachetop

title: bcc-cachetop(8)

text:
# bcc-cachetop(8)

## NAME
cachetop - Statistics for linux page cache hit/miss ratios per processes. Uses Linux eBPF/bcc.

## SYNOPSIS
cachetop [interval]

## DESCRIPTION
This traces four kernel functions and prints per-processes summaries every interval seconds. This can be useful for processes workload characterization, and looking for patterns in operation usage over time. It provides a top-like interface which by default sorts by HITS in ascending order.

This works by tracing kernel page cache functions using dynamic tracing, and will need updating to match any changes to these functions. Edit the script to customize which functions are traced.

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

## KEYBINDINGS
The following keybindings can be used to control the output of cachetop.

<

Use the previous column for sorting.

>

Use the next column for sorting.

r

Toggle sorting order (default ascending).

q

Quit cachetop.

## REQUIREMENTS
CONFIG_BPF and bcc.

## EXAMPLES
Update summaries every five second:

\# cachetop

Print summaries each second:

\# cachetop 1

## FIELDS
PID

Process ID of the process causing the cache activity.

UID

User ID of the process causing the cache activity.

HITS

Number of page cache hits.

MISSES

Number of page cache misses.

DIRTIES

Number of dirty pages added to the page cache.

READ_HIT%

Read hit percent of page cache usage.

WRITE_HIT%

Write hit percent of page cache usage.

BUFFERS_MB

Buffers size taken from /proc/meminfo.

CACHED_MB

Cached amount of data in current page cache taken from /proc/meminfo.

## OVERHEAD
This traces various kernel page cache functions and maintains in-kernel counts, which are asynchronously copied to user-space. While the rate of operations can be very high (>1G/sec) we can have up to 34% overhead, this is still a relatively efficient way to trace these events, and so the overhead is expected to be small for normal workloads. Measure in a test environment.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Emmanuel Bretelle

## SEE ALSO
cachestat (8)


bcc-capable

title: bcc-capable(8)

text:
# bcc-capable(8)

## NAME
capable - Trace security capability checks (cap_capable()).

## SYNOPSIS
capable [-h] [-v] [-p PID] [-K] [-U] [-x] [--cgroupmap MAPPATH]

[--mntnsmap MAPPATH] [--unique]

## DESCRIPTION
This traces security capability checks in the kernel, and prints details for each call. This can be useful for general debugging, and also security enforcement: determining a white list of capabilities an application needs.

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

## REQUIREMENTS
CONFIG_BPF, bcc.

## OPTIONS
-h USAGE message.

-v

Include non-audit capability checks. These are those deemed not interesting and not necessary to audit, such as CAP_SYS_ADMIN checks on memory allocation to affect the behavior of overcommit.

-K

Include kernel stack traces to the output.

-U

Include user-space stack traces to the output.

-x

Show extra fields in TID and INSETID columns.

--cgroupmap MAPPATH

Trace cgroups in this BPF map only (filtered in-kernel).

--mntnsmap MAPPATH

Trace mount namespaces in this BPF map only (filtered in-kernel).

--unique

Don't repeat stacks for the same PID or cgroup.

## EXAMPLES
Trace all capability checks system-wide:

\# capable

Trace capability checks for PID 181:

\# capable -p 181

Trace capability checks in a set of cgroups only (see special_filtering.md

from bcc sources for more details): # capable --cgroupmap /sys/fs/bpf/test01

## FIELDS
TIME(s)

Time of capability check: HH:MM:SS.

UID

User ID.

PID

Process ID.

COMM

Process name. CAP Capability number. NAME Capability name. See capabilities(7) for descriptions.

AUDIT

Whether this was an audit event. Use -v to include non-audit events. INSETID Whether the INSETID bit was set (Linux >= 5.1).

## OVERHEAD
This adds low-overhead instrumentation to capability checks, which are expected to be low frequency, however, that depends on the application. Test in a lab environment before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
capabilities(7)


bcc-cobjnew

title: bcc-cobjnew(8)

summary: Summarize object allocations in

text:
# bcc-cobjnew(8)

## NAME
uobjnew, cobjnew, javaobjnew, rubyobjnew, tclobjnew - Summarize object allocations in high-level languages.

## SYNOPSIS
cobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]

javaobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]

rubyobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]

tclobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]

uobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] [-l {c,java,ruby,tcl}] pid [interval]

## DESCRIPTION
uobjnew traces object allocations in high-level languages (including "malloc") and prints summaries of the most frequently allocated types by number of objects or number of bytes.

This tool relies on USDT probes embedded in many high-level languages, such as C, Java, Ruby, and Tcl. It requires a runtime instrumented with these probes, which in some cases requires building from source with a USDT-specific flag, such as "--enable-dtrace" or "--with-dtrace". For Java, the Java process must be started with the "-XX:+ExtendedDTraceProbes" flag.

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-C TOP_COUNT

Print the top object types sorted by number of instances.

-S TOP_SIZE

Print the top object types sorted by size.

-v

Print the resulting BPF program, for debugging purposes.

{c,java,ruby,tcl}

The language to trace.

pid

The process id to trace.

interval

Wait this many seconds and then print the summary and exit. By default, wait for Ctrl+C to exit.

## EXAMPLES
Trace object allocations in a Ruby process:

\# uobjnew ruby 148

Trace object allocations from "malloc" and print the top 10 by total size:

\# uobjnew -S 10 c 1788

## FIELDS
TYPE

The object type being allocated. For C (malloc), this is the block size.

ALLOCS

The number of objects allocated.

BYTES

The number of bytes allocated.

## OVERHEAD
Object allocation events are quite frequent, and therefore the overhead from running this tool can be considerable. Use with caution and make sure to test before using in a production environment. Nonetheless, even thousands of allocations per second will likely produce a reasonable overhead when investigating a problem.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _example.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Sasha Goldshtein

## SEE ALSO
ustat(8), ugc(8), memleak(8)


bcc-compactsnoop

title: bcc-compactsnoop(8)

text:
# bcc-compactsnoop(8)

## NAME
compactstall - Trace compact zone events. Uses Linux eBPF/bcc.

## SYNOPSIS
compactsnoop.py [-h] [-T] [-p PID] [-d DURATION] [-K] [-e]

## DESCRIPTION
compactsnoop traces the compact zone events, showing which processes are allocing pages with memory compaction. This can be useful for discovering when compact_stall (/proc/vmstat) continues to increase, whether it is caused by some critical processes or not.

This works by tracing the compact zone events using raw_tracepoints and one kretprobe.

For the Centos 7.6 (3.10.x kernel), see the version under tools/old, which uses an older memory compaction mechanism.

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-T

Include a timestamp column.

-p PID

Trace this process ID only (filtered in-kernel).

-d DURATION

Total duration of trace in seconds.

-K

Output kernel stack trace

-e

Show extended fields.

## EXAMPLES
Trace all compact zone events:

\# compactsnoop

Trace all compact zone events, for 10 seconds only:

\# compactsnoop -d 10

## FIELDS
TIME(s)

Time of the call, in seconds.

COMM

Process name

PID

Process ID

NODE

Memory node

ZONE

Zone of the node (such as DMA, DMA32, NORMAL eg)

ORDER

Shows which order alloc cause memory compaction, -1 means all orders (eg: write to /proc/sys/vm/compact_memory)

MODE

SYNC OR ASYNC

FRAGIDX (extra column)

The FRAGIDX is short for fragmentation index, which only makes sense if an allocation of a requested size would fail. If that is true, the fragmentation index indicates whether external fragmentation or a lack of memory was the problem. The value can be used to determine if page reclaim or compaction should be used.

Index is between 0 and 1 so return within 3 decimal places

0 => allocation would fail due to lack of memory

1 => allocation would fail due to fragmentation

MIN (extra column)

The min watermark of the zone

LOW (extra column)

The low watermark of the zone

HIGH (extra column)

The high watermark of the zone

FREE (extra column)

The nr_free_pages of the zone

LAT(ms)

compact zone's latency

STATUS

The compaction's result.

For (CentOS 7.6's kernel), the status include:

"skipped" (COMPACT_SKIPPED): compaction didn't start as it was not possible or direct reclaim was more suitable

"continue" (COMPACT_CONTINUE): compaction should continue to another pageblock

"partial" (COMPACT_PARTIAL): direct compaction partially compacted a zone and there are suitable pages

"complete" (COMPACT_COMPLETE): The full zone was compacted

For (kernel 4.7 and above):

"not_suitable_zone" (COMPACT_NOT_SUITABLE_ZONE): For more detailed tracepoint output - internal to compaction

"skipped" (COMPACT_SKIPPED): compaction didn't start as it was not possible or direct reclaim was more suitable

"deferred" (COMPACT_DEFERRED): compaction didn't start as it was deferred due to past failures

"no_suitable_page" (COMPACT_NOT_SUITABLE_PAGE): For more detailed tracepoint output - internal to compaction

"continue" (COMPACT_CONTINUE): compaction should continue to another pageblock

"complete" (COMPACT_COMPLETE): The full zone was compacted scanned but wasn't successful to compact suitable pages.

"partial_skipped" (COMPACT_PARTIAL_SKIPPED): direct compaction has scanned part of the zone but wasn't successful to compact suitable pages.

"contended" (COMPACT_CONTENDED): compaction terminated prematurely due to lock contentions

"success" (COMPACT_SUCCESS): direct compaction terminated after concluding that the allocation should now succeed

## OVERHEAD
This traces the kernel compact zone kprobe/kretprobe or raw_tracepoints and prints output for each event. As the rate of this is generally expected to be low (< 1000/s), the overhead is also expected to be negligible.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Wenbo Zhang


bcc-cpudist

title: bcc-cpudist(8)

text:
# bcc-cpudist(8)

## NAME
cpudist - On- and off-CPU task time as a histogram.

## SYNOPSIS
cpudist [-h] [-O] [-T] [-m] [-P] [-L] [-p PID] [interval] [count]

## DESCRIPTION
This measures the time a task spends on the CPU before being descheduled, and shows the times as a histogram. Tasks that spend a very short time on the CPU can be indicative of excessive context-switches and poor workload distribution, and possibly point to a shared source of contention that keeps tasks switching in and out as it becomes available (such as a mutex).

Similarly, the tool can also measure the time a task spends off-CPU before it is scheduled again. This can be helpful in identifying long blocking and I/O operations, or alternatively very short descheduling times due to short-lived locks or timers.

This tool uses in-kernel eBPF maps for storing timestamps and the histogram, for efficiency. Despite this, the overhead of this tool may become significant for some workloads: see the OVERHEAD section.

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-O

Measure off-CPU time instead of on-CPU time.

-T

Include timestamps on output.

-m

Output histogram in milliseconds.

-P

Print a histogram for each PID (tgid from the kernel's perspective).

-L

Print a histogram for each TID (pid from the kernel's perspective).

-p PID

Only show this PID (filtered in kernel for efficiency).

interval

Output interval, in seconds.

count

Number of outputs.

## EXAMPLES
Summarize task on-CPU time as a histogram:

\# cpudist

Summarize task off-CPU time as a histogram:

\# cpudist -O

Print 1 second summaries, 10 times:

\# cpudist 1 10

Print 1 second summaries, using milliseconds as units for the histogram, and include timestamps on output:

\# cpudist -mT 1

Trace PID 186 only, 1 second summaries:

\# cpudist -P 185 1

## FIELDS
usecs

Microsecond range

msecs

Millisecond range

count

How many times a task event fell into this range

distribution

An ASCII bar chart to visualize the distribution (count column)

## OVERHEAD
This traces scheduler tracepoints, which can become very frequent. While eBPF has very low overhead, and this tool uses in-kernel maps for efficiency, the frequency of scheduler events for some workloads may be high enough that the overhead of this tool becomes significant. Measure in a lab environment to quantify the overhead before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _example.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Sasha Goldshtein

## SEE ALSO
pidstat(1), runqlat(8)


bcc-cpuunclaimed

title: bcc-cpuunclaimed(8)

text:
# bcc-cpuunclaimed(8)

## NAME
cpuunclaimed - Sample CPU run queues and calculate unclaimed idle CPU. Uses Linux eBPF/bcc.

## SYNOPSIS
cpuunclaimed [-T] [-j] [-J] [interval [count]]

## DESCRIPTION
This tool samples the length of the run queues and determine when there are idle CPUs, yet queued threads waiting their turn. It reports the amount of idle (yet unclaimed by waiting threads) CPU as a system-wide percentage.

This situation can happen for a number of reasons:

-

An application has been bound to some, but not all, CPUs, and has runnable threads that cannot migrate to other CPUs due to this configuration.

-

CPU affinity: an optimization that leaves threads on CPUs where the CPU caches are warm, even if this means short periods of waiting while other CPUs are idle. The wait period is tunale (see sysctl, kernel.sched*).

-

Scheduler bugs.

An unclaimed idle of < 1% is likely to be CPU affinity, and not usually a cause for concern. By leaving the CPU idle, overall throughput of the system may be improved. This tool is best for identifying larger issues, > 2%, due to the coarseness of its 99 Hertz samples.

This is an experimental tool that currently works by use of sampling to keep overheads low. Tool assumptions:

-

CPU samples consistently fire around the same offset. There will sometimes be a lag as a sample is delayed by higher-priority interrupts, but it is assumed the subsequent samples will catch up to the expected offsets (as is seen in practice). You can use -J to inspect sample offsets. Some systems can power down CPUs when idle, and when they wake up again they may begin firing at a skewed offset: this tool will detect the skew, print an error, and exit.

-

All CPUs are online (see ncpu).

If this identifies unclaimed CPU, you can double check it by dumping raw samples (-j), as well as using other tracing tools to instrument scheduler events (although this latter approach has much higher overhead).

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## EXAMPLES
Sample and calculate unclaimed idle CPUs, output every 1 second (default:

\# cpuunclaimed

Print 5 second summaries, 10 times:

\# cpuunclaimed 5 10

Print 1 second summaries with timestamps:

\# cpuunclaimed -T 1

Raw dump of all samples (verbose), as comma-separated values:

\# cpuunclaimed -j

## FIELDS
%CPU

CPU utilization as a system-wide percentage.

unclaimed idle

Percentage of CPU resources that were idle when work was queued on other CPUs, as a system-wide percentage.

TIME

Time (HH:MM:SS)

TIMESTAMP_ns

Timestamp, nanoseconds.

CPU#

CPU ID.

OFFSET_ns_CPU#

Time offset that a sample fired within a sample group for this CPU.

## OVERHEAD
The overhead is expected to be low/negligible as this tool uses sampling at 99 Hertz (on all CPUs), which has a fixed and low cost, rather than sampling every scheduler event as many other approaches use (which can involve instrumenting millions of events per second). Sampled CPUs, run queue lengths, and timestamps are written to ring buffers that are periodically read by user space for reporting. Measure overhead in a test environment.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
runqlen(8)


bcc-criticalstat

title: bcc-criticalstat(8)

text:
# bcc-criticalstat(8)

## NAME
criticalstat - A tracer to find and report long atomic critical sections in kernel

## SYNOPSIS
criticalstat [-h] [-p] [-i] [-d DURATION]

## DESCRIPTION
criticalstat traces and reports occurrences of atomic critical sections in the kernel with useful stacktraces showing the origin of them. Such critical sections frequently occur due to use of spinlocks, or if interrupts or preemption were explicitly disabled by a driver. IRQ routines in Linux are also executed with interrupts disabled. There are many reasons. Such critical sections are a source of long latency/responsive issues for real-time systems.

This works by probing the preempt/irq and cpuidle tracepoints in the kernel. Since this uses BPF, only the root user can use this tool. Further, the kernel has to be built with certain CONFIG options enabled. See below.

## REQUIREMENTS
Enable CONFIG_PREEMPTIRQ_EVENTS and CONFIG_DEBUG_PREEMPT. Additionally, the following options should be DISABLED on older kernels: CONFIG_PROVE_LOCKING, CONFIG_LOCKDEP.

## OPTIONS
-h

Print usage message.

-p

Find long sections where preemption was disabled on local CPU.

-i

Find long sections where interrupt was disabled on local CPU.

-d DURATION

Only identify sections that are longer than DURATION in microseconds.

## EXAMPLES
Run with default options: irq disabled for more than 100 uS

\# criticalstat

Find sections with preemption disabled for more than 100 uS.

\# criticalstat -p

Find sections with IRQ disabled for more than 500 uS.

\# criticalstat -d 500

Find sections with preemption disabled for more than 500 uS.

\# criticalstat -p -d 500

## OVERHEAD
This tool can cause overhead if the application is spending a lot of time in kernel mode. The overhead is variable but can be 2-4% of performance degradation. If overhead is seen to be too much, please pass a higher DURATION to the -d option to filter more aggressively.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Joel Fernandes

## SEE ALSO
Linux kernel's preemptoff and irqoff tracers.