bcc-vfsstat

title: bcc-vfsstat(8)

text:
# bcc-vfsstat(8)

## NAME
vfsstat - Statistics for some common VFS calls. Uses Linux eBPF/bcc.

## SYNOPSIS
vfsstat [interval [count]]

## DESCRIPTION
This traces some common VFS calls and prints per-second summaries. This can be useful for general workload characterization, and looking for patterns in operation usage over time.

This works by tracing some kernel vfs functions using dynamic tracing, and will need updating to match any changes to these functions. Edit the script to customize which functions are traced. Also see vfscount, which is more easily customized to trace multiple functions.

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## EXAMPLES
Print summaries each second:

\# vfsstat

Print output every five seconds, three times:

\# vfsstat 5 3

## FIELDS
READ/s

Number of vfs_read() calls as a per-second average.

WRITE/s

Number of vfs_write() calls as a per-second average.

CREATE/s

Number of vfs_create() calls as a per-second average.

OPEN/s

Number of vfs_open() calls as a per-second average.

FSYNC/s

Number of vfs_fsync() calls as a per-second average.

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

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

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

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
vfscount(8)


bcc-virtiostat

package: bcc-tools

title: bcc-virtiostat(8)

text:
# bcc-virtiostat(8)

## NAME
virtiostat - Trace VIRTIO devices input/output statistics. Uses Linux eBPF/bcc.

## SYNOPSIS
virtiostat [-h] [-T] [-D] [-d DRIVER] [-n DEVNAME] [INTERVAL] [COUNT]

## DESCRIPTION
This tool traces VIRTIO devices input/output statistics. It works in lower layer of VIRTIO base driver, so it could trace all the devices of VIRTIO family. For example, we can't get IO statistics of 9p-fs in a guest virtual machine by iostat command, but we can analyze IO statistics by virtiostat. The outputing result shows In/Out SGs(scatter list operation) to represent positive correlation IOPS, and In/Out BW to represent throughput.

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-T

Include a time column on output (HH:MM:SS).

-D

Show debug infomation of bpf text.

-d DRIVER

Filter for driver name.

-n DEVNAME

Filter for device name.

INTERVAL

Print output every interval seconds.

COUNT

Total count of trace in seconds.

## EXAMPLES
Trace virtio device statistics and print 1 second summaries, 10 times:

\# virtiostat 1 10

Trace virtio block deivces only:

\# virtiostat -d virtio_blk

## OVERHEAD
This traces the kernel virtqueue_add_sgs, virtqueue_add_outbuf, virtqueue_add_inbuf, virtqueue_add_inbuf_ctx functions. The rate of this depends on all the VIRTIO devices IOPS.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

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

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
zhenwei pi

## SEE ALSO
iostat(1), iftop(8), funccount(8)


bcc-wakeuptime

title: bcc-wakeuptime(8)

text:
# bcc-wakeuptime(8)

## NAME
wakeuptime - Summarize sleep to wakeup time by waker kernel stack. Uses Linux eBPF/bcc.

## SYNOPSIS
wakeuptime [-h] [-u] [-p PID] [-v] [-f] [--stack-storage-size STACK_STORAGE_SIZE] [-m MIN_BLOCK_TIME] [-M MAX_BLOCK_TIME] [duration]

## DESCRIPTION
This program shows the kernel stack traces for threads that woke up other blocked threads, along with the process names of the waker and target, along with a sum of the time that the target was blocked: the "blocked time". It works by tracing when threads block and when they were then woken up, and measuring the time delta. This time measurement will be very similar to off-CPU time, however, off-CPU time may include a little extra time spent waiting on a run queue to be scheduled. The stack traces, process names, and time spent blocked is summarized in the kernel using an eBPF map for efficiency.

The output summary will help you identify reasons why threads were blocking by showing who woke them up, along with the time they were blocked. This spans all types of blocking activity: disk I/O, network I/O, locks, page faults, involuntary context switches, etc.

This can be used in conjunction with offcputime, which shows the stack trace of the blocked thread. wakeuptime shows the stack trace of the waker thread.

See http://www.brendangregg.com/FlameGraphs/offcpuflamegraphs.html

This tool only works on Linux 4.6+. It uses the new `BPF_STACK_TRACE` table APIs to generate the in-kernel stack traces.

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-f

Print output in folded stack format.

-u

Only trace user threads (not kernel threads).

-v

Show raw addresses (for non-folded format).

-p PID

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

--stack-storage-size STACK_STORAGE_SIZE

Change the number of unique stack traces that can be stored and displayed.

duration

Duration to trace, in seconds.

-m MIN_BLOCK_TIME

The amount of time in microseconds over which we store traces (default 1)

-M MAX_BLOCK_TIME

The amount of time in microseconds under which we store traces (default U64_MAX)

## EXAMPLES
Trace all thread blocking events, and summarize (in-kernel) by kernel stack trace and total blocked time:

\# wakeuptime

Trace user-mode target threads only:

\# wakeuptime -u

Trace for 5 seconds only:

\# wakeuptime 5

Trace for 5 seconds, and emit output in folded stack format (suitable for flame graphs):

\# wakeuptime -f 5

Trace PID 185 only:

\# wakeuptime -p 185

## OVERHEAD
This summarizes unique stack traces in-kernel for efficiency, allowing it to trace a higher rate of events than methods that post-process in user space. The stack trace and time data is only copied to user space once, when the output is printed. While these techniques greatly lower overhead, scheduler events are still a high frequency event, as they can exceed 1 million events per second, and so caution should still be used. Test before production use.

If the overhead is still a problem, take a look at the min block option. If your aim is to chase down longer blocking events, then this could be increased to filter shorter blocking events, further lowering overhead.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

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

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
offcputime(8), stackcount(8)


bcc-xfsdist

title: bcc-xfsdist(8)

text:
# bcc-xfsdist(8)

## NAME
xfsdist - Summarize XFS operation latency. Uses Linux eBPF/bcc.

## SYNOPSIS
xfsdist [-h] [-T] [-m] [-p PID] [interval] [count]

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

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

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-T

Don't include timestamps on interval output.

-m

Output in milliseconds.

-p PID

Trace this PID only.

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

\# xfsdist

Trace PID 181 only:

\# xfsdist -p 181

Print 1 second summaries, 10 times:

\# xfsdist 1 10

1 second summaries, printed in milliseconds

\# xfsdist -m 1

## FIELDS
msecs

Range of milliseconds for this bucket.

usecs

Range of microseconds for this bucket.

count

Number of operations in this time range.

distribution

ASCII representation of the distribution (the count column).

## OVERHEAD
This adds low-overhead instrumentation to these XFS operations, including reads and writes from the file system cache. Such reads and writes can be very frequent (depending on the workload; eg, 1M/sec), at which point the overhead of this tool may become noticeable. Measure and quantify before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

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

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
xfssnoop(8)


bcc-xfsslower

title: bcc-xfsslower(8)

text:
# bcc-xfsslower(8)

## NAME
xfsslower - Trace slow xfs file operations, with per-event details.

## SYNOPSIS
xfsslower [-h] [-j] [-p PID] [min_ms]

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

WARNING: See the OVERHEAD section.

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

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

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-p PID Trace this PID only.

min_ms

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

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

\# xfsslower

Trace slower than 1 ms:

\# xfsslower 1

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

\# xfsslower -j 1

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

\# xfsslower 0

Trace slower than 1 ms, for PID 181 only:

\# xfsslower -p 181 1

## FIELDS
TIME(s)

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

COMM

Process name.

PID

Process ID.

T

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

OFF_KB

File offset for the I/O, in Kbytes.

BYTES

Size of I/O, in bytes.

LAT(ms)

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

FILENAME

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

ENDTIME_us

Completion timestamp, microseconds (-j only).

OFFSET_b

File offset, bytes (-j only).

LATENCY_us

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

## OVERHEAD
This adds low-overhead instrumentation to these XFS operations, including reads and writes from the file system cache. Such reads and writes can be very frequent (depending on the workload; eg, 1M/sec), at which point the overhead of this tool (even if it prints no "slower" events) can begin to become significant. Measure and quantify before use. If this continues to be a problem, consider switching to a tool that prints in-kernel summaries only.

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

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

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

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

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


bcc-zfsdist

title: bcc-zfsdist(8)

text:
# bcc-zfsdist(8)

## NAME
zfsdist - Summarize ZFS operation latency. Uses Linux eBPF/bcc.

## SYNOPSIS
zfsdist [-h] [-T] [-m] [-p PID] [interval] [count]

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

This uses kernel dynamic tracing of the ZPL interface (ZFS POSIX Layer), and will need updates to match any changes to this interface.

This is intended to work with the ZFS on Linux project:

http://zfsonlinux.org

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-h

Print usage message.

-T

Don't include timestamps on interval output.

-m

Output in milliseconds.

-p PID

Trace this PID only.

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

\# zfsdist

Trace PID 181 only:

\# zfsdist -p 181

Print 1 second summaries, 10 times:

\# zfsdist 1 10

1 second summaries, printed in milliseconds

\# zfsdist -m 1

## FIELDS
msecs

Range of milliseconds for this bucket.

usecs

Range of microseconds for this bucket.

count

Number of operations in this time range.

distribution

ASCII representation of the distribution (the count column).

## OVERHEAD
This adds low-overhead instrumentation to these ZFS operations, including reads and writes from the file system cache. Such reads and writes can be very frequent (depending on the workload; eg, 1M/sec), at which point the overhead of this tool may become noticeable. Measure and quantify before use.

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

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

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
zfssnoop(8)


bcc-zfsslower

title: bcc-zfsslower(8)

text:
# bcc-zfsslower(8)

## NAME
zfsslower - Trace slow zfs file operations, with per-event details.

## SYNOPSIS
zfsslower [-h] [-j] [-p PID] [min_ms]

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

WARNING: See the OVERHEAD section.

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

This uses kernel dynamic tracing of the ZPL interface (ZFS POSIX Layer), and will need updates to match any changes to this interface.

This is intended to work with the ZFS on Linux project:

http://zfsonlinux.org

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

## REQUIREMENTS
CONFIG_BPF and bcc.

## OPTIONS
-p PID Trace this PID only.

min_ms

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

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

\# zfsslower

Trace slower than 1 ms:

\# zfsslower 1

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

\# zfsslower -j 1

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

\# zfsslower 0

Trace slower than 1 ms, for PID 181 only:

\# zfsslower -p 181 1

## FIELDS
TIME(s)

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

COMM

Process name.

PID

Process ID.

T

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

OFF_KB

File offset for the I/O, in Kbytes.

BYTES

Size of I/O, in bytes.

LAT(ms)

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

FILENAME

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

ENDTIME_us

Completion timestamp, microseconds (-j only).

OFFSET_b

File offset, bytes (-j only).

LATENCY_us

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

## OVERHEAD
This adds low-overhead instrumentation to these ZFS operations, including reads and writes from the file system cache. Such reads and writes can be very frequent (depending on the workload; eg, 1M/sec), at which point the overhead of this tool (even if it prints no "slower" events) can begin to become significant. Measure and quantify before use. If this continues to be a problem, consider switching to a tool that prints in-kernel summaries only.

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

## SOURCE
This is from bcc.

https://github.com/iovisor/bcc

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

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

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


title: bgpq3(8)

text:
# bgpq3(8)

## NAME
bgpq3 — bgp filtering automation for cisco and juniper routers

## SYNOPSIS
bgpq3

[-h host] [-S sources] [-EP] [-f asn | -G asn] [-346AbDdJjX] [-r len] [-R len] [-m max] [-W len] OBJECTS [...]

## DESCRIPTION
The bgpq3 utility used to generate Cisco and Juniper prefix-lists, extended access-lists, policy-statement terms and as-path lists based on RADB data.

The options are as follows:

-3

assume that your device is asn32-safe.

-4

generate IPv4 prefix/access-lists (default).

-6

generate IPv6 prefix/access-lists (IPv4 by default).

-A

try to aggregate prefix-lists as much as possible (not all output formats supported).

-b

generate output in BIRD format (default: Cisco).

-d

enable some debugging output.

-D

use asdot notation for Cisco as-path access-lists.

-E

generate extended access-list (Cisco) or policy-statement term using route-filters (Juniper).

-f number

generate input as-path access-list.

-G number

generate output as-path access-list.

-h host

host running IRRD database (default: whois.radb.net).

-J

generate config for Juniper (default: Cisco).

-j

generate output in JSON format (default: Cisco).

-m len

maximum prefix-length of accepted prefixes (default: 32 for IPv4 and 128 for IPv6).

-M match

extra match conditions for Juniper route-filters.

-l name

name of generated entry.

-P

generate prefix-list (default, backward compatibility).

-r len

allow more specific routes starting with specified masklen too.

-R len

allow more specific routes up to specified masklen too.

-S sources

use specified sources only (default: RADB,RIPE,APNIC).

-T

disable pipelining.

-W len

generate as-path strings of no more than len items (use 0 for inifinity).

-X

generate config for Cisco IOS XR devices (plain IOS by default).

OBJECTS

means networks (in prefix format), autonomous systems, as-sets and route-sets.

## EXAMPLES
Generating named juniper prefix-filter for AS20597:

```
~>bgpq3 -Jl eltel AS20597
policy-options {
replace:
 prefix-list eltel {
    81.9.0.0/20;
    81.9.32.0/20;
    81.9.96.0/20;
    81.222.128.0/20;
    81.222.192.0/18;
    85.249.8.0/21;
    85.249.224.0/19;
    89.112.0.0/19;
    89.112.4.0/22;
    89.112.32.0/19;
    89.112.64.0/19;
    217.170.64.0/20;
    217.170.80.0/20;
 }
}
```

For Cisco we can use aggregation (-A) flag to make this prefix-filter more compact:

```
~>bgpq3 -Al eltel AS20597
no ip prefix-list eltel
ip prefix-list eltel permit 81.9.0.0/20
ip prefix-list eltel permit 81.9.32.0/20
ip prefix-list eltel permit 81.9.96.0/20
ip prefix-list eltel permit 81.222.128.0/20
ip prefix-list eltel permit 81.222.192.0/18
ip prefix-list eltel permit 85.249.8.0/21
ip prefix-list eltel permit 85.249.224.0/19
ip prefix-list eltel permit 89.112.0.0/18 ge 19 le 19
ip prefix-list eltel permit 89.112.4.0/22
ip prefix-list eltel permit 89.112.64.0/19
ip prefix-list eltel permit 217.170.64.0/19 ge 20 le 20
```

- you see, prefixes 89.112.0.0/19 and 89.112.32.0/19 now aggregated into single entry 89.112.0.0/18 ge 19 le 19.

Well, for Juniper we can generate even more interesting policy-options, using -M <extra match conditions>, -R <len> and hierarchical names:

```
policy-options {
 policy-statement eltel {
  term specifics {
replace:
   from {
    community blackhole;
    route-filter 81.9.0.0/20 prefix-length-range /29-/32;
    route-filter 81.9.32.0/20 prefix-length-range /29-/32;
    route-filter 81.9.96.0/20 prefix-length-range /29-/32;
    route-filter 81.222.128.0/20 prefix-length-range /29-/32;
    route-filter 81.222.192.0/18 prefix-length-range /29-/32;
    route-filter 85.249.8.0/21 prefix-length-range /29-/32;
    route-filter 85.249.224.0/19 prefix-length-range /29-/32;
    route-filter 89.112.0.0/17 prefix-length-range /29-/32;
    route-filter 217.170.64.0/19 prefix-length-range /29-/32;
   }
  }
 }
}
```

generated policy-option term now allows all specifics with prefix-length between /29 and /32 for eltel networks if they match with special community Of course, this version supports IPv6 (-6):

```
~>bgpq3 -6l as-retn-6 AS-RETN6
no ipv6 prefix-list as-retn-6
ipv6 prefix-list as-retn-6 permit 2001:7fb:fe00::/48
ipv6 prefix-list as-retn-6 permit 2001:7fb:fe01::/48
[....]
```

and support for ASN 32 is also here

```
~>bgpq3 -J3f 112 AS-SPACENET
policy-options {
replace:
 as-path-group NN {
  as-path a0 "^112(112)*$";
  as-path a1 "^112(.)*(1898|5539|8495|8763|8878|12136|12931|15909)$";
  as-path a2 "^112(.)*(21358|23456|23600|24151|25152|31529|34127|34906)$";
  as-path a3 "^112(.)*(35052|41720|43628|44450|196611)$";
 }
}
```

see AS196611 in the end of the list ? That's AS3.3 in 'asplain' notation.

For non-ASN32 capable routers you should not use switch -3, and the result will be next:

```
~>bgpq3 -f 112 AS-SPACENET
no ip as-path access-list NN
ip as-path access-list NN permit ^112(_112)*$
ip as-path access-list NN permit ^112(_[0-9]+)*_(1898|5539|8495|8763)$
ip as-path access-list NN permit ^112(_[0-9]+)*_(8878|12136|12931|15909)$
ip as-path access-list NN permit ^112(_[0-9]+)*_(21358|23456|23600|24151)$
ip as-path access-list NN permit ^112(_[0-9]+)*_(25152|31529|34127|34906)$
ip as-path access-list NN permit ^112(_[0-9]+)*_(35052|41720|43628|44450)$
```

AS196611 is no more in the list, however, AS23456 (transition AS) would be added to list if it were not present.

## DIAGNOSTICS
When everything is OK, bgpq3 generates access-list to standard output and exits with status == 0. In case of errors they are printed to stderr and program exits with non-zero status.

## SEE ALSO
http://www.radb.net/ Routing Arbiter project http://tools.ietf.org/html/draft-michaelson-4byte-as-representation-05 for information on 'asdot' and 'asplain' notations. http://www.cisco.com/en/US/docs/ios/12_0s/release/ntes/120SNEWF.html#wp3521658 for information on Cisco implementation of ASN32.

## AUTHOR
Alexandre Snarskii ⟨snar@snar.spb.ru⟩


ddns-confgen

package: bind

title: ddns-confgen(8)

summary: ddns key generation tool

text:
# ddns-confgen(8)

## NAME
ddns-confgen - ddns key generation tool

## SYNOPSIS
ddns-confgen [-a algorithm] [-h] [-k keyname] [-q] [-s name] [-z zone]

## DESCRIPTION
ddns-confgen is an utility that generates keys for use in TSIG signing. The resulting keys can be used, for example, to secure dynamic DNS updates to a zone, or for the rndc command channel.

The key name can specified using -k parameter and defaults to ddns-key. The generated key is accompanied by configuration text and instructions that can be used with nsupdate and named when setting up dynamic DNS, including an example update-policy statement. (This usage is similar to the rndc-confgen command for setting up command-channel security.)

Note that named itself can configure a local DDNS key for use with nsupdate -l; it does this when a zone is configured with update-policy local;. ddns-confgen is only needed when a more elaborate configuration is required: for instance, if nsupdate is to be used from a remote system.

## OPTIONS
-a algorithm

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

-h

This option prints a short summary of options and arguments.

-k keyname

This option specifies the key name of the DDNS authentication key. The default is ddns-key when neither the -s nor -z option is specified; otherwise, the default is ddns-key as a separate label followed by the argument of the option, e.g., ddns-key.example.com. The key name must have the format of a valid domain name, consisting of letters, digits, hyphens, and periods.

-q

This option enables quiet mode, which prints only the key, with no explanatory text or usage examples. This is essentially identical to tsig-keygen.

-s name

This option generates a configuration example to allow dynamic updates of a single hostname. The example named.conf text shows how to set an update policy for the specified name using the "name" nametype. The default key name is ddns-key.name. Note that the "self" nametype cannot be used, since the name to be updated may differ from the key name. This option cannot be used with the -z option.

-z zone

This option generates a configuration example to allow dynamic updates of a zone. The example named.conf text shows how to set an update policy for the specified zone using the "zonesub" nametype, allowing updates to all subdomain names within that zone. This option cannot be used with the -s option.

## SEE ALSO
nsupdate(1), named.conf(5), named(8), BIND 9 Administrator Reference Manual.

## AUTHOR
Internet Systems Consortium

## COPYRIGHT
2024, Internet Systems Consortium


dnssec-cds

title: dnssec-cds(8)

text:
# dnssec-cds(8)

## NAME
dnssec-cds - change DS records for a child zone based on CDS/CDNSKEY

## SYNOPSIS
dnssec-cds [-a alg...] [-c class] [-D] {-d dsset-file} {-f child-file} [-i**[extension]] [-s** start-time] [-T ttl] [-u] [-v level] [-V] {domain}

## DESCRIPTION
The dnssec-cds command changes DS records at a delegation point based on CDS or CDNSKEY records published in the child zone. If both CDS and CDNSKEY records are present in the child zone, the CDS is preferred. This enables a child zone to inform its parent of upcoming changes to its key-signing keys (KSKs); by polling periodically with dnssec-cds, the parent can keep the DS records up-to-date and enable automatic rolling of KSKs.

Two input files are required. The -f child-file option specifies a file containing the child's CDS and/or CDNSKEY records, plus RRSIG and DNSKEY records so that they can be authenticated. The -d path option specifies the location of a file containing the current DS records. For example, this could be a dsset- file generated by dnssec-signzone, or the output of dnssec-dsfromkey, or the output of a previous run of dnssec-cds.

The dnssec-cds command uses special DNSSEC validation logic specified by RFC 7344. It requires that the CDS and/or CDNSKEY records be validly signed by a key represented in the existing DS records. This is typically the pre-existing KSK.

For protection against replay attacks, the signatures on the child records must not be older than they were on a previous run of dnssec-cds. Their age is obtained from the modification time of the dsset- file, or from the -s option.

To protect against breaking the delegation, dnssec-cds ensures that the DNSKEY RRset can be verified by every key algorithm in the new DS RRset, and that the same set of keys are covered by every DS digest type.

By default, replacement DS records are written to the standard output; with the -i option the input file is overwritten in place. The replacement DS records are the same as the existing records, when no change is required. The output can be empty if the CDS/CDNSKEY records specify that the child zone wants to be insecure.

WARNING:

Be careful not to delete the DS records when dnssec-cds fails!

Alternatively, dnssec-cds -u writes an nsupdate script to the standard output. The -u and -i options can be used together to maintain a dsset- file as well as emit an nsupdate script.

## OPTIONS
-a algorithm

This option specifies a digest algorithm to use when converting CDNSKEY records to DS records. This option can be repeated, so that multiple DS records are created for each CDNSKEY record. This option has no effect when using CDS records. The algorithm must be one of SHA-1, SHA-256, or SHA-384. These values are case-insensitive, and the hyphen may be omitted. If no algorithm is specified, the default is SHA-256.

-c class

This option specifies the DNS class of the zones.

-D

This option generates DS records from CDNSKEY records if both CDS and CDNSKEY records are present in the child zone. By default CDS records are preferred.

-d path

This specifies the location of the parent DS records. The path can be the name of a file containing the DS records; if it is a directory, dnssec-cds looks for a dsset- file for the domain inside the directory. To protect against replay attacks, child records are rejected if they were signed earlier than the modification time of the dsset- file. This can be adjusted with the -s option.

-f child-file

This option specifies the file containing the child's CDS and/or CDNSKEY records, plus its DNSKEY records and the covering RRSIG records, so that they can be authenticated. The examples below describe how to generate this file.

-iextension

This option updates the dsset- file in place, instead of writing DS records to the standard output. There must be no space between the -i and the extension. If no extension is provided, the old dsset- is discarded. If an extension is present, a backup of the old dsset- file is kept with the extension appended to its filename.

To protect against replay attacks, the modification time of the dsset- file is set to match the signature inception time of the child records, provided that it is later than the file's current modification time.

-s start-time

This option specifies the date and time after which RRSIG records become acceptable. This can be either an absolute or a relative time. An absolute start time is indicated by a number in YYYYMMDDHHMMSS notation; 20170827133700 denotes 13:37:00 UTC on August 27th, 2017. A time relative to the dsset- file is indicated with -N, which is N seconds before the file modification time. A time relative to the current time is indicated with now+N. If no start-time is specified, the modification time of the dsset- file is used.

-T ttl

This option specifies a TTL to be used for new DS records. If not specified, the default is the TTL of the old DS records. If they had no explicit TTL, the new DS records also have no explicit TTL.

-u

This option writes an nsupdate script to the standard output, instead of printing the new DS reords. The output is empty if no change is needed. Note: The TTL of new records needs to be specified: it can be done in the original dsset- file, with the -T option, or using the nsupdate ttl command.

-V

This option prints version information.

-v level

This option sets the debugging level. Level 1 is intended to be usefully verbose for general users; higher levels are intended for developers.

domain

This indicates the name of the delegation point/child zone apex.

## EXIT STATUS
The dnssec-cds command exits 0 on success, or non-zero if an error occurred.

If successful, the DS records may or may not need to be changed.

## EXAMPLES
Before running dnssec-signzone, ensure that the delegations are up-to-date by running dnssec-cds on every dsset- file.

To fetch the child records required by dnssec-cds, invoke dig as in the script below. It is acceptable if the dig fails, since dnssec-cds performs all the necessary checking.

```
for f in dsset-*
do

    d=${f#dsset-}

    dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |

    dnssec-cds -i -f /dev/stdin -d $f $d
done
```

When the parent zone is automatically signed by named, dnssec-cds can be used with nsupdate to maintain a delegation as follows. The dsset- file allows the script to avoid having to fetch and validate the parent DS records, and it maintains the replay attack protection time.

```
dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
dnssec-cds -u -i -f /dev/stdin -d $f $d |
nsupdate -l
```

## SEE ALSO
dig(1), dnssec-settime(8), dnssec-signzone(8), nsupdate(1), BIND 9 Administrator Reference Manual, RFC 7344.

## AUTHOR
Internet Systems Consortium

## COPYRIGHT
2024, Internet Systems Consortium


dnssec-checkds

title: dnssec-checkds(8)

text:
# dnssec-checkds(8)

## NAME
dnssec-checkds - DNSSEC delegation consistency checking tool

## SYNOPSIS
dnssec-checkds [-ddig path] [-Ddsfromkey path] [-ffile] [-ldomain] [-sfile] {zone}

## DESCRIPTION
dnssec-checkds verifies the correctness of Delegation Signer (DS) resource records for keys in a specified zone.

## OPTIONS
-a algorithm

Specify a digest algorithm to use when converting the zones DNSKEY records to expected DS records. This option can be repeated, so that multiple records are checked for each DNSKEY record. The algorithm must be one of SHA-1, SHA-256, or SHA-384. These values are case insensitive, and the hyphen may be omitted. If no algorithm is specified, the default is SHA-256.

-f file

If a file is specified, then the zone is read from that file to find the DNSKEY records. If not, then the DNSKEY records for the zone are looked up in the DNS.

-s file

Specifies a prepared dsset file, such as would be generated by dnssec-signzone, to use as a source for the DS RRset instead of querying the parent.

-d dig path

Specifies a path to a dig binary. Used for testing.

-D dsfromkey path

Specifies a path to a dnssec-dsfromkey binary. Used for testing.

## SEE ALSO
dnssec-dsfromkey(8), dnssec-keygen(8), dnssec-signzone(8),

## AUTHOR
Internet Systems Consortium

## COPYRIGHT
2024, Internet Systems Consortium


dnssec-coverage

title: dnssec-coverage(8)

text:
# dnssec-coverage(8)

## NAME
dnssec-coverage - checks future DNSKEY coverage for a zone

## SYNOPSIS
dnssec-coverage [-Kdirectory] [-llength] [-ffile] [-dDNSKEY TTL] [-mmax TTL] [-rinterval] [-ccompilezone path] [-k] [-z] [zone...]

## DESCRIPTION
dnssec-coverage verifies that the DNSSEC keys for a given zone or a set of zones have timing metadata set properly to ensure no future lapses in DNSSEC coverage.

If zone is specified, then keys found in the key repository matching that zone are scanned, and an ordered list is generated of the events scheduled for that key (i.e., publication, activation, inactivation, deletion). The list of events is walked in order of occurrence. Warnings are generated if any event is scheduled which could cause the zone to enter a state in which validation failures might occur: for example, if the number of published or active keys for a given algorithm drops to zero, or if a key is deleted from the zone too soon after a new key is rolled, and cached data signed by the prior key has not had time to expire from resolver caches.

If zone is not specified, then all keys in the key repository will be scanned, and all zones for which there are keys will be analyzed. (Note: This method of reporting is only accurate if all the zones that have keys in a given repository share the same TTL parameters.)

## OPTIONS
-K directory

Sets the directory in which keys can be found. Defaults to the current working directory.

-f file

If a file is specified, then the zone is read from that file; the largest TTL and the DNSKEY TTL are determined directly from the zone data, and the -m and -d options do not need to be specified on the command line.

-l duration

The length of time to check for DNSSEC coverage. Key events scheduled further into the future than duration will be ignored, and assumed to be correct. The value of duration can be set in seconds, or in larger units of time by adding a suffix: mi for minutes, h for hours, d for days, w for weeks, mo for months, y for years.

-m maximum TTL

Sets the value to be used as the maximum TTL for the zone or zones being analyzed when determining whether there is a possibility of validation failure. When a zone-signing key is deactivated, there must be enough time for the record in the zone with the longest TTL to have expired from resolver caches before that key can be purged from the DNSKEY RRset. If that condition does not apply, a warning will be generated. The length of the TTL can be set in seconds, or in larger units of time by adding a suffix: mi for minutes, h for hours, d for days, w for weeks, mo for months, y for years.

This option is not necessary if the -f has been used to specify a zone file. If -f has been specified, this option may still be used; it will override the value found in the file.

If this option is not used and the maximum TTL cannot be retrieved from a zone file, a warning is generated and a default value of 1 week is used.

-d DNSKEY TTL

Sets the value to be used as the DNSKEY TTL for the zone or zones being analyzed when determining whether there is a possibility of validation failure. When a key is rolled (that is, replaced with a new key), there must be enough time for the old DNSKEY RRset to have expired from resolver caches before the new key is activated and begins generating signatures. If that condition does not apply, a warning will be generated. The length of the TTL can be set in seconds, or in larger units of time by adding a suffix: mi for minutes, h for hours, d for days, w for weeks, mo for months, y for years.

This option is not necessary if -f has been used to specify a zone file from which the TTL of the DNSKEY RRset can be read, or if a default key TTL was set using ith the -L to dnssec-keygen. If either of those is true, this option may still be used; it will override the values found in the zone file or the key file.

If this option is not used and the key TTL cannot be retrieved from the zone file or the key file, then a warning is generated and a default value of 1 day is used.

-r resign interval

Sets the value to be used as the resign interval for the zone or zones being analyzed when determining whether there is a possibility of validation failure. This value defaults to 22.5 days, which is also the default in named. However, if it has been changed by the sig-validity-interval option in named.conf, then it should also be changed here. The length of the interval can be set in seconds, or in larger units of time by adding a suffix: mi for minutes, h for hours, d for days, w for weeks, mo for months, y for years.

-k

Only check KSK coverage; ignore ZSK events. Cannot be used with -z.

-z

Only check ZSK coverage; ignore KSK events. Cannot be used with -k.

-c compilezone path

Specifies a path to a named-compilezone binary. Used for testing.

## SEE ALSO
dnssec-checkds(8), dnssec-dsfromkey(8), dnssec-keygen(8), dnssec-signzone(8)

## AUTHOR
Internet Systems Consortium

## COPYRIGHT
2024, Internet Systems Consortium


dnssec-dsfromkey

title: dnssec-dsfromkey(8)

summary: DNSSEC DS RR generation tool

text:
# dnssec-dsfromkey(8)

## NAME
dnssec-dsfromkey - DNSSEC DS RR generation tool

## SYNOPSIS
dnssec-dsfromkey [ -1 | -2 | -a alg ] [ -C ] [-T TTL] [-v level] [-K directory] {keyfile}

dnssec-dsfromkey [ -1 | -2 | -a alg ] [ -C ] [-T TTL] [-v level] [-c class] [-A] {-f file} [dnsname]

dnssec-dsfromkey [ -1 | -2 | -a alg ] [ -C ] [-T TTL] [-v level] [-c class] [-K directory] {-s} {dnsname}

dnssec-dsfromkey [ -h | -V ]

## DESCRIPTION
The dnssec-dsfromkey command outputs DS (Delegation Signer) resource records (RRs), or CDS (Child DS) RRs with the -C option.

By default, only KSKs are converted (keys with flags = 257). The -A option includes ZSKs (flags = 256). Revoked keys are never included.

The input keys can be specified in a number of ways:

By default, dnssec-dsfromkey reads a key file named in the format Knnnn.+aaa+iiiii.key, as generated by dnssec-keygen.

With the -f file option, dnssec-dsfromkey reads keys from a zone file or partial zone file (which can contain just the DNSKEY records).

With the -s option, dnssec-dsfromkey reads a keyset- file, as generated by dnssec-keygen -C.

## OPTIONS
-1

This option is an abbreviation for -a SHA1.

-2

This option is an abbreviation for -a SHA-256.

-a algorithm

This option specifies a digest algorithm to use when converting DNSKEY records to DS records. This option can be repeated, so that multiple DS records are created for each DNSKEY record. The algorithm must be one of SHA-1, SHA-256, or SHA-384. These values are case-insensitive, and the hyphen may be omitted. If no algorithm is specified, the default is SHA-256.

-A

This option indicates that ZSKs are to be included when generating DS records. Without this option, only keys which have the KSK flag set are converted to DS records and printed. This option is only useful in -f zone file mode.

-c class

This option specifies the DNS class; the default is IN. This option is only useful in -s keyset or -f zone file mode.

-C

This option generates CDS records rather than DS records.

-f file

This option sets zone file mode, in which the final dnsname argument of dnssec-dsfromkey is the DNS domain name of a zone whose master file can be read from file. If the zone name is the same as file, then it may be omitted. If file is -, then the zone data is read from the standard input. This makes it possible to use the output of the dig command as input, as in:

dig dnskey example.com | dnssec-dsfromkey -f - example.com

-h

This option prints usage information.

-K directory

This option tells BIND 9 to look for key files or keyset- files in directory.

-s

This option enables keyset mode, in which the final dnsname argument from dnssec-dsfromkey is the DNS domain name used to locate a keyset- file.

-T TTL

This option specifies the TTL of the DS records. By default the TTL is omitted.

-v level

This option sets the debugging level.

-V

This option prints version information.

## EXAMPLE
To build the SHA-256 DS RR from the Kexample.com.+003+26160 keyfile, issue the following command:

dnssec-dsfromkey -2 Kexample.com.+003+26160

The command returns something similar to:

example.com. IN DS 26160 5 2 3A1EADA7A74B8D0BA86726B0C227AA85AB8BBD2B2004F41A868A54F0C5EA0B94

## FILES
The keyfile can be designated by the key identification Knnnn.+aaa+iiiii or the full file name Knnnn.+aaa+iiiii.key, as generated by dnssec-keygen.

The keyset file name is built from the directory, the string keyset-, and the dnsname.

## CAVEAT
A keyfile error may return "file not found," even if the file exists.

## SEE ALSO
dnssec-keygen(8), dnssec-signzone(8), BIND 9 Administrator Reference Manual, RFC 3658 (DS RRs), RFC 4509 (SHA-256 for DS RRs), RFC 6605 (SHA-384 for DS RRs), RFC 7344 (CDS and CDNSKEY RRs).

## AUTHOR
Internet Systems Consortium

## COPYRIGHT
2024, Internet Systems Consortium


dnssec-importkey

title: dnssec-importkey(8)

text:
# dnssec-importkey(8)

## NAME
dnssec-importkey - import DNSKEY records from external systems so they can be managed

## SYNOPSIS
dnssec-importkey [-K directory] [-L ttl] [-P date/offset] [-P sync date/offset] [-D date/offset] [-D sync date/offset] [-h] [-v level] [-V] {keyfile}

dnssec-importkey {-f filename} [-K directory] [-L ttl] [-P date/offset] [-P sync date/offset] [-D date/offset] [-D sync date/offset] [-h] [-v level] [-V] [dnsname]

## DESCRIPTION
dnssec-importkey reads a public DNSKEY record and generates a pair of .key/.private files. The DNSKEY record may be read from an existing .key file, in which case a corresponding .private file is generated, or it may be read from any other file or from the standard input, in which case both .key and .private files are generated.

The newly created .private file does not contain private key data, and cannot be used for signing. However, having a .private file makes it possible to set publication (-P) and deletion (-D) times for the key, which means the public key can be added to and removed from the DNSKEY RRset on schedule even if the true private key is stored offline.

## OPTIONS
-f filename

This option indicates the zone file mode. Instead of a public keyfile name, the argument is the DNS domain name of a zone master file, which can be read from filename. If the domain name is the same as filename, then it may be omitted. If filename is set to "-", then the zone data is read from the standard input.

-K directory

This option sets the directory in which the key files are to reside.

-L ttl

This option sets the default TTL to use for this key when it is converted into a DNSKEY RR. This is the TTL used when the key is imported into a zone, unless there was already a DNSKEY RRset in place, in which case the existing TTL takes precedence. Setting the default TTL to 0 or none removes it from the key.

-h

This option emits a usage message and exits.

-v level

This option sets the debugging level.

-V

This option prints version information.

## TIMING OPTIONS
Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the argument begins with a + or -, it is interpreted as an offset from the present time. For convenience, if such an offset is followed by one of the suffixes y, mo, w, d, h, or mi, then the offset is computed in years (defined as 365 24-hour days, ignoring leap years), months (defined as 30 24-hour days), weeks, days, hours, or minutes, respectively. Without a suffix, the offset is computed in seconds. To explicitly prevent a date from being set, use none or never.

-P date/offset

This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used to sign it.

-P sync date/offset

This option sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone.

-D date/offset

This option sets the date on which the key is to be deleted. After that date, the key is no longer included in the zone. (However, it may remain in the key repository.)

-D sync date/offset

This option sets the date on which the CDS and CDNSKEY records that match this key are to be deleted.

## FILES
A keyfile can be designed by the key identification Knnnn.+aaa+iiiii or the full file name Knnnn.+aaa+iiiii.key, as generated by dnssec-keygen.

## SEE ALSO
dnssec-keygen(8), dnssec-signzone(8), BIND 9 Administrator Reference Manual, RFC 5011.

## AUTHOR
Internet Systems Consortium

## COPYRIGHT
2024, Internet Systems Consortium


dnssec-keyfromlabel

title: dnssec-keyfromlabel(8)

summary: DNSSEC key generation tool

text:
# dnssec-keyfromlabel(8)

## NAME
dnssec-keyfromlabel - DNSSEC key generation tool

## SYNOPSIS
dnssec-keyfromlabel {-l label} [-3] [-a algorithm] [-A date/offset] [-c class] [-D date/offset] [-D sync date/offset] [-E engine] [-f flag] [-G] [-I date/offset] [-i interval] [-k] [-K directory] [-L ttl] [-n nametype] [-P date/offset] [-P sync date/offset] [-p protocol] [-R date/offset] [-S key] [-t type] [-v level] [-V] [-y] {name}

## DESCRIPTION
dnssec-keyfromlabel generates a pair of key files that reference a key object stored in a cryptographic hardware service module (HSM). The private key file can be used for DNSSEC signing of zone data as if it were a conventional signing key created by dnssec-keygen, but the key material is stored within the HSM and the actual signing takes place there.

The name of the key is specified on the command line. This must match the name of the zone for which the key is being generated.

## OPTIONS
-a algorithm

This option selects the cryptographic algorithm. The value of algorithm must be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. These values are case-insensitive. In some cases, abbreviations are supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for ECDSAP384SHA384. If RSASHA1 is specified along with the -3 option, then NSEC3RSASHA1 is used instead.

This option is mandatory except when using the -S option, which copies the algorithm from the predecessory key.

Changed in version 9.12.0: The default value RSASHA1 for newly generated keys was removed.

-3

This option uses an NSEC3-capable algorithm to generate a DNSSEC key. If this option is used with an algorithm that has both NSEC and NSEC3 versions, then the NSEC3 version is used; for example, dnssec-keygen -3a RSASHA1 specifies the NSEC3RSASHA1 algorithm.

-E engine

This option specifies the cryptographic hardware to use. When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually pkcs11). When BIND is built with native PKCS#11 cryptography (--enable-native-pkcs11), it defaults to the path of the PKCS#11 provider library specified via --with-pkcs11.

-l label

This option specifies the label for a key pair in the crypto hardware. When BIND 9 is built with OpenSSL-based PKCS#11 support, the label is an arbitrary string that identifies a particular key. It may be preceded by an optional OpenSSL engine name, followed by a colon, as in pkcs11:keylabel.

When BIND 9 is built with native PKCS#11 support, the label is a PKCS#11 URI string in the format pkcs11:keyword\ =value[;\ keyword\ =value;...]. Keywords include token, which identifies the HSM; object, which identifies the key; and pin-source, which identifies a file from which the HSM's PIN code can be obtained. The label is stored in the on-disk private file.

If the label contains a pin-source field, tools using the generated key files are able to use the HSM for signing and other operations without any need for an operator to manually enter a PIN. Note: Making the HSM's PIN accessible in this manner may reduce the security advantage of using an HSM; use caution with this feature.

-n nametype

This option specifies the owner type of the key. The value of nametype must either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with a host (KEY)), USER (for a key associated with a user (KEY)), or OTHER (DNSKEY). These values are case-insensitive.

-C

This option enables compatibility mode, which generates an old-style key, without any metadata. By default, dnssec-keyfromlabel includes the key's creation date in the metadata stored with the private key; other dates may be set there as well, including publication date, activation date, etc. Keys that include this data may be incompatible with older versions of BIND; the -C option suppresses them.

-c class

This option indicates that the DNS record containing the key should have the specified class. If not specified, class IN is used.

-f flag

This option sets the specified flag in the flag field of the KEY/DNSKEY record. The only recognized flags are KSK (Key-Signing Key) and REVOKE.

-G

This option generates a key, but does not publish it or sign with it. This option is incompatible with -P and -A.

-h

This option prints a short summary of the options and arguments to dnssec-keyfromlabel.

-K directory

This option sets the directory in which the key files are to be written.

-k

This option generates KEY records rather than DNSKEY records.

-L ttl

This option sets the default TTL to use for this key when it is converted into a DNSKEY RR. This is the TTL used when the key is imported into a zone, unless there was already a DNSKEY RRset in place, in which case the existing TTL would take precedence. Setting the default TTL to 0 or none removes it.

-p protocol

This option sets the protocol value for the key. The protocol is a number between 0 and 255. The default is 3 (DNSSEC). Other possible values for this argument are listed in RFC 2535 and its successors.

-S key

This option generates a key as an explicit successor to an existing key. The name, algorithm, size, and type of the key are set to match the predecessor. The activation date of the new key is set to the inactivation date of the existing one. The publication date is set to the activation date minus the prepublication interval, which defaults to 30 days.

-t type

This option indicates the type of the key. type must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default is AUTHCONF. AUTH refers to the ability to authenticate data, and CONF to the ability to encrypt data.

-v level

This option sets the debugging level.

-V

This option prints version information.

-y

This option allows DNSSEC key files to be generated even if the key ID would collide with that of an existing key, in the event of either key being revoked. (This is only safe to enable if RFC 5011 trust anchor maintenance is not used with either of the keys involved.)

## TIMING OPTIONS
Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the argument begins with a + or -, it is interpreted as an offset from the present time. For convenience, if such an offset is followed by one of the suffixes y, mo, w, d, h, or mi, then the offset is computed in years (defined as 365 24-hour days, ignoring leap years), months (defined as 30 24-hour days), weeks, days, hours, or minutes, respectively. Without a suffix, the offset is computed in seconds. To explicitly prevent a date from being set, use none or never.

-P date/offset

This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used to sign it. If not set, and if the -G option has not been used, the default is the current date.

-P sync date/offset

This option sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone.

-A date/offset

This option sets the date on which the key is to be activated. After that date, the key is included in the zone and used to sign it. If not set, and if the -G option has not been used, the default is the current date.

-R date/offset

This option sets the date on which the key is to be revoked. After that date, the key is flagged as revoked. It is included in the zone and is used to sign it.

-I date/offset

This option sets the date on which the key is to be retired. After that date, the key is still included in the zone, but it is not used to sign it.

-D date/offset

This option sets the date on which the key is to be deleted. After that date, the key is no longer included in the zone. (However, it may remain in the key repository.)

-D sync date/offset

This option sets the date on which the CDS and CDNSKEY records that match this key are to be deleted.

-i interval

This option sets the prepublication interval for a key. If set, then the publication and activation dates must be separated by at least this much time. If the activation date is specified but the publication date is not, the publication date defaults to this much time before the activation date; conversely, if the publication date is specified but not the activation date, activation is set to this much time after publication. If the key is being created as an explicit successor to another key, then the default prepublication interval is 30 days; otherwise it is zero.

As with date offsets, if the argument is followed by one of the suffixes y, mo, w, d, h, or mi, the interval is measured in years, months, weeks, days, hours, or minutes, respectively. Without a suffix, the interval is measured in seconds.

## GENERATED KEY FILES
When dnssec-keyfromlabel completes successfully, it prints a string of the form Knnnn.+aaa+iiiii to the standard output. This is an identification string for the key files it has generated.

- nnnn is the key name.

- aaa is the numeric representation of the algorithm.

- iiiii is the key identifier (or footprint).

dnssec-keyfromlabel creates two files, with names based on the printed string. Knnnn.+aaa+iiiii.key contains the public key, and Knnnn.+aaa+iiiii.private contains the private key.

The .key file contains a DNS KEY record that can be inserted into a zone file (directly or with an $INCLUDE statement).

The .private file contains algorithm-specific fields. For obvious security reasons, this file does not have general read permission.

## SEE ALSO
dnssec-keygen(8), dnssec-signzone(8), BIND 9 Administrator Reference Manual, RFC 4034, RFC 7512.

## AUTHOR
Internet Systems Consortium

## COPYRIGHT
2024, Internet Systems Consortium


dnssec-keygen

title: dnssec-keygen(8)

summary: DNSSEC key generation tool

text:
# dnssec-keygen(8)

## NAME
dnssec-keygen - DNSSEC key generation tool

## SYNOPSIS
dnssec-keygen [-3] [-A date/offset] [-a algorithm] [-b keysize] [-C] [-c class] [-D date/offset] [-d bits] [-D sync date/offset] [-E engine] [-f flag] [-G] [-g generator] [-h] [-I date/offset] [-i interval] [-K directory] [-k policy] [-L ttl] [-l file] [-n nametype] [-P date/offset] [-P sync date/offset] [-p protocol] [-q] [-R date/offset] [-S key] [-s strength] [-T rrtype] [-t type] [-V] [-v level] {name}

## DESCRIPTION
dnssec-keygen generates keys for DNSSEC (Secure DNS), as defined in RFC 2535 and RFC 4034. It can also generate keys for use with TSIG (Transaction Signatures) as defined in RFC 2845, or TKEY (Transaction Key) as defined in RFC 2930.

The name of the key is specified on the command line. For DNSSEC keys, this must match the name of the zone for which the key is being generated.

The dnssec-keymgr command acts as a wrapper around dnssec-keygen, generating and updating keys as needed to enforce defined security policies such as key rollover scheduling. Using dnssec-keymgr may be preferable to direct use of dnssec-keygen.

## OPTIONS
-3

This option uses an NSEC3-capable algorithm to generate a DNSSEC key. If this option is used with an algorithm that has both NSEC and NSEC3 versions, then the NSEC3 version is selected; for example, dnssec-keygen -3 -a RSASHA1 specifies the NSEC3RSASHA1 algorithm.

-a algorithm

This option selects the cryptographic algorithm. For DNSSEC keys, the value of algorithm must be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. For TKEY, the value must be DH (Diffie-Hellman); specifying this value automatically sets the -T KEY option as well. These values are case-insensitive. In some cases, abbreviations are supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for ECDSAP384SHA384. If RSASHA1 is specified along with the -3 option, NSEC3RSASHA1 is used instead.

This parameter must be specified except when using the -S option, which copies the algorithm from the predecessor key.

In prior releases, HMAC algorithms could be generated for use as TSIG keys, but that feature was removed in BIND 9.13.0. Use tsig-keygen to generate TSIG keys.

-b keysize

This option specifies the number of bits in the key. The choice of key size depends on the algorithm used: RSA keys must be between 1024 and 4096 bits; Diffie-Hellman keys must be between 128 and 4096 bits. Elliptic curve algorithms do not need this parameter. If the key size is not specified, some algorithms have pre-defined defaults. For example, RSA keys for use as DNSSEC zone-signing keys have a default size of 1024 bits; RSA keys for use as key-signing keys (KSKs, generated with -f KSK) default to 2048 bits.

-C

This option enables compatibility mode, which generates an old-style key, without any timing metadata. By default, dnssec-keygen includes the key's creation date in the metadata stored with the private key; other dates may be set there as well, including publication date, activation date, etc. Keys that include this data may be incompatible with older versions of BIND; the -C option suppresses them.

-c class

This option indicates that the DNS record containing the key should have the specified class. If not specified, class IN is used.

-d bits

This option specifies the key size in bits. For the algorithms RSASHA1, NSEC3RSASA1, RSASHA256, and RSASHA512 the key size must be between 1024 and 4096 bits; DH size is between 128 and 4096 bits. This option is ignored for algorithms ECDSAP256SHA256, ECDSAP384SHA384, ED25519, and ED448.

-E engine

This option specifies the cryptographic hardware to use, when applicable. When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually pkcs11). When BIND is built with native PKCS#11 cryptography (--enable-native-pkcs11), it defaults to the path of the PKCS#11 provider library specified via --with-pkcs11.

-f flag

This option sets the specified flag in the flag field of the KEY/DNSKEY record. The only recognized flags are KSK (Key-Signing Key) and REVOKE.

-G

This option generates a key, but does not publish it or sign with it. This option is incompatible with -P and -A.

-g generator

This option indicates the generator to use if generating a Diffie-Hellman key. Allowed values are 2 and 5. If no generator is specified, a known prime from RFC 2539 is used if possible; otherwise the default is 2.

-h

This option prints a short summary of the options and arguments to dnssec-keygen.

-K directory

This option sets the directory in which the key files are to be written.

-k policy

This option creates keys for a specific dnssec-policy. If a policy uses multiple keys, dnssec-keygen generates multiple keys. This also creates a ".state" file to keep track of the key state. This option creates keys according to the dnssec-policy configuration, hence it cannot be used at the same time as many of the other options that dnssec-keygen provides.

-L ttl

This option sets the default TTL to use for this key when it is converted into a DNSKEY RR. This is the TTL used when the key is imported into a zone, unless there was already a DNSKEY RRset in place, in which case the existing TTL takes precedence. If this value is not set and there is no existing DNSKEY RRset, the TTL defaults to the SOA TTL. Setting the default TTL to 0 or none is the same as leaving it unset.

-l file

This option provides a configuration file that contains a dnssec-policy statement (matching the policy set with -k).

-n nametype

This option specifies the owner type of the key. The value of nametype must either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with a host (KEY)), USER (for a key associated with a user (KEY)), or OTHER (DNSKEY). These values are case-insensitive. The default is ZONE for DNSKEY generation.

-p protocol

This option sets the protocol value for the generated key, for use with -T KEY. The protocol is a number between 0 and 255. The default is 3 (DNSSEC). Other possible values for this argument are listed in RFC 2535 and its successors.

-q

This option sets quiet mode, which suppresses unnecessary output, including progress indication. Without this option, when dnssec-keygen is run interactively to generate an RSA or DSA key pair, it prints a string of symbols to stderr indicating the progress of the key generation. A . indicates that a random number has been found which passed an initial sieve test; + means a number has passed a single round of the Miller-Rabin primality test; and a space ( ) means that the number has passed all the tests and is a satisfactory key.

-S key

This option creates a new key which is an explicit successor to an existing key. The name, algorithm, size, and type of the key are set to match the existing key. The activation date of the new key is set to the inactivation date of the existing one. The publication date is set to the activation date minus the prepublication interval, which defaults to 30 days.

-s strength

This option specifies the strength value of the key. The strength is a number between 0 and 15, and currently has no defined purpose in DNSSEC.

-T rrtype

This option specifies the resource record type to use for the key. rrtype must be either DNSKEY or KEY. The default is DNSKEY when using a DNSSEC algorithm, but it can be overridden to KEY for use with SIG(0).

-t type

This option indicates the type of the key for use with -T KEY. type must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default is AUTHCONF. AUTH refers to the ability to authenticate data, and CONF to the ability to encrypt data.

-V

This option prints version information.

-v level

This option sets the debugging level.

## TIMING OPTIONS
Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the argument begins with a + or -, it is interpreted as an offset from the present time. For convenience, if such an offset is followed by one of the suffixes y, mo, w, d, h, or mi, then the offset is computed in years (defined as 365 24-hour days, ignoring leap years), months (defined as 30 24-hour days), weeks, days, hours, or minutes, respectively. Without a suffix, the offset is computed in seconds. To explicitly prevent a date from being set, use none or never.

-P date/offset

This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used to sign it. If not set, and if the -G option has not been used, the default is the current date.

-P sync date/offset

This option sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone.

-A date/offset

This option sets the date on which the key is to be activated. After that date, the key is included in the zone and used to sign it. If not set, and if the -G option has not been used, the default is the current date. If set, and -P is not set, the publication date is set to the activation date minus the prepublication interval.

-R date/offset

This option sets the date on which the key is to be revoked. After that date, the key is flagged as revoked. It is included in the zone and is used to sign it.

-I date/offset

This option sets the date on which the key is to be retired. After that date, the key is still included in the zone, but it is not used to sign it.

-D date/offset

This option sets the date on which the key is to be deleted. After that date, the key is no longer included in the zone. (However, it may remain in the key repository.)

-D sync date/offset

This option sets the date on which the CDS and CDNSKEY records that match this key are to be deleted.

-i interval

This option sets the prepublication interval for a key. If set, then the publication and activation dates must be separated by at least this much time. If the activation date is specified but the publication date is not, the publication date defaults to this much time before the activation date; conversely, if the publication date is specified but not the activation date, activation is set to this much time after publication. If the key is being created as an explicit successor to another key, then the default prepublication interval is 30 days; otherwise it is zero.

As with date offsets, if the argument is followed by one of the suffixes y, mo, w, d, h, or mi, the interval is measured in years, months, weeks, days, hours, or minutes, respectively. Without a suffix, the interval is measured in seconds.

## GENERATED KEYS
When dnssec-keygen completes successfully, it prints a string of the form Knnnn.+aaa+iiiii to the standard output. This is an identification string for the key it has generated.

- nnnn is the key name.

- aaa is the numeric representation of the algorithm.

- iiiii is the key identifier (or footprint).

dnssec-keygen creates two files, with names based on the printed string. Knnnn.+aaa+iiiii.key contains the public key, and Knnnn.+aaa+iiiii.private contains the private key.

The .key file contains a DNSKEY or KEY record. When a zone is being signed by named or dnssec-signzone -S, DNSKEY records are included automatically. In other cases, the .key file can be inserted into a zone file manually or with an $INCLUDE statement.

The .private file contains algorithm-specific fields. For obvious security reasons, this file does not have general read permission.

## EXAMPLE
To generate an ECDSAP256SHA256 zone-signing key for the zone example.com, issue the command:

dnssec-keygen -a ECDSAP256SHA256 example.com

The command prints a string of the form:

Kexample.com.+013+26160

In this example, dnssec-keygen creates the files Kexample.com.+013+26160.key and Kexample.com.+013+26160.private.

To generate a matching key-signing key, issue the command:

dnssec-keygen -a ECDSAP256SHA256 -f KSK example.com

## SEE ALSO
dnssec-signzone(8), BIND 9 Administrator Reference Manual, RFC 2539, RFC 2845, RFC 4034.

## AUTHOR
Internet Systems Consortium

## COPYRIGHT
2024, Internet Systems Consortium


dnssec-keymgr

title: dnssec-keymgr(8)

text:
# dnssec-keymgr(8)

## NAME
dnssec-keymgr - ensure correct DNSKEY coverage based on a defined policy

## SYNOPSIS
dnssec-keymgr [-Kdirectory] [-cfile] [-f] [-k] [-q] [-v] [-z] [-gpath] [-spath] [zone...]

## DESCRIPTION
dnssec-keymgr is a high level Python wrapper to facilitate the key rollover process for zones handled by BIND. It uses the BIND commands for manipulating DNSSEC key metadata: dnssec-keygen and dnssec-settime.

DNSSEC policy can be read from a configuration file (default /etc/dnssec-policy.conf), from which the key parameters, publication and rollover schedule, and desired coverage duration for any given zone can be determined. This file may be used to define individual DNSSEC policies on a per-zone basis, or to set a "default" policy used for all zones.

When dnssec-keymgr runs, it examines the DNSSEC keys for one or more zones, comparing their timing metadata against the policies for those zones. If key settings do not conform to the DNSSEC policy (for example, because the policy has been changed), they are automatically corrected.

A zone policy can specify a duration for which we want to ensure the key correctness (coverage). It can also specify a rollover period (roll-period). If policy indicates that a key should roll over before the coverage period ends, then a successor key will automatically be created and added to the end of the key series.

If zones are specified on the command line, dnssec-keymgr will examine only those zones. If a specified zone does not already have keys in place, then keys will be generated for it according to policy.

If zones are not specified on the command line, then dnssec-keymgr will search the key directory (either the current working directory or the directory set by the -K option), and check the keys for all the zones represented in the directory.

Key times that are in the past will not be updated unless the -f is used (see below). Key inactivation and deletion times that are less than five minutes in the future will be delayed by five minutes.

It is expected that this tool will be run automatically and unattended (for example, by cron).

## OPTIONS
-c file

If -c is specified, then the DNSSEC policy is read from file. (If not specified, then the policy is read from /etc/dnssec-policy.conf; if that file doesnt exist, a built-in global default policy is used.)

-f

Force: allow updating of key events even if they are already in the past. This is not recommended for use with zones in which keys have already been published. However, if a set of keys has been generated all of which have publication and activation dates in the past, but the keys have not been published in a zone as yet, then this option can be used to clean them up and turn them into a proper series of keys with appropriate rollover intervals.

-g keygen-path

Specifies a path to a dnssec-keygen binary. Used for testing. See also the -s option.

-h

Print the dnssec-keymgr help summary and exit.

-K directory

Sets the directory in which keys can be found. Defaults to the current working directory.

-k

Only apply policies to KSK keys. See also the -z option.

-q

Quiet: suppress printing of dnssec-keygen and dnssec-settime.

-s settime-path

Specifies a path to a dnssec-settime binary. Used for testing. See also the -g option.

-v

Print the dnssec-keymgr version and exit.

-z

Only apply policies to ZSK keys. See also the -k option.

## POLICY CONFIGURATION
The dnssec-policy.conf file can specify three kinds of policies:

· Policy classes (policyname{ ... };) can be inherited by zone policies or other policy classes; these can be used to create sets of different security profiles. For example, a policy class normal might specify 1024-bit key sizes, but a class extra might specify 2048 bits instead; extra would be used for zones that had unusually high security needs.

· Algorithm policies: (algorithm-policyalgorithm{ ... }; ) override default per-algorithm settings. For example, by default, RSASHA256 keys use 2048-bit key sizes for both KSK and ZSK. This can be modified using algorithm-policy, and the new key sizes would then be used for any key of type RSASHA256. · Zone policies: (zonename{ ... }; ) set policy for a single zone by name. A zone policy can inherit a policy class by including a policy option. Zone names beginning with digits (i.e., 0-9) must be quoted. If a zone does not have its own policy then the "default" policy applies.

Options that can be specified in policies:

algorithm name;

The key algorithm. If no policy is defined, the default is RSASHA256.

coverage duration;

The length of time to ensure that keys will be correct; no action will be taken to create new keys to be activated after this time. This can be represented as a number of seconds, or as a duration using human-readable units (examples: "1y" or "6 months"). A default value for this option can be set in algorithm policies as well as in policy classes or zone policies. If no policy is configured, the default is six months.

directory path;

Specifies the directory in which keys should be stored.

key-size keytype size;

Specifies the number of bits to use in creating keys. The keytype is either "zsk" or "ksk". A default value for this option can be set in algorithm policies as well as in policy classes or zone policies. If no policy is configured, the default is 2048 bits for RSA keys.

keyttl duration;

The key TTL. If no policy is defined, the default is one hour.

post-publish keytype duration;

How long after inactivation a key should be deleted from the zone. Note: If roll-period is not set, this value is ignored. The keytype is either "zsk" or "ksk". A default duration for this option can be set in algorithm policies as well as in policy classes or zone policies. The default is one month.

pre-publish keytype duration;

How long before activation a key should be published. Note: If roll-period is not set, this value is ignored. The keytype is either "zsk" or "ksk". A default duration for this option can be set in algorithm policies as well as in policy classes or zone policies. The default is one month.

roll-period keytype duration;

How frequently keys should be rolled over. The keytype is either "zsk" or "ksk". A default duration for this option can be set in algorithm policies as well as in policy classes or zone policies. If no policy is configured, the default is one year for ZSKs. KSKs do not roll over by default.

standby keytype number;

Not yet implemented.

## REMAINING WORK
· Enable scheduling of KSK rollovers using the -P sync and -D sync options to dnssec-keygen and dnssec-settime. Check the parent zone (as in dnssec-checkds) to determine when its safe for the key to roll.

· Allow configuration of standby keys and use of the REVOKE bit, for keys that use RFC 5011 semantics.

## SEE ALSO
dnssec-coverage(8), dnssec-keygen(8), dnssec-settime(8), dnssec-checkds(8)

## AUTHOR
Internet Systems Consortium

## COPYRIGHT
2024, Internet Systems Consortium


dnssec-revoke

title: dnssec-revoke(8)

summary: set the REVOKED bit on a DNSSEC key

text:
# dnssec-revoke(8)

## NAME
dnssec-revoke - set the REVOKED bit on a DNSSEC key

## SYNOPSIS
dnssec-revoke [-hr] [-v level] [-V] [-K directory] [-E engine] [-f] [-R] {keyfile}

## DESCRIPTION
dnssec-revoke reads a DNSSEC key file, sets the REVOKED bit on the key as defined in RFC 5011, and creates a new pair of key files containing the now-revoked key.

## OPTIONS
-h

This option emits a usage message and exits.

-K directory

This option sets the directory in which the key files are to reside.

-r

This option indicates to remove the original keyset files after writing the new keyset files.

-v level

This option sets the debugging level.

-V

This option prints version information.

-E engine

This option specifies the cryptographic hardware to use, when applicable. When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually pkcs11). When BIND is built with native PKCS#11 cryptography (--enable-native-pkcs11), it defaults to the path of the PKCS#11 provider library specified via --with-pkcs11.

-f

This option indicates a forced overwrite and causes dnssec-revoke to write the new key pair, even if a file already exists matching the algorithm and key ID of the revoked key.

-R

This option prints the key tag of the key with the REVOKE bit set, but does not revoke the key.

## SEE ALSO
dnssec-keygen(8), BIND 9 Administrator Reference Manual, RFC 5011.

## AUTHOR
Internet Systems Consortium

## COPYRIGHT
2024, Internet Systems Consortium


dnssec-settime

title: dnssec-settime(8)

text:
# dnssec-settime(8)

## NAME
dnssec-settime - set the key timing metadata for a DNSSEC key

## SYNOPSIS
dnssec-settime [-f] [-K directory] [-L ttl] [-P date/offset] [-P ds date/offset] [-P sync date/offset] [-A date/offset] [-R date/offset] [-I date/offset] [-D date/offset] [-D ds date/offset] [-D sync date/offset] [-S key] [-i interval] [-h] [-V] [-v level] [-E engine] {keyfile} [-s] [-g state] [-d state date/offset] [-k state date/offset] [-r state date/offset] [-z state date/offset]

## DESCRIPTION
dnssec-settime reads a DNSSEC private key file and sets the key timing metadata as specified by the -P, -A, -R, -I, and -D options. The metadata can then be used by dnssec-signzone or other signing software to determine when a key is to be published, whether it should be used for signing a zone, etc.

If none of these options is set on the command line, dnssec-settime simply prints the key timing metadata already stored in the key.

When key metadata fields are changed, both files of a key pair (Knnnn.+aaa+iiiii.key and Knnnn.+aaa+iiiii.private) are regenerated.

Metadata fields are stored in the private file. A human-readable description of the metadata is also placed in comments in the key file. The private file's permissions are always set to be inaccessible to anyone other than the owner (mode 0600).

When working with state files, it is possible to update the timing metadata in those files as well with -s. With this option, it is also possible to update key states with -d (DS), -k (DNSKEY), -r (RRSIG of KSK), or -z (RRSIG of ZSK). Allowed states are HIDDEN, RUMOURED, OMNIPRESENT, and UNRETENTIVE.

The goal state of the key can also be set with -g. This should be either HIDDEN or OMNIPRESENT, representing whether the key should be removed from the zone or published.

It is NOT RECOMMENDED to manipulate state files manually, except for testing purposes.

## OPTIONS
-f

This option forces an update of an old-format key with no metadata fields. Without this option, dnssec-settime fails when attempting to update a legacy key. With this option, the key is recreated in the new format, but with the original key data retained. The key's creation date is set to the present time. If no other values are specified, then the key's publication and activation dates are also set to the present time.

-K directory

This option sets the directory in which the key files are to reside.

-L ttl

This option sets the default TTL to use for this key when it is converted into a DNSKEY RR. This is the TTL used when the key is imported into a zone, unless there was already a DNSKEY RRset in place, in which case the existing TTL takes precedence. If this value is not set and there is no existing DNSKEY RRset, the TTL defaults to the SOA TTL. Setting the default TTL to 0 or none removes it from the key.

-h

This option emits a usage message and exits.

-V

This option prints version information.

-v level

This option sets the debugging level.

-E engine

This option specifies the cryptographic hardware to use, when applicable. When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually pkcs11). When BIND is built with native PKCS#11 cryptography (--enable-native-pkcs11), it defaults to the path of the PKCS#11 provider library specified via --with-pkcs11.

## TIMING OPTIONS
Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the argument begins with a + or -, it is interpreted as an offset from the present time. For convenience, if such an offset is followed by one of the suffixes y, mo, w, d, h, or mi, then the offset is computed in years (defined as 365 24-hour days, ignoring leap years), months (defined as 30 24-hour days), weeks, days, hours, or minutes, respectively. Without a suffix, the offset is computed in seconds. To explicitly prevent a date from being set, use none or never.

-P date/offset

This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used to sign it.

-P ds date/offset

This option Sets the date on which DS records that match this key have been seen in the parent zone.

-P sync date/offset

This option sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone.

-A date/offset

This option sets the date on which the key is to be activated. After that date, the key is included in the zone and used to sign it.

-R date/offset

This option sets the date on which the key is to be revoked. After that date, the key is flagged as revoked. It is included in the zone and is used to sign it.

-I date/offset

This option sets the date on which the key is to be retired. After that date, the key is still included in the zone, but it is not used to sign it.

-D date/offset

This option sets the date on which the key is to be deleted. After that date, the key is no longer included in the zone. (However, it may remain in the key repository.)

-D ds date/offset

This option sets the date on which the DS records that match this key have been seen removed from the parent zone.

-D sync date/offset

This option sets the date on which the CDS and CDNSKEY records that match this key are to be deleted.

-S predecessor key

This option selects a key for which the key being modified is an explicit successor. The name, algorithm, size, and type of the predecessor key must exactly match those of the key being modified. The activation date of the successor key is set to the inactivation date of the predecessor. The publication date is set to the activation date minus the prepublication interval, which defaults to 30 days.

-i interval

This option sets the prepublication interval for a key. If set, then the publication and activation dates must be separated by at least this much time. If the activation date is specified but the publication date is not, the publication date defaults to this much time before the activation date; conversely, if the publication date is specified but not the activation date, activation is set to this much time after publication. If the key is being created as an explicit successor to another key, then the default prepublication interval is 30 days; otherwise it is zero.

As with date offsets, if the argument is followed by one of the suffixes y, mo, w, d, h, or mi, the interval is measured in years, months, weeks, days, hours, or minutes, respectively. Without a suffix, the interval is measured in seconds.

## KEY STATE OPTIONS
To test dnssec-policy it may be necessary to construct keys with artificial state information; these options are used by the testing framework for that purpose, but should never be used in production.

Known key states are HIDDEN, RUMOURED, OMNIPRESENT, and UNRETENTIVE.

-s

This option indicates that when setting key timing data, the state file should also be updated.

-g state

This option sets the goal state for this key. Must be HIDDEN or OMNIPRESENT.

-d state date/offset

This option sets the DS state for this key as of the specified date, offset from the current date.

-k state date/offset

This option sets the DNSKEY state for this key as of the specified date, offset from the current date.

-r state date/offset

This option sets the RRSIG (KSK) state for this key as of the specified date, offset from the current date.

-z state date/offset

This option sets the RRSIG (ZSK) state for this key as of the specified date, offset from the current date.

## PRINTING OPTIONS
dnssec-settime can also be used to print the timing metadata associated with a key.

-u

This option indicates that times should be printed in Unix epoch format.

-p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all

This option prints a specific metadata value or set of metadata values. The -p option may be followed by one or more of the following letters or strings to indicate which value or values to print: C for the creation date, P for the publication date, Pds` for the DS publication date, ``Psync for the CDS and CDNSKEY publication date, A for the activation date, R for the revocation date, I for the inactivation date, D for the deletion date, Dds for the DS deletion date, and Dsync for the CDS and CDNSKEY deletion date. To print all of the metadata, use all.

## SEE ALSO
dnssec-keygen(8), dnssec-signzone(8), BIND 9 Administrator Reference Manual, RFC 5011.

## AUTHOR
Internet Systems Consortium

## COPYRIGHT
2024, Internet Systems Consortium