named

title: named(8)

summary: Internet domain name server

text:
# named(8)

## NAME
named - Internet domain name server

## SYNOPSIS
named [ [-4] | [-6] ] [-c config-file] [-C] [-d debug-level] [-D string] [-E engine-name] [-f] [-g] [-L logfile] [-M option] [-m flag] [-n #cpus] [-p port] [-s] [-t directory] [-U #listeners] [-u user] [-v] [-V] [-X lock-file]

## DESCRIPTION
named is a Domain Name System (DNS) server, part of the BIND 9 distribution from ISC. For more information on the DNS, see RFC 1033 <https://datatracker.ietf.org/doc/html/rfc1033.html>, RFC 1034 <https://datatracker.ietf.org/doc/html/rfc1034.html>, and RFC 1035 <https://datatracker.ietf.org/doc/html/rfc1035.html>.

When invoked without arguments, named reads the default configuration file /etc/named.conf, reads any initial data, and listens for queries.

## OPTIONS
-4

This option tells named to use only IPv4, even if the host machine is capable of IPv6. -4 and -6 are mutually exclusive.

-6

This option tells named to use only IPv6, even if the host machine is capable of IPv4. -4 and -6 are mutually exclusive.

-c config-file

This option tells named to use config-file as its configuration file instead of the default, /etc/named.conf. To ensure that the configuration file can be reloaded after the server has changed its working directory due to to a possible directory option in the configuration file, config-file should be an absolute pathname.

-C

This option prints out the default built-in configuration and exits. NOTE: This is for debugging purposes only and is not an accurate representation of the actual configuration used by named at runtime.

-d debug-level

This option sets the daemon's debug level to debug-level. Debugging traces from named become more verbose as the debug level increases.

-D string

This option specifies a string that is used to identify a instance of named in a process listing. The contents of string are not examined.

-E engine-name

When applicable, this option specifies the hardware to use for cryptographic operations, such as a secure key store used for signing. When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually pkcs11).

-f

This option runs the server in the foreground (i.e., do not daemonize).

-g

This option runs the server in the foreground and forces all logging to stderr.

-L logfile

This option sets the log to the file logfile by default, instead of the system log.

-M option

This option sets the default (comma-separated) memory context options. The possible flags are:

- fill: fill blocks of memory with tag values when they are allocated or freed, to assist debugging of memory problems; this is the implicit default if named has been compiled with --enable-developer.

- nofill: disable the behavior enabled by fill; this is the implicit default unless named has been compiled with --enable-developer.

-m flag

This option turns on memory usage debugging flags. Possible flags are usage, trace and record. These correspond to the ISC_MEM_DEBUGXXXX flags described in <isc/mem.h>.

-n #cpus

This option creates #cpus worker threads to take advantage of multiple CPUs. If not specified, named tries to determine the number of CPUs present and creates one thread per CPU. If it is unable to determine the number of CPUs, a single worker thread is created.

-p value

This option specifies the port(s) on which the server will listen for queries. If value is of the form <portnum> or dns=<portnum>, the server will listen for DNS queries on portnum; if not not specified, the default is port 53. If value is of the form tls=<portnum>, the server will listen for TLS queries on portnum; the default is 853. If value is of the form https=<portnum>, the server will listen for HTTPS queries on portnum; the default is 443. If value is of the form http=<portnum>, the server will listen for HTTP queries on portnum; the default is 80.

-s

This option writes memory usage statistics to stdout on exit.

Note:

This option is mainly of interest to BIND 9 developers and may be removed or changed in a future release.

-S #max-socks

This option is deprecated and no longer has any function.

Warning:

This option should be unnecessary for the vast majority of users. The use of this option could even be harmful, because the specified value may exceed the limitation of the underlying system API. It is therefore set only when the default configuration causes exhaustion of file descriptors and the operational environment is known to support the specified number of sockets. Note also that the actual maximum number is normally slightly fewer than the specified value, because named reserves some file descriptors for its internal use.

-t directory

This option tells named to chroot to directory after processing the command-line arguments, but before reading the configuration file.

Warning:

This option should be used in conjunction with the -u option, as chrooting a process running as root doesn't enhance security on most systems; the way chroot is defined allows a process with root privileges to escape a chroot jail.

-U #dispatches

This option specifies the number of per-interface UDP #dispatches that named should use to handle the outgoing (recursive) UDP connection, to reduce contention between the resolver threads. If not specified, named calculates a default value based on the number of detected CPUs: 1 for a single CPU, and the number of detected CPUs minus one for machines with more than 1 CPU.

This cannot be increased to a value higher than the number of CPUs (see -n on how to override the value).

Warning:

This option should be unnecessary for the vast majority of users, and will be removed in the next version of BIND 9.

-u user

This option sets the setuid to user after completing privileged operations, such as creating sockets that listen on privileged ports.

Note:

On Linux, named uses the kernel's capability mechanism to drop all root privileges except the ability to bind to a privileged port and set process resource limits. Unfortunately, this means that the -u option only works when named is run on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or later, since previous kernels did not allow privileges to be retained after setuid.

-v

This option reports the version number and exits.

-V

This option reports the version number, build options, supported cryptographics algorithms, and exits.

-X lock-file

This option acquires a lock on the specified file at runtime; this helps to prevent duplicate named instances from running simultaneously. Use of this option overrides the lock-file option in named.conf <#std-iscman-named.conf>. If set to none, the lock file check is disabled.

## SIGNALS
In routine operation, signals should not be used to control the nameserver; rndc <#std-iscman-rndc> should be used instead.

SIGHUP

This signal forces a reload of the server.

SIGINT, SIGTERM

These signals shut down the server.

The result of sending any other signals to the server is undefined.

## CONFIGURATION
The named configuration file is too complex to describe in detail here. A complete description is provided in the BIND 9 Administrator Reference Manual.

named inherits the umask (file creation mode mask) from the parent process. If files created by named, such as journal files, need to have custom permissions, the umask should be set explicitly in the script used to start the named process.

## FILES
/etc/named.conf

The default configuration file.

/var/run/named.pid

The default process-id file.

## SEE ALSO
RFC 1033 <https://datatracker.ietf.org/doc/html/rfc1033.html>, RFC 1034 <https://datatracker.ietf.org/doc/html/rfc1034.html>, RFC 1035 <https://datatracker.ietf.org/doc/html/rfc1035.html>, named-checkconf(8) <#std-iscman-named-checkconf>, named-checkzone(8) <#std-iscman-named-checkzone>, rndc(8) <#std-iscman-rndc>, named.conf(5) <#std-iscman-named.conf>, BIND 9 Administrator Reference Manual.

## Author
Internet Systems Consortium

## Copyright
2026, Internet Systems Consortium


rndc

package: bind

title: rndc(8)

summary: name server control utility

text:
# rndc(8)

## NAME
rndc - name server control utility

## SYNOPSIS
rndc [-b source-address] [-c config-file] [-k key-file] [-s server] [-p port] [-q] [-r] [-V] [-y server_key] [[-4] | [-6]] {command}

## DESCRIPTION
rndc controls the operation of a name server. If rndc is invoked with no command line options or arguments, it prints a short summary of the supported commands and the available options and their arguments.

rndc communicates with the name server over a TCP connection, sending commands authenticated with digital signatures. In the current versions of rndc and named <#std-iscman-named>, the only supported authentication algorithms are HMAC-MD5 (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 (default), HMAC-SHA384, and HMAC-SHA512. They use a shared secret on each end of the connection, which provides TSIG-style authentication for the command request and the name server's response. All commands sent over the channel must be signed by a server_key known to the server.

rndc reads a configuration file to determine how to contact the name server and decide what algorithm and key it should use.

## OPTIONS
-4

This option indicates use of IPv4 only.

-6

This option indicates use of IPv6 only.

-b source-address

This option indicates source-address as the source address for the connection to the server. Multiple instances are permitted, to allow setting of both the IPv4 and IPv6 source addresses.

-c config-file

This option indicates config-file as the configuration file instead of the default, /etc/rndc.conf.

-k key-file

This option indicates key-file as the key file instead of the default, /etc/rndc.key. The key in /etc/rndc.key is used to authenticate commands sent to the server if the config-file does not exist.

-s server

server is the name or address of the server which matches a server statement in the configuration file for rndc. If no server is supplied on the command line, the host named by the default-server clause in the options statement of the rndc configuration file is used.

-p port

This option instructs BIND 9 to send commands to TCP port port instead of its default control channel port, 953.

-q

This option sets quiet mode, where message text returned by the server is not printed unless there is an error.

-r

This option instructs rndc to print the result code returned by named <#std-iscman-named> after executing the requested command (e.g., ISC_R_SUCCESS, ISC_R_FAILURE, etc.).

-V

This option enables verbose logging.

-y server_key

This option indicates use of the key server_key from the configuration file. For control message validation to succeed, server_key must be known by named <#std-iscman-named> with the same algorithm and secret string. If no server_key is specified, rndc first looks for a key clause in the server statement of the server being used, or if no server statement is present for that host, then in the default-key clause of the options statement. Note that the configuration file contains shared secrets which are used to send authenticated control commands to name servers, and should therefore not have general read or write access.

## COMMANDS
A list of commands supported by rndc can be seen by running rndc without arguments.

Currently supported commands are:

addzone zone [class [view]] configuration

This command adds a zone while the server is running. This command requires the allow-new-zones option to be set to yes. The configuration string specified on the command line is the zone configuration text that would ordinarily be placed in named.conf <#std-iscman-named.conf>. The configuration is saved in a file called viewname.nzf (or, if named <#std-iscman-named> is compiled with liblmdb, an LMDB database file called viewname.nzd). viewname is the name of the view, unless the view name contains characters that are incompatible with use as a file name, in which case a cryptographic hash of the view name is used instead. When named <#std-iscman-named> is restarted, the file is loaded into the view configuration so that zones that were added can persist after a restart.

This sample addzone command adds the zone example.com to the default view:

rndc addzone example.com '{ type primary; file "example.com.db"; };'

(Note the brackets around and semi-colon after the zone configuration text.)

See also rndc delzone and rndc modzone.

delzone [-clean] zone [class [view]]

This command deletes a zone while the server is running. If the -clean argument is specified, the zone's master file (and journal file, if any) are deleted along with the zone. Without the -clean option, zone files must be deleted manually. (If the zone is of type secondary or stub, the files needing to be removed are reported in the output of the rndc delzone command.)

If the zone was originally added via rndc addzone, then it is removed permanently. However, if it was originally configured in named.conf <#std-iscman-named.conf>, then that original configuration remains in place; when the server is restarted or reconfigured, the zone is recreated. To remove it permanently, it must also be removed from named.conf <#std-iscman-named.conf>.

See also rndc addzone and rndc modzone.

dnssec (-status | -rollover -key id [-alg algorithm] [-when time] | -checkds [-key id [-alg algorithm]] [-when time] published | withdrawn)) zone [class [view]]

This command allows you to interact with the "dnssec-policy" of a given zone. rndc dnssec -status show the DNSSEC signing state for the specified zone.

rndc dnssec -rollover allows you to schedule key rollover for a specific key (overriding the original key lifetime).

rndc dnssec -checkds informs named <#std-iscman-named> that the DS for a specified zone's key-signing key has been confirmed to be published in, or withdrawn from, the parent zone. This is required in order to complete a KSK rollover. The -key id and -alg algorithm arguments can be used to specify a particular KSK, if necessary; if there is only one key acting as a KSK for the zone, these arguments can be omitted. The time of publication or withdrawal for the DS is set to the current time by default, but can be overridden to a specific time with the argument -when time, where time is expressed in YYYYMMDDHHMMSS notation.

dnstap (-reopen | -roll [number])

This command closes and re-opens DNSTAP output files. rndc dnstap -reopen allows the output file to be renamed externally, so that named <#std-iscman-named> can truncate and re-open it.

rndc dnstap -roll causes the output file to be rolled automatically, similar to log files. The most recent output file has ".0" appended to its name; the previous most recent output file is moved to ".1", and so on. If number is specified, then the number of backup log files is limited to that number.

dumpdb [-all | -cache | -zones | -adb | -bad | -expired | -fail] [view ...]

This command dumps the server's caches (default) and/or zones to the dump file for the specified views. If no view is specified, all views are dumped. (See the dump-file option in the BIND 9 Administrator Reference Manual.)

flush

This command flushes the server's cache.

flushname name [view]

This command flushes the given name from the view's DNS cache and, if applicable, from the view's nameserver address database, bad server cache, and SERVFAIL cache.

flushtree name [view]

This command flushes the given name, and all of its subdomains, from the view's DNS cache, address database, bad server cache, and SERVFAIL cache.

freeze [zone [class [view]]]

This command suspends updates to a dynamic zone. If no zone is specified, then all zones are suspended. This allows manual edits to be made to a zone normally updated by dynamic update, and causes changes in the journal file to be synced into the master file. All dynamic update attempts are refused while the zone is frozen. See also rndc thaw.

halt [-p]

This command stops the server immediately. Recent changes made through dynamic update or IXFR are not saved to the master files, but are rolled forward from the journal files when the server is restarted. If -p is specified, named <#std-iscman-named>'s process ID is returned. This allows an external process to determine when named <#std-iscman-named> has completed halting. See also rndc stop.

loadkeys [zone [class [view]]]

This command fetches all DNSSEC keys for the given zone from the key directory. If they are within their publication period, they are merged into the zone's DNSKEY RRset. Unlike rndc sign, however, the zone is not immediately re-signed by the new keys, but is allowed to incrementally re-sign over time. This command requires that the zone be configured with a dnssec-policy, or that the auto-dnssec zone option be set to maintain, and also requires the zone to be configured to allow dynamic DNS. (See "Dynamic Update Policies" in the Administrator Reference Manual for more details.)

managed-keys (status | refresh | sync | destroy) [class [view]]

This command inspects and controls the "managed-keys" database which handles RFC 5011 <https://datatracker.ietf.org/doc/html/rfc5011.html> DNSSEC trust anchor maintenance. If a view is specified, these commands are applied to that view; otherwise, they are applied to all views.

- When run with the status keyword, this prints the current status of the managed-keys database.

- When run with the refresh keyword, this forces an immediate refresh query to be sent for all the managed keys, updating the managed-keys database if any new keys are found, without waiting the normal refresh interval.

- When run with the sync keyword, this forces an immediate dump of the managed-keys database to disk (in the file managed-keys.bind or (viewname.mkeys). This synchronizes the database with its journal file, so that the database's current contents can be inspected visually.

- When run with the destroy keyword, the managed-keys database is shut down and deleted, and all key maintenance is terminated. This command should be used only with extreme caution. Existing keys that are already trusted are not deleted from memory; DNSSEC validation can continue after this command is used. However, key maintenance operations cease until named <#std-iscman-named> is restarted or reconfigured, and all existing key maintenance states are deleted.

Running rndc reconfig or restarting named <#std-iscman-named> immediately after this command causes key maintenance to be reinitialized from scratch, just as if the server were being started for the first time. This is primarily intended for testing, but it may also be used, for example, to jumpstart the acquisition of new keys in the event of a trust anchor rollover, or as a brute-force repair for key maintenance problems.

modzone zone [class [view]] configuration

This command modifies the configuration of a zone while the server is running. This command requires the allow-new-zones option to be set to yes. As with addzone, the configuration string specified on the command line is the zone configuration text that would ordinarily be placed in named.conf <#std-iscman-named.conf>. If the zone was originally added via rndc addzone, the configuration changes are recorded permanently and are still in effect after the server is restarted or reconfigured. However, if it was originally configured in named.conf <#std-iscman-named.conf>, then that original configuration remains in place; when the server is restarted or reconfigured, the zone reverts to its original configuration. To make the changes permanent, it must also be modified in named.conf <#std-iscman-named.conf>.

See also rndc addzone and rndc delzone.

notify zone [class [view]]

This command resends NOTIFY messages for the zone.

notrace

This command sets the server's debugging level to 0. See also rndc trace.

nta [(-class class | -dump | -force | -remove | -lifetime duration)] domain [view]

This command sets a DNSSEC negative trust anchor (NTA) for domain, with a lifetime of duration. The default lifetime is configured in named.conf <#std-iscman-named.conf> via the nta-lifetime option, and defaults to one hour. The lifetime cannot exceed one week. A negative trust anchor selectively disables DNSSEC validation for zones that are known to be failing because of misconfiguration rather than an attack. When data to be validated is at or below an active NTA (and above any other configured trust anchors), named <#std-iscman-named> aborts the DNSSEC validation process and treats the data as insecure rather than bogus. This continues until the NTA's lifetime has elapsed.

NTAs persist across restarts of the named <#std-iscman-named> server. The NTAs for a view are saved in a file called name.nta, where name is the name of the view; if it contains characters that are incompatible with use as a file name, a cryptographic hash is generated from the name of the view.

An existing NTA can be removed by using the -remove option.

An NTA's lifetime can be specified with the -lifetime option. TTL-style suffixes can be used to specify the lifetime in seconds, minutes, or hours. If the specified NTA already exists, its lifetime is updated to the new value. Setting lifetime to zero is equivalent to -remove.

If -dump is used, any other arguments are ignored and a list of existing NTAs is printed. Note that this may include NTAs that are expired but have not yet been cleaned up.

Normally, named <#std-iscman-named> periodically tests to see whether data below an NTA can now be validated (see the nta-recheck option in the Administrator Reference Manual for details). If data can be validated, then the NTA is regarded as no longer necessary and is allowed to expire early. The -force parameter overrides this behavior and forces an NTA to persist for its entire lifetime, regardless of whether data could be validated if the NTA were not present.

The view class can be specified with -class. The default is class IN, which is the only class for which DNSSEC is currently supported.

All of these options can be shortened, i.e., to -l, -r, -d, -f, and -c.

Unrecognized options are treated as errors. To refer to a domain or view name that begins with a hyphen, use a double-hyphen (--) on the command line to indicate the end of options.

querylog [(on | off)]

This command enables or disables query logging. For backward compatibility, this command can also be used without an argument to toggle query logging on and off. Query logging can also be enabled by explicitly directing the queries category to a channel in the logging section of named.conf <#std-iscman-named.conf>, or by specifying querylog yes; in the options section of named.conf <#std-iscman-named.conf>.

reconfig

This command reloads the configuration file and loads new zones, but does not reload existing zone files even if they have changed. This is faster than a full rndc reload when there is a large number of zones, because it avoids the need to examine the modification times of the zone files.

recursing

This command dumps the list of queries named <#std-iscman-named> is currently recursing on, and the list of domains to which iterative queries are currently being sent. The first list includes all unique clients that are waiting for recursion to complete, including the query that is awaiting a response and the timestamp (seconds since the Unix epoch) of when named started processing this client query.

The second list comprises of domains for which there are active (or recently active) fetches in progress. It reports the number of active fetches for each domain and the number of queries that have been passed (allowed) or dropped (spilled) as a result of the fetches-per-zone limit. (Note: these counters are not cumulative over time; whenever the number of active fetches for a domain drops to zero, the counter for that domain is deleted, and the next time a fetch is sent to that domain, it is recreated with the counters set to zero).

refresh zone [class [view]]

This command schedules zone maintenance for the given zone.

reload

This command reloads the configuration file and zones.

zone [class [view]]

If a zone is specified, this command reloads only the given zone. If no zone is specified, the reloading happens asynchronously.

retransfer zone [class [view]]

This command retransfers the given secondary zone from the primary server. If the zone is configured to use inline-signing, the signed version of the zone is discarded; after the retransfer of the unsigned version is complete, the signed version is regenerated with new signatures.

scan

This command scans the list of available network interfaces for changes, without performing a full rndc reconfig or waiting for the interface-interval timer.

secroots [-] [view ...]

This command dumps the security roots (i.e., trust anchors configured via trust-anchors, or the managed-keys or trusted-keys statements [both deprecated], or dnssec-validation auto) and negative trust anchors for the specified views. If no view is specified, all views are dumped. Security roots indicate whether they are configured as trusted keys, managed keys, or initializing managed keys (managed keys that have not yet been updated by a successful key refresh query). If the first argument is -, then the output is returned via the rndc response channel and printed to the standard output. Otherwise, it is written to the secroots dump file, which defaults to named.secroots, but can be overridden via the secroots-file option in named.conf <#std-iscman-named.conf>.

See also rndc managed-keys.

serve-stale (on | off | reset | status) [class [view]]

This command enables, disables, resets, or reports the current status of the serving of stale answers as configured in named.conf <#std-iscman-named.conf>. If serving of stale answers is disabled by rndc-serve-stale off, then it remains disabled even if named <#std-iscman-named> is reloaded or reconfigured. rndc serve-stale reset restores the setting as configured in named.conf <#std-iscman-named.conf>.

rndc serve-stale status reports whether caching and serving of stale answers is currently enabled or disabled. It also reports the values of stale-answer-ttl and max-stale-ttl.

showzone zone [class [view]]

If the server is configured with allow-new-zones set to yes, then this command prints the configuration of a running zone. See also rndc addzone, rndc modzone. and rndc delzone.

sign zone [class [view]]

This command fetches all DNSSEC keys for the given zone from the key directory (see the key-directory option in the BIND 9 Administrator Reference Manual). If they are within their publication period, they are merged into the zone's DNSKEY RRset. If the DNSKEY RRset is changed, then the zone is automatically re-signed with the new key set. This command requires that the zone be configured with a dnssec-policy, or that the auto-dnssec zone option be set to allow or maintain, and also requires the zone to be configured to allow dynamic DNS. (See "Dynamic Update Policies" in the BIND 9 Administrator Reference Manual for more details.)

See also rndc loadkeys.

signing [(-list | -clear keyid/algorithm | -clear all | -nsec3param (parameters | none) | -serial value) zone [class [view]]

This command lists, edits, or removes the DNSSEC signing-state records for the specified zone. The status of ongoing DNSSEC operations, such as signing or generating NSEC3 chains, is stored in the zone in the form of DNS resource records of type sig-signing-type. rndc signing -list converts these records into a human-readable form, indicating which keys are currently signing or have finished signing the zone, and which NSEC3 chains are being created or removed. rndc signing -clear can remove a single key (specified in the same format that rndc signing -list uses to display it), or all keys. In either case, only completed keys are removed; any record indicating that a key has not yet finished signing the zone is retained.

rndc signing -nsec3param sets the NSEC3 parameters for a zone. This is the only supported mechanism for using NSEC3 with inline-signing zones. Parameters are specified in the same format as an NSEC3PARAM resource record: hash algorithm, flags, iterations, and salt, in that order.

Currently, the only defined value for hash algorithm is 1, representing SHA-1. The flags may be set to 0 or 1, depending on whether the opt-out bit in the NSEC3 chain should be set. iterations defines the number of additional times to apply the algorithm when generating an NSEC3 hash. The salt is a string of data expressed in hexadecimal, a hyphen (-) if no salt is to be used, or the keyword auto, which causes named <#std-iscman-named> to generate a random 64-bit salt.

The only recommended configuration is rndc signing -nsec3param 1 0 0 - zone, i.e. no salt, no additional iterations, no opt-out.

Warning:

Do not use extra iterations, salt, or opt-out unless all their implications are fully understood. A higher number of iterations causes interoperability problems and opens servers to CPU-exhausting DoS attacks.

rndc signing -nsec3param none removes an existing NSEC3 chain and replaces it with NSEC.

rndc signing -serial value sets the serial number of the zone to value. If the value would cause the serial number to go backwards, it is rejected. The primary use of this parameter is to set the serial number on inline signed zones.

stats

This command writes server statistics to the statistics file. (See the statistics-file option in the BIND 9 Administrator Reference Manual.)

status

This command displays the status of the server. Note that the number of zones includes the internal bind/CH zone and the default ./IN hint zone, if there is no explicit root zone configured.

stop -p

This command stops the server, making sure any recent changes made through dynamic update or IXFR are first saved to the master files of the updated zones. If -p is specified, named <#std-iscman-named>'s process ID is returned. This allows an external process to determine when named <#std-iscman-named> has completed stopping. See also rndc halt.

sync -clean [zone [class [view]]]

This command syncs changes in the journal file for a dynamic zone to the master file. If the "-clean" option is specified, the journal file is also removed. If no zone is specified, then all zones are synced.

tcp-timeouts [initial idle keepalive advertised]

When called without arguments, this command displays the current values of the tcp-initial-timeout, tcp-idle-timeout, tcp-keepalive-timeout, and tcp-advertised-timeout options. When called with arguments, these values are updated. This allows an administrator to make rapid adjustments when under a denial-of-service (DoS) attack. See the descriptions of these options in the BIND 9 Administrator Reference Manual for details of their use.

thaw [zone [class [view]]]

This command enables updates to a frozen dynamic zone. If no zone is specified, then all frozen zones are enabled. This causes the server to reload the zone from disk, and re-enables dynamic updates after the load has completed. After a zone is thawed, dynamic updates are no longer refused. If the zone has changed and the ixfr-from-differences option is in use, the journal file is updated to reflect changes in the zone. Otherwise, if the zone has changed, any existing journal file is removed. If no zone is specified, the reloading happens asynchronously. See also rndc freeze.

trace [level]

If no level is specified, this command increments the server's debugging level by one.

level

If specified, this command sets the server's debugging level to the provided value.

See also rndc notrace.

tsig-delete keyname [view]

This command deletes a given TKEY-negotiated key from the server. This does not apply to statically configured TSIG keys.

tsig-list

This command lists the names of all TSIG keys currently configured for use by named <#std-iscman-named> in each view. The list includes both statically configured keys and dynamic TKEY-negotiated keys.

validation (on | off | status) [view ...]

This command enables, disables, or checks the current status of DNSSEC validation. By default, validation is enabled. The cache is flushed when validation is turned on or off to avoid using data that might differ between states.

zonestatus zone [class [view]]

This command displays the current status of the given zone, including the master file name and any include files from which it was loaded, when it was most recently loaded, the current serial number, the number of nodes, whether the zone supports dynamic updates, whether the zone is DNSSEC signed, whether it uses automatic DNSSEC key management or inline signing, and the scheduled refresh or expiry times for the zone. See also rndc showzone.

rndc commands that specify zone names, such as reload retransfer, or zonestatus, can be ambiguous when applied to zones of type redirect. Redirect zones are always called ., and can be confused with zones of type hint or with secondary copies of the root zone. To specify a redirect zone, use the special zone name -redirect, without a trailing period. (With a trailing period, this would specify a zone called "-redirect".)

## LIMITATIONS
There is currently no way to provide the shared secret for a server_key without using the configuration file.

Several error messages could be clearer.

## SEE ALSO
rndc.conf(5) <#std-iscman-rndc.conf>, rndc-confgen(8) <#std-iscman-rndc-confgen>, named(8) <#std-iscman-named>, named.conf(5) <#std-iscman-named.conf>, BIND 9 Administrator Reference Manual.

## Author
Internet Systems Consortium

## Copyright
2026, Internet Systems Consortium

branch: sisyphus


rndc-confgen

title: rndc-confgen(8)

summary: rndc key generation tool

text:
# rndc-confgen(8)

## NAME
rndc-confgen - rndc key generation tool

## SYNOPSIS
rndc-confgen [-a] [-A algorithm] [-b keysize] [-c keyfile] [-h] [-k keyname] [-p port] [-s address] [-t chrootdir] [-u user]

## DESCRIPTION
rndc-confgen generates configuration files for rndc <#std-iscman-rndc>. It can be used as a convenient alternative to writing the rndc.conf <#std-iscman-rndc.conf> file and the corresponding controls and key statements in named.conf <#std-iscman-named.conf> by hand. Alternatively, it can be run with the -a option to set up a rndc.key file and avoid the need for a rndc.conf <#std-iscman-rndc.conf> file and a controls statement altogether.

## OPTIONS
-a

This option sets automatic rndc <#std-iscman-rndc> configuration, which creates a file /etc/rndc.key that is read by both rndc <#std-iscman-rndc> and named <#std-iscman-named> on startup. The rndc.key file defines a default command channel and authentication key allowing rndc <#std-iscman-rndc> to communicate with named <#std-iscman-named> on the local host with no further configuration. If a more elaborate configuration than that generated by rndc-confgen -a is required, for example if rndc is to be used remotely, run rndc-confgen without the -a option and set up rndc.conf <#std-iscman-rndc.conf> and named.conf <#std-iscman-named.conf> as directed.

-A algorithm

This option specifies the algorithm to use for the TSIG key. Available choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, and hmac-sha512. The default is hmac-sha256.

-b keysize

This option specifies the size of the authentication key in bits. The size must be between 1 and 512 bits; the default is the hash size.

-c keyfile

This option is used with the -a option to specify an alternate location for rndc.key.

-h

This option prints a short summary of the options and arguments to rndc-confgen.

-k keyname

This option specifies the key name of the rndc <#std-iscman-rndc> authentication key. This must be a valid domain name. The default is rndc-key.

-p port

This option specifies the command channel port where named <#std-iscman-named> listens for connections from rndc <#std-iscman-rndc>. The default is 953.

-q

This option prevets printing the written path in automatic configuration mode.

-s address

This option specifies the IP address where named <#std-iscman-named> listens for command-channel connections from rndc <#std-iscman-rndc>. The default is the loopback address 127.0.0.1.

-t chrootdir

This option is used with the -a option to specify a directory where named <#std-iscman-named> runs chrooted. An additional copy of the rndc.key is written relative to this directory, so that it is found by the chrooted named <#std-iscman-named>.

-u user

This option is used with the -a option to set the owner of the generated rndc.key file. If -t is also specified, only the file in the chroot area has its owner changed.

## EXAMPLES
To allow rndc <#std-iscman-rndc> to be used with no manual configuration, run:

rndc-confgen -a

To print a sample rndc.conf <#std-iscman-rndc.conf> file and the corresponding controls and key statements to be manually inserted into named.conf <#std-iscman-named.conf>, run:

rndc-confgen

## SEE ALSO
rndc(8) <#std-iscman-rndc>, rndc.conf(5) <#std-iscman-rndc.conf>, named(8) <#std-iscman-named>, BIND 9 Administrator Reference Manual.

## Author
Internet Systems Consortium

## Copyright
2026, Internet Systems Consortium


tsig-keygen

title: tsig-keygen(8)

summary: TSIG key generation tool

text:
# tsig-keygen(8)

## NAME
tsig-keygen - TSIG key generation tool

## SYNOPSIS
tsig-keygen [-a algorithm] [-h] [name]

## DESCRIPTION
tsig-keygen is an utility that generates keys for use with TSIG (Transaction Signatures) as defined in RFC 2845 <https://datatracker.ietf.org/doc/html/rfc2845.html>. The resulting keys can be used, for example, to secure dynamic DNS updates to a zone, or for the rndc <#std-iscman-rndc> command channel.

A domain name can be specified on the command line to be used as the name of the generated key. If no name is specified, the default is tsig-key.

## OPTIONS
-a algorithm

This option specifies the algorithm to use for the TSIG key. Available choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, and hmac-sha512. The default is hmac-sha256. Options are case-insensitive, and the "hmac-" prefix may be omitted.

-h

This option prints a short summary of options and arguments.

## SEE ALSO
nsupdate(1) <#std-iscman-nsupdate>, named.conf(5) <#std-iscman-named.conf>, named(8) <#std-iscman-named>, BIND 9 Administrator Reference Manual.

## Author
Internet Systems Consortium

## Copyright
2026, Internet Systems Consortium


bing

package: bing

title: bing(8)

text:
# bing(8)

## NAME
bing — compute point to point throughput using two sizes of ICMP ECHO_REQUEST packets to pairs of remote hosts.

## SYNOPSIS
bing

[-dDnrRPvVwz] [-c count] [-e samples] [-f samplefile] [-i wait] [-p pattern] [-s small packetsize] [-S big packetsize] [-u size increment] host1 host2 [...]

## DESCRIPTION
Bing determines bandwidth on a point-to-point link by sending ICMP ECHO_REQUEST packets and measuring their roundtrip times for different packet sizes on each end of the link.

host1 is supposed to be the nearest end of the link, while host2 is the other end.

The options are as follows:

-c count

Stop after count resets of the stats. Useful only in conjunction with the -e option. Defaults to 1.

-d

Set the SO_DEBUG option on the socket being used.

-D

Display the measured throughput at every received packet. By default, it is displayed only when the computed value changes, which itself changes only when the minimum roundtrip time for one of the packet sizes changes.

-e samples

Reset stats after sending samples ECHO_REQUEST packets.

-f samplefile

Saves the bandwidth measurements to the file samplefile.

-i wait

Wait wait seconds for each ECHO_REPLY packet. The default is to wait for four seconds.

-n

Numeric output only. No attempt will be made to lookup symbolic names for host addresses.

-P

Be pedantic regarding round-trip times. Normally, bing assumes that the roundtrip time for a small packet should always be smaller than the roundtrip time for a big packet to the same host, that for a given size the roundtrip time for host1 should always be smaller than the roundtrip time for host2, and that the increase in the roundtrip time between host1 and host2 should always be bigger for big packets than for small packets.

Bing takes advantage of this to better determine the minimum roundtrip times.

Option -P disables this behaviour, in the unlikely event it could be of any use someday. Even IP/X25 links are not weird enough to require this, though.

-p pattern

You may specify up to 16 ``pad'' bytes to fill out the packet you send. This is useful for diagnosing data-dependent problems in a network. For example, “-p ff” will cause the sent packet to be filled with all ones.

-R

Record route. Includes the RECORD_ROUTE option in the ECHO_REQUEST packet and displays the route buffer on returned packets. Note that the IP header is only large enough for nine such routes. Many hosts ignore or discard this option.

-r

Bypass the normal routing tables and send directly to a host on an attached network. If the host is not on a directly-attached network, an error is returned. This option can be used to ping a local host through an interface that has no route through it (e.g., after the interface was dropped by routed(8) ).

-s packetsize

Specifies the number of data bytes to be sent in the small packets. The default and minimum value is 8.

-S packetsize

Specifies the number of data bytes to be sent in the big packets. The default is 108. The size should be chosen so that big packet roundtrip times are long enough to be accurately measured (depending on clock resolution and number of hops).

-u size increment

Specifies that bing should start sending packets of the size of small packetsize and then increase the size by size increment until it reaches big packetsize.

-v

Verbose output. ICMP packets other than ECHO_RESPONSE that are received are listed.

-V

Very verbose output. The roundtrip time of each received echo is displayed.

-w

Display possible warnings about roundtrip times all the time. By default, warnings are printed only at the end.

-z

Fill packets with uncompressible (pseudo-random) data.

Round-trip times and packet loss statistics are computed. If duplicate packets are received, they are not included in the packet loss calculation, although the round trip time of these packets is used in calculating the minimum/average/maximum round-trip time numbers. When the specified number of loops have been made or if the program is terminated with a SIGINT, a brief summary is displayed.

This program is intended for use in network testing, measurement and management. Because of the load it can impose on the network, it is unwise to use bing during normal operations or from automated scripts.

## BUGS
Many Hosts and Gateways ignore the RECORD_ROUTE option.

The maximum IP header length is too small for options like RECORD_ROUTE to be completely useful. There's not much that that can be done about this, however.

Some of the final stats (average throughputs) almost never give a even marginally correct result.

## SEE ALSO
netstat(1), ifconfig(8), ping(8), routed(8), traceroute(8)

## AUTHOR
Pierre Beyssac <pb@fasterix.freenix.fr>


bitlbee

package: bitlbee

title: bitlbee(8)

summary: IRC gateway to IM chat networks

text:
# bitlbee(8)

## NAME
BitlBee - IRC gateway to IM chat networks

## SYNOPSIS
bitlbee [-I] [-c configuration file] [-d configuration directory]

bitlbee -D [-i address] [-p port number] [-n] [-v] [-c configuration file] [-d configuration directory]

bitlbee -h

## DESCRIPTION
BitlBee is an IRC daemon that can talk to instant messaging networks and acts as a gateway. Users can connect to the server with any normal IRC client and see their 'buddy list' in &bitlbee.

bitlbee is normally started as a system service (with init scripts, systemd units or equivalent). It can also be run as an inetd(8) / xinetd(8) service or a stand-alone daemon with the options below.

To use it, connect to it with an IRC client with a command such as "/connect localhost"

## RUN MODES
-I

Run in inetd(8) mode. This is the default setting for historical reasons, but not the recommended one (See ForkDaemon below).

-D

Run in Daemon mode. In this mode, BitlBee forks to the background and waits for new connections. All clients will be served from one process. This mode is also useful for debugging.

-F

Run in ForkDaemon mode. This is similar to ordinary daemon mode, but every client gets its own process. Easier to set up than inetd mode, and without the possible stability issues. This is the recommended runmode for most use cases.

## OPTIONS
-i address

When running in daemon mode, specifies the network interface (identified by IP address) to which the daemon should attach. Use this if you don't want BitlBee to listen on every interface (which is the default behaviour).

-p port number

When running in daemon mode, specifies the port number on which BitlBee should listen for connections. 6667 is the default value.

-n

Wehn running in daemon mode, this option prevents BitlBee from forking into the background.

-v

Be more verbose. This only works together with the -n flag.

-c path to other configuration file

Use a different configuration file.

-d path to user settings directory

BitlBee normally saves every user's settings in /var/lib/bitlbee/. If you want the settings to be stored somewhere else (for example, if you don't have write permissions in the default location), use this option.

-h

Show help information.

## COMMANDS
To get a complete list of commands, please use the help commands command in the &bitlbee channel after connecting to bitlbee.

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

http://www.bitlbee.org/

For more information on using BitlBee, once connected, you should use the help command in the &bitlbee channel.

## BUGS
Of course there are bugs. If you find some, please report them at http://bugs.bitlbee.org/.

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

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

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

## AUTHORS

Wilmer van der Gaast <wilmer@gaast.net>


bld

package: bld

title: bld(8)

text:
# bld(8)

## NAME
bld - A black list daemon

## SYNOPSIS
bld -h | [option]

## OPTIONS
-v

Output version information and exit

-n

Do not fork to become a daemon

-a address

Address to bind to

-p port

Port to listen to

-l number

Log verbosity (between 0 and 3)

-t number

Minimum time interval before blacklisting

-m number

Maximum submissions in time interval

-i number

IP list size

-b number

Blacklist size

-e number

Blacklist expiration

-P filename

Filename where to save PID

-T number

Timeout for client connections

-u user

User to run as

-g group

Group to run as

-f filename

Use a specific configuration file

-A filename

Filename where to find ACLs

-W filename

Filename where to find whitelist

-B filename

Filename where to store blacklist

-I filename

Filename where to store whole IP list

## DESCRIPTION
By default, the bld daemon listens to requests on port 2905. Requests are either IP addresses submissions or checks against the black list.

bld uses a very simple algorithm to decide whether to add IP addresses to the blacklist or not. The first time an IP address is submitted, it is added to an internal list with a timestamp and all further requests increment a counter for this IP. As soon as the minimum time interval is elapsed (default: 30 seconds), and if a maximum requests ratio is reached (default: 10 submissions in the 30 seconds interval), the IP is put in the blacklist. It is then blacklisted for a configurable time (default: 900 seconds).

## PROTOCOL
Requests sent to bld are rather simple. Each request or reply is followed by a linefeed and a carriage return. A client may only send one request per TCP session. As of now, two commands may be used: ip (address submission) and ip? (ask if address is blacklisted).

ip=a.b.c.d submits an IP address. The server acknowledges either with a 200 code if the address is not blacklisted or a 421 if it is.

ipdecr=a.b.c.d decrements the internal counter for an IP address. The lowest value for the counter is zero. The server always acknowledges with a 200 code.

ip?=a.b.c.d asks if address is blacklisted. The server reply may be 421 if it is or 200 if it's not.

ipbl=a.b.c.d forces the insertion in the blacklist. The server acknowledges with a 200 code.

If using IP based restrictions, the server reply may be 600 if the client is not in the correct ACL to perform a request. Any other error will generate a reply with a 500 error code.

## NOTES
bld binds to localhost by default and accepts any local request, so please make sure that only trusted users can establish a connection to the daemon. Please check that all authorized hosts meet the minimal security requirements before changing this parameter even if using an access control list (see bld_acl.conf(5)).

bld will log some statistics if it receives the SIGUSR1 signal. SIGUSR2 is used to force a dump of both lists in bld working directory.

## FILES
/etc/bld.conf /etc/bld_acl.conf /etc/bld_whitelist.conf /var/run/bld/bld.pid /var/run/bld/bld_iplist.dump /var/run/bld/bld_blacklist.dump

## SEE ALSO
bld.conf(5) bld_acl.conf(5) bld_whitelist.conf(5) bldread(8) bldquery(8) bldsubmit(8) blddecr(8)

## AUTHOR
Olivier Beyssac <obld@r14.freenix.org>


bld-mrtg.pl

title: bld-mrtg.pl(8)

text:
# bld-mrtg.pl(8)

## NAME
bld-mrtg.pl - return MRTG-friendly statistics about local BLD status

## SYNOPSIS
bld-mrtg.pl

## DESCRIPTION
bld-mrtg.pl reads bld daemon dump files and prints statistics about the number of currently blacklisted IPs and the number of IPs added within the last 5 minutes. The default output is MRTG-friendly.

## SEE ALSO
bld(8) bldread(8)

## AUTHOR
Olivier Beyssac <obld@r14.freenix.org>


title: bld-pf_log.pl(8)

text:
# bld-pf_log.pl(8)

## NAME
bld-pf_log.pl - feed BLD with Postifx log files

## SYNOPSIS
bld-pf_log.pl

## DESCRIPTION
bld-pf_log.pl reads mail logs and submits to a bld daemon anything that looks like a "user unknown" Postfix log line. This script gets its information from stdin, so the easiest way to use it is like this:

tail -f /path/to/postfix/logfile | bld-pf_log.pl

You may have to provide various options to the tail program in order to support file modifications such as log rotations.

## SEE ALSO
bld(8) bldread(8) tail(1)

## AUTHOR
Olivier Beyssac <obld@r14.freenix.org>


title: bld-pf_policy(8)

text:
# bld-pf_policy(8)

## NAME
bld-postfix_policy - BLD policy server for Postfix

## SYNOPSIS
bld-postfix_policy [-v] [host [port]]

## OPTIONS
-v

Log information to syslog

host and port

Connect to a BLD running on a different host and port (default localhost:2905)

## DESCRIPTION
bld-postfix_policy implements a policy server for Postfix. It is a safe interface to BLD: any error (eg unable to connect to the daemon) returns a "dunno" action instead of a reject code.

Please read Postfix documentation on how to install a policy server.

## SEE ALSO
bld(8) postfix(1)

## AUTHOR
Olivier Beyssac <obld@r14.freenix.org>


blddecr

title: blddecr(8)

text:
# blddecr(8)

## NAME
blddecr - decrement the counter of an IP address on a bld host

## SYNOPSIS
blddecr [host [port]] ip

## DESCRIPTION
blddecr asks the bld daemon listening on host:port (default localhost:2905) to decrement the counter for ip.

## SEE ALSO
bld(8) bldread(8) bldquery(8) bldinsert(8) blddecr(8)

## AUTHOR
Olivier Beyssac <obld@r14.freenix.org>


bldinsert

title: bldinsert(8)

text:
# bldinsert(8)

## NAME
bldsubmit - submit an IP address to a bld host

## SYNOPSIS
bldinsert [host [port]] ip

## DESCRIPTION
bldinsert adds ip to blacklist of the bld daemon listening on host:port (default localhost:2905).

## SEE ALSO
bld(8) bldread(8) bldquery(8) bldsubmit(8) blddecr(8)

## AUTHOR
Olivier Beyssac <obld@r14.freenix.org>


bldquery

title: bldquery(8)

text:
# bldquery(8)

## NAME
bldquery - query a bld host

## SYNOPSIS
bldquery [host [port]] ip

## DESCRIPTION
bldquery asks the bld daemon listening on host:port (default localhost:2905) if ip is blacklisted or not.

## SEE ALSO
bld(8) bldread(8) bldsubmit(8) bldinsert(8) blddecr(8)

## AUTHOR
Olivier Beyssac <obld@r14.freenix.org>


bldread

title: bldread(8)

text:
# bldread(8)

## NAME
bldread - read bld dumps

## SYNOPSIS
bld -h | filename

## OPTIONS
-h display usage

## DESCRIPTION
bldread is the utility designed to read bld dump files. It outputs semicolon separated values in the following order:

- IP address (`a.b.c.d')

- Insertion time (timestamp in seconds)

- Last update (timestamp in seconds)

- Number of submissions during the interval

- Second submissions counter

- options bitfield (`1' if forced insertion, no other options yet)

- Blacklist flag (`1' if blacklisted, `0' otherwise)

- Internal pointer value for debugging purposes

- Another internal pointer value for debugging purposes

## FILES
/var/run/bld/bld_iplist.dump /var/run/bld/bld_blacklist.dump

## SEE ALSO
bld(8) bldquery(8) bldsubmit(8) bldinsert(8) blddecr(8)

## AUTHOR
Olivier Beyssac <obld@r14.freenix.org>


bldsubmit

title: bldsubmit(8)

text:
# bldsubmit(8)

## NAME
bldsubmit - submit an IP address to a bld host

## SYNOPSIS
bldsubmit [host [port]] ip

## DESCRIPTION
bldsubmit submits ip to the bld daemon listening on host:port (default localhost:2905).

## SEE ALSO
bld(8) bldread(8) bldquery(8) bldinsert(8) blddecr(8)

## AUTHOR
Olivier Beyssac <obld@r14.freenix.org>


blkiomon

package: blktrace

title: blkiomon(8)

text:
# blkiomon(8)

## NAME
blkiomon - monitor block device I/O based o blktrace data

## SYNOPSIS
blkiomon -I interval [ -h file ] [ -b file ] [ -d file ] [ -D file ] [ -Q path_name -q msg_queue_id -m msg_id ] [ -V ]

## DESCRIPTION
blkiomon is a block device I/O monitor. It periodically generates per-device request size and request latency statistics from blktrace data. It provides histograms as well as data that can be used to calculate min, max, average and variance. For this purpose, it consumes D and C traces read from stdin. Note, that this doesn't work for logical volumes, as high-level drivers don't see the completion of the events (C).

There are options for binary output and human-readable output to files and stdout. Output to a message queue is supported as well.

There is no need to use blkparse with blkiomon. blkiomon is capable of consuming binary output written to stdout by blktrace.

## OPTIONS
-I interval

--interval=interval

Set sample interval

-h file

--human-readable=file

Human-readable output file. Use '-' for stdout.

-b file

--binary=file

Binary output file. Use '-' for stdout.

-d file

--dump-lldd=file

Output file for data emitted by low level device driver.

-D file

--debug=file

Output file for debugging data. Use '-' for stdout.

-Q path_name

--msg-queue=path_name

Sets path_name as path name for existing message queue to be used for binary output.

-q msg_queue_id

--msg-queue-id=msg_queue_id

Sets msg_queue_id as ID for an existing message queue to be used for binary output.

-m msg_id

--msg-id=msg_id

Sets msg_id as message identifier to be used for binary output messages written to an existing message queue.

-V

--version

Print program version.

## EXAMPLES
To get I/O statistics for /dev/sdw every 10 seconds for a period of one hour, use the following command:

% blktrace /dev/sdw -a issue -a complete -w 3600 -o - | blkiomon -I 10 -h -

## AUTHORS
blkiomon and this man page were written by Martin Peschke.

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

## COPYRIGHT
Copyright © 2008 IBM Corp.

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.

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


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

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, HSP and/or BLE-MIDI 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.

--loglevel=LEVEL

Set the priority level threshold for log messages. Only messages of the given level or higher are logged. The LEVELs are, in decreasing order:

- error - error conditions

- warning - warning conditions

- info - informational messages

If bluealsa was built with debug enabled, then an additional, lowest, level is available:

•

debug - debug messages

If this option is not given then the default is to use the lowest level (i.e., all messages are logged).

-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, mSBC (if mSBC support is compiled-in) and LC3-SWB (if LC3-SWB 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.

--io-rt-priority=NUM

Set the FIFO scheduler real-time priority of the I/O threads to NUM. By default all I/O threads run at the same priority as the main thread. This option allows the user to increase the priority of the I/O threads. This can be useful when playing audio with a low latency requirement.

It is recommended to use this option when using the HFP profile with the mSBC codec, as the Linux kernel does not provide any buffering for the mSBC SCO socket. If the data are not read from the socket in time, the kernel will drop them. This can lead to lots of "Missing mSBC packets" warnings which will be audible as clicks in the audio.

For more information about scheduling policies and priorities see sched(7).

--disable-realtek-usb-fix

Since Linux kernel 5.14 Realtek USB adapters have required bluealsa to apply a fix for mSBC. This option disables that fix and may be necessary when using an earlier kernel.

--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)

--midi-advertisement

Advertise BLE-MIDI service using Bluetooth LE advertising.

--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), Headset Profile (HSP) and Bluetooth Low Energy MIDI (BLE-MIDI). 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). BLE-MIDI, on the other hand, is used for transmitting MIDI messages over Bluetooth LE.

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 and LC3-SWB codecs.

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

- midi - Bluetooth LE MIDI

The hfp-ofono and midi profiles are available only when bluealsa was compiled respectively with oFono and BLE-MIDI support.

Enabling HFP over oFono will automatically disable hfp-hf and hfp-ag. Also, it is important to note that BlueZ permits only one service to register the HFP profile, 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
/usr/share/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. BlueALSA installs its default file into the directory /usr/share/dbus-1/system.d, but the distribution or local administrator may override that by placing a modified policy file into /etc/dbus-1/system.d

/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-2024 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>