kdc.conf

title: kdc.conf(5)

summary: Kerberos V5 KDC configuration file

text:
# kdc.conf(5)

## NAME
kdc.conf - Kerberos V5 KDC configuration file

The kdc.conf file supplements krb5.conf for programs which are typically only used on a KDC, such as the krb5kdc and kadmind daemons and the kdb5_util program. Relations documented here may also be specified in krb5.conf; for the KDC programs mentioned, krb5.conf and kdc.conf will be merged into a single configuration profile.

Normally, the kdc.conf file is found in the KDC state directory, /var/lib/kerberos/krb5kdc. You can override the default location by setting the environment variable KRB5_KDC_PROFILE.

Please note that you need to restart the KDC daemon for any configuration changes to take effect.

## STRUCTURE
The kdc.conf file is set up in the same format as the krb5.conf file.

## SECTIONS
The kdc.conf file may contain the following sections:

[kdcdefaults]

Default values for KDC behavior

[realms]

Realm-specific database configuration and settings

[dbdefaults]

Default database settings

[dbmodules]

Per-database settings

[logging]

Controls how Kerberos daemons perform logging

### [kdcdefaults]
Some relations in the [kdcdefaults] section specify default values for realm variables, to be used if the [realms] subsection does not contain a relation for the tag. See the [realms] section for the definitions of these relations.

- host_based_services

- kdc_listen

- kdc_ports

- kdc_tcp_listen

- kdc_tcp_ports

- no_host_referral

- restrict_anonymous_to_tgt

The following [kdcdefaults] variables have no per-realm equivalent:

kdc_max_dgram_reply_size

Specifies the maximum packet size that can be sent over UDP. The default value is 4096 bytes.

kdc_tcp_listen_backlog

(Integer.) Set the size of the listen queue length for the KDC daemon. The value may be limited by OS settings. The default value is 5.

spake_preauth_kdc_challenge

(String.) Specifies the group for a SPAKE optimistic challenge. See the spake_preauth_groups variable in [libdefaults] for possible values. The default is not to issue an optimistic challenge. (New in release 1.17.)

### [realms]
Each tag in the [realms] section is the name of a Kerberos realm. The value of the tag is a subsection where the relations define KDC parameters for that particular realm. The following example shows how to define one parameter for the ATHENA.MIT.EDU realm:

```
[realms]

    ATHENA.MIT.EDU = {

        max_renewable_life = 7d 0h 0m 0s

    }
```

The following tags may be specified in a [realms] subsection:

acl_file

(String.) Location of the access control list file that kadmind uses to determine which principals are allowed which permissions on the Kerberos database. To operate without an ACL file, set this relation to the empty string with acl_file = "". The default value is /var/lib/kerberos/krb5kdc/kadm5.acl. For more information on Kerberos ACL file see kadm5.acl.

database_module

(String.) This relation indicates the name of the configuration section under [dbmodules] for database-specific parameters used by the loadable database library. The default value is the realm name. If this configuration section does not exist, default values will be used for all database parameters.

database_name

(String, deprecated.) This relation specifies the location of the Kerberos database for this realm, if the DB2 module is being used and the [dbmodules] configuration section does not specify a database name. The default value is /var/lib/kerberos/krb5kdc/principal.

default_principal_expiration

(Absolute time string.) Specifies the default expiration date of principals created in this realm. The default value is 0, which means no expiration date.

default_principal_flags

(Flag string.) Specifies the default attributes of principals created in this realm. The format for this string is a comma-separated list of flags, with '+' before each flag that should be enabled and '-' before each flag that should be disabled. The postdateable, forwardable, tgt-based, renewable, proxiable, dup-skey, allow-tickets, and service flags default to enabled. There are a number of possible flags:

allow-tickets

Enabling this flag means that the KDC will issue tickets for this principal. Disabling this flag essentially deactivates the principal within this realm.

dup-skey

Enabling this flag allows the KDC to issue user-to-user service tickets for this principal.

forwardable

Enabling this flag allows the principal to obtain forwardable tickets.

hwauth

If this flag is enabled, then the principal is required to preauthenticate using a hardware device before receiving any tickets.

no-auth-data-required

Enabling this flag prevents PAC or AD-SIGNEDPATH data from being added to service tickets for the principal.

ok-as-delegate

If this flag is enabled, it hints the client that credentials can and should be delegated when authenticating to the service.

ok-to-auth-as-delegate

Enabling this flag allows the principal to use S4USelf tickets.

postdateable

Enabling this flag allows the principal to obtain postdateable tickets.

preauth

If this flag is enabled on a client principal, then that principal is required to preauthenticate to the KDC before receiving any tickets. On a service principal, enabling this flag means that service tickets for this principal will only be issued to clients with a TGT that has the preauthenticated bit set.

proxiable

Enabling this flag allows the principal to obtain proxy tickets.

pwchange

Enabling this flag forces a password change for this principal.

pwservice

If this flag is enabled, it marks this principal as a password change service. This should only be used in special cases, for example, if a user's password has expired, then the user has to get tickets for that principal without going through the normal password authentication in order to be able to change the password.

renewable

Enabling this flag allows the principal to obtain renewable tickets.

service

Enabling this flag allows the the KDC to issue service tickets for this principal. In release 1.17 and later, user-to-user service tickets are still allowed if the dup-skey flag is set.

tgt-based

Enabling this flag allows a principal to obtain tickets based on a ticket-granting-ticket, rather than repeating the authentication process that was used to obtain the TGT.

dict_file

(String.) Location of the dictionary file containing strings that are not allowed as passwords. The file should contain one string per line, with no additional whitespace. If none is specified or if there is no policy assigned to the principal, no dictionary checks of passwords will be performed.

disable_pac

(Boolean value.) If true, the KDC will not issue PACs for this realm, and S4U2Self and S4U2Proxy operations will be disabled. The default is false, which will permit the KDC to issue PACs. New in release 1.20.

encrypted_challenge_indicator

(String.) Specifies the authentication indicator value that the KDC asserts into tickets obtained using FAST encrypted challenge pre-authentication. New in 1.16.

host_based_services

(Whitespace- or comma-separated list.) Lists services which will get host-based referral processing even if the server principal is not marked as host-based by the client.

iprop_enable

(Boolean value.) Specifies whether incremental database propagation is enabled. The default value is false.

iprop_ulogsize

(Integer.) Specifies the maximum number of log entries to be retained for incremental propagation. The default value is 1000. Prior to release 1.11, the maximum value was 2500. New in release 1.19.

iprop_master_ulogsize

The name for iprop_ulogsize prior to release 1.19. Its value is used as a fallback if iprop_ulogsize is not specified.

iprop_replica_poll

(Delta time string.) Specifies how often the replica KDC polls for new updates from the primary. The default value is 2m (that is, two minutes). New in release 1.17.

iprop_slave_poll

(Delta time string.) The name for iprop_replica_poll prior to release 1.17. Its value is used as a fallback if iprop_replica_poll is not specified.

iprop_listen

(Whitespace- or comma-separated list.) Specifies the iprop RPC listening addresses and/or ports for the kadmind daemon. Each entry may be an interface address, a port number, or an address and port number separated by a colon. If the address contains colons, enclose it in square brackets. If no address is specified, the wildcard address is used. If kadmind fails to bind to any of the specified addresses, it will fail to start. The default (when iprop_enable is true) is to bind to the wildcard address at the port specified in iprop_port. New in release 1.15.

iprop_port

(Port number.) Specifies the port number to be used for incremental propagation. When iprop_enable is true, this relation is required in the replica KDC configuration file, and this relation or iprop_listen is required in the primary configuration file, as there is no default port number. Port numbers specified in iprop_listen entries will override this port number for the kadmind daemon.

iprop_resync_timeout

(Delta time string.) Specifies the amount of time to wait for a full propagation to complete. This is optional in configuration files, and is used by replica KDCs only. The default value is 5 minutes (5m). New in release 1.11.

iprop_logfile

(File name.) Specifies where the update log file for the realm database is to be stored. The default is to use the database_name entry from the realms section of the krb5 config file, with .ulog appended. (NOTE: If database_name isn't specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the [dbmodules] section, then the hard-coded default for database_name is used. Determination of the iprop_logfile default value will not use values from the [dbmodules] section.)

kadmind_listen

(Whitespace- or comma-separated list.) Specifies the kadmin RPC listening addresses and/or ports for the kadmind daemon. Each entry may be an interface address, a port number, an address and port number separated by a colon, or a UNIX domain socket pathname. If the address contains colons, enclose it in square brackets. If no address is specified, the wildcard address is used. To disable listening for kadmin RPC connections, set this relation to the empty string with kadmind_listen = "". If kadmind fails to bind to any of the specified addresses, it will fail to start. The default is to bind to the wildcard address at the port specified in kadmind_port, or the standard kadmin port (749). New in release 1.15.

kadmind_port

(Port number.) Specifies the port on which the kadmind daemon is to listen for this realm. Port numbers specified in kadmind_listen entries will override this port number. The assigned port for kadmind is 749, which is used by default.

key_stash_file

(String.) Specifies the location where the master key has been stored (via kdb5_util stash). The default is /var/lib/kerberos/krb5kdc/.k5.REALM, where REALM is the Kerberos realm.

kdc_listen

(Whitespace- or comma-separated list.) Specifies the listening addresses and/or ports for the krb5kdc daemon. Each entry may be an interface address, a port number, an address and port number separated by a colon, or a UNIX domain socket pathname. If the address contains colons, enclose it in square brackets. If no address is specified, the wildcard address is used. If no port is specified, the standard port (88) is used. To disable listening on UDP, set this relation to the empty string with kdc_listen = "". If the KDC daemon fails to bind to any of the specified addresses, it will fail to start. The default is to bind to the wildcard address on the standard port. New in release 1.15.

kdc_ports

(Whitespace- or comma-separated list, deprecated.) Prior to release 1.15, this relation lists the ports for the krb5kdc daemon to listen on for UDP requests. In release 1.15 and later, it has the same meaning as kdc_listen if that relation is not defined.

kdc_tcp_listen

(Whitespace- or comma-separated list.) Specifies the TCP listening addresses and/or ports for the krb5kdc daemon. The syntax is identical to that of kdc_listen. To disable listening on TCP, set this relation to the empty string with kdc_tcp_listen = "". The default is to bind to the same addresses and ports as for UDP. New in release 1.15.

kdc_tcp_ports

(Whitespace- or comma-separated list, deprecated.) Prior to release 1.15, this relation lists the ports for the krb5kdc daemon to listen on for UDP requests. In release 1.15 and later, it has the same meaning as kdc_tcp_listen if that relation is not defined.

kpasswd_listen

(Comma-separated list.) Specifies the kpasswd listening addresses and/or ports for the kadmind daemon. Each entry may be an interface address, a port number, an address and port number separated by a colon, or a UNIX domain socket pathname. If the address contains colons, enclose it in square brackets. If no address is specified, the wildcard address is used. To disable listening for kpasswd requests, set this relation to the empty string with kpasswd_listen = "". If kadmind fails to bind to any of the specified addresses, it will fail to start. The default is to bind to the wildcard address at the port specified in kpasswd_port, or the standard kpasswd port (464). New in release 1.15.

kpasswd_port

(Port number.) Specifies the port on which the kadmind daemon is to listen for password change requests for this realm. Port numbers specified in kpasswd_listen entries will override this port number. The assigned port for password change requests is 464, which is used by default.

master_key_name

(String.) Specifies the name of the principal associated with the master key. The default is K/M.

master_key_type

(Key type string.) Specifies the master key's key type. The default value for this is aes256-cts-hmac-sha1-96. For a list of all possible values, see Encryption types.

max_life

(Time duration string.) Specifies the maximum time period for which a ticket may be valid in this realm. The default value is 24 hours.

max_renewable_life

(Time duration string.) Specifies the maximum time period during which a valid ticket may be renewed in this realm. The default value is 0.

no_host_referral

(Whitespace- or comma-separated list.) Lists services to block from getting host-based referral processing, even if the client marks the server principal as host-based or the service is also listed in host_based_services. no_host_referral = * will disable referral processing altogether.

reject_bad_transit

(Boolean value.) If set to true, the KDC will check the list of transited realms for cross-realm tickets against the transit path computed from the realm names and the capaths section of its krb5.conf file; if the path in the ticket to be issued contains any realms not in the computed path, the ticket will not be issued, and an error will be returned to the client instead. If this value is set to false, such tickets will be issued anyways, and it will be left up to the application server to validate the realm transit path. If the disable-transited-check flag is set in the incoming request, this check is not performed at all. Having the reject_bad_transit option will cause such ticket requests to be rejected always.

This transit path checking and config file option currently apply only to TGS requests.

The default value is true.

restrict_anonymous_to_tgt

(Boolean value.) If set to true, the KDC will reject ticket requests from anonymous principals to service principals other than the realm's ticket-granting service. This option allows anonymous PKINIT to be enabled for use as FAST armor tickets without allowing anonymous authentication to services. The default value is false. New in release 1.9.

spake_preauth_indicator

(String.) Specifies an authentication indicator value that the KDC asserts into tickets obtained using SPAKE pre-authentication. The default is not to add any indicators. This option may be specified multiple times. New in release 1.17.

supported_enctypes

(List of key:salt strings.) Specifies the default key/salt combinations of principals for this realm. Any principals created through kadmin will have keys of these types. The default value for this tag is aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal. For lists of possible values, see Keysalt lists.

### [dbdefaults]
The [dbdefaults] section specifies default values for some database parameters, to be used if the [dbmodules] subsection does not contain a relation for the tag. See the [dbmodules] section for the definitions of these relations.

- ldap_kerberos_container_dn

- ldap_kdc_dn

- ldap_kdc_sasl_authcid

- ldap_kdc_sasl_authzid

- ldap_kdc_sasl_mech

- ldap_kdc_sasl_realm

- ldap_kadmind_dn

- ldap_kadmind_sasl_authcid

- ldap_kadmind_sasl_authzid

- ldap_kadmind_sasl_mech

- ldap_kadmind_sasl_realm

- ldap_service_password_file

- ldap_conns_per_server

### [dbmodules]
The [dbmodules] section contains parameters used by the KDC database library and database modules. Each tag in the [dbmodules] section is the name of a Kerberos realm or a section name specified by a realm's database_module parameter. The following example shows how to define one database parameter for the ATHENA.MIT.EDU realm:

```
[dbmodules]

    ATHENA.MIT.EDU = {

        disable_last_success = true

    }
```

The following tags may be specified in a [dbmodules] subsection:

database_name

This DB2-specific tag indicates the location of the database in the filesystem. The default is /var/lib/kerberos/krb5kdc/principal.

db_library

This tag indicates the name of the loadable database module. The value should be db2 for the DB2 module, klmdb for the LMDB module, or kldap for the LDAP module.

disable_last_success

If set to true, suppresses KDC updates to the "Last successful authentication" field of principal entries requiring preauthentication. Setting this flag may improve performance. (Principal entries which do not require preauthentication never update the "Last successful authentication" field.). First introduced in release 1.9.

disable_lockout

If set to true, suppresses KDC updates to the "Last failed authentication" and "Failed password attempts" fields of principal entries requiring preauthentication. Setting this flag may improve performance, but also disables account lockout. First introduced in release 1.9.

ldap_conns_per_server

This LDAP-specific tag indicates the number of connections to be maintained per LDAP server.

ldap_kdc_dn and ldap_kadmind_dn

These LDAP-specific tags indicate the default DN for binding to the LDAP server. The krb5kdc daemon uses ldap_kdc_dn, while the kadmind daemon and other administrative programs use ldap_kadmind_dn. The kadmind DN must have the rights to read and write the Kerberos data in the LDAP database. The KDC DN must have the same rights, unless disable_lockout and disable_last_success are true, in which case it only needs to have rights to read the Kerberos data. These tags are ignored if a SASL mechanism is set with ldap_kdc_sasl_mech or ldap_kadmind_sasl_mech.

ldap_kdc_sasl_mech and ldap_kadmind_sasl_mech

These LDAP-specific tags specify the SASL mechanism (such as EXTERNAL) to use when binding to the LDAP server. New in release 1.13.

ldap_kdc_sasl_authcid and ldap_kadmind_sasl_authcid

These LDAP-specific tags specify the SASL authentication identity to use when binding to the LDAP server. Not all SASL mechanisms require an authentication identity. If the SASL mechanism requires a secret (such as the password for DIGEST-MD5), these tags also determine the name within the ldap_service_password_file where the secret is stashed. New in release 1.13.

ldap_kdc_sasl_authzid and ldap_kadmind_sasl_authzid

These LDAP-specific tags specify the SASL authorization identity to use when binding to the LDAP server. In most circumstances they do not need to be specified. New in release 1.13.

ldap_kdc_sasl_realm and ldap_kadmind_sasl_realm

These LDAP-specific tags specify the SASL realm to use when binding to the LDAP server. In most circumstances they do not need to be set. New in release 1.13.

ldap_kerberos_container_dn

This LDAP-specific tag indicates the DN of the container object where the realm objects will be located.

ldap_servers

This LDAP-specific tag indicates the list of LDAP servers that the Kerberos servers can connect to. The list of LDAP servers is whitespace-separated. The LDAP server is specified by a LDAP URI. It is recommended to use ldapi: or ldaps: URLs to connect to the LDAP server.

ldap_service_password_file

This LDAP-specific tag indicates the file containing the stashed passwords (created by kdb5_ldap_util stashsrvpw) for the ldap_kdc_dn and ldap_kadmind_dn objects, or for the ldap_kdc_sasl_authcid or ldap_kadmind_sasl_authcid names for SASL authentication. This file must be kept secure.

mapsize

This LMDB-specific tag indicates the maximum size of the two database environments in megabytes. The default value is 128. Increase this value to address "Environment mapsize limit reached" errors. New in release 1.17.

max_readers

This LMDB-specific tag indicates the maximum number of concurrent reading processes for the databases. The default value is 128. New in release 1.17.

nosync

This LMDB-specific tag can be set to improve the throughput of kadmind and other administrative agents, at the expense of durability (recent database changes may not survive a power outage or other sudden reboot). It does not affect the throughput of the KDC. The default value is false. New in release 1.17.

unlockiter

If set to true, this DB2-specific tag causes iteration operations to release the database lock while processing each principal. Setting this flag to true can prevent extended blocking of KDC or kadmin operations when dumps of large databases are in progress. First introduced in release 1.13.

The following tag may be specified directly in the [dbmodules] section to control where database modules are loaded from:

db_module_dir

This tag controls where the plugin system looks for database modules. The value should be an absolute path.

### [logging]
The [logging] section indicates how krb5kdc and kadmind perform logging. It may contain the following relations:

admin_server

Specifies how kadmind performs logging.

kdc

Specifies how krb5kdc performs logging.

default

Specifies how either daemon performs logging in the absence of relations specific to the daemon.

debug

(Boolean value.) Specifies whether debugging messages are included in log outputs other than SYSLOG. Debugging messages are always included in the system log output because syslog performs its own priority filtering. The default value is false. New in release 1.15.

Logging specifications may have the following forms:

FILE=filename or FILE:filename

This value causes the daemon's logging messages to go to the filename. If the = form is used, the file is overwritten. If the : form is used, the file is appended to.

STDERR

This value causes the daemon's logging messages to go to its standard error stream.

CONSOLE

This value causes the daemon's logging messages to go to the console, if the system supports it.

DEVICE=<devicename>

This causes the daemon's logging messages to go to the specified device.

SYSLOG[:severity[:facility]]

This causes the daemon's logging messages to go to the system log. For backward compatibility, a severity argument may be specified, and must be specified in order to specify a facility. This argument will be ignored.

The facility argument specifies the facility under which the messages are logged. This may be any of the following facilities supported by the syslog(3) call minus the LOG_ prefix: KERN, USER, MAIL, DAEMON, AUTH, LPR, NEWS, UUCP, CRON, and LOCAL0 through LOCAL7. If no facility is specified, the default is AUTH.

In the following example, the logging messages from the KDC will go to the console and to the system log under the facility LOG_DAEMON, and the logging messages from the administrative server will be appended to the file /var/adm/kadmin.log and sent to the device /dev/tty04.

```
[logging]

    kdc = CONSOLE

    kdc = SYSLOG:INFO:DAEMON

    admin_server = FILE:/var/adm/kadmin.log

    admin_server = DEVICE=/dev/tty04
```

If no logging specification is given, the default is to use syslog. To disable logging entirely, specify default = DEVICE=/dev/null.

### [otp]
Each subsection of [otp] is the name of an OTP token type. The tags within the subsection define the configuration required to forward a One Time Password request to a RADIUS server.

For each token type, the following tags may be specified:

server

This is the server to send the RADIUS request to. It can be a hostname with optional port, an ip address with optional port, or a Unix domain socket address. The default is /var/lib/kerberos/krb5kdc/<name>.socket.

secret

This tag indicates a filename (which may be relative to /var/lib/kerberos/krb5kdc) containing the secret used to encrypt the RADIUS packets. The secret should appear in the first line of the file by itself; leading and trailing whitespace on the line will be removed. If the value of server is a Unix domain socket address, this tag is optional, and an empty secret will be used if it is not specified. Otherwise, this tag is required.

timeout

An integer which specifies the time in seconds during which the KDC should attempt to contact the RADIUS server. This tag is the total time across all retries and should be less than the time which an OTP value remains valid for. The default is 5 seconds.

retries

This tag specifies the number of retries to make to the RADIUS server. The default is 3 retries (4 tries).

strip_realm

If this tag is true, the principal without the realm will be passed to the RADIUS server. Otherwise, the realm will be included. The default value is true.

indicator

This tag specifies an authentication indicator to be included in the ticket if this token type is used to authenticate. This option may be specified multiple times. (New in release 1.14.)

In the following example, requests are sent to a remote server via UDP:

```
[otp]

    MyRemoteTokenType = {

        server = radius.mydomain.com:1812

        secret = SEmfiajf42$

        timeout = 15

        retries = 5

        strip_realm = true

    }
```

An implicit default token type named DEFAULT is defined for when the per-principal configuration does not specify a token type. Its configuration is shown below. You may override this token type to something applicable for your situation:

```
[otp]

    DEFAULT = {

        strip_realm = false

    }
```

## PKINIT OPTIONS
NOTE:

The following are pkinit-specific options. These values may be specified in [kdcdefaults] as global defaults, or within a realm-specific subsection of [realms]. Also note that a realm-specific value over-rides, does not add to, a generic [kdcdefaults] specification. The search order is:

1.

realm-specific subsection of [realms]:

```
[realms]

    EXAMPLE.COM = {

        pkinit_anchors = FILE:/usr/local/example.com.crt

    }
```

2.

generic value in the [kdcdefaults] section:

```
[kdcdefaults]

    pkinit_anchors = DIR:/usr/local/generic_trusted_cas/
```

For information about the syntax of some of these options, see Specifying PKINIT identity information in krb5.conf.

pkinit_anchors

Specifies the location of trusted anchor (root) certificates which the KDC trusts to sign client certificates. This option is required if pkinit is to be supported by the KDC. This option may be specified multiple times.

pkinit_dh_min_bits

Specifies the minimum strength of Diffie-Hellman group the KDC is willing to accept for key exchange. Valid values in order of increasing strength are 1024, 2048, P-256, 4096, P-384, and P-521. The default is 2048. (P-256, P-384, and P-521 are new in release 1.22.)

pkinit_allow_upn

Specifies that the KDC is willing to accept client certificates with the Microsoft UserPrincipalName (UPN) Subject Alternative Name (SAN). This means the KDC accepts the binding of the UPN in the certificate to the Kerberos principal name. The default value is false. Without this option, the KDC will only accept certificates with the id-pkinit-san as defined in RFC 4556. There is currently no option to disable SAN checking in the KDC.

pkinit_eku_checking

This option specifies what Extended Key Usage (EKU) values the KDC is willing to accept in client certificates. The values recognized in the kdc.conf file are:

kpClientAuth

This is the default value and specifies that client certificates must have the id-pkinit-KPClientAuth EKU as defined in RFC 4556.

scLogin

If scLogin is specified, client certificates with the Microsoft Smart Card Login EKU (id-ms-kp-sc-logon) will be accepted.

none

If none is specified, then client certificates will not be checked to verify they have an acceptable EKU. The use of this option is not recommended.

pkinit_identity

Specifies the location of the KDC's X.509 identity information. This option is required if pkinit is to be supported by the KDC.

pkinit_indicator

Specifies an authentication indicator to include in the ticket if pkinit is used to authenticate. This option may be specified multiple times. (New in release 1.14.)

pkinit_pool

Specifies the location of intermediate certificates which may be used by the KDC to complete the trust chain between a client's certificate and a trusted anchor. This option may be specified multiple times.

pkinit_revoke

Specifies the location of Certificate Revocation List (CRL) information to be used by the KDC when verifying the validity of client certificates. This option may be specified multiple times.

pkinit_require_crl_checking

The default certificate verification process will always check the available revocation information to see if a certificate has been revoked. If a match is found for the certificate in a CRL, verification fails. If the certificate being verified is not listed in a CRL, or there is no CRL present for its issuing CA, and pkinit_require_crl_checking is false, then verification succeeds. However, if pkinit_require_crl_checking is true and there is no CRL information available for the issuing CA, then verification fails.

pkinit_require_crl_checking should be set to true if the policy is such that up-to-date CRLs must be present for every CA.

pkinit_require_freshness

Specifies whether to require clients to include a freshness token in PKINIT requests. The default value is false. (New in release 1.17.)

## ENCRYPTION TYPES
Any tag in the configuration files which requires a list of encryption types can be set to some combination of the following strings. Encryption types marked as "weak" and "deprecated" are available for compatibility but not recommended for use.

des3-cbc-raw

Triple DES cbc mode raw (weak)

des3-cbc-sha1 des3-hmac-sha1 des3-cbc-sha1-kd

Triple DES cbc mode with HMAC/sha1 (deprecated)

aes256-cts-hmac-sha1-96 aes256-cts aes256-sha1

AES-256 CTS mode with 96-bit SHA-1 HMAC

aes128-cts-hmac-sha1-96 aes128-cts aes128-sha1

AES-128 CTS mode with 96-bit SHA-1 HMAC

aes256-cts-hmac-sha384-192 aes256-sha2

AES-256 CTS mode with 192-bit SHA-384 HMAC

aes128-cts-hmac-sha256-128 aes128-sha2

AES-128 CTS mode with 128-bit SHA-256 HMAC

arcfour-hmac rc4-hmac arcfour-hmac-md5

RC4 with HMAC/MD5 (deprecated)

arcfour-hmac-exp rc4-hmac-exp arcfour-hmac-md5-exp

Exportable RC4 with HMAC/MD5 (weak)

camellia256-cts-cmac camellia256-cts

Camellia-256 CTS mode with CMAC

camellia128-cts-cmac camellia128-cts

Camellia-128 CTS mode with CMAC

des3

The triple DES family: des3-cbc-sha1

aes

The AES family: aes256-cts-hmac-sha1-96, aes128-cts-hmac-sha1-96, aes256-cts-hmac-sha384-192, and aes128-cts-hmac-sha256-128

rc4

The RC4 family: arcfour-hmac

camellia

The Camellia family: camellia256-cts-cmac and camellia128-cts-cmac

The string DEFAULT can be used to refer to the default set of types for the variable in question. Types or families can be removed from the current list by prefixing them with a minus sign ("-"). Types or families can be prefixed with a plus sign ("+") for symmetry; it has the same meaning as just listing the type or family. For example, "DEFAULT -rc4" would be the default set of encryption types with RC4 types removed, and "des3 DEFAULT" would be the default set of encryption types with triple DES types moved to the front.

While aes128-cts and aes256-cts are supported for all Kerberos operations, they are not supported by very old versions of our GSSAPI implementation (krb5-1.3.1 and earlier). Services running versions of krb5 without AES support must not be given keys of these encryption types in the KDC database.

The aes128-sha2 and aes256-sha2 encryption types are new in release 1.15. Services running versions of krb5 without support for these newer encryption types must not be given keys of these encryption types in the KDC database.

## KEYSALT LISTS
Kerberos keys for users are usually derived from passwords. Kerberos commands and configuration parameters that affect generation of keys take lists of enctype-salttype ("keysalt") pairs, known as keysalt lists. Each keysalt pair is an enctype name followed by a salttype name, in the format enc:salt. Individual keysalt list members are separated by comma (",") characters or space characters. For example:

```
kadmin -e aes256-cts:normal,aes128-cts:normal
```

would start up kadmin so that by default it would generate password-derived keys for the aes256-cts and aes128-cts encryption types, using a normal salt.

To ensure that people who happen to pick the same password do not have the same key, Kerberos 5 incorporates more information into the key using something called a salt. The supported salt types are as follows:

normal

default for Kerberos Version 5

norealm

same as the default, without using realm information

onlyrealm

uses only realm information as the salt

special

generate a random salt

## SAMPLE KDC.CONF FILE
Here's an example of a kdc.conf file:

```
[kdcdefaults]

    kdc_listen = 88

    kdc_tcp_listen = 88
[realms]

    ATHENA.MIT.EDU = {

        kadmind_port = 749

        max_life = 12h 0m 0s

        max_renewable_life = 7d 0h 0m 0s

        master_key_type = aes256-cts-hmac-sha1-96

        supported_enctypes = aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal

        database_module = openldap_ldapconf

    }
[logging]

    kdc = FILE:/usr/local/var/krb5kdc/kdc.log

    admin_server = FILE:/usr/local/var/krb5kdc/kadmin.log
[dbdefaults]

    ldap_kerberos_container_dn = cn=krbcontainer,dc=mit,dc=edu
[dbmodules]

    openldap_ldapconf = {

        db_library = kldap

        disable_last_success = true

        ldap_kdc_dn = "cn=krbadmin,dc=mit,dc=edu"

            # this object needs to have read rights on

            # the realm container and principal subtrees

        ldap_kadmind_dn = "cn=krbadmin,dc=mit,dc=edu"

            # this object needs to have read and write rights on

            # the realm container and principal subtrees

        ldap_service_password_file = /etc/kerberos/service.keyfile

        ldap_servers = ldaps://kerberos.mit.edu

        ldap_conns_per_server = 5

    }
```

## FILES
/var/lib/kerberos/krb5kdc/kdc.conf

## SEE ALSO
krb5.conf, krb5kdc, kadm5.acl

## AUTHOR
MIT

## COPYRIGHT
1985-2026, MIT


title: k5identity(5)

text:
# k5identity(5)

## NAME
k5identity - Kerberos V5 client principal selection rules

## DESCRIPTION
The .k5identity file, which resides in a user's home directory, contains a list of rules for selecting a client principals based on the server being accessed. These rules are used to choose a credential cache within the cache collection when possible.

Blank lines and lines beginning with # are ignored. Each line has the form:

principal field=value ...

If the server principal meets all of the field constraints, then principal is chosen as the client principal. The following fields are recognized:

realm

If the realm of the server principal is known, it is matched against value, which may be a pattern using shell wildcards. For host-based server principals, the realm will generally only be known if there is a [domain_realm] section in krb5.conf with a mapping for the hostname.

service

If the server principal is a host-based principal, its service component is matched against value, which may be a pattern using shell wildcards.

host

If the server principal is a host-based principal, its hostname component is converted to lower case and matched against value, which may be a pattern using shell wildcards. If the server principal matches the constraints of multiple lines in the .k5identity file, the principal from the first matching line is used. If no line matches, credentials will be selected some other way, such as the realm heuristic or the current primary cache.

## EXAMPLE
The following example .k5identity file selects the client principal alice@KRBTEST.COM if the server principal is within that realm, the principal alice/root@EXAMPLE.COM if the server host is within a servers subdomain, and the principal alice/mail@EXAMPLE.COM when accessing the IMAP service on mail.example.com:

```
alice@KRBTEST.COM       realm=KRBTEST.COM
alice/root@EXAMPLE.COM  host=*.servers.example.com
alice/mail@EXAMPLE.COM  host=mail.example.com service=imap
```

## SEE ALSO
kerberos(1), krb5.conf

## AUTHOR
MIT

## COPYRIGHT
1985-2026, MIT

branch: sisyphus


title: k5login(5)

summary: Kerberos V5 acl file for host access

text:
# k5login(5)

## NAME
k5login - Kerberos V5 acl file for host access

## DESCRIPTION
The .k5login file, which resides in a user's home directory, contains a list of the Kerberos principals. Anyone with valid tickets for a principal in the file is allowed host access with the UID of the user in whose home directory the file resides. One common use is to place a .k5login file in root's home directory, thereby granting system administrators remote root access to the host via Kerberos.

## EXAMPLES
Suppose the user alice had a .k5login file in her home directory containing just the following line:

```
bob@FOOBAR.ORG
```

This would allow bob to use Kerberos network applications, such as ssh(1), to access alice's account, using bob's Kerberos tickets. In a default configuration (with k5login_authoritative set to true in krb5.conf), this .k5login file would not let alice use those network applications to access her account, since she is not listed! With no .k5login file, or with k5login_authoritative set to false, a default rule would permit the principal alice in the machine's default realm to access the alice account.

Let us further suppose that alice is a system administrator. Alice and the other system administrators would have their principals in root's .k5login file on each host:

```
alice@BLEEP.COM
joeadmin/root@BLEEP.COM
```

This would allow either system administrator to log in to these hosts using their Kerberos tickets instead of having to type the root password. Note that because bob retains the Kerberos tickets for his own principal, bob@FOOBAR.ORG, he would not have any of the privileges that require alice's tickets, such as root access to any of the site's hosts, or the ability to change alice's password.

## SEE ALSO
kerberos(1)

## AUTHOR
MIT

## COPYRIGHT
1985-2026, MIT


kryoptic.conf

package: kryoptic

title: kryoptic.conf(5)

text:
# kryoptic.conf(5)

## NAME
kryoptic.conf - Configuration file for the Kryoptic PKCS#11 module

## SYNOPSIS
/etc/kryoptic/token.conf

${XDG_CONFIG_HOME}/kryoptic/token.conf

${HOME}/.config/kryoptic/token.conf

## DESCRIPTION
The kryoptic.conf file is a TOML-formatted configuration file used by the Kryoptic PKCS#11 module. It allows configuring global settings and provisioning multiple independent slots, each representing an idealized hardware slot where a cryptographic token can be utilized.

Kryoptic searches for the configuration file in the following order:

1.

The path specified by the KRYOPTIC_CONF environment variable.

2.

${XDG_CONFIG_HOME}/kryoptic/token.conf (if the XDG_CONFIG_HOME environment variable is set).

3.

${HOME}/.config/kryoptic/token.conf (if the HOME environment variable is set).

4.

A system-wide directory, typically /usr/local/etc/kryoptic/token.conf or /etc/kryoptic/token.conf depending on build-time configuration.

## GLOBAL OPTIONS
[ec_point_encoding]

Allows setting a global default encoding for CKA_EC_POINT attributes to maintain compatibility with applications that expect specific encodings (e.g., DER encoded EC Points).

encoding = string

Valid values are “Bytes” or “Der”. The default is “Bytes”. This can be overridden at runtime by setting the KRYOPTIC_EC_POINT_ENCODING environment variable.

## SLOT CONFIGURATION
Tokens are configured by defining one or more [[slots]] sections. In Kryoptic, slots provide independent tokens with their own separate storage. Slots cannot share the same storage.

[[slots]]

slot = integer

(Required) The slot number (a 32-bit unsigned integer) identifying this slot.

description = string

(Optional) A customized description for the slot. If not provided, a default description is returned to PKCS#11 applications.

manufacturer = string

(Optional) A customized manufacturer string. If not provided, a default string is used.

dbtype = string

(Required) The storage implementation (token type) for the slot (e.g., “sqlite”, “nssdb”).

dbargs = string

(Required) Storage-specific configuration options. For example, the path to a SQLite database file (e.g., "/var/lib/kryoptic/token.sql").

mechanisms = array of strings

(Optional) A list of allowed or denied mechanisms, altering the mechanisms this token claims to implement.

By default, this acts as an allow list (e.g., ["CKM_SHA256", "CKM_RSA_PKCS"]), making only the explicitly mentioned mechanisms available. To configure a deny list, the first element must be the exact string "DENY", followed by the mechanisms to be removed (e.g., ["DENY", "CKM_SHA256"]). Using "DENY" in any position other than the first is not supported and will cause an error.

objects_dedup = string

(Optional) Specifies which objects to deduplicate on creation. For compatibility with NSS softokn, some or all objects can be deduplicated on insertion; upon match, the original object is overridden with the attributes of the new object being created instead of creating a separate object. Valid values are “TrustOnly”, “TrustAndCertificates”, or “All”. Defaults to not set for configured databases, but defaults to “All” for NSS databases loaded via initialization string options. WARNING: It is recommended to leave this empty. Side effects may include destroying key material irrecoverably if the “All” option is used.

[slots.fips_behavior]

(Optional) Add tweaks for behavior in FIPS mode.

keys_always_sensitive = boolean

Changes the behavior of the token in the slot to always enforce keys to be private/sensitive. The default is false (unless dbtype is "nssdb", which defaults to true).

## ENVIRONMENT VARIABLES
KRYOPTIC_CONF

Specifies the exact path to the kryoptic.conf file, bypassing default search paths. It is strongly advised to set this variable for most use cases.

KRYOPTIC_EC_POINT_ENCODING

Overrides the ec_point_encoding.encoding setting specified in the configuration file. Valid values are “BYTES” or “DER”.

## EXAMPLES
Below is an example of a kryoptic.conf file configuring two slots and specifying EC point encoding:

```
[ec_point_encoding]
encoding = "Der"
[[slots]]
slot = 1
description = "My SQLite Token"
manufacturer = "Kryoptic"
dbtype = "sqlite"
dbargs = "/var/lib/kryoptic/token.sql"
mechanisms = ["DENY", "CKM_MD5"]
objects_dedup = "TrustOnly"
[[slots]]
slot = 2
dbtype = "nssdb"
dbargs = "configDir=/etc/pki/nssdb"

```

## SEE ALSO
kryoptic(7), softhsm_migrate(1)


tlshd.conf

package: ktls-utils

title: tlshd.conf(5)

summary: tlshd configuration file

text:
# tlshd.conf(5)

## NAME
tlshd.conf - tlshd configuration file

## SYNOPSIS
/etc/tlshd/config

/etc/tlshd.conf (deprecated)

## DESCRIPTION
The tlshd program implements a user agent that services TLS handshake requests on behalf of kernel TLS consumers. Its configuration file contains information that the program reads when it starts up. The file is designed to be human readable and contains a list of keywords with values that provide various types of information. The configuration file is considered a trusted source of information.

The tlshd program reads this file once when it is launched. Thus changes made in this file take effect only when the tlshd program is restarted. If this file does not exist, the tlshd program exits immediately.

## OPTIONS
The configuration file is split into sections.

The [debug] section specifies debugging settings for the tlshd program. In this section, there are three available options:

loglevel

This option specifies an integer which indicates the debug message level. Zero, the quietest setting, is the default.

tls

This option specifies an integer which indicates the debug message level for TLS library calls. Zero, the quietest setting, is the default.

nl

This option specifies an integer which indicates the debug message level for netlink library calls. Zero, the quietest setting, is the default.

The [authenticate] section specifies default authentication material when establishing TLS sessions. In this section, there is one available option:

keyrings

This option specifies a semicolon-separated list of auxiliary keyrings that contain handshake authentication tokens. tlshd links these keyrings into its session keyring. The configuration file may specify either a keyring's name or serial number. tlshd always includes the .nvme, .nfs, and .nfsd keyrings on its session keyring.

And, in this section, there are two subsections: [client] and [server]. The tlshd program consults the settings in the [client] subsection when handling the client end of a handshake, and it consults the settings in the [server] subsection when handling the server end of a handshake.

In each of these two subsections, there are four available options:

x509.truststore

This option specifies the pathname of a file containing a PEM-encoded trust store that is to be used to verify a certificate during a handshake. If this option is not specified, tlshd uses the system's trust store.

x509.crl

This option specifies the pathname of a file containing PEM-encoded certificate revocation lists (CRL) that are to be used to verify the revocation status of certificates during each handshake. If this option is not specified, CRL checking is skipped.

x509.certificate

This option specifies the pathname of a file containing a PEM-encoded x.509 certificate that is to be presented during a handshake request when no other certificate is available.

x509.private_key

This option specifies the pathname of a file containing a PEM-encoded private key associated with the above certificate.

x509.pq.certificate

This option specifies the pathname of a file containing a PEM-encoded x.509 certificate that is to be presented during a handshake request if the peer supports post-quantum cryptography. This certificate must be using a post-quantum public-key algorithm (ML-DSA-44, ML-DSA-65, or ML-DSA-87). If the peer does not support post-quantum cryptography, the certificate configured in the x509.certificate option will be presented instead.

x509.pq.private_key

This option specifies the pathname of a file containing a PEM-encoded private key associated with the above certificate.

## SEE ALSO
tlshd(8), tls-session-tags(7)

## AUTHOR
Chuck Lever


kyua.conf

package: kyua

title: kyua.conf(5)

summary: Configuration file for the kyua tool

text:
# kyua.conf(5)

## NAME
kyua.conf — Configuration file for the kyua tool

## SYNOPSIS
syntax(int version);

Variables: architecture, platform, test_suites, unprivileged_user.

## DESCRIPTION
The configuration of Kyua is a simple collection of key/value pairs called configuration variables. There are configuration variables that have a special meaning to the runtime engine implemented by kyua(1), and there are variables that only have meaning in the context of particular test suites.

Configuration files are Lua scripts. In their most basic form, their whole purpose is to assign values to variables, but the user has the freedom to implement any logic he desires to compute such values.

### File versioning
Every kyua.conf file starts with a call to syntax(int version). This call determines the specific schema used by the file so that future backwards-incompatible modifications to the file can be introduced.

Any new kyua.conf file should set version to ‘2’.

### Runtime configuration variables
The following variables are internally recognized by kyua(1):

architecture

Name of the system architecture (aka processor type).

parallelism

Maximum number of test cases to execute concurrently.

platform

Name of the system platform (aka machine type).

unprivileged_user

Name or UID of the unprivileged user. If set, the given user must exist in the system and his privileges will be used to run test cases that need regular privileges when kyua(1) is executed as root.

### Test-suite configuration variables
Each test suite is able to recognize arbitrary configuration variables, and their type and meaning is specific to the test suite. Because the existence and naming of these variables depends on every test suite, this manual page cannot detail them; please refer to the documentation of the test suite you are working with for more details on this topic.

Test-suite specific configuration variables are defined inside the test_suites dictionary. The general syntax is:

```
test_suites.<test_suite_name>.<variable_name> = <value>
```

where test_suite_name is the name of the test suite, variable_name is the name of the variable to set, and value is a value. The value can be a string, an integer or a boolean.

## FILES
/usr/share/kyua/examples/kyua.conf

Sample configuration file.

## EXAMPLES
The following kyua.conf shows a simple configuration file that overrides a bunch of the built-in kyua(1) configuration variables:

```
syntax(2)

architecture = 'x86_64'
platform = 'amd64'
```

The following is a more complex example that introduces the definition of per-test suite configuration variables:

```
syntax(2)

-- Assign built-in variables.
unprivileged_user = '_tests'

-- Assign test-suite variables.  All of these must be strings.
test_suites.NetBSD.file_systems = 'ffs ext2fs'
test_suites.X11.graphics_driver = 'vesa'
```

## SEE ALSO
kyua(1)


kyuafile

title: kyuafile(5)

summary: Test suite description files

text:
# kyuafile(5)

## NAME
Kyuafile — Test suite description files

## SYNOPSIS
atf_test_program(string name, [string metadata]);

current_kyuafile();

fs.basename(string path);

fs.dirname(string path);

fs.exists(string path);

fs.files(string path);

fs.is_absolute(string path);

fs.join(string path, string path);

include(string path);

plain_test_program(string name, [string metadata]);

syntax(int version);

tap_test_program(string name, [string metadata]);

test_suite(string name);

## DESCRIPTION
A test suite is a collection of test programs and is represented by a hierarchical layout of test binaries on the file system. Any subtree of the file system can represent a test suite, provided that it includes one or more Kyuafiles, which are the test suite definition files.

A Kyuafile is a Lua script whose purpose is to describe the structure of the test suite it belongs to. To do so, the script has access to a collection of special functions provided by kyua(1) as described in Helper functions.

### File versioning
Every Kyuafile file starts with a call to syntax(int version). This call determines the specific schema used by the file so that future backwards-incompatible modifications to the file can be introduced.

Any new Kyuafile file should set version to ‘2’.

### Test suite definition
If the Kyuafile registers any test programs, the Kyuafile must define the name of the test suite the test programs belong to by using the test_suite() function at the very beginning of the file.

The test suite name provided in the test_suite() call tells kyua(1) which set of configuration variables from kyua.conf(5) to pass to the test programs at run time.

### Test program registration
A Kyuafile can register test programs by means of a variety of *_test_program() functions, all of which take the name of a test program and a set of optional metadata properties that describe such test program.

The test programs to be registered must live in the current directory; in other words, the various *_test_program() calls cannot reference test programs in other directories. The rationale for this is to force all Kyuafile files to be self-contained, and to simplify their internal representation.

ATF test programs are those that use the atf(7) libraries. They can be registered with the atf_test_program() table constructor. This function takes the name of the test program and a collection of optional metadata settings for all the test cases in the test program. Any metadata properties defined by the test cases themselves override the metadata values defined here.

Plain test programs are those that return 0 on success and non-0 on failure; in general, most test programs (even those that use fancy unit-testing libraries) behave this way and thus also qualify as plain test programs. They can be registered with the plain_test_program() table constructor. This function takes the name of the test program, an optional test_suite name that overrides the global test suite name, and a collection of optional metadata settings for the test program.

TAP test programs are those that implement the Test Anything Protocol. They can be registered with the tap_test_program() table constructor. This function takes the name of the test program and a collection of optional metadata settings for the test program.

The following metadata properties can be passed to any test program definition:

allowed_architectures

Whitespace-separated list of machine architecture names allowed by the test. If empty or not defined, the test is allowed to run on any machine architecture.

allowed_platforms

Whitespace-separated list of machine platform names allowed by the test. If empty or not defined, the test is allowed to run on any machine platform.

custom.NAME

Custom variable defined by the test where ‘NAME’ denotes the name of the variable. These variables are useful to tag your tests with information specific to your project. The values of such variables are propagated all the way from the tests to the results files and later to any generated reports. Note that if the name happens to have dashes or any other special characters in it, you will have to use a special Lua syntax to define the property. Refer to the EXAMPLES section below for clarification.

description

Textual description of the test.

is_exclusive

If true, indicates that this test program cannot be executed along any other programs at the same time. Test programs that affect global system state, such as those that modify the value of a sysctl(8) setting, must set themselves as exclusive to prevent failures due to race conditions. Defaults to false.

required_configs

Whitespace-separated list of configuration variables that the test requires to be defined before it can run.

required_disk_space

Amount of available disk space that the test needs to run successfully.

required_files

Whitespace-separated list of paths that the test requires to exist before it can run.

required_memory

Amount of physical memory that the test needs to run successfully.

required_programs

Whitespace-separated list of basenames or absolute paths pointing to executable binaries that the test requires to exist before it can run.

required_user

If empty, the test has no restrictions on the calling user for it to run. If set to ‘unprivileged’, the test needs to not run as root. If set to ‘root’, the test must run as root.

timeout

Amount of seconds that the test is allowed to execute before being killed.

### Recursion
To reference test programs in another subdirectory, a different Kyuafile must be created in that directory and it must be included into the original Kyuafile by means of the include() function.

include() may only be called with a relative path and with at most one directory component. This is by design: Kyua uses the file system structure as the layout of the test suite definition. Therefore, each subdirectory in a test suite must include its own Kyuafile and each Kyuafile can only descend into the Kyuafiles of immediate subdirectories.

If you need to source a Kyuafile located in disjoint parts of your file system namespace, you will have to create a ‘shadow tree’ using symbolic links and possibly helper Kyuafiles to plug the various subdirectories together. See the EXAMPLES section below for details.

Note that each file is processed in its own Lua environment: there is no mechanism to pass state from one file to the other. The reason for this is that there is no such thing as a “top-level” Kyuafile in a test suite: the user has to be able to run the test suite from any directory in a given hierarchy, and this execution must not depend on files that live in parent directories.

### Top-level Kyuafile
Every system has a top directory into which test suites get installed. The default is /usr/libexec/kyua. Within this directory live test suites, each of which is in an independent subdirectory. Each subdirectory can be provided separately by independent third-party packages.

Kyua allows running all the installed test suites at once in order to provide comprehensive cross-component reports. In order to do this, there is a special file in the top directory that knows how to inspect the subdirectories in search for other Kyuafiles and include them.

The FILES section includes more details on where this file lives.

### Helper functions
The ‘base’, ‘string’, and ‘table’ Lua modules are fully available in the context of a Kyuafile.

The following extra functions are provided by Kyua:

string current_kyuafile()

Returns the absolute path to the current Kyuafile.

string fs.basename(string path)

Returns the last component of the given path.

string fs.dirname(string path)

Returns the given path without its last component or a dot if the path has a single component.

bool fs.exists(string path)

Checks if the given path exists. If the path is not absolute, it is relative to the directory containing the Kyuafile in which the call to this function occurs.

iterator fs.files(string path)

Opens a directory for scanning of its entries. The returned iterator yields an entry on each call, and the entry is simply the filename. If the path is not absolute, it is relative to the directory containing the Kyuafile in which the call to this function occurs.

is_absolute fs.is_absolute(string path)

Returns true if the given path is absolute; false otherwise.

join fs.join(string path, string path)

Concatenates the two paths. The second path cannot be absolute.

## FILES
/usr/libexec/kyua/Kyuafile.

Top-level Kyuafile for the current system.

/usr/share/kyua/examples/Kyuafile.top.

Sample file to serve as a top-level Kyuafile.

## EXAMPLES
The following Kyuafile is the simplest you can define. It provides a test suite definition and registers a couple of different test programs using different interfaces:

```
syntax(2)

test_suite('first')

atf_test_program{name='integration_test'}
plain_test_program{name='legacy_test'}
```

The following example is a bit more elaborate. It introduces some metadata properties to the test program definitions and recurses into a couple of subdirectories:

```
syntax(2)

test_suite('second')

plain_test_program{name='legacy_test',
                   allowed_architectures='amd64 i386',
                   required_files='/bin/ls',
                   timeout=30}

tap_test_program{name='privileged_test',
                 required_user='root'}

include('module-1/Kyuafile')
include('module-2/Kyuafile')
```

The syntax to define custom properties may be not obvious if their names have any characters that make the property name not be a valid Lua identifier. Dashes are just one example. To set such properties, do something like this:

```
syntax(2)

test_suite('FreeBSD')

plain_test_program{name='the_test',
                   ['custom.FreeBSD-Bug-Id']='category/12345'}
```

### Connecting disjoint test suites
Now suppose you had various test suites on your file system and you would like to connect them together so that they could be executed and treated as a single unit. The test suites we would like to connect live under /usr/tests, /usr/local/tests and ~/local/tests.

We cannot create a Kyuafile that references these because the include() directive does not support absolute paths. Instead, what we can do is create a shadow tree using symbolic links:

```
$ mkdir ~/everything
$ ln -s /usr/tests ~/everything/system-tests
$ ln -s /usr/local/tests ~/everything/local-tests
$ ln -s ~/local/tests ~/everything/home-tests
```

And then we create an ~/everything/Kyuafile file to drive the execution of the integrated test suite:

```
syntax(2)

test_suite('test-all-the-things')

include('system-tests/Kyuafile')
include('local-tests/Kyuafile')
include('home-tests/Kyuafile')
```

Or, simply, you could reuse the sample top-level Kyuafile to avoid having to manually craft the list of directories into which to recurse:

```
$ cp /usr/share/kyua/examples/Kyuafile.top ~/everything/Kyuafile
```

## SEE ALSO
kyua(1)


labwc-actions

package: labwc-base

title: labwc-actions(5)

text:
# labwc-actions(5)

## NAME
labwc - actions

## ACTIONS
Actions are used in menus and keyboard/mouse bindings.

<action name="Close" />

Close top-most window.

<action name="Kill" />

Kill the process associated with the current window by sending it the SIGTERM signal.

<action name="Execute" command="value" />

Execute command. Note that in the interest of backward compatibility, labwc supports <execute> as an alternative to <command> even though openbox documentation states that it is deprecated. Note: Tilde (~) is expanded in the command before passing to execvp().

<action name="Exit" />

Exit labwc.

<action name="Focus" />

Give focus to window under cursor.

<action name="Unfocus" />

Remove focus from the window that is currently focused.

<action name="Raise" />

Restack the current window above other open windows.

<action name="Lower" />

Restack the current window below other open windows.

<action name="Iconify" />

Iconify (minimize) focused window.

<action name="Move" />

Begin interactive move of window under cursor.

<action name="MoveToEdge" direction="value" snapWindows="value" />

Move window until it hits the next edge. direction [left|up|right|down] Direction in which to move.

snapWindows [yes|no] Move window until it hits an edge of another window or screen edge. If set to "no", only move to the next screen edge. Default is yes.

<action name="Resize" direction="value" />

Begin interactive resize of window under cursor. direction [up|down|left|right|up-left|up-right|down-left|down-right] Edge or corner from which to start resizing. If this is not provided, the direction is inferred from the cursor position.

<action name="ResizeRelative" left="" right="" top="" bottom="" />

Resize window relative to its current size. Values of left, right, top or bottom tell how much to resize on that edge of window, positive values grow window, negative shrink window.

<action name="GrowToEdge" direction="value" />

Resize window to fill the space between its edge and any other window edge. direction [left|up|right|down] Direction in which to grow.

<action name="ShrinkToEdge" direction="value" />

Reverse of GrowToEdge. Shrinks by a maximum of 50%. direction [left|up|right|down] Direction in which to shrink.

<action name="MoveTo" x="" y="" />

Move to position (x, y).

<action name="ResizeTo" width="" height="" />

Resize window. width The width to resize the window to in pixels.

height The height to resize the window to in pixels.

<action name="MoveToCursor" />

Move to be centered on cursor. Tries to prevent any part of the window from going off-screen. This action is deprecated from v0.7.3. To ensure your config works in future labwc releases, please use: <action name="AutoPlace" policy="cursor">

<action name="MoveRelative" x="" y="" />

Move window relative to its current position. Positive value of x moves it right, negative left. Positive value of y moves it down, negative up.

<action name="ToggleSnapToEdge" direction="value" combine="value" />

<action name="SnapToEdge" direction="value" combine="value" />

Resize window to fill half or quarter the output in the given direction. direction [up|down|left|right|up-left|up-right|down-left|down-right|center]

Direction in which to snap the window.

combine [yes|no]

Allows to snap a window to an output corner by combining two directions. For example, snapping a window to right and then to up places it in the up-right quarter of the output. Default is no.

ToggleSnapToEdge additionally toggles the active window between tiled to the given direction and its untiled position.

<action name="ToggleSnapToRegion" region="value" />

<action name="SnapToRegion" region="value" />

Resize and move active window according to the given region. ToggleSnapToRegion additionally toggles the active window between tiled to the given region and its untiled position.

See labwc-config(5) for further information on how to define regions.

<action name="UnSnap" />

Resize and move the active window back to its untiled or unmaximized position if it had been maximized or tiled to a direction or region.

<action name="NextWindow" workspace="current" output="all" identifier="all" />

<action name="PreviousWindow" workspace="current" output="all" identifier="all" />

<action name="NextWindowImmediate" workspace="current" output="all" identifier="all" />

<action name="PreviousWindowImmediate" workspace="current" output="all" identifier="all" />

Cycle focus to next/previous window, respectively.

Default keybinds for NextWindow and PreviousWindow are Alt-Tab and Shift-Alt-Tab. While cycling through windows, the arrow keys move the selected window forwards/backwards and the escape key halts the cycling. NextWindowImmediate and PreviousWindowImmediate skip the Window Switcher and OSD, useful for binding to keys without modifiers.

workspace [all|current] This determines whether to cycle through windows on all workspaces or the current workspace. Default is "current".

output [all|focused|cursor] This determines whether to cycle through windows on all outputs, the focused output, or the output under the cursor. Default is "all".

identifier [all|current] This determines whether to cycle through all windows or only windows of the same application as the currently focused window. Default is "all".

<action name="Reconfigure" />

Re-load configuration and theme files.

<action name="ShowMenu" menu="root-menu" />

Show a menu.

```
<action name="ShowMenu" menu="MENU">

  <atCursor>yes|no</atCursor>

  <position>

    <x>X</x>

    <y>Y</y>

  </position>
</action>
```

menu The name of the menu to show. The menus "root-menu", "client-menu", "client-send-to-menu" and "client-list-combined-menu" are guaranteed to exist, but others may be defined explicitly. See labwc-menu(5) for more information. atCursor [yes|no] When opening a menu, open the menu at the location of the mouse cursor. When set to no, the menu will appear at the upper-left corner of the window associated with the action or underneath the window button that opened the menu. Default is yes.

position Show the menu in the specified position on the monitor that has cursor focus, see below.

The position tag has two sub-tags. <x> and <y> specify a position and take either a pixel value, the string "center" which will center the menu in that dimension, or a relative value specified as a percentage A relative value is interpreted in terms of the monitor the menu will be shown on, and will be relative to the left/top edge of the menu window and monitor for positive values, and to the right/bottom edge for negative values.

The example below demonstrates how the 'root-menu' can be opened from a bottom aligned panel using the command `wtype -M logo -k Space`:

```
<keybind key="W-Space">

  <action name="ShowMenu">

  <menu>root-menu</menu>

  <position>

    <x>0</x>

    <y>-0</y>

  </position>

  </action>
</keybind>
```

<action name="SetDecorations" decorations="value" forceSSD="no" />

Set decorations of focused window. decorations [full|border|none] full enables the whole server side decorations. With border. only the borders and invisible resize area are enabled. none disables everything.

forceSSD [yes|no] If this is no, this action will be ignored for windows that have client side decorations if it would increase the amount of decoration. Default is no.

<action name="ToggleDecorations" />

Toggle decorations of focused window. This is a 3-state action which can be executed multiple times:

- Only the titlebar will be hidden, borders and resize area are kept

- Remaining decorations will be disabled

- Decorations will be shown normally

By disabling the theme configuration 'keepBorder' the first step will be removed and the action only toggles between on and off.

<action name="ToggleFullscreen" />

Toggle fullscreen state of focused window.

<action name="ToggleMaximize" direction="value" />

Toggle maximize state of focused window. Supported directions are "both" (default), "horizontal", and "vertical".

<action name="Maximize" direction="value" />

Maximize focused window in the direction(s) specified. Supported directions are "both" (default), "horizontal", and "vertical".

<action name="UnMaximize" direction="value" />

Unmaximize focused window in the direction(s) specified and return it to its pre-maximized dimensions. Supported directions are "both" (default), "horizontal", and "vertical".

<action name="ToggleAlwaysOnTop" />

Toggle always-on-top of focused window.

<action name="ToggleAlwaysOnBottom" />

Toggle between layers 'always-on-bottom' and 'normal'. When a window is in the 'always-on-bottom' layer, it is rendered below all other top-level windows. It is anticipated that this action will be useful when defining window-rules for desktop-management tools that do not support the wlr-layer-shell protocol.

<action name="ToggleOmnipresent" />

Toggle omnipresent (visible on all workspaces / sticky) for the focused window.

<action name="ToggleKeybinds" />

Stop handling keybinds/mousebinds other than ToggleKeybinds itself. This can be used to allow A-Tab and similar keybinds/mousebinds to be delivered to Virtual Machines, VNC clients or nested compositors. A second call will restore all original keybinds/mousebinds. This action will only affect the window that had keyboard focus when the binding was executed. Thus when switching to another window, all the usual keybinds will function again until switching back to the original window. There can be multiple windows with this mode set.

<action name="ToggleTearing" />

Toggles tearing for the focused window between enabled and disabled. This overrides the preference (tearing hint) from the focused window. Requires the config option 'allowTearing'. When 'allowTearing' is set to 'fullscreen' or 'fullscreenForced', tearing will still only be enabled if the active window is in fullscreen mode.

<action name="FocusOutput" output="HDMI-A-1" direction="value" wrap="no" />

Give focus to topmost window on other output and warp the cursor to the center of the window. If output is specified, the focus is given to the specified output and direction is ignored. If output is omitted, direction may be one of "left", "right", "up" or "down" to indicate that the focus should be given to the next output in that direction (if one exists).

wrap [yes|no] When using the direction attribute, wrap around from right-to-left or top-to-bottom, and vice versa. Default is no.

If the target output does not contain any windows, the cursor will be centered on the output.

<action name="MoveToOutput" output="HDMI-A-1" direction="value" wrap="no" />

Moves active window to other output, unless the window state is fullscreen. If output is specified, the window will be sent directly to the specified output and direction is ignored. If output is omitted, direction may be one of "left", "right", "up" or "down" to indicate that the window should be moved to the next output in that direction (if one exists).

wrap [yes|no] When using the direction attribute, wrap around from right-to-left or top-to-bottom, and vice versa. Default is no.

<action name="FitToOutput" />

Resizes active window size to width and height of the output when the window size exceeds the output size.

<action name="GoToDesktop" to="value" wrap="yes" toggle="no" />

Switch to workspace. to The workspace to switch to. Supported values are "current", "last", "left", "right", "left-occupied", "right-occupied" or the full name of a workspace or its index (starting at 1) as configured in rc.xml.

wrap [yes|no] Wrap around from last desktop to first, and vice versa. Default is yes.

toggle [yes|no] Toggle to “last” if already on the workspace that would be the actual destination. Default is no.

<action name="SendToDesktop" to="value" follow="yes" wrap="yes" />

Send active window to workspace. to The workspace to send the window to. Supported values are the same as for GoToDesktop.

follow [yes|no] Also switch to the specified workspace. Default is yes.

wrap [yes|no] Wrap around from last desktop to first, and vice versa. Default is yes.

<action name="VirtualOutputAdd" output_name="value" />

Add virtual output (headless backend). For example, it can be used to overlay virtual output on real output, but with a different resolution (this can be done with `wlr-randr` or `wdisplays`). After that, virtual output can be selected for screen sharing (casting), effectively sharing only the region of the screen.

It must be noted that overlaying virtual output and real output is not endorsed or explicitly supported by wlroots. For example, after configuring virtual output, real output must be reconfigured as well (for the overlay configuration to work correctly). This is the example configuration:

```
<keybind key="W-v">

  <action name="VirtualOutputAdd" output_name="ScreenCasting" />

  <action name="Execute" command='sh -c "wlr-randr --output ScreenCasting --pos 0,0 --scale 2 --custom-mode 3840x2110; wlr-randr --output eDP-1 --pos 0,0 --scale 2 --mode 3840x2160"' />
</keybind>
<keybind key="W-c">

  <action name="VirtualOutputRemove" />
</keybind>
```

Note that the vertical resolution of "ScreenCasting" output is just 50px smaller than "eDP-1" output to cut off bottom panel from screen sharing. Virtual output is also useful for extending the desktop to (maybe mobile) remote systems like tablets. E.g. simply adding a virtual output, attaching wayvnc to it and running a VNC client on the remote system.

output_name The name of virtual output. Providing virtual output name is beneficial for further automation. Default is "HEADLESS-X".

<action name="VirtualOutputRemove" output_name="value" />

Remove virtual output (headless backend). output_name The name of virtual output. If not supplied, will remove the last virtual output added.

<action name="AutoPlace" policy="value" />

Reposition the window according to the desired placement policy. policy [automatic|cursor|center|cascade] Use the specified policy, which has the same meaning as the corresponding value for <placement><policy>. Default is automatic.

<action name="Shade" />

<action name="Unshade" />

<action name="ToggleShade" />

Set, unset, or toggle, respectively, the "shaded" state of the active window. When shaded, window contents are hidden, leaving only the titlebar visible. Full-screen windows or those without server-side decorations (including those for which the server-side titlebar has been hidden) are not eligible for shading.

<action name="WarpCursor" to="output" x="center" y="center" />

Warp the cursor to a position relative to the active output or window. to [output|window] Specifies the target area of the warp. Default is "output"

x [center|value] Specifies the horizontal warp position within the target area. "center": Moves the cursor to the horizontal center of the target area. Positive or negative integers warp the cursor to a position offset by the specified number of pixels from the left or right edge of the target area, respectively. Default is "center"

y [center|value] Equivalent for the vertical warp position within the target area. Default is "center"

<action name="HideCursor" />

Hide the pointer or stylus cursor. The cursor becomes visible again on following pointer actions, stylus actions or touchpad gestures. Use together with the WarpCursor action to not just hide the cursor but to additionally move it away to prevent e.g. hover effects.

<action name="EnableScrollWheelEmulation" />

<action name="DisableScrollWheelEmulation" />

<action name="ToggleScrollWheelEmulation">

Enable, disable or toggle scroll wheel emulation on cursor motion, respectively. This can be useful for trackball mouses to use the rotating ball not just for moving the cursor, but also for (mouse wheel) scrolling. See also <libinput><scrollFactor> in labwc-config(5) for fine tuning the scroll speed.

<action name="EnableTabletMouseEmulation" />

<action name="DisableTabletMouseEmulation" />

<action name="ToggleTabletMouseEmulation">

Enable, disable or toggle mouse emulation for drawing tablets, respectively.

<action name="ToggleMagnify">

Toggle the screen magnifier on or off at the last magnification level used.

<action name="ToggleShowDesktop" />

Minimize all windows in the current workspace so that the desktop becomes visible. On calling the action again the hidden windows are unminimized, provided that - since the initial `ShowDesktop` - (a) no windows have been unminimized; (b) workspaces have not been switched; and (c) no new applications have been started.

<action name="ZoomIn">

<action name="ZoomOut">

Increase or decrease the magnification level for the screen magnifier. If the magnifier is currently off, ZoomIn will enable it at the lowest magnification, equal to (1 + the magnifier increment set in the theme). If the magnifier is on and at the lowest magnification, ZoomOut will turn it off.

<action name="None" />

If used as the only action for a binding: clear an earlier defined binding.

<action name="DebugToggleKeyStateIndicator" />

Toggle visibility of key-state on-screen display (OSD). Note: This is for debugging purposes only.

## CONDITIONAL ACTIONS
Actions that execute other actions. Used in keyboard/mouse bindings.

<action name="If">

This action will execute one set of actions if the focused window matches the criteria, or another if it does not. The arguments are as follows:

```
<action name="If">

  <query />

  <prompt message="" />

  <then><action /></then>

  <else><action /></else>
</action>
```

query

Define a query with zero or more conditions. All conditions must be evaluated as true in order for the window to match this query. Multiple queries can be defined. Pattern matching is done according to glob(7) and is case-insensitive.

Conditions are as follows:

identifier

XDG shell app_id for Wayland clients, WM_CLASS for XWayland clients.

title

XDG shell title for Wayland clients, WM_NAME for XWayland clients.

type

Internal heuristics for Wayland clients, NET_WM_WINDOW_TYPE for XWayland clients.

shaded [yes|no]

Whether or not the client is rolled up.

maximized [both|horizontal|vertical|none]

Whether the client is maximized along both axes, the horizontal axis only, the vertical axis only, or neither axis (none).

iconified [yes|no]

Whether or not the client is iconified.

focused [yes|no]

Whether or not the client is focused.

omnipresent [yes|no]

Whether or not the client is visible on all desktops.

desktop

The desktop the client is currently on. This can be the number or name of a desktop, or special relative values "current", "other", "left", "right", "left-occupied", "right-occupied" or "last". The "left" , "right", "left-occupied" and "right-occupied" directions will not wrap.

tiled [up|right|down|left|up-left|up-right|down-left|down-right|center|any]

Whether the client is tiled (snapped) along the indicated screen edge.

tiled_region

Whether the client is tiled (snapped) to the indicated region. The indicated region may be a glob.

decoration [full|border|none]

Whether the client has full server-side decorations, borders only, or no server-side decorations.

monitor [current|left|right|<monitor_name>]

Whether the client is on a monitor relative to the to the currently focused monitor (current, left, or right) or on a monitor with the supplied <monitor_name>.

This argument is optional.

prompt

Display a yes/no prompt dialog (labnag by default). If 'yes' is selected, the then branch will be taken; and similarly with 'no' and else. This argument is optional. Note that the syntax is different to that of Openbox where a prompt element is not tied to If-actions but would just be a child of the downstream action. The reason for this difference is increased flexibility and functionality gained by optionally using an else branch.

```
<keybind key="W-q">

  <action name="If">

    <prompt message="Quit?" />

    <then>

      <action name="Exit" />

    </then>

  </action>
</keybind>
```

then

A list of actions to be executed if the window matches any query. This argument is optional.

else

A list of actions to be executed if the window does not match any query. This argument is optional.

<action name="ForEach">

Identical to "If" action, but applies to all windows, not just the focused one. The ForEach action has another optional none branch which gets executed when no window has been matched by the query. This allows for example to implement a run-or-raise functionality.

## SEE ALSO
labwc(1), labwc-config(5), labwc-theme(5), glob(7)