blktrace

title: blktrace(8)

text:
# blktrace(8)

## NAME
blktrace - generate traces of the i/o traffic on block devices

## SYNOPSIS
blktrace -d dev [ -r debugfs_path ] [ -o output ] [ -w time ] [ -a action ] [ -A action_mask ] [ -v ]

## DESCRIPTION
blktrace is a block layer IO tracing mechanism which provides detailed information about request queue operations up to user space. There are three major components: a kernel component, a utility to record the i/o trace information for the kernel to user space, and utilities to analyse and view the trace information. This man page describes blktrace, which records the i/o event trace information for a specific block device to a file.

The blktrace utility extracts event traces from the kernel (via the relaying through the debug file system). Some background details concerning the run-time behaviour of blktrace will help to understand some of the more arcane command line options:

-

blktrace receives data from the kernel in buffers passed up through the debug file system (relay). Each device being traced has a file created in the mounted directory for the debugfs, which defaults to /sys/kernel/debug -- this can be overridden with the -r command line argument.

-

blktrace defaults to collecting all events that can be traced. To limit the events being captured, you can specify one or more filter masks via the -a option. Alternatively, one may specify the entire mask utilising a hexadecimal value that is version-specific. (Requires understanding of the internal representation of the filter mask.)

-

As noted above, the events are passed up via a series of buffers stored into debugfs files. The size and number of buffers can be specified via the -b and -n arguments respectively.

-

blktrace stores the extracted data into files stored in the local directory. The format of the file names is (by default) device.blktrace.cpu, where device is the base device name (e.g, if we are tracing /dev/sda, the base device name would be sda); and cpu identifies a CPU for the event stream. The device portion of the event file name can be changed via the -o option.

-

blktrace may also be run concurrently with blkparse to produce live output -- to do this specify -o - for blktrace.

-

The default behaviour for blktrace is to run forever until explicitly killed by the user (via a control-C, or sending SIGINT signal to the process via invocation the kill (1) utility). Also you can specify a run-time duration for blktrace via the -w option -- then blktrace will run for the specified number of seconds, and then halt.

## OPTIONS
-A hex-mask

--set-mask=hex-mask

Set filter mask to hex-mask (see below for masks)

-a mask

--act-mask=mask

Add mask to current filter (see below for masks)

-b size

--buffer-size=size

Specifies buffer size for event extraction (scaled by 1024). The default buffer size is 512KiB.

-d dev

--dev=dev

Adds dev as a device to trace

-I file

--input-devs=file

Adds the devices found in file as devices to trace

-n num-sub

--num-sub-buffers=num-sub

Specifies number of buffers to use. blktrace defaults to 4 sub buffers.

-l

--listen

Run in network listen mode (blktrace server)

-h hostname

--host=hostname

Run in network client mode, connecting to the given host

-p number

--port=number

Network port to use (default 8462)

-s

--no-sendfile

Make the network client NOT use sendfile() to transfer data

-o basename

--output=basename

Specifies base name for input files. Default is device.blktrace.cpu. Specifying -o - runs in live mode with blkparse (writing data to standard out).

-D dir

--output-dir=dir

Prepend file to output file name(s) This only works when supplying a single device, or when piping the output via "-o -" with multiple devices.

-r rel-path

--relay=rel-path

Specifies debugfs mount point

-v

--version

Outputs version

-V

--version

Outputs version

-w seconds

--stopwatch=seconds

Sets run time to the number of seconds specified

## FILTER MASKS
The following masks may be passed with the -a command line option, multiple filters may be combined via multiple -a command line options.

barrier: barrier attribute

complete: completed by driver

discard: discard / trim traces

fs: requests

issue: issued to driver

pc: packet command events

queue: queue operations

read: read traces

requeue: requeue operations

sync: synchronous attribute

write: write traces

notify: trace messages

drv_data: additional driver specific trace

## REQUEST TYPES
blktrace distinguishes between two types of block layer requests, file system and SCSI commands. The former are dubbed fs requests, the latter pc requests. File system requests are normal read/write operations, i.e. any type of read or write from a specific disk location at a given size. These requests typically originate from a user process, but they may also be initiated by the vm flushing dirty data to disk or the file system syncing a super or journal block to disk. pc requests are SCSI commands. blktrace sends the command data block as a payload so that blkparse can decode it.

## EXAMPLES
To trace the i/o on the device /dev/sda and parse the output to human readable form, use the following command:

% blktrace -d /dev/sda -o - | blkparse -i -

This same behaviour can be achieve with the convenience script btrace. The command

% btrace /dev/sda

has exactly the same effect as the previous command. See btrace (8) for more information.

To trace the i/o on a device and save the output for later processing with blkparse, use blktrace like this:

% blktrace /dev/sda /dev/sdb

This will trace i/o on the devices /dev/sda and /dev/sdb and save the recorded information in the files sda and sdb in the current directory, for the two different devices, respectively. This trace information can later be parsed by the blkparse utility:

% blkparse sda sdb

which will output the previously recorded tracing information in human readable form to stdout. See blkparse (1) for more information.

## AUTHORS
blktrace was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This man page was created from the blktrace documentation by Bas Zoetekouw.

## REPORTING BUGS
Report bugs to <linux-btrace@vger.kernel.org>

## COPYRIGHT
Copyright © 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.

This is free software. You may redistribute copies of it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.

This manual page was created for Debian by Bas Zoetekouw. It was derived from the documentation provided by the authors and it may be used, distributed and modified under the terms of the GNU General Public License, version 2.

On Debian systems, the text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-2.

## SEE ALSO
btrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1)


btrace

package: blktrace

title: btrace(8)

summary: perform live tracing for block devices

text:
# btrace(8)

## NAME
btrace - perform live tracing for block devices

## SYNOPSIS
btrace [-s] [-t] [-w N] [-n N] [-b N] [-r <dbg mnt>] [-a <trace>...] <dev>...

## DESCRIPTION
The btrace script provides a quick and easy way to do live tracing of block devices. It calls blktrace on the specified devices and pipes the output through blkparse for formatting. See blktrace (8) for more in-depth information about how blktrace works.

## OPTIONS
-s Displays data sorted by program (see blkparse (1)).

-t Displays time deltas per IO (see blkparse (1)).

-w N Sets run time to the number of seconds specified (see blktrace (8)).

-n N Specifies the number of buffers to use (see blktrace (8)).

-b N Specifies buffer size for event extraction (scaled by 1024) (see blktrace (8)).

-r <dbg mnt> Specifies the debugfs mountpoint.

-a <trace>... Adds mask to current filter (see blktrace (8)).

<dev> Specifies the device to trace.

## EXAMPLE
Simply running

% btrace /dev/sda

will show a trace of the device /dev/sda.

## AUTHORS
blkparse was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This man page was created from the blktrace documentation by Bas Zoetekouw.

## REPORTING BUGS
Report bugs to <linux-btrace@vger.kernel.org>

## COPYRIGHT
Copyright © 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.

This is free software. You may redistribute copies of it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.

This manual page was created for Debian by Bas Zoetekouw. It was derived from the documentation provided by the authors and it may be used, distributed and modified under the terms of the GNU General Public License, version 2.

On Debian systems, the text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-2.

## SEE ALSO
blktrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1)


btrecord

title: btrecord(8)

summary: recreate IO loads recorded by blktrace

text:
# btrecord(8)

## NAME
btrecord - recreate IO loads recorded by blktrace

## SYNOPSIS
Usage:

btrecord [ options ] <dev...>

## DESCRIPTION
The btrecord and btreplay tools provide the ability to record and replay IOs captured by the blktrace utility. Attempts are made to maintain ordering, CPU mappings and time-separation of IOs.

The blktrace utility provides the ability to collect detailed traces from the kernel for each IO processed by the block IO layer. The traces provide a complete timeline for each IO processed, including detailed information concerning when an IO was first received by the block IO layer — indicating the device, CPU number, time stamp, IO direction, sector number and IO size (number of sectors). Using this information, one is able to replay the IO again on the same machine or another set up entirely.

The basic operating work-flow to replay IOs would be something like:

-

Run blktrace to collect traces. Here you specify the

device or devices that you wish to trace and later replay IOs upon. Note:

the only traces you are interested in are QUEUE requests —

thus, to save system resources (including storage for traces), one could

specify the -a queue command line option to blktrace.

-

While blktrace is running, you run the workload that you

are interested in.

-

When the work load has completed, you stop the blktrace

utility (thus saving all traces over the complete workload).

-

You extract the pertinent IO information from the traces saved by

blktrace using the btrecord utility. This will parse

each trace file created by blktrace, and crafty IO descriptions

to be used in the next phase of the workload processing.

-

Once btrecord has successfully created a series of data

files to be processed, you can run the btreplay utility which

attempts to generate the same IOs seen during the sample workload phase.

## OPTIONS
-d <dir>

--input-directory=<dir>

Set input directory. This option requires a single parameter providing the directory name for where input files are to be found. The default directory is the current directory (.).

-D <dir>

--output-directory=<dir>

Set output directory. This option requires a single parameter providing the directory name for where output files are to be found. The default directory is the current directory (.).

-F

--find-traces

Find trace files automatically This option instructs btreplay to go find all the trace files in the directory specified (either via the -d option, or in the default directory (.).

-h

--help

Show help and exit.

-V

--version

Show version number and exit.

-m <nanoseconds>

--max-bunch-time=<nanoseconds>

The -m option requires a single parameter which specifies an amount of time (in nanoseconds) to include in any one bunch of IOs that are to be processed. The smaller the value, the smaller the number of IOs processed at one time — perhaps yielding in more realistic replay. However, after a certain point the amount of overhead per bunch may result in additional real replay time, thus yielding less accurate replay times. The default value is 10,000,000 nanoseconds (10 milliseconds).

-M <num>

--max-pkts=<num>

Set maximum number of packets per bunch. The -M option requires a single parameter which specifies the maximum number of IOs to store in a single bunch. As with the -m option, smaller values may or may not yield more accurate replay times. The default value is 8, with a maximum value of up to 512 being supported.

-o <basename>

--output-base=<basename>

Set base name for output files. Each output file has 3 fields: 1.

Device identifier (taken directly from the device name of the

blktrace output file).

2.

btrecord base name — by default ``replay''.

3.

The CPU number (again, taken directly from the

blktrace output file name).

This option requires a single parameter that will override the default name (replay), and replace it with the specified value.

-v

--verbose

Enable verbose output. This option will output some simple statistics at the end of a successful run. Example output is:

```
sdab:0: 580661 pkts (tot), 126030 pkts (replay), 89809 bunches, 1.4 pkts/bunch
sdab:1: 2559775 pkts (tot), 430172 pkts (replay), 293029 bunches, 1.5 pkts/bunch
sdab:2: 653559 pkts (tot), 136522 pkts (replay), 102288 bunches, 1.3 pkts/bunch
sdab:3: 474773 pkts (tot), 117849 pkts (replay), 69572 bunches, 1.7 pkts/bunch
```

The meaning of the columns is:

1.

The first field contains the device name and CPU identifier. Thus:

sdab:0: means the device sdab and traces on CPU 0.

2.

The second field contains the total number of packets processed for each

device file.

3.

The next field shows the number of packets eligible for replay.

4.

The fourth field contains the total number of IO bunches.

5.

The last field shows the average number of IOs per bunch recorded.

## AUTHORS
btrecord was written by Alan D. Brunelle. This man page was created from the btreplay documentation by Bas Zoetekouw.

## REPORTING BUGS
Report bugs to <linux-btrace@vger.kernel.org>

## COPYRIGHT
Copyright © 2007 Alan D. Brunelle, Alan D. Brunelle and Nathan Scott.

This is free software. You may redistribute copies of it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.

This manual page was created for Debian by Bas Zoetekouw. It was derived from the documentation provided by the authors and it may be used, distributed and modified under the terms of the GNU General Public License, version 2.

On Debian systems, the text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-2.

## SEE ALSO
The full documentation for btreplay can be found in /usr/share/doc/blktrace on Debian systems.

blktrace (8), blkparse (1), btreplay (8)


btreplay

title: btreplay(8)

summary: recreate IO loads recorded by blktrace

text:
# btreplay(8)

## NAME
btreplay - recreate IO loads recorded by blktrace

## SYNOPSIS
btreplay [ options ] <dev...>

## DESCRIPTION
The btrecord and btreplay tools provide the ability to record and replay IOs captured by the blktrace utility. Attempts are made to maintain ordering, CPU mappings and time-separation of IOs.

The blktrace utility provides the ability to collect detailed traces from the kernel for each IO processed by the block IO layer. The traces provide a complete timeline for each IO processed, including detailed information concerning when an IO was first received by the block IO layer — indicating the device, CPU number, time stamp, IO direction, sector number and IO size (number of sectors). Using this information, one is able to replay the IO again on the same machine or another set up entirely.

The basic operating work-flow to replay IOs would be something like:

-

Run blktrace to collect traces. Here you specify the

device or devices that you wish to trace and later replay IOs upon. Note:

the only traces you are interested in are QUEUE requests —

thus, to save system resources (including storage for traces), one could

specify the -a queue command line option to blktrace.

-

While blktrace is running, you run the workload that you

are interested in.

-

When the work load has completed, you stop the blktrace

utility (thus saving all traces over the complete workload).

-

You extract the pertinent IO information from the traces saved by

blktrace using the btrecord utility. This will parse

each trace file created by blktrace, and crafty IO descriptions

to be used in the next phase of the workload processing.

-

Once btrecord has successfully created a series of data

files to be processed, you can run the btreplay utility which

attempts to generate the same IOs seen during the sample workload phase.

## OPTIONS
-c <num>

--cpus=<num>

Set number of CPUs to use.

-d <dir>

--input-directory=<dir>

Set input directory. This option requires a single parameter providing the directory name for where input files are to be found. The default directory is the current directory (.).

-F

--find-records

Find record files automatically This option instructs btreplay to go find all the record files in the directory specified (either via the -d option, or in the default directory (.).

-h

--help

Show help and exit.

-i <basename>

--input-base=<basename>

Set base name for input files. Each input file has 3 fields: 1.

Device identifier (taken directly from the device name of the

blktrace output file).

2.

btrecord base name — by default ``replay''.

3.

The CPU number (again, taken directly from the

blktrace output file name).

This option requires a single parameter that will override the default name (replay), and replace it with the specified value.

-I <num>

--iterations=<num>

Set number of iterations to run. This option requires a single parameter which specifies the number of times to run through the input files. The default value is 1

-M <filename>

--map-devs=<filename>

Specify device mappings. This option requires a single parameter which specifies the name of a file contain device mappings. The file must be very simply managed, with just two pieces of data per line:

-

The device name on the recorded system (with the '/dev/'

removed). Example: /dev/sda would just be sda.

-

The device name on the replay system to use (again, without the

'/dev/' path prepended).

An example file for when one would map devices /dev/sda and /dev/sdb on the recorded system to dev/sdg and sdh on the replay system would be:

```
sda sdg
sdb sdh
```

The only entries in the file that are allowed are these two element lines — we do not (yet?) support the notion of blank lines, or comment lines, or the like.

The utility allows for multiple -M options to be supplied on the command line.

-N

--no-stalls

Disable pre-bunch stalls. When specified on the command line, all pre-bunch stall indicators will be ignored. IOs will be replayed without inter-bunch delays.

-x <factor>

--acc-factor=<factor>

Specify acceleration factor. Default value is 1 (no acceleration).

-v

--verbose

Enable verbose output. When specified on the command line, this option instructs btreplay to store information concerning each stall and IO operation performed by btreplay. The name of each file so created will be the input file name used with an extension of .rep appended onto it. Thus, an input file of the name sdab.replay.3 would generate a verbose output file with the name sdab.replay.3.rep in the directory specified for input files. In addition, btreplay will also output to stderr the names of the input files being processed.

-V

--version

Show version number and exit.

-W

--write-enable

Enable writing during replay. As a precautionary measure, by default btreplay will not process write requests. In order to enable btreplay to actually write to devices one must explicitly specify the -W option.

## AUTHORS
btreplay was written by Alan D. Brunelle. This man page was created from the btreplay documentation by Bas Zoetekouw.

## REPORTING BUGS
Report bugs to <linux-btrace@vger.kernel.org>

## COPYRIGHT
Copyright © 2007 Alan D. Brunelle, Alan D. Brunelle and Nathan Scott.

This is free software. You may redistribute copies of it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.

This manual page was created for Debian by Bas Zoetekouw. It was derived from the documentation provided by the authors and it may be used, distributed and modified under the terms of the GNU General Public License, version 2.

On Debian systems, the text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-2.

## SEE ALSO
The full documentation for btreplay can be found in /usr/share/doc/blktrace on Debian systems.

blktrace (8), blkparse (1), btrecord (8)


bluetoothd

package: bluez

title: bluetoothd(8)

summary: Bluetooth daemon

text:
# bluetoothd(8)

## NAME
bluetoothd - Bluetooth daemon

## SYNOPSIS
bluetoothd [--version] | [--help]

bluetoothd [--nodetach] [--compat] [--experimental] [--debug=<files>] [--plugin=<plugins>] [--noplugin=<plugins>]

## DESCRIPTION
This manual page documents briefly the bluetoothd daemon, which manages all the Bluetooth devices. bluetoothd can also provide a number of services via the D-Bus message bus system.

## OPTIONS
-v, --version

Print bluetoothd version and exit.

-h, --help

Print bluetoothd options and exit.

-n, --nodetach

Enable logging in foreground. Directs log output to the controlling terminal in addition to syslog.

-f, --configfile

Specifies an explicit config file path instead of relying on the default path(/etc/bluetooth/main.conf) for the config file.

-d, --debug=<file1>:<file2>:...

Sets how much information bluetoothd sends to the log destination (usually syslog's "daemon" facility). If the file options are omitted, then debugging information from all the source files are printed. If file options are present, then only debug prints from that source file are printed. The option can be a pattern containing "*" and "?" characters. Example: --debug=src/adapter.c:src/agent.c

-p, --plugin=<plugin1>,<plugin2>,..

Load these plugins only. The option can be a pattern containing "*" and "?" characters.

-P, --noplugin=<plugin1>,<plugin2>,..

Never load these plugins. The option can be a pattern containing "*" and "?" characters.

-C, --compat

Provide deprecated command line interfaces.

-E, --experimental

Enable D-Bus experimental interfaces. These interfaces are not guaranteed to be compatible or present in future releases.

-T, --testing

Enable D-Bus testing interfaces. These interfaces are only meant for test validation of the internals of bluetoothd and shall not never be used by anything other than that.

-K, --kernel=<uuid1>,<uuid2>,...

Enable Kernel experimental features. Kernel experimental features are considered unstable and may be removed from future kernel releases.

## FILES
/etc/bluetooth/main.conf

Location of the global configuration file.

## RESOURCES
http://www.bluez.org

## REPORTING BUGS
linux-bluetooth@vger.kernel.org

## AUTHOR
Marcel Holtmann, Philipp Matthias Hahn, Fredrik Noring

## COPYRIGHT
Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL).


bluealsa

package: bluez-alsa

title: bluealsa(8)

summary: Bluetooth Audio ALSA Backend

text:
# bluealsa(8)

## NAME
bluealsa - Bluetooth Audio ALSA Backend

## SYNOPSIS
bluealsa -p PROFILE [OPTION]...

## DESCRIPTION
bluealsa is a Linux daemon to give applications access to Bluetooth audio streams using the Bluetooth A2DP, HFP and/or HSP profiles. It provides a D-Bus API to applications, and can be used by ALSA applications via libasound plugins (see bluealsa-plugins(7) for details).

## OPTIONS
-h, --help

Output a usage message and exit.

-V, --version

Output the version number and exit.

-S, --syslog

Send output to system logger (syslogd(8)). By default, log output is sent to stderr.

-B NAME, --dbus=NAME

BlueALSA D-Bus service name suffix. Without this option, bluealsa registers itself as an "org.bluealsa" D-Bus service. For more information see the EXAMPLES below.

-i hciX, --device=hciX

HCI device to use. Can be specified multiple times to select more than one HCI. Because HCI numbering can change after a system reboot, this option also accepts HCI MAC address for the hciX value, for example: --device=00:11:22:33:44:55 Without this option, the default is to use all available HCI devices.

-p NAME, --profile=NAME

Enable NAME Bluetooth profile. May be given multiple number of times to enable multiple profiles. It is mandatory to enable at least one Bluetooth profile. For the list of supported profiles see Profiles in the NOTES section below.

-c NAME, --codec=NAME

Enable or disable NAME Bluetooth audio codec. May be given multiple number of times to enable (or disable) multiple codecs. In order to disable given audio codec (remove it from the list of audio codecs enabled by default), the NAME has to be prefixed with - (minus) character. It is not possible to disable SBC and CVSD codecs which are mandatory for A2DP and HFP/HSP respectively.

By default BlueALSA enables SBC, AAC (if AAC support is compiled-in), CVSD and mSBC (if mSBC support is compiled-in). For the list of supported audio codecs see the "Available BT audio codecs" section of the bluealsa command-line help message.

--initial-volume=NUM

Set the initial volume to NUM % when a device is first connected. NUM must be an integer in the range from 0 to 100. By default the volume of all PCMs of a device is set to 100% (full volume) when the device is first connected. For some devices, particularly headphones, this can lead to an unpleasant experience. This option allows the user to choose an alternative initial volume level. Only one value can be specified and each device on first connect will have the volume level of all its PCMs set to this value. However, a device with native volume control may then immediately override this level. On subsequent connects the volume will be set to the remembered value from the last disconnection. See Volume control in the NOTES section below for more information.

--keep-alive=SEC

Keep Bluetooth transport alive for SEC number of seconds after streaming was closed. This option is required when using bluealsa with applications that close and then immediately re-open the same PCM as part of their initialization; for example applications built with the portaudio portability library and many other "portable" applications.

It can also be useful when playing short audio files in quick succession. It will reduce the gap between playbacks caused by Bluetooth audio transport acquisition.

--a2dp-force-mono

Force monophonic sound for A2DP profile.

--a2dp-force-audio-cd

Force 44.1 kHz sampling frequency for A2DP profile. Some Bluetooth devices can handle streams sampled at either 48kHz or 44.1kHz, in which case they normally default to using 48kHz. With this option, bluealsa will request such a device uses only 44.1 kHz sample rate.

--a2dp-volume

Enable native A2DP volume control. By default bluealsa will use its own internal scaling algorithm to attenuate the volume. This option disables that internal scaling and instead passes the volume change request to the A2DP device. This feature can also be controlled during runtime for individual PCMs via the BlueALSA D-Bus API or by the BlueALSA ALSA plugins; and if so the changed setting will be remembered. See Volume control in the NOTES section below for more information. Note that this feature might not work with all Bluetooth headsets.

--sbc-quality=MODE

Set SBC encoder quality. Default value is high. The MODE can be one of:

- low - low audio quality (mono: 114 kbps, stereo: 213 kbps)

- medium - medium audio quality (mono: 132 kbps, stereo: 237 kbps)

- high - high audio quality (mono: 198 kbps, stereo: 345 kbps)

- xq - SBC Dual Channel HD (SBC XQ) (452 kbps)

- xq+ - SBC Dual Channel HD (SBC XQ+) (551 kbps)

--mp3-algorithm=TYPE

Select LAME encoder internal algorithm. Default value is expensive. The TYPE can be one of:

- fast - OK quality, really fast

- cheap - good quality, fast

- expensive - near-best quality, not too slow

- best - best quality, slow

If CPU power consumption is not an issue, one might safely select best as the algorithm type. Also, please note that the true quality is determined by the selected bit rate or used VBR quality option (--mp3-vbr-quality).

--mp3-vbr-quality=MODE

Set variable bit rate (VBR) quality. Default value is standard. The MODE can be one of:

- low - low audio quality (100-130 kbps)

- medium - medium audio quality (140-185 kbps)

- standard - standard audio quality (170-210 kbps)

- high - high audio quality (190-250 kbps)

- extreme - best audio quality, no low-pass filter (220-260 kbps)

--aac-afterburner

Enables Fraunhofer AAC afterburner feature, which is a type of analysis by synthesis algorithm. This feature increases the audio quality at the cost of increased processing power and overall memory consumption.

--aac-bitrate=BPS

Set the target bit rate for constant bit rate (CBR) mode or the maximum peak bit rate for variable bit rate (VBR) mode. Default value is 220000 bits per second.

--aac-latm-version=NUM

Select LATM syntax version used for AAC audio transport. Default value is 1. The NUM can be one of:

- 0 - LATM syntax specified by ISO-IEC 14496-3 (2001), should work with all older BT devices

- 1 - LATM syntax specified by ISO-IEC 14496-3 (2005), should work with newer BT devices

--aac-true-bps

Enable true "bit per second" bit rate. A2DP AAC specification requires that for the constant bit rate (CBR) mode every RTP frame has the same bit rate and for the variable bit rate (VBR) mode the maximum peak bit rate limit is also per RTP frame. However, a single RTP frame does not contain a single full second of audio. This option enables true bit rate calculation (per second), which means that per RTP frame bit rate may vary even for CBR mode. This feature is not enabled by default, because it violates A2DP AAC specification. Enabling it should result in an enhanced audio quality, but will for sure produce fragmented RTP frames. If RTP fragmentation is not supported by used A2DP sink device (e.g., headphones) one might hear clearly audible clicks in the playback audio. In such case, please do not enable this option.

--aac-vbr

Prefer variable bit rate mode over constant bit rate mode. Please note, that this option does not necessarily mean that the variable bit rate (VBR) mode will be used. Used AAC configuration depends on a remote Bluetooth device capabilities.

--lc3plus-bitrate=BPS

Set LC3plus encoder bit rate for constant bit rate mode (CBR) as BPS. Default value is 396800 bits per second.

--ldac-abr

Enables LDAC adaptive bit rate, which will dynamically adjust encoder quality based on the connection stability.

--ldac-quality=MODE

Specifies LDAC encoder quality. Default value is standard. The MODE can be one of:

- mobile - mobile quality (44.1 kHz: 303 kbps, 48 kHz: 330 kbps)

- standard - standard quality (44.1 kHz: 606 kbps, 48 kHz: 660 kbps)

- high - high quality (44.1 kHz: 909 kbps, 48 kHz: 990 kbps)

--xapl-resp-name=NAME

Set the product name send in the XAPL response message. By default, the name is set as "BlueALSA". However, some devices (reported with e.g., Sony WM-1000XM4) will not provide battery level notification unless the product name is set as "iPhone".

## NOTES

### Profiles
bluealsa provides support for Bluetooth Advanced Audio Distribution Profile (A2DP), Hands-Free Profile (HFP) and Headset Profile (HSP). A2DP profile is dedicated for streaming music (i.e., stereo, 48 kHz or more sampling frequency), while HFP and HSP for two-way voice transmission (mono, 8 kHz or 16 kHz sampling frequency).

The Bluetooth audio profiles are not peer-to-peer; they each have a source or gateway role (a2dp-source, hfp-ag, or hsp-ag) and a sink or target role (a2dp-sink, hfp-hf, hsp-hs). The source/gateway role is the audio player (e.g., mobile phone), the sink/target role is the audio renderer (e.g., headphones or speaker). The bluealsa daemon can perform any combination of profiles and roles, although it is most common to use it either as a source/gateway:

```
bluealsa -p a2dp-source -p hfp-ag -p hsp-ag
```

or as a sink/target:

```
bluealsa -p a2dp-sink -p hfp-hf -p hsp-hs
```

or with oFono for HFP support,

source/gateway:

```
bluealsa -p a2dp-source -p hfp-ofono -p hsp-ag
```

sink/target:

```
bluealsa -p a2dp-sink -p hfp-ofono -p hsp-hs
```

With A2DP, bluealsa always includes the mandatory SBC codec and may also include various optional codecs like AAC, aptX, and other.

With HFP, bluealsa always includes the mandatory CVSD codec and may also include the optional mSBC codec.

The full list of available optional codecs, which depends on selected compilation options, will be shown with bluealsa command-line help message.

The list of profile NAME-s accepted by the --profile=NAME option:

- a2dp-source - Advanced Audio Source (streaming audio to connected device)

- a2dp-sink - Advanced Audio Sink (receiving audio from connected device)

- hfp-ofono - Hands-Free AG/HF handled by oFono

- hfp-ag - Hands-Free Audio Gateway

- hfp-hf - Hands-Free

- hsp-ag Headset Audio Gateway

- hsp-hs - Headset

The hfp-ofono is available only when bluealsa was compiled with oFono support. Enabling HFP over oFono will automatically disable hfp-hf and hfp-ag.

BlueZ permits only one service to register the HSP and HFP profiles, and that service is automatically registered with every HCI device.

For the A2DP profile, BlueZ allows each HCI device to be registered to a different service, so it is possible to have multiple instances of bluealsa offering A2DP support, each with a unique service name given with the --dbus= option, so long as they are registered to different HCI devices using the --device= option. See the EXAMPLES below.

A profile connection does not immediately initiate the audio stream(s); audio can only flow when the profile transport is "acquired". Acquisition can only be performed by the source/gateway role. When acting as source/gateway, bluealsa acquires the profile transport (i.e., initiates the audio connection) when a client opens a PCM. When bluealsa is acting as target, a client can open a PCM as soon as the profile is connected, but the audio stream(s) will not begin until the remote source/gateway has acquired the transport.

### Volume control
The Bluetooth specifications for HFP and HSP include optional support for volume control of the target by the gateway device. For A2DP, volume control is optionally provided by the AVRCP profile. bluealsa provides a single, consistent, abstracted interface for volume control of PCMs. This interface can use the native Bluetooth features or alternatively bluealsa also implements its own internal volume control, called "soft-volume". For A2DP the default is to use soft-volume, but this can be overridden to use the Bluetooth native support where available by using the --a2dp-volume command line option. For HFP/HSP the default is to use Bluetooth native volume control.

When using soft-volume, bluealsa scales PCM samples before encoding, and after decoding, and does not interact with the Bluetooth AVRCP volume property or HFP/HSP volume control. Volume can only be modified by local clients. (Note that Bluetooth headphones or speakers with their own volume controls will still be able to alter their own volume, but this change will not be notified to bluealsa local clients, they will only see the soft-volume setting).

When using native volume control, bluealsa links the PCM volume setting to the AVRCP volume property or HFP/HSP volume control. No scaling of PCM samples is applied. Volume can be modified by both local clients and the remote device. Local clients will be notified of volume changes made by controls on the remote device.

A2DP native volume control does not permit independent values for left and right channels, so when a client sets such values bluealsa will set the Bluetooth volume as the average of the two channels.

Volume level, mute status, and soft-volume selection can all be controlled for each PCM by using the D-Bus API (or by using ALSA plugins, see bluealsa-plugins(7) for more information). The current value of these settings for each PCM is stored in the filesystem so that the device can be disconnected and later re-connected without losing its volume settings.

When a device is connected, the volume level of its PCMs is set according to the following criteria (highest priority first):

1.

saved value from previous connection of the device

2.

value set by the --initial-volume command line option

3.

100%

its mute status according to:

1.

saved value from previous connection

2.

false

and its soft-volume status according to:

1.

saved value from previous connection

2.

false for SCO (i.e., use native volume control).

3.

false for A2DP if the --a2dp-volume command line option is given

4.

true for A2DP (i.e., use soft-volume control).

When native volume control is enabled, then the remote device may also modify the volume level after this initial setting. Mute and soft-volume are implemented locally by the bluealsa daemon and cannot be modified by the remote device.

Note that bluealsa relies on support from BlueZ to implement native volume control for A2DP using AVRCP, and BlueZ has not always provided robust support here. It is recommended to use BlueZ release 5.65 or later to be certain that native A2DP volume control will always be available with those devices which provide it.

## FILES
/etc/dbus-1/system.d/bluealsa.conf

BlueALSA service D-Bus policy file. D-Bus will deny all access to the org.bluealsa service (even to root) unless permission is granted by a policy file. The default file permits only root to own this service, and only members of the audio group to exchange messages with it.

/var/lib/bluealsa/XX:XX:XX:XX:XX:XX

BlueALSA volume persistent state storage. Files are named after the Bluetooth device address to which they refer.

## EXAMPLES
Emulate Bluetooth headset with A2DP and HSP support:

```
bluealsa -p a2dp-sink -p hsp-hs
```

On systems with more than one HCI device, it is possible to expose different profiles on different HCI devices. A system with three HCI devices might (for example) use hci0 for an A2DP sink service named "org.bluealsa.sink" and both hci1 and hci2 for an A2DP source service named "org.bluealsa.source". Such a setup might be created as follows:

```
bluealsa -B sink -i hci0 -p a2dp-sink &
bluealsa -B source -i hci1 -i hci2 -p a2dp-source &
```

Setup like this will also require a change to the BlueALSA D-Bus configuration file in order to allow connection with BlueALSA services with suffixed names. Please add following lines to the BlueALSA D-Bus policy:

```
...
<allow send_destination="org.bluealsa.sink" />
<allow send_destination="org.bluealsa.source" />
...
```

## COPYRIGHT
Copyright (c) 2016-2023 Arkadiusz Bokowy.

The bluez-alsa project is licensed under the terms of the MIT license.

## SEE ALSO
bluealsa-aplay(1), bluealsa-cli(1), bluealsa-rfcomm(1), bluetoothctl(1), bluealsa-plugins(7), bluetoothd(8)

Project web site

https://github.com/arkq/bluez-alsa


bmon

package: bmon

title: bmon(8)

summary: bandwidth monitor and rate estimator

text:
# bmon(8)

## NAME
bmon - bandwidth monitor and rate estimator

## SYNOPSIS
bmon [--show-all] [--use-si] [--input=MODULE] [--output=MODULE] [OPTIONS...]

## DESCRIPTION
bmon is a monitoring and debugging tool to capture networking related statistics and prepare them visually in a human friendly way. It features various output methods including an interactive curses user interface and a programmable text output for scripting.

## OPTIONS
-h, --help

Prints a short help text and exits.

-V, --version

Prints the versioning identifier and exits.

-i, --input=MODULE[:OPTIONS][,MODULE...]

Set list of input modules to load and use. Multiple modules can be used in parallel. bmon automatically loads a useful and working input module by default. See INPUT MODULES for more details.

-o, --outputMODULE[:OPTIONS][,MODULE...]

Set list of output modules to load and use. Multiple modules can be used in parallel. By default, bmon will use the curses output mode, if that is not available due to an incompatible console it will fall back to a simple text mode. See OUTPUT MODULES for more details.

-U, --use-si

Use SI unit system (1KB = 1'000 bytes) instead of 1KB = 1'024 bytes.

-f, --configfile=FILE

Set alternative path to configuration file.

-p, --policy=POLICY

Set policy defining which network interfaces to display. See INTERFACE SELECTION for more details.

-a, --show-all=

Display all interfaces, even interface that are administratively down.

-r, --read-interval=FLOAT

Set interval in seconds in which input modules read statistics from their source. The default is 1.0 seconds.

-R, --rate-interval=FLOAT

Set interval in seconds in which the rate per counter is calculated. The default is 1.0 seconds.

-b, --use-bit

Show rates in bits per second instead of bytes per second.

-L, --lifetime=FLOAT

Set lifetime of an element in seconds before it is no longer displayed without receiving any statistical updates. The default is 30 seconds.

## INPUT MODULES
Input modules provide statistical data about elements. Each element consists of attributes which represents a counter, a rate, or a percentage. Elements may carry additional child elements to represent a hierarchy. Each element is assigned to a group defined by the input module. Input modules are polled in the frequence of the configured read interval.

The following input modules are available:

netlink

Uses the Netlink protocol to collect interface and traffic control statistics from the kernel. This is the default input module.

proc

Reads interface statistics from the /proc/net/dev file. This is considered a legacy interface and provided for backwards compatibily reasons. This is a fallback module if the Netlink interface is not available.

dummy

Programmable input module for debugging and testing purposes.

null

No data collected.

To receive additional information about a module, run the module with the "help" option set like this:

bmon -i netlink:help

See MODULE CONFIGURATION for more details.

## OUTPUT MODULES
Output modules display or export the statistical data collected by input modules. Multiple output modules can be run at the same time. bmon will not prevent possible conflicts such as multiple output modules writing to the console.

The following output modules exist:

curses

Interactive curses based text user interface providing real time rate estimations and a graphical representatio nof each attribute. Press '?' to display the quick reference guide. This is the default output mode.

ascii

Simple programmable text output intended for human consumption. Capable of printing list of interfaces, detailed counters and graphs to the console. This is the default fallback output mode if curses is not available.

format

Fully scriptable output mode inteded for consumption by other programs. See the module help text for additional information.

null

Disable output.

To receive additional information about a module, run the module with the "help" option set like this:

bmon -o curses:help

See MODULE CONFIGURATION for more details.

## MODULE CONFIGURATION
The syntax to configure modules is as follows:

ARGUMENT ::= mod1[:OPTS][,mod2[:OPTS]...]

OPTS ::= OPTION[;OPTION...]

OPTION ::= option[=value]

Run the module with option "help" to receive the list of options for each module:

bmon -i module:help

## INTERFACE SELECTION
The following syntax is used to define the interface selection policy:

SELECTION ::= NAME[,NAME[,...]]

NAME ::= [!]interface

The interface name may contain the character '*' which will act as a wildcard and represents any number of any character type, e.g. eth*, h*0, ...

Examples:

lo,eth0,eth1

eth*,!eth0

## EXAMPLES
To run bmon in curses mode monitoring the interfaces eth0 and eth1:

bmon -p eth0,eth1 -o curses

To run bmon in format mode, monitoring any eth* interfaces, with a specified format string:

bmon -p 'eth*' -o format:fmt='$(element:name) $(attr:rxrate:packets)\n'

## FILES
/etc/bmon.conf

$HOME/.bmonrc

## SEE ALSO
ip(8), netstat(8), ifconfig(8), netlink(7),

## AUTHOR
Thomas Graf <tgraf@suug.ch> among others


boltd

package: bolt

title: boltd(8)

text:
# boltd(8)

## NAME
boltd - thunderbolt device managing system daemon

## SYNOPSIS
boltd [OPTIONS]

## DESCRIPTION
boltd is the thunderbolt device manager daemon. Its goal is to enable the secure and convenient use of thunderbolt devices by using the security features of modern thunderbolt controllers. It provides the org.freedesktop.bolt name on the system bus. boltd is autostarted via systemd/udev if a thunderbolt device is connected.

The thunderbolt I/O technology works by bridging PCIe between the controllers on each end of the connection, which in turn means that devices connected via Thunderbolt are ultimately connected via PCIe. Therefore thunderbolt can achieve very high connection speeds, fast enough to even drive external graphics cards. The downside is that it also makes certain attacks possible. To mitigate these security problems, the latest version — known as Thunderbolt 3 — supports different security levels:

none

No security. The behavior is identical to previous Thunderbolt versions.

dponly

No PCIe tunnels are created at all, but DisplayPort tunnels are allowed and will work.

user

Connected devices must be authorized by the user. Only then will the PCIe tunnels be activated.

secure

Basically the same as user mode, but additionally a key will be written to the device the first time the device is connected. This key will then be used to verify the identity of the connected device.

usbonly

One PCIe tunnel is created to a usb controller in a thunderbolt dock; no other downstream PCIe tunnels are authorized (needs 4.17 kernel and recent hardware).

The primary task of boltd is to authorize thunderbolt peripherals if the security level is either user or secure. It provides a D-Bus API to list devices, enroll them (authorize and store them in the local database) and forget them again (remove previously enrolled devices). It also emits signals if new devices are connected (or removed). During enrollment devices can be set to be automatically authorized as soon as they are connected. A command line tool, called boltctl(1), can be used to control the daemon and perform all the above mentioned tasks.

The pre-boot access control list (BootACL) feature is active when supported by the firmware and when boltd is running on a new enough Linux kernel (>= 4.17). The BootACL is a list of UUIDs, that can be written to the thunderbolt controller. If enabled in the BIOS, all devices in that list will be authorized by the firmware during pre-boot, which means these devices can be used in the BIOS setup and also during Linux early boot. NB: no device verification is done, even when the security level is set to secure mode in the BIOS, i.e. the maximal effective security level for devices in the BootACL is only user. If BootACL support is present, all new devices will be automatically added. Devices that are forgotten (removed from boltd) will also be removed from the BootACL. When a controller is offline, changes to the BootACL will be written to a journal and synchronized back when the controller is online again.

IOMMU support: if the hardware and firmware support using the input–output memory management unit (IOMMU) to restrict direct memory access to certain safe regions, boltd will detect that feature and change its behavior: As long as iommu support is active, as indicated by the iommu_dma_protection sysfs attribute of the domain controller, new devices will be automatically enrolled with the iommu policy and existing devices with iommu (or auto) policy will be automatically authorized by boltd without any user interaction. When iommu is not active, devices that were enrolled with the iommu policy will not be authorized automatically. The status of iommu support can be inspected by using boltctl domains.

## OPTIONS
-h, --help

Prints a short help text and exits.

--version

Shows the version number and exits.

-r, --replace

Replace the currently running boltd instance.

--journal

Force logging to the journal.

-v, --verbose

Print debug output.

## ENVIRONMENT
RUNTIME_DIRECTORY

Specifies the path where the daemon stores data that only has to live as long as the current boot. Will be set automatically when started via systemd (>= 240). If not set the default path for runtime data is /run/boltd.

STATE_DIRECTORY

Specifies the path where the daemon stores device information, including the keys used for authorization. Overwrites the path that was set at compile time. Will be set automatically when started via systemd (>= 240).

BOLT_DBPATH

Same as STATE_DIRECTORY but takes precedence over that, if set.

## EXIT STATUS
On success 0 is returned, a non-zero failure code otherwise.

## AUTHOR
Written by Christian Kellner <ckellner@redhat.com>.

## SEE ALSO
boltctl(1)


bonnie++

package: bonnie++

title: bonnie++(8)

summary: program to test hard drive performance.

text:
# bonnie++(8)

## NAME
bonnie++ - program to test hard drive performance.

## SYNOPSIS
bonnie++ [-d dir] [-c concurrency] [-s size(MiB)[:chunk-size(b)[:seeks[:seekers]]]] [-n number-to-stat(*1024)[:max-size[:min-size][:num-directories[:chunk-size]]]] [-m machine-name] [-r ram-size-in-MiB] [-x number-of-tests] [-u uid-to-use:gid-to-use] [-g gid-to-use] [-q] [-f size-for-char-io] [-b] [-D] [-p processes | -y p|s ] [-z seed-num|-Z random-file]

## DESCRIPTION
This manual page documents briefly the bonnie++, program.

Bonnie++ is a program to test hard drives and file systems for performance or the lack therof. There are a many different types of file system operations which different applications use to different degrees. Bonnie++ tests some of them and for each test gives a result of the amount of work done per second and the percentage of CPU time this took. For performance results higher numbers are better, for CPU usage and latency lower are better (NB a configuration scoring a performance result of 2000 and a CPU result of 90% is better in terms of CPU use than a configuration delivering performance of 1000 and CPU usage of 60%).

There are two sections to the program's operations. The first is to test the IO throughput in a fashion that is designed to simulate some types of database applications. The second is to test creation, reading, and deleting many small files in a fashion similar to the usage patterns of programs such as Squid or INN.

All the details of the tests performed by Bonnie++ are contained in the file /usr/share/doc/bonnie++/readme.html

## OPTIONS
For Bonnie++ every option is of the form of a hyphen followed by a letter and then the next parameter contains the value.

-d

the directory to use for the tests.

-c

the level of concurrency (default 1). The number of copies of the test to be performed at the same time.

-s

the size of the file(s) for IO performance measures in megabytes. If the size is greater than 1G then multiple files will be used to store the data, and each file will be up to 1G in size. This parameter may include the chunk size seperated from the size by a colon. The chunk-size is measured in bytes and must be a power of two from 256 to 1048576, the default is 8192. NB You can specify the size in giga-bytes or the chunk-size in kilo-bytes if you add g or k to the end of the number respectively. This parameter may also include the number of seeks (default 8192) and the number of seeker processes (default 5). If the specified size is 0 then this test will be skipped.

-n

the number of files for the file creation test. This is measured in multiples of 1024 files. This is because no-one will want to test less than 1024 files, and we need the extra space on braille displays. If the specified number is 0 then this test will be skipped.

The default for this test is to test with 0 byte files. To use files of other sizes you can specify number:max:min:num-directories:chunk-size where max is the maximum size and min is the minimum size (both default to 0 if not specified). If minimum and maximum sizes are specified then every file will have a random size from the range min..max inclusive. If you specify a number of directories then the files will be evenly distributed amoung that many sub-directories.

If max is -1 then hard links will be created instead of files. If max is -2 then soft links will be created instead of files.

-m

name of the machine - for display purposes only.

-r

RAM size in megabytes. If you specify this the other parameters will be checked to ensure they make sense for a machine of that much RAM. You should not need to do this in general use as it should be able to discover the RAM size. NB If you specify a size of 0 then all checks will be disabled...

-x

number of test runs. This is useful if you want to perform more than one test. It will dump output continuously in CSV format until either the number of tests have been completed, or it is killed.

-u

user-id to use. When running as root specify the UID to use for the tests. It is not recommended to use root (since the occasion when a Bonnie++ bug wiped out someone's system), so if you really want to run as root then use -u root. Also if you want to specify the group to run as then use the user:group format. If you specify a user by name but no group then the primary group of that user will be chosen. If you specify a user by number and no group then the group will be nogroup.

-g

group-id to use. Same as using :group for the -u parameter, just a different way to specify it for compatibility with other programs.

-q

quiet mode. If specified then some of the extra informational messages will be suppressed. Also the csv data will be the only output on standard out and the plain text data will be on standard error. This means you can run bonnie++ -q >> file.csv to record your csv data.

-f size-for-char-io

fast mode control, skips per-char IO tests if no parameter, otherwise specifies the size of the tests for per-char IO tests (default 20M).

-b

no write buffering. fsync() after every write.

-p

number of processes to serve semaphores for. This is used to create the semaphores for synchronising multiple Bonnie++ processes. All the processes which are told to use the semaphore with -ys will start each test with synchronization. Use "-p -1" to delete the semaphore.

-y s|p

perform synchronization before each test. Option s for semaphores and option p for prompting.

-D

use direct IO (O_DIRECT) for the bulk IO tests

-z seed

random number seed to repeat the same test.

-Z random-file

file containing random data in network byte order.

## MULTIPLE PROCESSES
Run the following commands to run three copies of Bonnie++ simultaneously:

bonnie++ -p3

bonnie++ -y > out1 &

bonnie++ -y > out2 &

bonnie++ -y > out3 &

## OUTPUT
The primary output is plain-text in 80 columns which is designed to fit well when pasted into email and which will work well with Braille displays.

The second type of output is CSV (Comma Seperated Values). This can easily be imported into any spread-sheet or database program. Also I have included the programs bon_csv2html and bon_csv2txt to convert CSV data to HTML and plain-ascii respectively.

The "Name:Size etc" field has the name, filesize, IO chunk size, concurrency, number of seeks, and number of seek processes separated by : characters.

For every test two numbers are reported, the amount of work done (higher numbers are better) and the percentage of CPU time taken to perform the work (lower numbers are better). If a test completes in less than 500ms then the output will be displayed as "++++". This is because such a test result can't be calculated accurately due to rounding errors and I would rather display no result than a wrong result.

Data volumes for the 80 column text display use "K" for KiB (1024 bytes), "M" for MiB (1048576 bytes), and "G" for GiB (1073741824 bytes). So K/sec means a multiple of 1024 bytes per second.

## AUTHOR
This program, its manual page, and the Debian package were written by Russell Coker <russell@coker.com.au>, parts of the program are based on the work of Tim Bray <tbray@textuality.com>.

The documentation, the Perl scripts, and all the code for testing the creation of thousands of files was written by Russell Coker, but the entire package is under joint copyright with Tim Bray.

## SIGNALS
Handles SIGINT and does a cleanup (which may take some time), a second SIGINT or a SIGQUIT will cause it to immediately die.

SIGXCPU and SIGXFSZ act like SIGINT.

Ignores SIGHUP.

## BUGS
The random file sizes will add up to different values for different test runs. I plan to add some code that checks the sum and ensures that the sum of the values will be the same on seperate runs.

## AVAILABILITY
The source is available from http://www.coker.com.au/bonnie++ .

See http://etbe.coker.com.au/category/benchmark for further information.

## SEE ALSO
zcav(8), getc_putc(8), bon_csv2html(1), bon_csv2txt(1)


title: getc_putc(8)

summary: program to test hard drive performance.

text:
# getc_putc(8)

## NAME
getc_putc - program to test hard drive performance.

## SYNOPSIS
getc_putc [-d dir] [-s size(KiB)] [-m machine-name] [-u uid-to-use:gid-to-use] [-g gid-to-use]

## DESCRIPTION
This manual page documents briefly the getc_putc, program.

This is a simple adjunct to the bonnie++ benchmark. It is used to test various ways of doing IO one byte at a time, usually you don't need to do enough of this for it to be a performance issue for it to matter much which way you do it. But sometimes it's necessary (for example whan parsing IO from a terminal and then launching another process which will take over all IO, such as a simple shell).

The real benefits of this are to help settle some arguements about the performance of such things, and to educate novices about how bad per-byte IO really is.

## OPTIONS
For getc_putc every option is of the form of a hyphen followed by a letter and then the next parameter contains the value.

-d

the directory to use for the tests.

-s

the size of the file for byte IO performance measured in kilobytes. NB You can specify the size in mega-bytes if you add 'm' to the end of the number. The default for this test is to test with a 512MiB file. Of the file only 1/64 of it will be used for write() and read() system calls (anything else takes too long).

-m

name of the machine - for display purposes only.

-u

user-id to use. When running as root specify the UID to use for the tests. It is not recommended to use root, so if you really want to run as root then use -u root. Also if you want to specify the group to run as then use the user:group format. If you specify a user by name but no group then the primary group of that user will be chosen. If you specify a user by number and no group then the group will be nogroup.

-g

group-id to use. Same as using :group for the -u parameter, just a different way to specify it for compatibility with other programs.

-q

quiet mode. If specified then some of the extra informational messages will be suppressed. Also the csv data will be the only output on standard out and the plain text data will be on standard error. This means you can run getc_putc -q >> file.csv to record your csv data.

## OUTPUT
The primary output is plain-text in 80 columns which is designed to fit well when pasted into email and which will work well with Braille displays.

The second type of output is CSV (Comma Seperated Values). This can easily be imported into any spread-sheet or database program.

For every test the result is a speed in KiB/s. I do not display the CPU time because it presumably is 99% of the power of a single CPU (or something very close to that).

## AUTHOR
This program, it's manual page, and the Debian package were written by Russell Coker <russell@coker.com.au>.

The documentation, the Perl scripts, and all the code for testing the creation of thousands of files was written by Russell Coker, but the entire package is under joint copyright with Tim Bray.

## SIGNALS
Handles SIGINT and does a cleanup (which may take some time), a second SIGINT or a SIGQUIT will cause it to immidiately die.

SIGXCPU and SIGXFSZ act like SIGINT.

Ignores SIGHUP.

## AVAILABILITY
The source is available from http://www.coker.com.au/bonnie++ .

See http://etbe.coker.com.au/category/benchmark for further information.

## SEE ALSO
bonnie++(8), zcav(8)


zcav

title: zcav(8)

text:
# zcav(8)

## NAME
zcav - program to test raw hard drive throughput.

## SYNOPSIS
zcav [-b block-size[:chunk-size]] [-c count] [-r [first-block]:last-block] [-w] [-s skip-rate] [-u uid-to-use:gid-to-use] [-g gid-to-use] [-l log-file] [-f] file-name [-l log-file [-f] file-name]...

## DESCRIPTION
This manual page documents briefly the zcav, program.

Modern hard drives have a constant rotational speed but have varying numbers of sectors per track (outside tracks are longer and have more sectors). This is referred to as Zoned Constant Angular Velocity (or ZCAV). The outer tracks will have a higher data transfer rate due to having more sectors per track, these tracks generally have the lower track/sector numbers.

This program tests the ZCAV performance of a hard drive, by reading the entire data on it a specified number of times. The file name given as the first parameter, it can be specified as -, for standard input. This file will be opened as read-only and in usual operation it will be /dev/hdX or /dev/ide/host0/busX/targetY/lun0/disc depending on whether you use devfs or not (NB operating systems other than Linux will have different device names).

The output should be able to be easily graphed with gnuplot which is what I use to view the results.

## OPTIONS
-b

the size (in Meg) of the blocks to read/write (default 512M), optionally followed by a ':' and the chunk size for read/write operations (default 1M). Note that the chunk size must be less than or equal to the block size and must also be significantly less than the size of the RAM in the machine. Also note that for the write test there will be a fsync() after writing every chunk.

-c

the number of times to read/write the entire disk.

-r

the range of data (in Meg) to read/write on each pass (default the entire device). Useful if you want to quickly test part of a large drive. If a single number is given then that is the last block to read, if two numbers then it's the start and end of a range. Values are in megs, but they are rounded down to the block size.

-s

skip rate. The option -s 10 will cause it to read every 10th block and skip the rest. Accepts values from 2 to 20.

-f

the file-name for the input data. This isn't needed on well configured systems that have a recent Glibc where you can specify the file name without the -f flag.

-u

user-id to use. When running as root specify the UID to run the tests as, it is not recommended to use root, so if you want to run as root use -u root. Also if you want to specify the group to run as then use the user:group format. If you specify a user by name but no group then the primary group of that user will be chosen. If you specify a user by number and no group then the group will be nogroup.

-g

group-id to use. Same as using :group for the -u parameter, just a different way to specify it for compatibility with other programs.

-w

write zero blocks to the disk instead of reading from the disk - will destroy data!

## AUTHOR
This program, it's manual page, and the Debian package were written by Russell Coker <russell@coker.com.au>.

## AVAILABILITY
The source is available from http://www.coker.com.au/bonnie++ .

See http://etbe.coker.com.au/category/benchmark for further information.


title: boot0cfg(8)

text:
# boot0cfg(8)

## NAME
boot0cfg — boot manager installation/configuration utility

## SYNOPSIS
boot0cfg

[-Bv] [-b boot0] [-d drive] [-e bell character] [-f file] [-i volume-id] [-m mask] [-o options] [-s slice] [-t ticks] disk

## DESCRIPTION
The FreeBSD ‘boot0’ boot manager permits the operator to select from which disk and slice an i386 machine (PC) is booted.

Note that what are referred to here as “slices” are typically called “partitions” in non-BSD documentation relating to the PC. Typically, only non-removable disks are sliced.

The boot0cfg utility optionally installs the ‘boot0’ boot manager on the specified disk; and allows various operational parameters to be configured.

On PCs, a boot manager typically occupies sector 0 of a disk, which is known as the Master Boot Record (MBR). The MBR contains both code (to which control is passed by the PC BIOS) and data (an embedded table of defined slices).

The options are:

-B

Install the ‘boot0’ boot manager. This option causes MBR code to be replaced, without affecting the embedded slice table.

-b boot0

Specify which ‘boot0’ image to use. The default is /usr/share/boot0/boot0lin (this version does not support FAT partitions type in the sake of Linux SWAP, LVM, RAID and LBA extended partition type), /usr/share/boot0/boot0 is the original FreeBSD version, /usr/share/boot0/boot0pxe provides experimental PXE loader code. All theese ‘boot0’ variations will use the video card as output. Alternatively /usr/share/boot0/boot0sio can be used for output to the COM1 port. (Be aware that nothing will be output to the COM1 port unless the modem signals DSR and CTS are active.)

-d drive

Specify the drive number used by the PC BIOS in referencing the drive which contains the specified disk. Typically this will be 0x80 for the first hard drive, 0x81 for the second hard drive, and so on; however any integer between 0 and 0xff is acceptable here.

-e bell character

Set the character to be printed in case of input error.

-f file

Specify that a backup copy of the preexisting MBR should be written to file. This file is created if it does not exist, and replaced if it does.

-i volume-id

Specifies a volume-id (in the form XXXX-XXXX) to be saved at location 0x1b8 in the MBR. This information is sometimes used by NT, XP and Vista to identify the disk drive. The option is only compatible with version 2.00 of the 512-byte boot block.

-m mask

Specify slices to be enabled/disabled, where mask is an integer between 0 (no slices enabled) and 0xf (all four slices enabled). Each mask bit enables corresponding slice if set to 1. The least significant bit of the mask corresponds to slice 1, the most significant bit of the mask corresponds to slice 4.

-o options

A comma-separated string of any of the following options may be specified (with “no” prepended as necessary): packet

Use the disk packet (BIOS INT 0x13 extensions) interface, as opposed to the legacy (CHS) interface, when doing disk I/O. This allows booting above cylinder 1023, but requires specific BIOS support. The default is ‘packet’.

setdrv

Forces the drive containing the disk to be referenced using drive number definable by means of the -d option. The default is ‘nosetdrv’.

update

Allow the MBR to be updated by the boot manager. (The MBR may be updated to flag slices as ‘active’, and to save slice selection information.) This is the default; a ‘noupdate’ option causes the MBR to be treated as read-only.

-s slice

Set the default boot selection to slice. Values between 1 and 4 refer to slices; a value of 5 refers to the option of booting from a second disk. The special string “PXE” or a value of 6 can be used to boot via PXE.

-t ticks

Set the timeout value to ticks. (There are approximately 18.2 ticks per second.)

-v

Verbose: display information about the slices defined, etc.

## FILES
/usr/share/boot0/boot0lin

The default ‘boot0’ image

/usr/share/boot0/boot0

Unmodified FreeBSD ‘boot0’ variant

/usr/share/boot0/boot0pxe

Experimental PXE bootloader

/usr/share/boot0/boot0sio

Image for serial consoles (COM1,9600,8,N,1,MODEM)

## EXIT STATUS
The boot0cfg utility exits 0 on success, and >0 if an error occurs.

## EXAMPLES
To boot slice 2 on the next boot:

boot0cfg -s 2 ad0

To enable just slices 1 and 3 in the menu:

boot0cfg -m 0x5 ad0

To go back to non-interactive booting, use fdisk(8) to install the default MBR:

fdisk -B ad0

## SEE ALSO
geom(4), boot(8), fdisk(8), gpart(8)

## AUTHORS
Robert Nordier ⟨rnordier@FreeBSD.org⟩.

## BUGS
Use of the ‘packet’ option may cause ‘boot0’ to fail, depending on the nature of BIOS support.

Use of the ‘setdrv’ option with an incorrect -d operand may cause the boot0 code to write the MBR to the wrong disk, thus trashing its previous content. Be careful.


rebootin

package: bootloader-utils

title: rebootin(8)

text:
# rebootin(8)

## NAME
rebootin - Reboots the machine using a particular Boot Loader entry

## SYNOPSIS
rebootin [OPTIONS] <label>

## DESCRIPTION
rebootin reboots the machine it is launched on. While with a simple reboot you need to manually select the boot entry to use at startup, rebootin allows to specify the boot entry on the command line.

<label> is the name of the entry as named in the boot loader configuration file.

rebootin currently works only with LILO.

## OPTIONS
-f, --fastboot

Create a /fastboot file to reboot in fastboot mode (eg: no fsck(8)).

-n, --noreboot

Don't reboot immediately just set the flags for next reboot.

-l, --list

Display the list of available boot entries.

-h, --help

Show help.

## FILES
/etc/lilo.conf /boot/grub/menu.lst

The rebootin executable (perl script)

## SEE ALSO
grub(8), lilo(8), fsck(8)

## AUTHORS
Pascal Rigaux, Mandrakesoft

pixel@mandrakesoft.com

Chmouel Boudjnah, Mandrakesoft

chmouel@mandrakesoft.com


bpftool

package: bpftool

title: bpftool(8)

text:
# bpftool(8)

## NAME
BPFTOOL - tool for inspection and simple manipulation of eBPF programs and maps

## SYNOPSIS
bpftool [OPTIONS] OBJECT { COMMAND | help } bpftool batch file FILE

bpftool version

OBJECT := { map | program | link | cgroup | perf | net | feature | btf | gen | struct_ops | iter }

OPTIONS := { { -V | --version } | { -j | --json } [{ -p | --pretty }] | { -d | --debug } | { -l | --legacy } }

MAP-COMMANDS := { show | list | create | dump | update | lookup | getnext | delete | pin | event_pipe | help }

PROG-COMMANDS := { show | list | dump jited | dump xlated | pin | load | attach | detach | help }

LINK-COMMANDS := { show | list | pin | detach | help }

CGROUP-COMMANDS := { show | list | attach | detach | help }

PERF-COMMANDS := { show | list | help }

NET-COMMANDS := { show | list | help }

FEATURE-COMMANDS := { probe | help }

BTF-COMMANDS := { show | list | dump | help }

GEN-COMMANDS := { object | skeleton | min_core_btf | help }

STRUCT-OPS-COMMANDS := { show | list | dump | register | unregister | help }

ITER-COMMANDS := { pin | help }

## DESCRIPTION
bpftool allows for inspection and simple modification of BPF objects on the system. Note that format of the output of all tools is not guaranteed to be stable and should not be depended upon.

## OPTIONS
-h, --help

Print short help message (similar to bpftool help).

-V, --version

Print bpftool's version number (similar to bpftool version), the number of the libbpf version in use, and optional features that were included when bpftool was compiled. Optional features include linking against libbfd to provide the disassembler for JIT-ted programs (bpftool prog dump jited) and usage of BPF skeletons (some features like bpftool prog profile or showing pids associated to BPF objects may rely on it).

-j, --json

Generate JSON output. For commands that cannot produce JSON, this option has no effect.

-p, --pretty

Generate human-readable JSON output. Implies -j.

-d, --debug

Print all logs available, even debug-level information. This includes logs from libbpf as well as from the verifier, when attempting to load programs.

-l, --legacy

Use legacy libbpf mode which has more relaxed BPF program requirements. By default, bpftool has more strict requirements about section names, changes pinning logic and doesn't support some of the older non-BTF map declarations. See https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0 for details.

-m, --mapcompat

Allow loading maps with unknown map definitions.

-n, --nomount

Do not automatically attempt to mount any virtual file system (such as tracefs or BPF virtual file system) when necessary.

## SEE ALSO
bpf(2), bpf-helpers(7), bpftool-btf(8), bpftool-cgroup(8), bpftool-feature(8), bpftool-gen(8), bpftool-iter(8), bpftool-link(8), bpftool-map(8), bpftool-net(8), bpftool-perf(8), bpftool-prog(8), bpftool-struct_ops(8)


bpftool-btf

title: bpftool-btf(8)

summary: tool for inspection of BTF data

text:
# bpftool-btf(8)

## NAME
bpftool-btf - tool for inspection of BTF data

## SYNOPSIS
bpftool [OPTIONS] btf COMMAND OPTIONS := { { -j | --json } [{ -p | --pretty }] | { -d | --debug } | { -l | --legacy } | { -B | --base-btf } }

COMMANDS := { dump | help }

## BTF COMMANDS

```
bpftool btf { show | list } [id BTF_ID]
bpftool btf dump BTF_SRC [format FORMAT]
bpftool btf help
BTF_SRC := { id BTF_ID | prog PROG | map MAP [{key | value | kv | all}] | file FILE }
FORMAT := { raw | c }
MAP := { id MAP_ID | pinned FILE }
PROG := { id PROG_ID | pinned FILE | tag PROG_TAG }
```

## DESCRIPTION
bpftool btf { show | list } [id BTF_ID]

Show information about loaded BTF objects. If a BTF ID is specified, show information only about given BTF object, otherwise list all BTF objects currently loaded on the system. Since Linux 5.8 bpftool is able to discover information about processes that hold open file descriptors (FDs) against BTF objects. On such kernels bpftool will automatically emit this information as well.

bpftool btf dump BTF_SRC

Dump BTF entries from a given BTF_SRC. When id is specified, BTF object with that ID will be loaded and all its BTF types emitted.

When map is provided, it's expected that map has associated BTF object with BTF types describing key and value. It's possible to select whether to dump only BTF type(s) associated with key (key), value (value), both key and value (kv), or all BTF types present in associated BTF object (all). If not specified, kv is assumed.

When prog is provided, it's expected that program has associated BTF object with BTF types.

When specifying FILE, an ELF file is expected, containing .BTF section with well-defined BTF binary format data, typically produced by clang or pahole.

format option can be used to override default (raw) output format. Raw (raw) or C-syntax (c) output formats are supported.

bpftool btf help

Print short help message.

## OPTIONS
-h, --help

Print short help message (similar to bpftool help).

-V, --version

Print bpftool's version number (similar to bpftool version), the number of the libbpf version in use, and optional features that were included when bpftool was compiled. Optional features include linking against libbfd to provide the disassembler for JIT-ted programs (bpftool prog dump jited) and usage of BPF skeletons (some features like bpftool prog profile or showing pids associated to BPF objects may rely on it).

-j, --json

Generate JSON output. For commands that cannot produce JSON, this option has no effect.

-p, --pretty

Generate human-readable JSON output. Implies -j.

-d, --debug

Print all logs available, even debug-level information. This includes logs from libbpf as well as from the verifier, when attempting to load programs.

-l, --legacy

Use legacy libbpf mode which has more relaxed BPF program requirements. By default, bpftool has more strict requirements about section names, changes pinning logic and doesn't support some of the older non-BTF map declarations. See https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0 for details.

-B, --base-btf FILE

Pass a base BTF object. Base BTF objects are typically used with BTF objects for kernel modules. To avoid duplicating all kernel symbols required by modules, BTF objects for modules are "split", they are built incrementally on top of the kernel (vmlinux) BTF object. So the base BTF reference should usually point to the kernel BTF. When the main BTF object to process (for example, the module BTF to dump) is passed as a FILE, bpftool attempts to autodetect the path for the base object, and passing this option is optional. When the main BTF object is passed through other handles, this option becomes necessary.

## EXAMPLES
\# bpftool btf dump id 1226

```
[1] PTR '(anon)' type_id=2
[2] STRUCT 'dummy_tracepoint_args' size=16 vlen=2

        'pad' type_id=3 bits_offset=0

        'sock' type_id=4 bits_offset=64
[3] INT 'long long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
[4] PTR '(anon)' type_id=5
[5] FWD 'sock' fwd_kind=union
```

This gives an example of default output for all supported BTF kinds.

$ cat prog.c

```
struct fwd_struct;
enum my_enum {

        VAL1 = 3,

        VAL2 = 7,
};
typedef struct my_struct my_struct_t;
struct my_struct {

        const unsigned int const_int_field;

        int bitfield_field: 4;

        char arr_field[16];

        const struct fwd_struct *restrict fwd_field;

        enum my_enum enum_field;

        volatile my_struct_t *typedef_ptr_field;
};
union my_union {

        int a;

        struct my_struct b;
};
struct my_struct struct_global_var __attribute__((section("data_sec"))) = {

        .bitfield_field = 3,

        .enum_field = VAL1,
};
int global_var __attribute__((section("data_sec"))) = 7;
__attribute__((noinline))
int my_func(union my_union *arg1, int arg2)
{

        static int static_var __attribute__((section("data_sec"))) = 123;

        static_var++;

        return static_var;
}
```

$ bpftool btf dump file prog.o

```
[1] PTR '(anon)' type_id=2
[2] UNION 'my_union' size=48 vlen=2

        'a' type_id=3 bits_offset=0

        'b' type_id=4 bits_offset=0
[3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
[4] STRUCT 'my_struct' size=48 vlen=6

        'const_int_field' type_id=5 bits_offset=0

        'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4

        'arr_field' type_id=8 bits_offset=40

        'fwd_field' type_id=10 bits_offset=192

        'enum_field' type_id=14 bits_offset=256

        'typedef_ptr_field' type_id=15 bits_offset=320
[5] CONST '(anon)' type_id=6
[6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
[7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED
[8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16
[9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none)
[10] RESTRICT '(anon)' type_id=11
[11] PTR '(anon)' type_id=12
[12] CONST '(anon)' type_id=13
[13] FWD 'fwd_struct' fwd_kind=union
[14] ENUM 'my_enum' size=4 vlen=2

        'VAL1' val=3

        'VAL2' val=7
[15] PTR '(anon)' type_id=16
[16] VOLATILE '(anon)' type_id=17
[17] TYPEDEF 'my_struct_t' type_id=4
[18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2

        'arg1' type_id=1

        'arg2' type_id=3
[19] FUNC 'my_func' type_id=18
[20] VAR 'struct_global_var' type_id=4, linkage=global-alloc
[21] VAR 'global_var' type_id=3, linkage=global-alloc
[22] VAR 'my_func.static_var' type_id=3, linkage=static
[23] DATASEC 'data_sec' size=0 vlen=3

        type_id=20 offset=0 size=48

        type_id=21 offset=0 size=4

        type_id=22 offset=52 size=4
```

The following commands print BTF types associated with specified map's key, value, both key and value, and all BTF types, respectively. By default, both key and value types will be printed.

\# bpftool btf dump map id 123 key

```
[39] TYPEDEF 'u32' type_id=37
```

\# bpftool btf dump map id 123 value

```
[86] PTR '(anon)' type_id=87
```

\# bpftool btf dump map id 123 kv

```
[39] TYPEDEF 'u32' type_id=37
[86] PTR '(anon)' type_id=87
```

\# bpftool btf dump map id 123 all

```
[1] PTR '(anon)' type_id=0
.
.
.
[2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4
```

All the standard ways to specify map or program are supported:

\# bpftool btf dump map id 123

\# bpftool btf dump map pinned /sys/fs/bpf/map_name

\# bpftool btf dump prog id 456

\# bpftool btf dump prog tag b88e0a09b1d9759d

\# bpftool btf dump prog pinned /sys/fs/bpf/prog_name

```
# bpftool btf dump file /sys/kernel/btf/i2c_smbus
(or)
# I2C_SMBUS_ID=$(bpftool btf show -p | jq '.[] | select(.name=="i2c_smbus").id')
# bpftool btf dump id ${I2C_SMBUS_ID} -B /sys/kernel/btf/vmlinux
```

```
[104848] STRUCT 'i2c_smbus_alert' size=40 vlen=2

        'alert' type_id=393 bits_offset=0

        'ara' type_id=56050 bits_offset=256
[104849] STRUCT 'alert_data' size=12 vlen=3

        'addr' type_id=16 bits_offset=0

        'type' type_id=56053 bits_offset=32

        'data' type_id=7 bits_offset=64
[104850] PTR '(anon)' type_id=104848
[104851] PTR '(anon)' type_id=104849
[104852] FUNC 'i2c_register_spd' type_id=84745 linkage=static
[104853] FUNC 'smbalert_driver_init' type_id=1213 linkage=static
[104854] FUNC_PROTO '(anon)' ret_type_id=18 vlen=1

        'ara' type_id=56050
[104855] FUNC 'i2c_handle_smbus_alert' type_id=104854 linkage=static
[104856] FUNC 'smbalert_remove' type_id=104854 linkage=static
[104857] FUNC_PROTO '(anon)' ret_type_id=18 vlen=2

        'ara' type_id=56050

        'id' type_id=56056
[104858] FUNC 'smbalert_probe' type_id=104857 linkage=static
[104859] FUNC 'smbalert_work' type_id=9695 linkage=static
[104860] FUNC 'smbus_alert' type_id=71367 linkage=static
[104861] FUNC 'smbus_do_alert' type_id=84827 linkage=static
```

## SEE ALSO
bpf(2), bpf-helpers(7), bpftool(8), bpftool-cgroup(8), bpftool-feature(8), bpftool-gen(8), bpftool-iter(8), bpftool-link(8), bpftool-map(8), bpftool-net(8), bpftool-perf(8), bpftool-prog(8), bpftool-struct_ops(8)


bpftool-cgroup

title: bpftool-cgroup(8)

text:
# bpftool-cgroup(8)

## NAME
bpftool-cgroup - tool for inspection and simple manipulation of eBPF progs

## SYNOPSIS
bpftool [OPTIONS] cgroup COMMAND OPTIONS := { { -j | --json } [{ -p | --pretty }] | { -d | --debug } | { -l | --legacy } | { -f | --bpffs } }

COMMANDS := { show | list | tree | attach | detach | help }

## CGROUP COMMANDS

```
bpftool cgroup { show | list } CGROUP [effective]
bpftool cgroup tree [CGROUP_ROOT] [effective]
bpftool cgroup attach CGROUP ATTACH_TYPE PROG [ATTACH_FLAGS]
bpftool cgroup detach CGROUP ATTACH_TYPE PROG
bpftool cgroup help
PROG := { id PROG_ID | pinned FILE | tag PROG_TAG }
ATTACH_TYPE := { cgroup_inet_ingress | cgroup_inet_egress |

cgroup_inet_sock_create | cgroup_sock_ops |
cgroup_device | cgroup_inet4_bind | cgroup_inet6_bind |
cgroup_inet4_post_bind | cgroup_inet6_post_bind |
cgroup_inet4_connect | cgroup_inet6_connect |
cgroup_inet4_getpeername | cgroup_inet6_getpeername |
cgroup_inet4_getsockname | cgroup_inet6_getsockname |
cgroup_udp4_sendmsg | cgroup_udp6_sendmsg |
cgroup_udp4_recvmsg | cgroup_udp6_recvmsg |
cgroup_sysctl | cgroup_getsockopt | cgroup_setsockopt |
cgroup_inet_sock_release }

ATTACH_FLAGS := { multi | override }
```

## DESCRIPTION
bpftool cgroup { show | list } CGROUP [effective]

List all programs attached to the cgroup CGROUP. Output will start with program ID followed by attach type, attach flags and program name.

If effective is specified retrieve effective programs that will execute for events within a cgroup. This includes inherited along with attached ones.

bpftool cgroup tree [CGROUP_ROOT] [effective]

Iterate over all cgroups in CGROUP_ROOT and list all attached programs. If CGROUP_ROOT is not specified, bpftool uses cgroup v2 mountpoint. The output is similar to the output of cgroup show/list commands: it starts with absolute cgroup path, followed by program ID, attach type, attach flags and program name.

If effective is specified retrieve effective programs that will execute for events within a cgroup. This includes inherited along with attached ones.

bpftool cgroup attach CGROUP ATTACH_TYPE PROG [ATTACH_FLAGS]

Attach program PROG to the cgroup CGROUP with attach type ATTACH_TYPE and optional ATTACH_FLAGS. ATTACH_FLAGS can be one of: override if a sub-cgroup installs some bpf program, the program in this cgroup yields to sub-cgroup program; multi if a sub-cgroup installs some bpf program, that cgroup program gets run in addition to the program in this cgroup.

Only one program is allowed to be attached to a cgroup with no attach flags or the override flag. Attaching another program will release old program and attach the new one.

Multiple programs are allowed to be attached to a cgroup with multi. They are executed in FIFO order (those that were attached first, run first).

Non-default ATTACH_FLAGS are supported by kernel version 4.14 and later.

ATTACH_TYPE can be on of: ingress ingress path of the inet socket (since 4.10); egress egress path of the inet socket (since 4.10); sock_create opening of an inet socket (since 4.10); sock_ops various socket operations (since 4.12); device device access (since 4.15); bind4 call to bind(2) for an inet4 socket (since 4.17); bind6 call to bind(2) for an inet6 socket (since 4.17); post_bind4 return from bind(2) for an inet4 socket (since 4.17); post_bind6 return from bind(2) for an inet6 socket (since 4.17); connect4 call to connect(2) for an inet4 socket (since 4.17); connect6 call to connect(2) for an inet6 socket (since 4.17); sendmsg4 call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected udp4 socket (since 4.18); sendmsg6 call to sendto(2), sendmsg(2), sendmmsg(2) for an unconnected udp6 socket (since 4.18); recvmsg4 call to recvfrom(2), recvmsg(2), recvmmsg(2) for an unconnected udp4 socket (since 5.2); recvmsg6 call to recvfrom(2), recvmsg(2), recvmmsg(2) for an unconnected udp6 socket (since 5.2); sysctl sysctl access (since 5.2); getsockopt call to getsockopt (since 5.3); setsockopt call to setsockopt (since 5.3); getpeername4 call to getpeername(2) for an inet4 socket (since 5.8); getpeername6 call to getpeername(2) for an inet6 socket (since 5.8); getsockname4 call to getsockname(2) for an inet4 socket (since 5.8); getsockname6 call to getsockname(2) for an inet6 socket (since 5.8). sock_release closing an userspace inet socket (since 5.9).

bpftool cgroup detach CGROUP ATTACH_TYPE PROG

Detach PROG from the cgroup CGROUP and attach type ATTACH_TYPE.

bpftool prog help

Print short help message.

## OPTIONS
-h, --help

Print short help message (similar to bpftool help).

-V, --version

Print bpftool's version number (similar to bpftool version), the number of the libbpf version in use, and optional features that were included when bpftool was compiled. Optional features include linking against libbfd to provide the disassembler for JIT-ted programs (bpftool prog dump jited) and usage of BPF skeletons (some features like bpftool prog profile or showing pids associated to BPF objects may rely on it).

-j, --json

Generate JSON output. For commands that cannot produce JSON, this option has no effect.

-p, --pretty

Generate human-readable JSON output. Implies -j.

-d, --debug

Print all logs available, even debug-level information. This includes logs from libbpf as well as from the verifier, when attempting to load programs.

-l, --legacy

Use legacy libbpf mode which has more relaxed BPF program requirements. By default, bpftool has more strict requirements about section names, changes pinning logic and doesn't support some of the older non-BTF map declarations. See https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0 for details.

-f, --bpffs

Show file names of pinned programs.

## EXAMPLES

```
# mount -t bpf none /sys/fs/bpf/
# mkdir /sys/fs/cgroup/test.slice
# bpftool prog load ./device_cgroup.o /sys/fs/bpf/prog
# bpftool cgroup attach /sys/fs/cgroup/test.slice/ device id 1 allow_multi
```

\# bpftool cgroup list /sys/fs/cgroup/test.slice/

```
ID       AttachType      AttachFlags     Name
1        device          allow_multi     bpf_prog1
```

```
# bpftool cgroup detach /sys/fs/cgroup/test.slice/ device id 1
# bpftool cgroup list /sys/fs/cgroup/test.slice/
```

```
ID       AttachType      AttachFlags     Name
```

## SEE ALSO
bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8), bpftool-feature(8), bpftool-gen(8), bpftool-iter(8), bpftool-link(8), bpftool-map(8), bpftool-net(8), bpftool-perf(8), bpftool-prog(8), bpftool-struct_ops(8)


bpftool-feature

title: bpftool-feature(8)

text:
# bpftool-feature(8)

## NAME
bpftool-feature - tool for inspection of eBPF-related parameters for Linux kernel or net device

## SYNOPSIS
bpftool [OPTIONS] feature COMMAND OPTIONS := { { -j | --json } [{ -p | --pretty }] | { -d | --debug } | { -l | --legacy } }

COMMANDS := { probe | help }

## FEATURE COMMANDS

```
bpftool feature probe [COMPONENT] [full] [unprivileged] [macros [prefix PREFIX]]
bpftool feature list_builtins GROUP
bpftool feature help
COMPONENT := { kernel | dev NAME }
GROUP := { prog_types | map_types | attach_types | link_types | helpers }
```

## DESCRIPTION
bpftool feature probe [kernel] [full] [macros [prefix PREFIX]]

Probe the running kernel and dump a number of eBPF-related parameters, such as availability of the bpf() system call, JIT status, eBPF program types availability, eBPF helper functions availability, and more. By default, bpftool does not run probes for bpf_probe_write_user() and bpf_trace_printk() helpers which print warnings to kernel logs. To enable them and run all probes, the full keyword should be used.

If the macros keyword (but not the -j option) is passed, a subset of the output is dumped as a list of #define macros that are ready to be included in a C header file, for example. If, additionally, prefix is used to define a PREFIX, the provided string will be used as a prefix to the names of the macros: this can be used to avoid conflicts on macro names when including the output of this command as a header file.

Keyword kernel can be omitted. If no probe target is specified, probing the kernel is the default behaviour.

When the unprivileged keyword is used, bpftool will dump only the features available to a user who does not have the CAP_SYS_ADMIN capability set. The features available in that case usually represent a small subset of the parameters supported by the system. Unprivileged users MUST use the unprivileged keyword: This is to avoid misdetection if bpftool is inadvertently run as non-root, for example. This keyword is unavailable if bpftool was compiled without libcap.

bpftool feature probe dev NAME [full] [macros [prefix PREFIX]]

Probe network device for supported eBPF features and dump results to the console. The keywords full, macros and prefix have the same role as when probing the kernel.

bpftool feature list_builtins GROUP

List items known to bpftool. These can be BPF program types (prog_types), BPF map types (map_types), attach types (attach_types), link types (link_types), or BPF helper functions (helpers). The command does not probe the system, but simply lists the elements that bpftool knows from compilation time, as provided from libbpf (for all object types) or from the BPF UAPI header (list of helpers). This can be used in scripts to iterate over BPF types or helpers.

bpftool feature help

Print short help message.

## OPTIONS
-h, --help

Print short help message (similar to bpftool help).

-V, --version

Print bpftool's version number (similar to bpftool version), the number of the libbpf version in use, and optional features that were included when bpftool was compiled. Optional features include linking against libbfd to provide the disassembler for JIT-ted programs (bpftool prog dump jited) and usage of BPF skeletons (some features like bpftool prog profile or showing pids associated to BPF objects may rely on it).

-j, --json

Generate JSON output. For commands that cannot produce JSON, this option has no effect.

-p, --pretty

Generate human-readable JSON output. Implies -j.

-d, --debug

Print all logs available, even debug-level information. This includes logs from libbpf as well as from the verifier, when attempting to load programs.

-l, --legacy

Use legacy libbpf mode which has more relaxed BPF program requirements. By default, bpftool has more strict requirements about section names, changes pinning logic and doesn't support some of the older non-BTF map declarations. See https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0 for details.

## SEE ALSO
bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8), bpftool-cgroup(8), bpftool-gen(8), bpftool-iter(8), bpftool-link(8), bpftool-map(8), bpftool-net(8), bpftool-perf(8), bpftool-prog(8), bpftool-struct_ops(8)