udflabel

title: udflabel(8)

summary: show or change UDF filesystem label

text:
# udflabel(8)

## NAME
udflabel — show or change UDF filesystem label

## SYNOPSIS
udflabel [encoding-options] [block-options] [identifier-options] device [new-label]

## DESCRIPTION
When udflabel is invoked without identifier-options and without specifying new-label then it shows current label of UDF filesystem on device to standard output terminated by new line. Otherwise it updates UDF filesystem (up to the revision 2.60) on device with new specified identifiers from identifier-options. Specifying new-label is synonym for both --lvid and --vid, see section UDF LABEL AND UUID.

## OPTIONS

### GENERAL OPTIONS
-h,--help

Display the usage and the list of options.

### BLOCK OPTIONS
-b,--blocksize= block-size

Specify the size of blocks in bytes. Valid block size for a UDF filesystem is a power of two in the range from 512 to 32768 and must match a device logical (sector) size. If omitted, udflabel tries to autodetect block size. First it tries logical (sector) size and then all valid block sizes.

--startblock= start-block

Specify the block location where the UDF filesystem starts. It is used for calculating the block location of the Volume Recognition Sequence (32 kB after the start block) and the first Anchor Volume Descriptor Pointer (256 blocks after the start block). Normally start block is 0, but for Multisession UDF optical discs it is the block location where the last session of Multisession UDF disc starts.

If omitted, udflabel for optical disc tries to detect start block of the last session from disc Table Of Contents. Otherwise value 0 is used.

For accessing some previous session of Multisession UDF optical disc, it is required to specify correct block where that previous session starts. And also to specify where that session ends via --lastblock option.

For Multisession UDF disc images stored in file there is no way to detect where the last session starts and therefore it is necessary to specify the correct start block location manually from the original optical disc Table Of Contents.

(Option available since udflabel 2.3)

--lastblock= last-block

Specify the block location where the UDF filesystem ends. It is used for calculating the block location of second and third Anchor Volume Descriptor Pointer (256 blocks prior the last block and the last block itself). Normally last block is number of disk blocks minus one, but for Multisession UDF optical discs when reading different session than the last one (specified by --startblock) it is the block location where the specified session ends.

If omitted, udflabel for optical disc tried to detect the last recorded block with fallback to the last block of device or disk file image.

For accessing some previous session of Multisession UDF optical disc, it is required to specify correct value for both --startblock and --lastblock options.

(Option available since udflabel 2.3)

--vatblock= vat-block

Specify the block location of the Virtual Allocation Table. Virtual Allocation Table is present only on UDF disks with Virtual Partition Map and must be at the last written/recorded disk block. If omitted, udflabel for optical disc tries to detect the last recorded block with fallback to the last block of block device or disk file image or block specified by --lastblock. In most cases, this fallback does not have to work and for disk file images with Virtual Allocation Table it is necessary to specify the correct location.

Virtual Allocation Table contains Logical Volume Identifier (UDF Label).

--force

Force updating UDF disks without write support or write protected UDF disks. Some UDF disks may have set write protect flag. Some media, like CD-ROM, DVD-ROM or BD-ROM are read-only. Other media, like CD-RW or DVD-RW, are write-once. UDF is designed also for such media where updating Label or Identifiers is not possible. But in some rare cases, it could make sense to try and overwrite the existing Label or Identifiers also for UDF filesystem which has Access Type either Read-Only or Recordable (Write-Once). This is possible only if underlying media supports overwriting. E.g. UDF image of CD-ROM stored on hard disk or Read-Only UDF image burned to DVD-RAM or BD-RE discs. Option --force ignores UDF Access Type and treats it as Overwritable. Also it ignores UDF SoftWriteProtect and HardWriteProtected flags.

-n,--no-write

Not really, do not write to device. Just simulate and display what would happen with device. Useful for determining which UDF blocks would be overwritten.

### IDENTIFIER OPTIONS
-u,--uuid= uuid

Specify the UDF uuid. Must be exactly 16 hexadecimal lowercase digits and is used for first 16 characters of --fullvsid option. Special value random generates new uuid from local time and a random number. See section UDF LABEL AND UUID.

--lvid= new-logical-volume-identifier

Specify the new Logical Volume Identifier.

--vid= new-volume-identifier

Specify the new Volume Identifier.

--vsid= new-volume-set-identifier

Specify the new 17.–127. character of Volume Set Identifier. See section UDF LABEL AND UUID.

--fsid= new-file-set-identifier

Specify the new File Set Identifier.

--fullvsid= new-full-volume-set-identifier

Specify the new Volume Set identifier. Overwrite previous --uuid and --vsid options. See section UDF LABEL AND UUID.

--owner= new-owner-name

Specify the new Owner name, person who created the medium or filesystem. It is stored in UDF Logical Volume Info1, part of UDF Implementation Use Volume Descriptor. (Option available since udflabel 2.3)

--organization= new-organization-name

Specify the new Organization name responsible for creating the medium or filesystem. It is stored in UDF Logical Volume Info2, part of UDF Implementation Use Volume Descriptor. (Option available since udflabel 2.3)

--contact= new-contact-information

Specify the new Contact information for the medium or filesystem. It is stored in UDF Logical Volume Info3, part of UDF Implementation Use Volume Descriptor. (Option available since udflabel 2.3)

--appid= new-application-identifier

Specify the new Application Identifier which identifies application that created medium or filesystem. It is stored in UDF Primary Volume Descriptor. This identifier can be empty or must start with * and contain only 7bit ASCII characters. (Option available since udflabel 2.3)

--impid= new-developer-identifier

Specify the new Developer Identifier for Implementation Identifier. It is unique identification of the implementation which created medium or filesystem. It is stored in UDF Primary Volume Descriptor. This identifier must start with * and contain only 7bit ASCII characters. (Option available since udflabel 2.3)

### ENCODING OPTIONS
--locale

Treat identifier string options as strings encoded according to current locale settings (default). Must be specified as the first argument.

--u8

Treat identifier string options as strings encoded in 8-bit OSTA Compressed Unicode format without leading Compression ID byte, which is equivalent to Latin1 (ISO-8859-1). Must be specified as first argument.

--u16

Treat identifier string options as strings encoded in 16-bit OSTA Compressed Unicode format without leading Compression ID byte, which is equivalent to UTF-16BE. Note that it is not possible to include zero byte in command line options, therefore any character which has at least one zero byte cannot be supplied (this applies to all Latin1 characters). Must be specified as the first argument.

--utf8

Treat identifier string options as strings encoded in UTF-8. Must be specified as the first argument.

## UDF LABEL AND UUID
UDF specification does not say anything about a disk label but it describes that UDF Logical Volume Identifier is an extremely important field for media identification in a jukebox as that field is displayed to the user. And based on this statement it is a common practice for the majority of UDF implementations to use UDF Logical Volume Identifier as a UDF disk label.

UDF specification does not have a concept of disk UUID like other filesystems. But mandates that the first 16 characters of UDF Volume Set Identifier are unique, a non-fixed and a non-trivial value. Plus first eight characters are hexadecimal digits. Windows application format.exe and Mac OS X application newfs_udf are known to violates this requirement and set only the first 8 characters as unique (others are fixed). Since, there are still a lot of UDF implementations which use in the first 16 characters only hexadecimal digits and all compliant UDF implementations have hexadecimal digits in the first 8 characters, the following algorithm for generating stable UUID was informally chosen and now is used by udftools, util-linux, grub2 and other projects:

0. If Volume Set Identifier has less then 8 characters then stop with empty UUID

1. Take the first 16 bytes from UTF-8 encoded string of Volume Set Identifier

2. If all bytes are hexadecimal digits then use their lowercase form as UUID

3. If first 8 bytes are not all hexadecimal digits then convert those 8 bytes to their hexadecimal representation (resulting in 16 bytes) and use as UUID

4. Otherwise, compose UUID from two 8 byte parts: 1. part: Use the lowercase form of the first 8 bytes (which are hexadecimal digits)

2. part: Convert next 4 bytes (9.–12. pos.) to their hexadecimal representation

Which means that this generated UUID has always 16 hexadecimal lowercase digits. In most cases, this UUID matches case-insensitively the first 16 characters of UDF Volume Set Identifier and for all disks compliant to the UDF specification the first 8 bytes of UUID matches case-insensitively the first 8 characters of UDF Volume Set Identifier. In that algorithm was chosen UTF-8 encoding because it is the only commonly used Unicode transformation to bytes with fixed points in all hexadecimal digits.

## EXIT STATUS
udflabel returns 0 if successful, non-zero if there are problems like block device does not contain UDF filesystem or updating failed.

## LIMITATIONS
udflabel is not able to set new Label, Logical Volume Identifier and File Set Identifier for disks with Virtual Allocation Table (used by Write Once media).

udflabel prior to version 2.3 was unable to handle Multisession UDF discs correctly. It always accessed only the first session (the oldest one) and not the last session (the most recent).

udflabel prior to version 2.2 was unable to print and process Unicode strings with code points above U+FFFF correctly. When option --utf8 was specified then input strings were limited to 3-byte UTF-8 sequences and when option --u16 was specified then input strings were limited just to UCS-2BE strings (subset of UTF-16BE).

udflabel prior to version 2.2 ignored UDF SoftWriteProtect and HardWriteProtected flags and overwritten such disks without any notice.

udflabel prior to version 2.2 was not able to set a new Label, Logical Volume Identifier and File Set Identifier for disks with Metadata Partition (used by UDF revisions higher then 2.01).

udflabel prior to version 2.1 was not able to read Label correctly if the disk had Virtual Allocation Table stored outside of Information Control Block.

## AUTHOR

```
Pali Rohár <pali.rohar@gmail.com>
```

## AVAILABILITY
udflabel is part of the udftools package since version 2.0 and is available from https://github.com/pali/udftools/.

## SEE ALSO
mkudffs(8), pktsetup(8), cdrwtool(1), udfinfo(1), wrudf(1)


udisks

title: udisks(8)

summary: Disk Manager

text:
# udisks(8)

## NAME
udisks - Disk Manager

## DESCRIPTION
udisks provides interfaces to enumerate and perform operations on disks and storage devices. Any application (including unprivileged ones) can access the udisksd(8) daemon via the name org.freedesktop.UDisks2 on the system message bus[1]. In addition to the D-Bus API, a library, libudisks2 is also provided. This library can be used from C/C++ and any high-level language with GObjectIntrospection[2] support such as Javascript and Python. udisks is only indirectly involved in what devices and objects are shown in the user interface.

## ACCESS CONTROL
By default, logged-in users in active log-in sessions are permitted to perform operations (for example, mounting, unlocking or modifying) on devices attached to the seat their session is on. Access-control is fine-grained and based on polkit(8), see the “Authorization Checks” chapter in the udisks documentation for more information. Note that the x-udisks-auth option can be used in the /etc/fstab and /etc/crypttab files to specify that additional authorization is required to mount resp. unlock the device (typically requiring the user to authenticate as an administrator).

## DRIVE CONFIGURATION
At start-up and when a drive is connected, udisksd(8) will apply configuration stored in the file /etc/udisks2/IDENTIFIER.conf where IDENTIFIER is the value of the Drive:Id property for the drive. If the file changes on disk its new contents will also be applied to the drive. Typically, users or administrators will never need to edit drive configuration files as they are effectively managed through graphical applications such as gnome-disks(1). Manually editing configuration files is however supported — the file format is a simple .ini-like format (see the Desktop Entry Specification[3] for the exact syntax). New groups and keys may be added in the future.

### ATA group
The ATA group is for settings that apply to drives using the ATA command-set. The following keys are supported:

StandbyTimeout

The standby timeout. A value of zero means "timeouts are disabled": the device will not automatically enter standby mode. Values from 1 to 240 specify multiples of 5 seconds, yielding timeouts from 5 seconds to 20 minutes. Values from 241 to 251 specify from 1 to 11 units of 30 minutes, yielding timeouts from 30 minutes to 5.5 hours. A value of 252 signifies a timeout of 21 minutes. A value of 253 sets a vendor-defined timeout period between 8 and 12 hours, and the value 254 is reserved. 255 is interpreted as 21 minutes plus 15 seconds. Note that some older drives may have very different interpretations of these values. This is similar to the -S option in hdparm(8).

APMLevel

The Advanced Power Management level. A low value means aggressive power management and a high value means better performance. Possible settings range from values 1 through 127 (which permit spin-down), and values 128 through 254 (which do not permit spin-down). The highest degree of power management is attained with a setting of 1, and the highest I/O performance with a setting of 254. A value of 255 can be used to disable Advanced Power Management altogether on the drive (not all drives support disabling it, but most do). This is similar to the -B option in hdparm(8).

AAMLevel

The Automatic Acoustic Management level. Most modern harddisk drives have the ability to speed down the head movements to reduce their noise output. The possible values are between 0 and 254. 128 is the most quiet (and therefore slowest) setting and 254 the fastest (and loudest). Some drives have only two levels (quiet / fast), while others may have different levels between 128 and 254. At the moment, most drives only support 3 options, off, quiet, and fast. These have been assigned the values 0, 128, and 254 at present, respectively, but integer space has been incorporated for future expansion, should this change. This is similar to the -M option in hdparm(8).

WriteCacheEnabled

A boolean specifying whether to enable or disable the Write Cache. Valid values for this key are “true” and “false”. This is similar to the -W option in hdparm(8). This key was added in 2.1.

ReadLookaheadEnabled

A boolean specifying whether to enable or disable the Read Look-ahead. Valid values for this key are “true” and “false”. This is similar to the -A option in hdparm(8). This key was added in 2.6.0.

## DEVICE INFORMATION
udisks relies on recent versions of udev(7) and the Linux kernel. Influential device properties in the udev database include:

UDISKS_SYSTEM

If set, this overrides the value of the HintSystem property.

UDISKS_IGNORE

If set, this overrides the value of the HintIgnore property.

UDISKS_AUTO

If set, this overrides the value of the HintAuto property.

UDISKS_CAN_POWER_OFF

If set, this overrides the value of the CanPowerOff property.

UDISKS_NAME

The name to use for the device when presenting it in an user interface. This corresponds to the HintName property.

UDISKS_ICON_NAME

The icon to use for the device when presenting it in an user interface. If set, the name must adhere to the freedesktop.org icon theme specification[4]. This corresponds to the HintIconName property.

UDISKS_SYMBOLIC_ICON_NAME

The icon to use for the device when presenting it in an user interface using a symbolic icon. If set, the name must adhere to the freedesktop.org icon theme specification[4]. This corresponds to the HintSymbolicIconName property.

UDISKS_FILESYSTEM_SHARED

If set to 1, the filesystem on the device will be mounted in a shared directory (e.g. /media/VolumeName) instead of a private directory (e.g. /run/media/$USER/VolumeName) when the Filesystem.Mount() method is handled.

ID_SEAT

The physical seat the device is attached to. If unset or set to the empty string, “seat0” (the first seat) is assumed.

ID_ATA_SMART_ACCESS

Override the access method for SMART data retrieval. Valid values include: sat16, sat12, linux-ide, sunplus, jmicron, none and auto (default). Specify none to avoid any I/O, in such a case the SmartUpdated property will always equal to “0”.

## API STABILITY
udisks guarantees a stable D-Bus API within the same major version and this guarantee also extends to the client-side library libudisks2. Additionally, several major versions of udisks can be installed and operate at the same time although interoperability may be limited - for example, a device mounted using the udisks N.x API may require additional authorization if attempting to unmount it through the the (N-1).x API.

The udisks developers do not anticipate breaking API but does reserve the right to do so and if it happens, promises to bump the major version and ensure the new major version of udisks is parallel-installable with any older major version. However, note that programs, man pages and other artifacts may change name (for example, adopt a “2” suffix) to make room for the next major version. Therefore, applications can not rely on tools like e.g. udisksctl(1) to be available. Additionally, there is no guarantee that the options, command-line switches etc. of command-line tools or similar will remain stable.

Instead, applications should only use the D-Bus API, the libudisks2 library or tools such as dbus-send(1) or gdbus(1) to interact with udisksd(8).

## AUDIENCE
The intended audience of udisks include operating system developers working on the higher-level parts of the operating system, for example the desktop shell (such as GNOME[5]) and disk management applications (e.g. GNOME's Disks[6] application). Software on this level typically depend on a specific (major) version of udisks and may even have support for previous versions of udisks or alternative interfaces performing the same role as udisks.

While udisks indeed provides a stable API and a clear upgrade path, it may not be an appropriate dependency for third party applications. For example, if the operating system switches to udisks version N.x and an application is still using the udisks (N-1).x API, the application will not work unless udisks (N-1).x is installed. While this situation is still workable (since both udisks N.x and udisks (N-1).x can be installed) it may not be desirable to ask the user to install the old version - in fact, the operating system vendor may not even provide a packaged version of the old version. Hence, if an application does not want to tie itself to a specific version of the operating system, it should not use udisks.

Viable alternatives to udisks are APIs that are guaranteed to be around for longer time-frames, including:

•Low-level APIs and commands such as e.g. sysfs[7], libudev[8], /proc/self/mountinfo[9] and util-linux[10].

•High-level APIs such as GVolumeMonitor[11].

In particular, for desktop applications it is a much better idea to use something like GVolumeMonitor since it will make the application show the same devices as the desktop shell (e.g. file manager, file chooser and so on) is showing.

## AUTHOR
This man page was originally written for UDisks2 by David Zeuthen <zeuthen@gmail.com> with a lot of help from many others.

## BUGS
Please send bug reports to either the distribution bug tracker or the upstream bug tracker at https://github.com/storaged-project/udisks/issues.

## SEE ALSO
udev(7), polkit(8), udisksd(8), udisksctl(1), umount.udisks2(8), gnome-disks(1)

## NOTES
1.

system message bus

http://www.freedesktop.org/wiki/Software/dbus

2.

GObjectIntrospection

https://live.gnome.org/GObjectIntrospection

3.

Desktop Entry Specification

http://freedesktop.org/wiki/Specifications/desktop-entry-spec

4.

freedesktop.org icon theme specification

http://www.freedesktop.org/wiki/Specifications/icon-theme-spec

5.

GNOME

http://www.gnome.org

6.

Disks

https://live.gnome.org/Design/Apps/Disks

7.

sysfs

http://en.wikipedia.org/wiki/Sysfs

8.

libudev

https://www.freedesktop.org/software/systemd/man/libudev.html

9.

/proc/self/mountinfo

http://www.kernel.org/doc/Documentation/filesystems/proc.txt

10.

util-linux

http://en.wikipedia.org/wiki/Util-linux

11.

GVolumeMonitor

http://developer.gnome.org/gio/stable/volume_mon.html

branch: sisyphus


udisksd

title: udisksd(8)

summary: The udisks system daemon

text:
# udisksd(8)

## NAME
udisksd - The udisks system daemon

## SYNOPSIS
udisksd [--help] [--replace] [--debug] [--no-sigint] [--force-load-modules]

## DESCRIPTION
The udisksd program provides the org.freedesktop.UDisks2 name on the system message bus. Users or administrators should never need to start this daemon as it will be automatically started by dbus-daemon(1) or systemd(1) whenever an application tries to access its D-Bus interfaces.

See the udisks(8) man page for more information.

## OPTIONS
--help

Show help options.

--replace

Replace existing daemon.

--debug

Print debug or informational messages on stdout/stderr.

--no-sigint

Do not handle SIGINT for controlled shutdown.

--force-load-modules

Activate modules on startup

## AUTHOR
This man page was originally written for UDisks2 by David Zeuthen <zeuthen@gmail.com> with a lot of help from many others.

## BUGS
Please send bug reports to either the distribution bug tracker or the upstream bug tracker at https://github.com/storaged-project/udisks/issues.

## SEE ALSO
udisks(8), udisksctl(1), umount.udisks2(8), polkit(8), dbus-daemon(1), systemd(1)


title: umount.udisks2(8)

text:
# umount.udisks2(8)

## NAME
umount.udisks2 - unmount file systems that have been mounted by UDisks2

## DESCRIPTION
The umount.udisks2 program is a helper for the umount(8) program. Its purpose is to clean up automatically created directories created at file system mount-time. It should never be called directly.

## AUTHOR
This man page was originally written for UDisks2 by David Zeuthen <zeuthen@gmail.com> with a lot of help from many others.

## BUGS
Please send bug reports to either the distribution bug tracker or the upstream bug tracker at https://github.com/storaged-project/udisks/issues.

## SEE ALSO
udisks(8), udisksd(8), udisksctl(1), umount(8),


ufw

package: ufw

title: ufw(8)

text:
# ufw(8)

## NAME
ufw - program for managing a netfilter firewall

## DESCRIPTION
This program is for managing a Linux firewall and aims to provide an easy to use interface for the user.

## USAGE
ufw [--dry-run] enable|disable|reload

ufw [--dry-run] default allow|deny|reject [incoming|outgoing|routed]

ufw [--dry-run] logging on|off|LEVEL

ufw [--dry-run] reset

ufw [--dry-run] status [verbose|numbered]

ufw [--dry-run] show REPORT

ufw [--dry-run] [delete] [insert NUM] allow|deny|reject|limit [in|out] [log|log-all] [ PORT[/PROTOCOL] | APPNAME ] [comment COMMENT]

ufw [--dry-run] [rule] [delete] [insert NUM] allow|deny|reject|limit [in|out [on INTERFACE]] [log|log-all] [proto PROTOCOL] [from ADDRESS [port PORT | app APPNAME ]] [to ADDRESS [port PORT | app APPNAME ]] [comment COMMENT]

ufw [--dry-run] route [delete] [insert NUM] allow|deny|reject|limit [in|out on INTERFACE] [log|log-all] [proto PROTOCOL] [from ADDRESS [port PORT | app APPNAME]] [to ADDRESS [port PORT | app APPNAME]] [comment COMMENT]

ufw [--dry-run] delete NUM

ufw [--dry-run] app list|info|default|update

## OPTIONS
--version

show program's version number and exit

-h, --help

show help message and exit

--dry-run

don't modify anything, just show the changes

enable

reloads firewall and enables firewall on boot.

disable

unloads firewall and disables firewall on boot

reload

reloads firewall

default allow|deny|reject DIRECTION

change the default policy for traffic going DIRECTION, where DIRECTION is one of incoming, outgoing or routed. Note that existing rules will have to be migrated manually when changing the default policy. See RULE SYNTAX for more on deny and reject.

logging on|off|LEVEL

toggle logging. Logged packets use the LOG_KERN syslog facility. Systems configured for rsyslog support may also log to /var/log/ufw.log. Specifying a LEVEL turns logging on for the specified LEVEL. The default log level is 'low'. See LOGGING for details.

reset

Disables and resets firewall to installation defaults. Can also give the --force option to perform the reset without confirmation.

status

show status of firewall and ufw managed rules. Use status verbose for extra information. In the status output, 'Anywhere' is synonymous with 'any' and '0.0.0.0/0'. Note that when using status, there is a subtle difference when reporting interfaces. For example, if the following rules are added:

ufw allow in on eth0 from 192.168.0.0/16

ufw allow out on eth1 to 10.0.0.0/8

ufw route allow in on eth0 out on eth1 to 10.0.0.0/8 from 192.168.0.0/16

ufw limit 2222/tcp comment 'SSH port'

ufw status will output:

To Action From

-- ------ ----

Anywhere on eth0 ALLOW 192.168.0.0/16

10.0.0.0/8 ALLOW OUT Anywhere on eth1

10.0.0.0/8 on eth1 ALLOW FWD 192.168.0.0/16 on eth0

Anywhere LIMIT Anywhere # SSH port

For the input and output rules, the interface is reported relative to the firewall system as an endpoint, whereas with route rules, the interface is reported relative to the direction packets flow through the firewall.

show REPORT

display information about the running firewall. See REPORTS

allow ARGS

add allow rule. See RULE SYNTAX

deny ARGS

add deny rule. See RULE SYNTAX

reject ARGS

add reject rule. See RULE SYNTAX

limit ARGS

add limit rule. Currently only IPv4 is supported. See RULE SYNTAX

delete RULE|NUM

deletes the corresponding RULE

insert NUM RULE

insert the corresponding RULE as rule number NUM

## RULE SYNTAX
Users can specify rules using either a simple syntax or a full syntax. The simple syntax only specifies the port and optionally the protocol to be allowed or denied on the host.

Both syntaxes support specifying a comment for the rule. For existing rules, specifying a different comment updates the comment and specifying '' removes the comment.

Example rules using the simple syntax:

ufw allow 53

This rule will allow tcp and udp port 53 to any address on this host. To specify a protocol, append '/protocol' to the port. For example:

ufw allow 25/tcp

This will allow tcp port 25 to any address on this host. ufw will also check /etc/services for the port and protocol if specifying a service by name. Eg:

ufw allow smtp

ufw supports both ingress and egress filtering and users may optionally specify a direction of either in or out for either incoming or outgoing traffic. If no direction is supplied, the rule applies to incoming traffic. Eg:

ufw allow in http

ufw reject out smtp

ufw reject telnet comment 'telnet is unencrypted'

Users can also use a fuller syntax, specifying the source and destination addresses and ports. This syntax is loosely based on OpenBSD's PF syntax. For example:

ufw deny proto tcp to any port 80

This will deny all traffic to tcp port 80 on this host. Another example:

ufw deny proto tcp from 10.0.0.0/8 to 192.168.0.1 port 25

This will deny all traffic from the RFC1918 Class A network to tcp port 25 with the address 192.168.0.1.

ufw deny proto tcp from 2001:db8::/32 to any port 25

This will deny all traffic from the IPv6 2001:db8::/32 to tcp port 25 on this host. IPv6 must be enabled in /etc/default/ufw for IPv6 firewalling to work.

ufw deny in on eth0 to 224.0.0.1 proto igmp

This will deny all igmp traffic to 224.0.0.1 on the eth0 interface.

ufw allow in on eth0 to 192.168.0.1 proto gre

This will allow all gre traffic to 192.168.0.1 on the eth0 interface.

ufw allow proto tcp from any to any port 80,443,8080:8090 comment 'web app'

The above will allow all traffic to tcp ports 80, 443 and 8080-8090 inclusive and adds a comment for the rule. When specifying multiple ports, the ports list must be numeric, cannot contain spaces and must be modified as a whole. Eg, in the above example you cannot later try to delete just the '443' port. You cannot specify more than 15 ports (ranges count as 2 ports, so the port count in the above example is 4).

ufw supports several different protocols. The following are valid in any rule and enabled when the protocol is not specified:

tcp

udp

The following have certain restrictions and are not enabled when the protocol is not specified:

ah valid without port number

esp valid without port number

gre valid without port number

ipv6 valid for IPv4 addresses and without port number

igmp valid for IPv4 addresses and without port number

Rules for traffic not destined for the host itself but instead for traffic that should be routed/forwarded through the firewall should specify the route keyword before the rule (routing rules differ significantly from PF syntax and instead take into account netfilter FORWARD chain conventions). For example:

ufw route allow in on eth1 out on eth2

This will allow all traffic routed to eth2 and coming in on eth1 to traverse the firewall.

ufw route allow in on eth0 out on eth1 to 12.34.45.67 port 80 proto tcp

This rule allows any packets coming in on eth0 to traverse the firewall out on eth1 to tcp port 80 on 12.34.45.67.

In addition to routing rules and policy, you must also setup IP forwarding. This may be done by setting the following in /etc/ufw/sysctl.conf:

net/ipv4/ip_forward=1

net/ipv6/conf/default/forwarding=1

net/ipv6/conf/all/forwarding=1

then restarting the firewall:

ufw disable

ufw enable

Be aware that setting kernel tunables is operating system specific and ufw sysctl settings may be overridden. See the sysctl manual page for details.

ufw supports connection rate limiting, which is useful for protecting against brute-force login attacks. When a limit rule is used, ufw will normally allow the connection but will deny connections if an IP address attempts to initiate 6 or more connections within 30 seconds. See http://www.debian-administration.org/articles/187 for details. Typical usage is:

ufw limit ssh/tcp

Sometimes it is desirable to let the sender know when traffic is being denied, rather than simply ignoring it. In these cases, use reject instead of deny. For example:

ufw reject auth

By default, ufw will apply rules to all available interfaces. To limit this, specify DIRECTION on INTERFACE, where DIRECTION is one of in or out (interface aliases are not supported). For example, to allow all new incoming http connections on eth0, use:

ufw allow in on eth0 to any port 80 proto tcp

To delete a rule, simply prefix the original rule with delete with or without the rule comment. For example, if the original rule was:

ufw deny 80/tcp

Use this to delete it:

ufw delete deny 80/tcp

You may also specify the rule by NUM, as seen in the status numbered output. For example, if you want to delete rule number '3', use:

ufw delete 3

If you have IPv6 enabled and are deleting a generic rule that applies to both IPv4 and IPv6 (eg 'ufw allow 22/tcp'), deleting by rule number will delete only the specified rule. To delete both with one command, prefix the original rule with delete.

To insert a rule, specify the new rule as normal, but prefix the rule with the rule number to insert. For example, if you have four rules, and you want to insert a new rule as rule number three, use:

ufw insert 3 deny to any port 22 from 10.0.0.135 proto tcp

To see a list of numbered rules, use:

ufw status numbered

ufw supports per rule logging. By default, no logging is performed when a packet matches a rule. Specifying log will log all new connections matching the rule, and log-all will log all packets matching the rule. For example, to allow and log all new ssh connections, use:

ufw allow log 22/tcp

See LOGGING for more information on logging.

## EXAMPLES
Deny all access to port 53:

ufw deny 53

Allow all access to tcp port 80:

ufw allow 80/tcp

Allow all access from RFC1918 networks to this host:

ufw allow from 10.0.0.0/8

ufw allow from 172.16.0.0/12

ufw allow from 192.168.0.0/16

Deny access to udp port 514 from host 1.2.3.4:

ufw deny proto udp from 1.2.3.4 to any port 514

Allow access to udp 1.2.3.4 port 5469 from 1.2.3.5 port 5469:

ufw allow proto udp from 1.2.3.5 port 5469 to 1.2.3.4 port 5469

## REMOTE MANAGEMENT
When running ufw enable or starting ufw via its initscript, ufw will flush its chains. This is required so ufw can maintain a consistent state, but it may drop existing connections (eg ssh). ufw does support adding rules before enabling the firewall, so administrators can do:

ufw allow proto tcp from any to any port 22

before running 'ufw enable'. The rules will still be flushed, but the ssh port will be open after enabling the firewall. Please note that once ufw is 'enabled', ufw will not flush the chains when adding or removing rules (but will when modifying a rule or changing the default policy). By default, ufw will prompt when enabling the firewall while running under ssh. This can be disabled by using 'ufw --force enable'.

## APPLICATION INTEGRATION
ufw supports application integration by reading profiles located in /etc/ufw/applications.d. To list the names of application profiles known to ufw, use:

ufw app list

Users can specify an application name when adding a rule (quoting any profile names with spaces). For example, when using the simple syntax, users can use:

ufw allow <name>

Or for the extended syntax:

ufw allow from 192.168.0.0/16 to any app <name>

You should not specify the protocol with either syntax, and with the extended syntax, use app in place of the port clause.

Details on the firewall profile for a given application can be seen with:

ufw app info <name>

where '<name>' is one of the applications seen with the app list command. User's may also specify all to see the profiles for all known applications.

Syntax for the application profiles is a simple .INI format:

[<name>]

title=<title>

description=<description>

ports=<ports>

The 'ports' field may specify a '|'-separated list of ports/protocols where the protocol is optional. A comma-separated list or a range (specified with 'start:end') may also be used to specify multiple ports, in which case the protocol is required. For example:

[SomeService]

title=Some title

desctiption=Some description

ports=12/udp|34|56,78:90/tcp

In the above example, 'SomeService' may be used in app rules and it specifies UDP port 12, TCP and UDP on port 34 and TCP ports 56 and 78-90 inclusive.

After creating or editing an application profile, user's can run:

ufw app update <name>

This command will automatically update the firewall with updated profile information. If specify 'all' for name, then all the profiles will be updated. To update a profile and add a new rule to the firewall automatically, user's can run:

ufw app update --add-new <name>

The behavior of the update --add-new command can be configured using:

ufw app default <policy>

The default application policy is skip, which means that the update --add-new command will do nothing. Users may also specify a policy of allow or deny so the update --add-new command may automatically update the firewall. WARNING: it may be a security to risk to use a default allow policy for application profiles. Carefully consider the security ramifications before using a default allow policy.

## APPLICATION INTEGRATION EXAMPLES
Disallow incoming SSH (allowed by default):

ufw delete allow to any app SSH

Allow incoming UPnP (Universal Plug and Play) where the destination address is one of the standard multicast destination addresses for UPnP:

ufw allow to 239.255.255.250 app UPnP

ufw allow to ff02::f app UPnP

Disallow incoming mDNS (Multicast DNS) where the destination address is one of the standard multicast destination addresses for mDNS (allowed by default):

ufw delete allow to 224.0.0.251 app mDNS

ufw delete allow to ff02::fb app mDNS

(Unfortunately, it is not currently possible to store the destination addresses as part of the application definition.)

## LOGGING
ufw supports multiple logging levels. ufw defaults to a loglevel of 'low' when a loglevel is not specified. Users may specify a loglevel with:

ufw logging LEVEL

LEVEL may be 'off', 'low', 'medium', 'high' and 'full'. Log levels are defined as:

off

disables ufw managed logging

low

logs all blocked packets not matching the defined policy (with rate limiting), as well as packets matching logged rules

medium

log level low, plus all allowed packets not matching the defined policy, all INVALID packets, and all new connections. All logging is done with rate limiting.

high

log level medium (without rate limiting), plus all packets with rate limiting

full

log level high without rate limiting

Loglevels above medium generate a lot of logging output, and may quickly fill up your disk. Loglevel medium may generate a lot of logging output on a busy system.

Specifying 'on' simply enables logging at log level 'low' if logging is currently not enabled.

## REPORTS
The following reports are supported. Each is based on the live system and with the exception of the listening report, is in raw iptables format:

raw

builtins

before-rules

user-rules

after-rules

logging-rules

listening

added

The raw report shows the complete firewall, while the others show a subset of what is in the raw report.

The listening report will display the ports on the live system in the listening state for tcp and the open state for udp, along with the address of the interface and the executable listening on the port. An '*' is used in place of the address of the interface when the executable is bound to all interfaces on that port. Following this information is a list of rules which may affect connections on this port. The rules are listed in the order they are evaluated by the kernel, and the first match wins. Please note that the default policy is not listed and tcp6 and udp6 are shown only if IPV6 is enabled.

The added report displays the list of rules as they were added on the command-line. This report does not show the status of the running firewall (use 'ufw status' instead). Because rules are normalized by ufw, rules may look different than the originally added rule. Also, ufw does not record command ordering, so an equivalent ordering is used which lists IPv6-only rules after other rules.

## NOTES
On installation, ufw is 'enabled' (but only actually enabled on bootup if ufw.service is enabled in systemd) with a default incoming policy of deny, a default forward policy of deny, and a default outgoing policy of allow, with stateful tracking for NEW connections for incoming and forwarded connections. As exceptions to the default deny policy, INPUT on the following application ports is allowed by default:

- SSH (port 22/tcp)

- mDNS (port 5353/udp with the multicast destination addresses 224.0.0.251 for IPv4 and ff02::fb for IPv6)

These rules can easily be removed through the ufw command line or its graphical frontends. In addition to the above, a default ruleset is put in place that does the following:

- DROP packets with RH0 headers

- DROP INVALID packets

- ACCEPT certain icmp packets (INPUT and FORWARD): destination-unreachable, source-quench, time-exceeded, parameter-problem, and echo-request for IPv4. destination-unreachable, packet-too-big, time-exceeded, parameter-problem, and echo-request for IPv6.

- ACCEPT icmpv6 packets for stateless autoconfiguration (INPUT)

- ACCEPT ping replies from IPv6 link-local (ffe8::/10) addresses (INPUT)

- ACCEPT DHCP client traffic (INPUT)

- DROP non-local traffic (INPUT)

Rule ordering is important and the first match wins. Therefore when adding rules, add the more specific rules first with more general rules later.

ufw is not intended to provide complete firewall functionality via its command interface, but instead provides an easy way to add or remove simple rules.

The status command shows basic information about the state of the firewall, as well as rules managed via the ufw command. It does not show rules from the rules files in /etc/ufw. To see the complete state of the firewall, users can ufw show raw. This displays the filter, nat, mangle and raw tables using:

iptables -n -L -v -x -t

ip6tables -n -L -v -x -t

See the iptables and ip6tables documentation for more details.

If the default policy is set to REJECT, ufw may interfere with rules added outside of the ufw framework. See README for details.

IPV6 is allowed by default. To change this behavior to only accept IPv6 traffic on the loopback interface, set IPV6 to 'no' in /etc/default/ufw and reload ufw. When IPv6 is enabled, you may specify rules in the same way as for IPv4 rules, and they will be displayed with ufw status. Rules that match both IPv4 and IPv6 addresses apply to both IP versions. For example, when IPv6 is enabled, the following rule will allow access to port 22 for both IPv4 and IPv6 traffic:

ufw allow 22

IPv6 over IPv4 tunnels and 6to4 are supported by using the 'ipv6' protocol ('41'). This protocol can only be used with the full syntax. For example:

ufw allow to 10.0.0.1 proto ipv6

ufw allow to 10.0.0.1 from 10.4.0.0/16 proto ipv6

IPSec is supported by using the 'esp' ('50') and 'ah' ('51') protocols. These protocols can only be used with the full syntax. For example:

ufw allow to 10.0.0.1 proto esp

ufw allow to 10.0.0.1 from 10.4.0.0/16 proto esp

ufw allow to 10.0.0.1 proto ah

ufw allow to 10.0.0.1 from 10.4.0.0/16 proto ah

In addition to the command-line interface, ufw also provides a framework which allows administrators to modify default behavior as well as take full advantage of netfilter. See the ufw-framework manual page for more information.

## SEE ALSO
ufw-framework(8), iptables(8), ip6tables(8), iptables-restore(8), ip6tables-restore(8), sysctl(8), sysctl.conf(5)

## AUTHOR
ufw is Copyright 2008-2014, Canonical Ltd.

ufw and this manual page was originally written by Jamie Strandboge <jamie@canonical.com>


ufw-framework

title: ufw-framework(8)

summary: using the ufw framework

text:
# ufw-framework(8)

## NAME
ufw-framework - using the ufw framework

## DESCRIPTION
ufw provides both a command line interface and a framework for managing a netfilter firewall. While the ufw command provides an easy to use interface for managing a firewall, the ufw framework provides the administrator methods to customize default behavior and add rules not supported by the command line tool. In this way, ufw can take full advantage of Linux netfilter's power and flexibility.

## OVERVIEW
The framework provides boot time initialization, rules files for adding custom rules, a method for loading netfilter modules, configuration of kernel parameters and configuration of IPv6. The framework consists of the following files:

/usr/libexec/ufw/ufw-init

initialization script

/etc/ufw/before.init

initialization customization script run before ufw is initialized

/etc/ufw/after.init

initialization customization script run after ufw is initialized

/etc/ufw/before[6].rules

rules file containing rules evaluated before UI added rules

/var/lib/ufw/user[6].rules

rules file containing UI added rules (managed with the ufw command)

/etc/ufw/after[6].rules

rules file containing rules evaluated after UI added rules

/etc/default/ufw

high level configuration

/etc/ufw/sysctl.conf

kernel network tunables

/etc/ufw/ufw.conf

additional high level configuration

## BOOT INITIALIZATION
ufw is started on boot with /usr/libexec/ufw/ufw-init. This script is a standard SysV style initscript used by the ufw command and should not be modified. The /etc/before.init and /etc/after.init scripts may be used to perform any additional firewall configuration that is not yet supported in ufw itself and if they exist and are executable, ufw-init will execute these scripts. ufw-init will exit with error if either of these scripts exit with error. ufw-init supports the following arguments:

start:

loads the firewall

stop:

unloads the firewall

restart:

reloads the firewall

force-reload:

same as restart

status:

basic status of the firewall

force-stop:

same as stop, except does not check if the firewall is already loaded

flush-all:

flushes the built-in chains, deletes all non-built-in chains and resets the policy to ACCEPT

ufw-init will call before.init and after.init with start, stop, status and flush-all, but typically, if used, these scripts need only implement start and stop.

ufw uses many user-defined chains in addition to the built-in iptables chains. If MANAGE_BUILTINS in /etc/default/ufw is set to 'yes', on stop and reload the built-in chains are flushed. If it is set to 'no', on stop and reload the ufw secondary chains are removed and the ufw primary chains are flushed. In addition to flushing the ufw specific chains, it keeps the primary chains in the same order with respect to any other user-defined chains that may have been added. This allows for ufw to interoperate with other software that may manage their own firewall rules.

To ensure your firewall is loading on boot, you must integrate this script into the boot process. Consult your distribution's documentation for the proper way to modify your boot process if ufw is not already integrated.

## RULES FILES
ufw is in part a front-end for iptables-restore, with its rules saved in /etc/ufw/before.rules, /etc/ufw/after.rules and /var/lib/ufw/user.rules. Administrators can customize before.rules and after.rules as desired using the standard iptables-restore syntax. Rules are evaluated as follows: before.rules first, user.rules next, and after.rules last. IPv6 rules are evaluated in the same way, with the rules files named before6.rules, user6.rules and after6.rules. Please note that ufw status only shows rules added with ufw and not the rules found in the /etc/ufw rules files.

Important: ufw only uses the *filter table by default. You may add any other tables such as *nat, *raw and *mangle as desired. For each table a corresponding COMMIT statement is required.

After modifying any of these files, you must reload ufw for the rules to take effect. See the EXAMPLES section for common uses of these rules files.

## MODULES
Netfilter has many different connection tracking modules. These modules are aware of the underlying protocol and allow the administrator to simplify his or her rule sets. You can adjust which netfilter modules to load by adjusting IPT_MODULES in /etc/default/ufw. Some popular modules to load are:

nf_conntrack_ftp

nf_nat_ftp

nf_conntrack_irc

nf_nat_irc

nf_conntrack_netbios_ns

nf_conntrack_pptp

nf_conntrack_tftp

nf_nat_tftp

## KERNEL PARAMETERS
ufw will read in /etc/ufw/sysctl.conf on boot when enabled. Please note that /etc/ufw/sysctl.conf overrides values in the system systcl.conf (usually /etc/sysctl.conf). Administrators can change the file used by modifying /etc/default/ufw.

## IPV6
IPv6 is enabled by default. When disabled, all incoming, outgoing and forwarded packets are dropped, with the exception of traffic on the loopback interface. To adjust this behavior, set IPV6 to 'yes' in /etc/default/ufw. See the ufw manual page for details.

## EXAMPLES
As mentioned, ufw loads its rules files into the kernel by using the iptables-restore and ip6tables-restore commands. Users wanting to add rules to the ufw rules files manually must be familiar with these as well as the iptables and ip6tables commands. Below are some common examples of using the ufw rules files. All examples assume IPv4 only and that DEFAULT_FORWARD_POLICY in /etc/default/ufw is set to DROP.

### IP Masquerading
To allow IP masquerading for computers from the 10.0.0.0/8 network on eth1 to share the single IP address on eth0:

Edit /etc/ufw/sysctl.conf to have:

net.ipv4.ip_forward=1

Add to the end of /etc/ufw/before.rules, after the *filter section:

*nat

:POSTROUTING ACCEPT [0:0]

-A POSTROUTING -s 10.0.0.0/8 -o eth0 -j MASQUERADE

COMMIT

If your firewall is using IPv6 tunnels or 6to4 and is also doing NAT, then you should not usually masquerade protocol '41' (ipv6) packets. For example, instead of the above, /etc/ufw/before.rules can be adjusted to have:

*nat

:POSTROUTING ACCEPT [0:0]

-A POSTROUTING -s 10.0.0.0/8 --protocol ! 41 -o eth0 -j MASQUERADE

COMMIT

Add the ufw route to allow the traffic:

ufw route allow in on eth1 out on eth0 from 10.0.0.0/8

### Port Redirections
To forward tcp port 80 on eth0 to go to the webserver at 10.0.0.2:

Edit /etc/ufw/sysctl.conf to have:

net.ipv4.ip_forward=1

Add to the end of /etc/ufw/before.rules, after the *filter section:

*nat

:PREROUTING ACCEPT [0:0]

-A PREROUTING -p tcp -i eth0 --dport 80 -j DNAT \

--to-destination 10.0.0.2:80

COMMIT

Add the ufw route rule to allow the traffic:

ufw route allow in on eth0 to 10.0.0.2 port 80 proto tcp

### Egress filtering
To block RFC1918 addresses going out of eth0:

Add the ufw route rules to reject the traffic:

ufw route reject out on eth0 to 10.0.0.0/8

ufw route reject out on eth0 to 172.16.0.0/12

ufw route reject out on eth0 to 192.168.0.0/16

### Full example
This example combines the other examples and demonstrates a simple routing firewall. Warning: this setup is only an example to demonstrate the functionality of the ufw framework in a concise and simple manner and should not be used in production without understanding what each part does and does not do. Your firewall will undoubtedly want to be less open.

This router/firewall has two interfaces: eth0 (Internet facing) and eth1 (internal LAN). Internal clients have addresses on the 10.0.0.0/8 network and should be able to connect to anywhere on the Internet. Connections to port 80 from the Internet should be forwarded to 10.0.0.2. Access to ssh port 22 from the administrative workstation (10.0.0.100) to this machine should be allowed. Also make sure no internal traffic goes to the Internet.

Edit /etc/ufw/sysctl.conf to have:

net.ipv4.ip_forward=1

Add to the end of /etc/ufw/before.rules, after the *filter section:

*nat

:PREROUTING ACCEPT [0:0]

:POSTROUTING ACCEPT [0:0]

-A PREROUTING -p tcp -i eth0 --dport 80 -j DNAT \

--to-destination 10.0.0.2:80

-A POSTROUTING -s 10.0.0.0/8 -o eth0 -j MASQUERADE

COMMIT

Add the necessary ufw rules:

ufw route reject out on eth0 to 10.0.0.0/8

ufw route reject out on eth0 to 172.16.0.0/12

ufw route reject out on eth0 to 192.168.0.0/16

ufw route allow in on eth1 out on eth0 from 10.0.0.0/8

ufw route allow in on eth0 to 10.0.0.2 port 80 proto tcp

ufw allow in on eth1 from 10.0.0.100 to any port 22 proto tcp

## NOTES
When using ufw with libvirt and bridging, packets may be blocked. The libvirt team recommends that the following sysctl's be set to disable netfilter on the bridge:

net.bridge.bridge-nf-call-ip6tables = 0

net.bridge.bridge-nf-call-iptables = 0

net.bridge.bridge-nf-call-arptables = 0

Note that the bridge module must be loaded in to the kernel before these values are set. One way to ensure this works properly with ufw is to add 'bridge' to IPT_MODULES in /etc/default/ufw, and then add the above rules to /etc/ufw/sysctl.conf.

Alternatively to disabling netfilter on the bridge, you can configure iptables to allow all traffic to be forwarded across the bridge. Eg, add to /etc/ufw/before.rules within the *filter section:

-I FORWARD -m physdev --physdev-is-bridged -j ACCEPT

## SEE ALSO
ufw(8), iptables(8), ip6tables(8), iptables-restore(8), ip6tables-restore(8), sysctl(8), sysctl.conf(5)

## AUTHOR
ufw is Copyright 2008-2014, Canonical Ltd.

ufw and this manual page was originally written by Jamie Strandboge <jamie@canonical.com>


ulogd

package: ulogd

title: ulogd(8)

summary: netfilter/iptables logging daemon

text:
# ulogd(8)

## NAME
ulogd - netfilter/iptables logging daemon

## SYNOPSIS
ulogd [options]

## DESCRIPTION
ulogd is a logging daemon that reads event messages coming from the Netfilter connection tracking, the Netfilter packet logging subsystem and from the Netfilter accounting subsystem. You have to enable support for connection tracking event delivery; ctnetlink and the NFLOG target in your Linux kernel 2.6.x or load their respective modules. The deprecated ULOG target (which has been superseded by NFLOG) is no longer supported.

The received messages can be logged into files or into a mySQL, sqlite3 or PostgreSQL database. IPFIX and Graphite output are also supported.

## OPTIONS
-d, --daemon

fork ulogd into background (start as daemon)

-c <filename>, --configfile <filename>

use <filename> as configuration file instead of /etc/ulogd.conf

-h, --help

show usage information

-V, --version

show version information and copyright

-v, --verbose

verbose output on stdout when not running as daemon

-l, --loglevel <level>

set log level to <level>: debug(1), info(3), notice(5), error(7) or fatal(8) (default 5)

-u <UID>, --uid <UID>

change UID/GID

-i <pluginpath>, --info <pluginpath>

display infos about plugin

-p <filename>, --pidfile <filename>

record the ulogd process ID to the given file name

## FILES
/etc/ulogd.conf

/var/log/ulogd/ulogd.log

## SEE ALSO
There is more documentation about the daemon and the database plugins (including examples) in the directories

```
/usr/share/doc/ulogd
```

/usr/share/doc/ulogd-mysql and

```
/usr/share/doc/ulogd-pgsql
```

## AUTHOR
This manual page was written by Joerg Wendland <joergland@debian.org>, for the Debian GNU/Linux system (but may be used by others).


unbound

package: unbound

title: unbound(8)

summary: Unbound DNS validating resolver 1.25.1.

text:
# unbound(8)

## NAME
unbound - Unbound DNS validating resolver 1.25.1.

## SYNOPSIS
unbound [-hdpVv] [-c <cfgfile>]

## DESCRIPTION
unbound is a caching DNS resolver.

It uses a built in list of authoritative nameservers for the root zone (.), the so called root hints. On receiving a DNS query it will ask the root nameservers for an answer and will in almost all cases receive a delegation to a top level domain (TLD) authoritative nameserver. It will then ask that nameserver for an answer. It will recursively continue until an answer is found or no answer is available (NXDOMAIN). For performance and efficiency reasons that answer is cached for a certain time (the answer's time-to-live or TTL). A second query for the same name will then be answered from the cache. Unbound can also do DNSSEC validation.

To use a locally running Unbound for resolving put:

```
nameserver 127.0.0.1
```

into resolv.conf(5).

If authoritative DNS is needed as well using nsd(8), careful setup is required because authoritative nameservers and resolvers are using the same port number (53).

The available options are:

-h

Show the version number and commandline option help, and exit.

-c <cfgfile>

Set the config file with settings for unbound to read instead of reading the file at the default location, /var/lib/unbound/unbound.conf. The syntax is described in unbound.conf(5).

-d

Debug flag: do not fork into the background, but stay attached to the console. This flag will also delay writing to the log file until the thread-spawn time, so that most config and setup errors appear on stderr. If given twice or more, logging does not switch to the log file or to syslog, but the log messages are printed to stderr all the time.

-p

Don't use a pidfile. This argument should only be used by supervision systems which can ensure that only one instance of Unbound will run concurrently.

-v

Increase verbosity. If given multiple times, more information is logged. This is in addition to the verbosity (if any) from the config file.

-V

Show the version number and build options, and exit.

## SEE ALSO
unbound.conf(5), unbound-checkconf(8), nsd(8).

## AUTHOR
Unbound developers are mentioned in the CREDITS file in the distribution.

## COPYRIGHT
1999-2026, NLnet Labs


unbound-checkconf

title: unbound-checkconf(8)

text:
# unbound-checkconf(8)

## NAME
unbound-checkconf - Check Unbound 1.25.1 configuration file for errors.

## SYNOPSIS
unbound-checkconf [-hf] [-o option] [cfgfile]

## DESCRIPTION
unbound-checkconf checks the configuration file for the unbound(8) DNS resolver for syntax and other errors. The config file syntax is described in unbound.conf(5).

The available options are:

-h

Show the version and commandline option help.

-f

Print full pathname, with chroot applied to it. Use with the -o option.

-q

Make the operation quiet, suppress output on success.

-o <option>

If given, after checking the config file the value of this option is printed to stdout. For "" (disabled) options an empty line is printed.

cfgfile

The config file to read with settings for Unbound. It is checked. If omitted, the config file at the default location is checked.

## EXIT CODE
The unbound-checkconf program exits with status code 1 on error, 0 for a correct config file.

## FILES
/var/lib/unbound/unbound.conf

Unbound configuration file.

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

## AUTHOR
Unbound developers are mentioned in the CREDITS file in the distribution.

## COPYRIGHT
1999-2026, NLnet Labs


unbound-control-setup

title: unbound-control-setup(8)

text:
# unbound-control-setup(8)

## NAME
unbound-control - Unbound 1.25.1 remote server control utility.

## SYNOPSIS
unbound-control [-hq] [-c cfgfile] [-s server] command

## DESCRIPTION
unbound-control performs remote administration on the unbound(8) DNS server. It reads the configuration file, contacts the Unbound server over TLS sends the command and displays the result.

The available options are:

-h

Show the version and commandline option help.

-c <cfgfile>

The config file to read with settings. If not given the default config file /var/lib/unbound/unbound.conf is used.

-s <server[@port]>

IPv4 or IPv6 address of the server to contact. If not given, the address is read from the config file.

-q

Quiet, if the option is given it does not print anything if it works ok.

## COMMANDS
There are several commands that the server understands.

start

Start the server. Simply execs unbound(8). The unbound executable is searched for in the PATH set in the environment. It is started with the config file specified using -c or the default config file.

stop

Stop the server. The server daemon exits.

reload

Reload the server. This flushes the cache and reads the config file fresh.

reload_keep_cache

Reload the server but try to keep the RRset and message cache if (re)configuration allows for it. That means the caches sizes and the number of threads must not change between reloads.

fast_reload [+dpv]

Reload the server, but keep downtime to a minimum, so that user queries keep seeing service. This needs the code compiled with threads. The config is loaded in a thread, and prepared, then it briefly pauses the existing server and updates config options. The intent is that the pause does not impact the service of user queries. The cache is kept. Also user queries worked on are kept and continue, but with the new config options. NOTE:

This command is experimental at this time.

The amount of temporal memory needed during a fast_reload is twice the amount needed for configuration. This is because Unbound temporarily needs to store both current configuration values and new ones while trying to fast_reload. Zones loaded from disk (authority zones and RPZ zones) are included in such memory needs.

Options that can be changed are for forwards, stubs, views, authority zones, RPZ zones and local zones.

Also access-control and similar options, interface-action and similar options and tcp-connection-limit. It can reload some define-tag changes, more on that below. Further options include insecure-lan-zones, domain-insecure, trust-anchor-file, trust-anchor, trusted-keys-file, auto-trust-anchor-file, edns-client-string, ipset, log-identity, infra-cache-numhosts, msg-cache-size, rrset-cache-size, key-cache-size, ratelimit-size, neg-cache-size, num-queries-per-thread, jostle-timeout, use-caps-for-id, unwanted-reply-threshold, tls-use-sni, outgoing-tcp-mss, ip-dscp, max-reuse-tcp-queries, tcp-reuse-timeout, tcp-auth-query-timeout, delay-close. iter-scrub-promiscuous. tls-service-key. tls-service-pem.

It does not work with interface and outgoing-interface changes, also not with remote control, outgoing-port-permit, outgoing-port-avoid, msg-buffer-size, any *-slabs options and statistics-interval changes.

For dnstap these options can be changed: dnstap-log-resolver-query-messages, dnstap-log-resolver-response-messages, dnstap-log-client-query-messages, dnstap-log-client-response-messages, dnstap-log-forwarder-query-messages and dnstap-log-forwarder-response-messages.

It does not work with these options: dnstap-enable, dnstap-bidirectional, dnstap-socket-path, dnstap-ip, dnstap-tls, dnstap-tls-server-name, dnstap-tls-cert-bundle, dnstap-tls-client-key-file and dnstap-tls-client-cert-file.

The options dnstap-send-identity, dnstap-send-version, dnstap-identity, and dnstap-version can be loaded when +p is not used.

The +v option makes the output verbose which includes the time it took to do the reload. With +vv it is more verbose which includes the amount of memory that was allocated temporarily to perform the reload; this amount of memory can be big if the config has large contents. In the timing output the 'reload' time is the time during which the server was paused.

The +p option makes the reload not pause threads, they keep running. Locks are acquired, but items are updated in sequence, so it is possible for threads to see an inconsistent state with some options from the old and some options from the new config, such as cache TTL parameters from the old config and forwards from the new config. The stubs and forwards are updated at the same time, so that they are viewed consistently, either old or new values together. The option makes the reload time take eg. 3 microseconds instead of 0.3 milliseconds during which the worker threads are interrupted. So, the interruption is much shorter, at the expense of some inconsistency. After the reload itself, every worker thread is briefly contacted to make them release resources, this makes the delete timing a little longer, and takes up time from the remote control servicing worker thread.

With the nopause option (+p), the reload does not work to reload some options, that fast reload works on without the nopause option: val-bogus-ttl, val-override-date, val-sig-skew-min, val-sig-skew-max, val-max-restart, val-nsec3-keysize-iterations, target-fetch-policy, outbound-msg-retry, max-sent-count, max-query-restarts, do-not-query-address, do-not-query-localhost, private-address, private-domain, caps-exempt, nat64-prefix, do-nat64, infra-host-ttl, infra-keep-probing, ratelimit, ip-ratelimit, ip-ratelimit-cookie, wait-limit-netblock, wait-limit-cookie-netblock, ratelimit-below-domain, ratelimit-for-domain.

The +d option makes the reload drop queries that the worker threads are working on. This is like flush_requestlist. Without it the queries are kept so that users keep getting answers for those queries that are currently processed. The drop makes it so that queries during the life time of the query processing see only old, or only new config options.

When there are changes to the config tags, from the define-tag option, then the +d option is implicitly turned on with a warning printout, and queries are dropped. This is to stop references to the old tag information, by the old queries. If the number of tags is increased in the newly loaded config, by adding tags at the end, then the implicit +d option is not needed.

For response ip, that is actions associated with IP addresses, and perhaps intersected with access control tag and action information, those settings are stored with a query when it comes in based on its source IP address. The old information is kept with the query until the queries are done. This is gone when those queries are resolved and finished, or it is possible to flush the requestlist with +d.

verbosity number

Change verbosity value for logging. Same values as the verbosity: keyword in unbound.conf(5). This new setting lasts until the server is issued a reload (taken from config file again), or the next verbosity control command.

log_reopen

Reopen the logfile, close and open it. Useful for logrotation to make the daemon release the file it is logging to. If you are using syslog it will attempt to close and open the syslog (which may not work if chrooted).

stats

Print statistics. Resets the internal counters to zero, this can be controlled using the statistics-cumulative: config statement. Statistics are printed with one [name]: [value] per line.

stats_noreset

Peek at statistics. Prints them like the stats command does, but does not reset the internal counters to zero.

status

Display server status. Exit code 3 if not running (the connection to the port is refused), 1 on error, 0 if running.

local_zone name type

Add new local zone with name and type. Like local-zone config statement. If the zone already exists, the type is changed to the given argument.

local_zone_remove name

Remove the local zone with the given name. Removes all local data inside it. If the zone does not exist, the command succeeds.

local_data RR data...

Add new local data, the given resource record. Like local-data: keyword, except for when no covering zone exists. In that case this remote control command creates a transparent zone with the same name as this record.

local_data_remove name

Remove all RR data from local name. If the name already has no items, nothing happens. Often results in NXDOMAIN for the name (in a static zone), but if the name has become an empty nonterminal (there is still data in domain names below the removed name), NOERROR nodata answers are the result for that name.

local_zones

Add local zones read from stdin of unbound-control. Input is read per line, with name space type on a line. For bulk additions.

local_zones_remove

Remove local zones read from stdin of unbound-control. Input is one name per line. For bulk removals.

local_datas

Add local data RRs read from stdin of unbound-control. Input is one RR per line. For bulk additions.

local_datas_remove

Remove local data RRs read from stdin of unbound-control. Input is one name per line. For bulk removals.

dump_cache

The contents of the cache is printed in a text format to stdout. You can redirect it to a file to store the cache in a file. Not supported in remote Unbounds in multi-process operation.

load_cache

The contents of the cache is loaded from stdin. Uses the same format as dump_cache uses. Loading the cache with old, or wrong data can result in old or wrong data returned to clients. Loading data into the cache in this way is supported in order to aid with debugging. Not supported in remote Unbounds in multi-process operation.

cache_lookup [+t] names

Print to stdout the RRsets and messages that are in the cache. For every name listed the content at or under the name is printed. Several names separated by spaces can be given, each is printed. When subnetcache is enabled, also matching entries from the subnet cache are printed. The +t option allows tld and root names. With it names like 'com' and '.' can be used, but it takes a lot of effort to look up in the cache.

lookup name

Print to stdout the name servers that would be used to look up the name specified.

flush [+c] name

Remove the name from the cache. Removes the types A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV, NAPTR, SVCB and HTTPS. Because that is fast to do. Other record types can be removed using flush_type or flush_zone. The +c option removes the items also from the cachedb cache. If cachedb is in use.

flush_type [+c] name type

Remove the name, type information from the cache. The +c option removes the items also from the cachedb cache. If cachedb is in use.

flush_zone [+c] name

Remove all information at or below the name from the cache. The rrsets and key entries are removed so that new lookups will be performed. This needs to walk and inspect the entire cache, and is a slow operation. The entries are set to expired in the implementation of this command (so, with serve-expired enabled, it'll serve that information but schedule a prefetch for new information). The +c option removes the items also from the cachedb cache. If cachedb is in use.

flush_bogus [+c]

Remove all bogus data from the cache. The +c option removes the items also from the cachedb cache. If cachedb is in use.

flush_negative [+c]

Remove all negative data from the cache. This is nxdomain answers, nodata answers and servfail answers. Also removes bad key entries (which could be due to failed lookups) from the dnssec key cache, and iterator last-resort lookup failures from the rrset cache. The +c option removes the items also from the cachedb cache. If cachedb is in use.

flush_stats

Reset statistics to zero.

flush_requestlist

Drop the queries that are worked on. Stops working on the queries that the server is working on now. The cache is unaffected. No reply is sent for those queries, probably making those users request again later. Useful to make the server restart working on queries with new settings, such as a higher verbosity level.

dump_requestlist

Show what is worked on. Prints all queries that the server is currently working on. Prints the time that users have been waiting. For internal requests, no time is printed. And then prints out the module status. This prints the queries from the first thread, and not queries that are being serviced from other threads.

flush_infra all|IP

If all then entire infra cache is emptied. If a specific IP address, the entry for that address is removed from the cache. It contains EDNS, ping and lameness data.

dump_infra

Show the contents of the infra cache.

set_option opt: val

Set the option to the given value without a reload. The cache is therefore not flushed. The option must end with a ':' and whitespace must be between the option and the value. Some values may not have an effect if set this way, the new values are not written to the config file, not all options are supported. This is different from the set_option call in libunbound, where all values work because Unbound has not been initialized. The values that work are: statistics-interval, statistics-cumulative, do-not-query-localhost, harden-short-bufsize, harden-large-queries, harden-glue, harden-dnssec-stripped, harden-below-nxdomain, harden-referral-path, prefetch, prefetch-key, log-queries, hide-identity, hide-version, identity, version, val-log-level, val-log-squelch, ignore-cd-flag, add-holddown, del-holddown, keep-missing, tcp-upstream, ssl-upstream, max-udp-size, ratelimit, ip-ratelimit, cache-max-ttl, cache-min-ttl, cache-max-negative-ttl.

get_option opt

Get the value of the option. Give the option name without a trailing ':'. The value is printed. If the value is "", nothing is printed and the connection closes. On error 'error ...' is printed (it gives a syntax error on unknown option). For some options a list of values, one on each line, is printed. The options are shown from the config file as modified with set_option. For some options an override may have been taken that does not show up with this command, not results from e.g. the verbosity and forward control commands. Not all options work, see list_stubs, list_forwards, list_local_zones and list_local_data for those.

list_stubs

List the stub zones in use. These are printed one by one to the output. This includes the root hints in use.

list_forwards

List the forward zones in use. These are printed zone by zone to the output.

list_insecure

List the zones with domain-insecure.

list_local_zones

List the local zones in use. These are printed one per line with zone type.

list_local_data

List the local data RRs in use. The resource records are printed.

insecure_add zone

Add a domain-insecure for the given zone, like the statement in unbound.conf. Adds to the running Unbound without affecting the cache contents (which may still be bogus, use flush_zone to remove it), does not affect the config file.

insecure_remove zone

Removes domain-insecure for the given zone.

forward_add [+it] zone addr ...

Add a new forward zone to running Unbound. With +i option also adds a domain-insecure for the zone (so it can resolve insecurely if you have a DNSSEC root trust anchor configured for other names). The addr can be IP4, IP6 or nameserver names, like forward-zone config in unbound.conf. The +t option sets it to use TLS upstream, like forward-tls-upstream: yes.

forward_remove [+i] zone

Remove a forward zone from running Unbound. The +i also removes a domain-insecure for the zone.

stub_add [+ipt] zone addr ...

Add a new stub zone to running Unbound. With +i option also adds a domain-insecure for the zone. With +p the stub zone is set to prime, without it it is set to notprime. The addr can be IP4, IP6 or nameserver names, like the stub-zone: config in unbound.conf. The +t option sets it to use TLS upstream, like stub-tls-upstream: yes.

stub_remove [+i] zone

Remove a stub zone from running Unbound. The +i also removes a domain-insecure for the zone.

forward [off | addr ... ]

Setup forwarding mode. Configures if the server should ask other upstream nameservers, should go to the internet root nameservers itself, or show the current config. You could pass the nameservers after a DHCP update. Without arguments the current list of addresses used to forward all queries to is printed. On startup this is from the forward-zone "." configuration. Afterwards it shows the status. It prints off when no forwarding is used.

If off is passed, forwarding is disabled and the root nameservers are used. This can be used to avoid to avoid buggy or non-DNSSEC supporting nameservers returned from DHCP. But may not work in hotels or hotspots.

If one or more IPv4 or IPv6 addresses are given, those are then used to forward queries to. The addresses must be separated with spaces. With '@port' the port number can be set explicitly (default port is 53 (DNS)).

By default the forwarder information from the config file for the root "." is used. The config file is not changed, so after a reload these changes are gone. Other forward zones from the config file are not affected by this command.

ratelimit_list [+a]

List the domains that are ratelimited. Printed one per line with current estimated qps and qps limit from config. With +a it prints all domains, not just the ratelimited domains, with their estimated qps. The ratelimited domains return an error for uncached (new) queries, but cached queries work as normal.

ip_ratelimit_list [+a]

List the ip addresses that are ratelimited. Printed one per line with current estimated qps and qps limit from config. With +a it prints all ips, not just the ratelimited ips, with their estimated qps. The ratelimited ips are dropped before checking the cache.

list_auth_zones

List the auth zones that are configured. Printed one per line with a status, indicating if the zone is expired and current serial number. Configured RPZ zones are included.

auth_zone_reload zone

Reload the auth zone (or RPZ zone) from zonefile. The zonefile is read in overwriting the current contents of the zone in memory. This changes the auth zone contents itself, not the cache contents. Such cache contents exists if you set Unbound to validate with for-upstream: yes and that can be cleared with flush_zone zone.

auth_zone_transfer zone

Transfer the auth zone (or RPZ zone) from master. The auth zone probe sequence is started, where the masters are probed to see if they have an updated zone (with the SOA serial check). And then the zone is transferred for a newer zone version.

rpz_enable zone

Enable the RPZ zone if it had previously been disabled.

rpz_disable zone

Disable the RPZ zone.

view_list_local_zones view

list_local_zones for given view.

view_local_zone view name type

local_zone for given view.

view_local_zone_remove view name

local_zone_remove for given view.

view_list_local_data view

list_local_data for given view.

view_local_data view RR data...

local_data for given view.

view_local_data_remove view name

local_data_remove for given view.

view_local_datas_remove view

Remove a list of local_data for given view from stdin. Like local_datas_remove.

view_local_datas view

Add a list of local_data for given view from stdin. Like local_datas.

add_cookie_secret secret

Add or replace a cookie secret persistently. secret needs to be an 128 bit hex string. Cookie secrets can be either active or staging. Active cookie secrets are used to create DNS Cookies, but verification of a DNS Cookie succeeds with any of the active or staging cookie secrets. The state of the current cookie secrets can be printed with the print_cookie_secrets command.

When there are no cookie secrets configured yet, the secret is added as active. If there is already an active cookie secret, the secret is added as staging or replacing an existing staging secret.

To "roll" a cookie secret used in an anycast set. The new secret has to be added as staging secret to all nodes in the anycast set. When all nodes can verify DNS Cookies with the new secret, the new secret can be activated with the activate_cookie_secret command. After all nodes have the new secret active for at least one hour, the previous secret can be dropped with the drop_cookie_secret command.

Persistence is accomplished by writing to a file which is configured with the cookie-secret-file option in the server section of the config file. This is disabled by default, "".

drop_cookie_secret

Drop the staging cookie secret.

activate_cookie_secret

Make the current staging cookie secret active, and the current active cookie secret staging.

print_cookie_secrets

Show the current configured cookie secrets with their status.

## EXIT CODE
The unbound-control program exits with status code 1 on error, 0 on success.

## SET UP
The setup requires a self-signed certificate and private keys for both the server and client. The script unbound-control-setup generates these in the default run directory, or with -d in another directory. If you change the access control permissions on the key files you can decide who can use unbound-control, by default owner and group but not all users. Run the script under the same username as you have configured in unbound.conf or as root, so that the daemon is permitted to read the files, for example with:

```
sudo -u unbound unbound-control-setup
```

If you have not configured a username in unbound.conf, the keys need read permission for the user credentials under which the daemon is started. The script preserves private keys present in the directory. After running the script as root, turn on control-enable in unbound.conf.

## STATISTIC COUNTERS
The stats and stats_noreset commands show a number of statistic counters:

threadX.num.queries

number of queries received by thread

threadX.num.queries_ip_ratelimited

number of queries rate limited by thread

threadX.num.queries_cookie_valid

number of queries with a valid DNS Cookie by thread

threadX.num.queries_cookie_client

number of queries with a client part only DNS Cookie by thread

threadX.num.queries_cookie_invalid

number of queries with an invalid DNS Cookie by thread

threadX.num.queries_discard_timeout

number of queries removed due to discard-timeout by thread

threadX.num.queries_replyaddr_limit

number of queries removed due to replyaddr limits by thread

threadX.num.queries_wait_limit

number of queries removed due to wait-limit by thread

threadX.num.cachehits

number of queries that were successfully answered using a cache lookup

threadX.num.cachemiss

number of queries that needed recursive processing

threadX.num.dnscrypt.crypted

number of queries that were encrypted and successfully decapsulated by dnscrypt.

threadX.num.dnscrypt.cert

number of queries that were requesting dnscrypt certificates.

threadX.num.dnscrypt.cleartext

number of queries received on dnscrypt port that were cleartext and not a request for certificates.

threadX.num.dnscrypt.malformed

number of request that were neither cleartext, not valid dnscrypt messages.

threadX.num.dns_error_reports

number of DNS Error Reports generated by thread

threadX.num.prefetch

number of cache prefetches performed. This number is included in cachehits, as the original query had the unprefetched answer from cache, and resulted in recursive processing, taking a slot in the requestlist. Not part of the recursivereplies (or the histogram thereof) or cachemiss, as a cache response was sent.

threadX.num.expired

number of replies that served an expired cache entry.

threadX.num.queries_timed_out

number of queries that are dropped because they waited in the UDP socket buffer for too long.

threadX.query.queue_time_us.max

The maximum wait time for packets in the socket buffer, in microseconds. This is only reported when sock-queue-timeout is enabled.

threadX.num.recursivereplies

The number of replies sent to queries that needed recursive processing. Could be smaller than threadX.num.cachemiss if due to timeouts no replies were sent for some queries.

threadX.requestlist.avg

The average number of requests in the internal recursive processing request list on insert of a new incoming recursive processing query.

threadX.requestlist.max

Maximum size attained by the internal recursive processing request list.

threadX.requestlist.overwritten

Number of requests in the request list that were overwritten by newer entries. This happens if there is a flood of queries that recursive processing and the server has a hard time. The counter is increased when during the flood the jostle-timeout allows a query to be removed in favor of a new incoming query. The older query is then dropped to make space.

threadX.requestlist.exceeded

Queries that were dropped because the request list was full. This happens if a flood of queries need recursive processing, and the server can not keep up. The counter is increased when during the flood there is no space to be made with the jostle out of an older query, and the new query is dropped. Since no older queries are removed, see jostle-timeout setting, there is no space for the new query.

threadX.requestlist.current.all

Current size of the request list, includes internally generated queries (such as priming queries and glue lookups).

threadX.requestlist.current.user

Current size of the request list, only the requests from client queries.

threadX.requestlist.current.replies

Current count of the number of reply entries waiting on request list entries. Because a request list entry can send results to multiple reply addresses, this number may be larger than the size of the request list.

threadX.recursion.time.avg

Average time it took to answer queries that needed recursive processing. Note that queries that were answered from the cache are not in this average.

threadX.recursion.time.median

The median of the time it took to answer queries that needed recursive processing. The median means that 50% of the user queries were answered in less than this time. Because of big outliers (usually queries to non responsive servers), the average can be bigger than the median. This median has been calculated by interpolation from a histogram.

threadX.tcpusage

The currently held tcp buffers for incoming connections. A spot value on the time of the request. This helps you spot if the incoming-num-tcp buffers are full.

total.num.queries

summed over threads.

total.num.queries_ip_ratelimited

summed over threads.

total.num.queries_cookie_valid

summed over threads.

total.num.queries_cookie_client

summed over threads.

total.num.queries_cookie_invalid

summed over threads.

total.num.queries_discard_timeout

summed over threads.

total.num.queries_replyaddr_limit

summed over threads.

total.num.queries_wait_limit

summed over threads.

total.num.cachehits

summed over threads.

total.num.cachemiss

summed over threads.

total.num.dnscrypt.crypted

summed over threads.

total.num.dnscrypt.cert

summed over threads.

total.num.dnscrypt.cleartext

summed over threads.

total.num.dnscrypt.malformed

summed over threads.

total.num.dns_error_reports

summed over threads.

total.num.prefetch

summed over threads.

total.num.expired

summed over threads.

total.num.queries_timed_out

summed over threads.

total.query.queue_time_us.max

the maximum of the thread values.

total.num.recursivereplies

summed over threads.

total.requestlist.avg

averaged over threads.

total.requestlist.max

the maximum of the thread requestlist.max values.

total.requestlist.overwritten

summed over threads.

total.requestlist.exceeded

summed over threads.

total.requestlist.current.all

summed over threads.

total.requestlist.current.user

summed over threads.

total.requestlist.current.replies

summed over threads.

total.recursion.time.median

averaged over threads.

total.tcpusage

summed over threads.

time.now

current time in seconds since 1970.

time.up

uptime since server boot in seconds.

time.elapsed

time since last statistics printout, in seconds.

## EXTENDED STATISTICS
mem.cache.rrset

Memory in bytes in use by the RRset cache.

mem.cache.message

Memory in bytes in use by the message cache.

mem.cache.dnscrypt_shared_secret

Memory in bytes in use by the dnscrypt shared secrets cache.

mem.cache.dnscrypt_nonce

Memory in bytes in use by the dnscrypt nonce cache.

mem.mod.iterator

Memory in bytes in use by the iterator module.

mem.mod.validator

Memory in bytes in use by the validator module. Includes the key cache and negative cache.

mem.streamwait

Memory in bytes in used by the TCP and TLS stream wait buffers. These are answers waiting to be written back to the clients.

mem.http.query_buffer

Memory in bytes used by the HTTP/2 query buffers. Containing (partial) DNS queries waiting for request stream completion.

mem.http.response_buffer

Memory in bytes used by the HTTP/2 response buffers. Containing DNS responses waiting to be written back to the clients.

mem.quic

Memory in bytes used by QUIC. Containing connection information, stream information, queries read and responses written back to the clients.

histogram.<sec>.<usec>.to.<sec>.<usec>

Shows a histogram, summed over all threads. Every element counts the recursive queries whose reply time fit between the lower and upper bound. Times larger or equal to the lowerbound, and smaller than the upper bound. There are 40 buckets, with bucket sizes doubling.

num.query.type.A

The total number of queries over all threads with query type A. Printed for the other query types as well, but only for the types for which queries were received, thus =0 entries are omitted for brevity.

num.query.type.other

Number of queries with query types 256-65535.

num.query.class.IN

The total number of queries over all threads with query class IN (internet). Also printed for other classes (such as CH (CHAOS) sometimes used for debugging), or NONE, ANY, used by dynamic update. num.query.class.other is printed for classes 256-65535.

num.query.opcode.QUERY

The total number of queries over all threads with query opcode QUERY. Also printed for other opcodes, UPDATE, ...

num.query.tcp

Number of queries that were made using TCP towards the Unbound server.

num.query.tcpout

Number of queries that the Unbound server made using TCP outgoing towards other servers.

num.query.udpout

Number of queries that the Unbound server made using UDP outgoing towards other servers.

num.query.tls

Number of queries that were made using TLS towards the Unbound server. These are also counted in num.query.tcp, because TLS uses TCP.

num.query.tls.resume

Number of TLS session resumptions, these are queries over TLS towards the Unbound server where the client negotiated a TLS session resumption key.

num.query.https

Number of queries that were made using HTTPS towards the Unbound server. These are also counted in num.query.tcp and num.query.tls, because HTTPS uses TLS and TCP.

num.query.quic

Number of queries that were made using QUIC towards the Unbound server. These are also counted in num.query.tls, because TLS is used for these queries.

num.query.ipv6

Number of queries that were made using IPv6 towards the Unbound server.

num.query.flags.RD

The number of queries that had the RD flag set in the header. Also printed for flags QR, AA, TC, RA, Z, AD, CD. Note that queries with flags QR, AA or TC may have been rejected because of that.

num.query.edns.present

number of queries that had an EDNS OPT record present.

num.query.edns.DO

number of queries that had an EDNS OPT record with the DO (DNSSEC OK) bit set. These queries are also included in the num.query.edns.present number.

num.query.ratelimited

The number of queries that are turned away from being send to nameserver due to ratelimiting.

num.query.dnscrypt.shared_secret.cachemiss

The number of dnscrypt queries that did not find a shared secret in the cache. This can be use to compute the shared secret hitrate.

num.query.dnscrypt.replay

The number of dnscrypt queries that found a nonce hit in the nonce cache and hence are considered a query replay.

num.answer.rcode.NXDOMAIN

The number of answers to queries, from cache or from recursion, that had the return code NXDOMAIN. Also printed for the other return codes.

num.answer.rcode.nodata

The number of answers to queries that had the pseudo return code nodata. This means the actual return code was NOERROR, but additionally, no data was carried in the answer (making what is called a NOERROR/NODATA answer). These queries are also included in the num.answer.rcode.NOERROR number. Common for AAAA lookups when an A record exists, and no AAAA.

num.answer.secure

Number of answers that were secure. The answer validated correctly. The AD bit might have been set in some of these answers, where the client signalled (with DO or AD bit in the query) that they were ready to accept the AD bit in the answer.

num.answer.bogus

Number of answers that were bogus. These answers resulted in SERVFAIL to the client because the answer failed validation.

num.rrset.bogus

The number of rrsets marked bogus by the validator. Increased for every RRset inspection that fails.

num.valops

The number of validation operations performed by the validator. Increased for every RRSIG verification operation regardless of the validation result. The RRSIG and key combination needs to first pass some sanity checks before Unbound even performs the verification, e.g., length/protocol checks.

unwanted.queries

Number of queries that were refused or dropped because they failed the access control settings.

unwanted.replies

Replies that were unwanted or unsolicited. Could have been random traffic, delayed duplicates, very late answers, or could be spoofing attempts. Some low level of late answers and delayed duplicates are to be expected with the UDP protocol. Very high values could indicate a threat (spoofing).

msg.cache.count

The number of items (DNS replies) in the message cache.

rrset.cache.count

The number of RRsets in the rrset cache. This includes rrsets used by the messages in the message cache, but also delegation information.

infra.cache.count

The number of items in the infra cache. These are IP addresses with their timing and protocol support information.

key.cache.count

The number of items in the key cache. These are DNSSEC keys, one item per delegation point, and their validation status.

msg.cache.max_collisions

The maximum number of hash table collisions in the msg cache. This is the number of hashes that are identical when a new element is inserted in the hash table. If the value is very large, like hundreds, something is wrong with the performance of the hash table, hash values are incorrect or malicious.

rrset.cache.max_collisions

The maximum number of hash table collisions in the rrset cache. This is the number of hashes that are identical when a new element is inserted in the hash table. If the value is very large, like hundreds, something is wrong with the performance of the hash table, hash values are incorrect or malicious.

dnscrypt_shared_secret.cache.count

The number of items in the shared secret cache. These are precomputed shared secrets for a given client public key/server secret key pair. Shared secrets are CPU intensive and this cache allows Unbound to avoid recomputing the shared secret when multiple dnscrypt queries are sent from the same client.

dnscrypt_nonce.cache.count

The number of items in the client nonce cache. This cache is used to prevent dnscrypt queries replay. The client nonce must be unique for each client public key/server secret key pair. This cache should be able to host QPS * replay window interval keys to prevent replay of a query during replay window seconds.

num.query.authzone.up

The number of queries answered from auth-zone data, upstream queries. These queries would otherwise have been sent (with fallback enabled) to the internet, but are now answered from the auth zone.

num.query.authzone.down

The number of queries for downstream answered from auth-zone data. These queries are from downstream clients, and have had an answer from the data in the auth zone.

num.query.aggressive.NOERROR

The number of queries answered using cached NSEC records with NODATA RCODE. These queries would otherwise have been sent to the internet, but are now answered using cached data.

num.query.aggressive.NXDOMAIN

The number of queries answered using cached NSEC records with NXDOMAIN RCODE. These queries would otherwise have been sent to the internet, but are now answered using cached data.

num.query.subnet

Number of queries that got an answer that contained EDNS client subnet data.

num.query.subnet_cache

Number of queries answered from the edns client subnet cache. These are counted as cachemiss by the main counters, but hit the client subnet specific cache after getting processed by the edns client subnet module.

num.query.cachedb

Number of queries answered from the external cache of cachedb. These are counted as cachemiss by the main counters, but hit the cachedb external cache after getting processed by the cachedb module.

num.rpz.action.<rpz_action>

Number of queries answered using configured RPZ policy, per RPZ action type. Possible actions are: nxdomain, nodata, passthru, drop, tcp-only, local-data, disabled, and cname-override.

## FILES
/var/lib/unbound/unbound.conf

Unbound configuration file.

/var/lib/unbound

directory with private keys (unbound_server.key and unbound_control.key) and self-signed certificates (unbound_server.pem and unbound_control.pem).

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

## AUTHOR
Unbound developers are mentioned in the CREDITS file in the distribution.

## COPYRIGHT
1999-2026, NLnet Labs