pki-logging

package: dogtag-pki-base

title: pki-logging(5)

summary: PKI Common Logging Configuration

text:
# pki-logging(5)

## NAME
pki-logging - PKI Common Logging Configuration

## LOCATION
/usr/share/pki/etc/logging.properties, /etc/pki/logging.properties

## DESCRIPTION
PKI clients and tools use java.util.logging ⟨https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html⟩ (JUL) as the logging framework.

The default logging configuration is located at /usr/share/pki/etc/logging.properties.

By default only log messages with level WARNING or higher will be logged on the console.

```
java.util.logging.ConsoleHandler.level = ALL
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format = %4$s: %5$s%6$s%n
```

For more information see the following documents:

- java.util.logging.ConsoleHandler ⟨https://docs.oracle.com/javase/8/docs/api/java/util/logging/ConsoleHandler.html⟩

- java.util.logging.Level ⟨https://docs.oracle.com/javase/8/docs/api/java/util/logging/Level.html⟩

- java.util.logging.SimpleFormatter ⟨https://docs.oracle.com/javase/8/docs/api/java/util/logging/SimpleFormatter.html⟩

- java.util.Formatter ⟨https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html⟩

## CUSTOMIZATION
To customize the logging configuration, copy the default logging configuration into a new location:

```
$ cp /usr/share/pki/etc/logging.properties /etc/pki/logging.properties
```

Then edit the file as needed. For example, to troubleshoot issues with PKI library add the following lines:

```
netscape.level = ALL
com.netscape.level = ALL
org.dogtagpki.level = ALL
```

To troubleshoot issues with RESTEasy add the following line:

```
org.jboss.resteasy.level = ALL
```

Then specify the location of the custom logging configuration in the following parameter in /etc/pki/pki.conf:

```
PKI_LOGGING_CONFIG=/etc/pki/logging.properties
```

Then restart the application.

## SEE ALSO
pki-server-logging(5)

## AUTHORS
Dogtag PKI Team <devel@lists.dogtagpki.org>.

## COPYRIGHT
Copyright (c) 2016 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at ⟨http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt⟩.


package: dogtag-pki-healthcheck

title: pki_healthcheck.conf(5)

summary: PKI Healthcheck configuration file.

text:
# pki_healthcheck.conf(5)

## NAME
pki_healthcheck.conf - PKI Healthcheck configuration file.

## DESCRIPTION
The healthcheck.conf configuration file is used to set the defaults when running pki-healthcheck tool.

## SYNTAX
The configuration options are not case sensitive. The values may be case sensitive, depending on the option.

Blank lines are ignored. Lines beginning with # are comments and are ignored.

Valid lines consist of an option name, an equals sign and a value. Spaces surrounding equals sign are ignored. An option terminates at the end of a line.

Values should not be quoted, the quotes will not be stripped.

```
# Wrong - don't include quotes
verbose = "True"
# Right - Properly formatted options
verbose = True
verbose=True
```

Options must appear in the section named [default] or [dogtag]. There are no other sections defined or used currently.

Options may be defined that are not used. Be careful of misspellings, they will not be rejected.

## OPTIONS
The following options are relevant for the healthcheck tool:

cert_expiration_days

The number of days left before a certificate expires to start displaying a warning. The default is 28.

instance_name

The name of the PKI instance. The default is pki-tomcat

## EXAMPLES
[default]

cert_expiration_days = 30

[dogtag]

instance_name = pki-tomcat

## FILES
/etc/pki/healthcheck.conf

## SEE ALSO
pki-healthcheck (8)

## AUTHORS
Dinesh Prasanth M K <dmoluguw@redhat.com>

## COPYRIGHT
Copyright (c) 2020 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at ⟨http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt⟩.


pki-server-logging

package: dogtag-pki-server

title: pki-server-logging(5)

summary: PKI Server Logging Configuration

text:
# pki-server-logging(5)

## NAME
pki-server-logging - PKI Server Logging Configuration

## LOCATION
/var/lib/pki/instance/conf/logging.properties, /var/lib/pki/instance/conf/subsystem/CS.cfg

## DESCRIPTION
PKI server logging can be configured using the following logging frameworks:

- java.util.logging ⟨https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html⟩

- Internal Logging

### java.util.logging
Tomcat uses java.util.logging (JUL) as the default logging framework. The configuration is described in Tomcat Logging ⟨http://tomcat.apache.org/tomcat-9.0-doc/logging.html⟩.

The default configuration is located at /usr/share/pki/server/conf/logging.properties. During server deployment a link will be created at /var/lib/pki/instance/conf/logging.properties.

By default only log messages with level WARNING or higher will be logged on the console (i.e. systemd journal).

```
java.util.logging.ConsoleHandler.level = ALL
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format = %4$s: %5$s%6$s%n
```

The systemd journal can be viewed with the following command:

```
$ journalctl -u pki-tomcatd@<instance>.service
```

For more information see the following documents:

- java.util.logging.ConsoleHandler ⟨https://docs.oracle.com/javase/8/docs/api/java/util/logging/ConsoleHandler.html⟩

- java.util.logging.Level ⟨https://docs.oracle.com/javase/8/docs/api/java/util/logging/Level.html⟩

- java.util.logging.SimpleFormatter ⟨https://docs.oracle.com/javase/8/docs/api/java/util/logging/SimpleFormatter.html⟩

- java.util.Formatter ⟨https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html⟩

### Internal Logging
Each PKI subsystem uses an internal logging framework for debugging purposes.

The logging configuration is stored in /var/lib/pki/instance/conf/subsystem/CS.cfg.

```
debug.level=10
```

The debug.level determines the amount of details to be logged. The value ranges from 0 (most details) to 10 (least details). The default value is 10.

## CUSTOMIZATION

### java.util.logging
To customize JUL configuration, replace the link with a copy of the default configuration:

```
$ rm -f /var/lib/pki/<instance>/conf/logging.properties
$ cp /usr/share/pki/server/conf/logging.properties /var/lib/pki/<instance>/conf
$ chown pkiuser.pkiuser /var/lib/pki/<instance>/conf/logging.properties
```

Then edit the file as needed. For example, to troubleshoot issues with PKI library add the following lines:

```
netscape.level = ALL
com.netscape.level = ALL
org.dogtagpki.level = ALL
```

To troubleshoot issues with RESTEasy add the following line:

```
org.jboss.resteasy.level = ALL
```

Then restart the server.

### Internal Logging
To customize the internal logging configuration, edit the CS.cfg as needed, then restart the server.

## AUTHORS
Dogtag PKI Team <devel@lists.dogtagpki.org>.

## SEE ALSO
pki-logging(5)

## COPYRIGHT
Copyright (c) 2016 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at ⟨http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt⟩.


title: pki_default.cfg(5)

text:
# pki_default.cfg(5)

## NAME
pki_default.cfg - PKI server default deployment configuration file.

## LOCATION
/usr/share/pki/server/etc/default.cfg

## DESCRIPTION
This file contains the default settings for a Certificate Server instance created using pkispawn. This file should not be edited, as it can be modified when the Certificate Server packages are updated. Instead, when setting up a Certificate Server instance, a user should provide pkispawn with a configuration file containing overrides to the defaults in /usr/share/pki/server/etc/default.cfg. See pkispawn(8) for details.

## SECTIONS
default.cfg contains parameters that are grouped into sections. These sections are stacked, so that parameters defined in earlier sections can be overwritten by parameters defined in later sections. The sections are read in the following order: [DEFAULT], [Tomcat], and the subsystem section ([CA], [KRA], [OCSP], [TKS], or [TPS]). This allows the ability to specify parameters to be shared by all subsystems in [DEFAULT] or [Tomcat], and subsystem-specific customization.

There are a small number of bootstrap parameters which are passed in the configuration file by pkispawn. Other parameter's values can be interpolated tokens rather than explicit values. For example:

```
pki_ca_signing_nickname=caSigningCert cert-%(pki_instance_name)s CA
```

This substitutes the value of pki_instance_name into the parameter value. It is possible to interpolate any non-password parameter within a section or in [DEFAULT]. Any parameter used in interpolation can ONLY be overridden within the same section. So, for example, pki_instance_name should only be overridden in [DEFAULT]; otherwise, interpolations can fail.

Note: Any non-password related parameter values in the configuration file that needs to contain a % character must be properly escaped. For example, a value of foo%bar would be specified as foo%%bar in the configuration file.

## PRE-CHECK PARAMETERS
Once the configuration parameters have been constructed from the above sections and overrides, pkispawn will perform a series of basic tests to determine if the parameters being passed in are valid and consistent, before starting any installation. In pre-check mode, these tests are executed and then pkispawn exits.

It is possible to disable specific tests by setting the directives below. While all these tests should pass to ensure a successful installation, it may be reasonable to skip tests in pre-check mode.

pki_skip_ds_verify

Skip verification of the Directory Server credentials. In this test, pkispawn attempts to bind to the directory server instance for the internal database using the provided credentials. This could be skipped if the directory server instance does not yet exist or is inaccessible. Defaults to False.

pki_skip_sd_verify

Skip verification of the security domain user/password. In this test, pkispawn attempts to log onto the security domain using the provided credentials. This can be skipped if the security domain is unavailable. Defaults to False.

## GENERAL INSTANCE PARAMETERS
The parameters described below, as well as the parameters located in the following sections, can be customized as part of a deployment. This list is not exhaustive.

pki_instance_name

Name of the instance. The instance is located at /var/lib/pki/instance_name. For Java subsystems, the default is specified as pki-tomcat.

pki_https_port, pki_http_port

Secure and unsecure ports. Defaults to standard Tomcat ports 8443 and 8090, respectively.

pki_ajp_port, pki_tomcat_server_port

Ports for Tomcat subsystems. Defaults to standard Tomcat ports of 8009 and 8005, respectively.

pki_ajp_host

Host on which to listen for AJP requests. Defaults to localhost4 to listen to local traffic only on IPv4 stack. NOTE Deprecated in favor of pki_ajp_host_ipv4.

pki_ajp_host_ipv4 Host on which to listen for AJP requests. Defaults to localhost4 to listen to local traffic only on IPv4 stack.

pki_ajp_host_ipv6 Host on which to listen for AJP requests. Defaults to localhost6 to listen to local traffic only on IPv6 stack.

pki_proxy_http_port, pki_proxy_https_port, pki_enable_proxy

Ports for an Apache proxy server. Certificate Server instances can be run behind an Apache proxy server, which will communicate with the Tomcat instance through the AJP port. See the Red Hat Certificate System documentation ⟨https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System⟩ for details.

pki_user, pki_group, pki_audit_group

Specifies the default administrative user, group, and auditor group identities for PKI instances. The default user and group are both specified as pkiuser, and the default audit group is specified as pkiaudit.

pki_token_name, pki_token_password

The token and password where this instance's system certificate and keys are stored. Defaults to the NSS internal software token.

pki_hsm_enable, pki_hsm_libfile, pki_hsm_modulename

If an optional hardware security module (HSM) is being utilized (rather than the default software security module included in NSS), then the pki_hsm_enable parameter must be set to True (by default this parameter is False), and values must be supplied for both the pki_hsm_libfile (e.g. /opt/nfast/toolkits/pkcs11/libcknfast.so) and pki_hsm_modulename parameters (e.g. nethsm).

### SYSTEM CERTIFICATE PARAMETERS
pkispawn sets up a number of system certificates for each subsystem. The system certificates which are required differ between subsystems. Each system certificate is denoted by a tag, as noted below. The different system certificates are:

- signing certificate ("ca_signing"). Used to sign other certificates. Required for CA.

- OCSP signing certificate ("ocsp_signing" in CA, "signing" in OCSP). Used to sign CRLs. Required for OCSP and CA.

- storage certificate ("storage"). Used to encrypt keys for storage in KRA. Required for KRA only.

- transport certificate ("transport"). Used to encrypt keys in transport to the KRA. Required for KRA only.

- subsystem certificate ("subsystem"). Used to communicate between subsystems within the security domain. Issued by the security domain CA. Required for all subsystems.

- server certificate ("sslserver"). Used for communication with the server. One server certificate is required for each Certificate Server instance.

- audit signing certificate ("audit_signing"). Used to sign audit logs. Required for all subsystems except the RA.

Each system certificate can be customized using the parameters below:

pki_<tag>_key_type, pki_<type>_key_size, pki_<tag>_key_algorithm

Characteristics of the private key. See the Red Hat Certificate System documentation ⟨https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System⟩ for possible options. The defaults are RSA for the type, 2048 bits for the key size, and SHA256withRSA for the algorithm.

pki_<tag>_signing_algorithm

For signing certificates, the algorithm used for signing. Defaults to SHA256withRSA.

pki_<tag>_token

Location where the certificate and private key are stored. Defaults to the internal software NSS token database.

pki_<tag>_nickname

Nickname for the certificate in the token database.

pki_<tag>_subject_dn

Subject DN for the certificate. The subject DN for the SSL Server certificate must include CN=hostname.

All system certs can be configured to request the PSS variant of rsa signing algorithms (when applicable).

pki_use_pss_rsa_signing_algorithm

Set this to True if algs such as SHA256withRSA/PSS for each subsystem signing algorithm is desired. The default is false. If set only, this setting will cause all other signing algorithm values to be promoted to <alg>/PSS.

Ex: (SHA256withRSA/PSS)

If this setting is not set, the standard default algorithms will continue to be used, without PSS support.. If higher than 256 support is desired, each algorithm must be set explicitly, example:

pki_ca_signing_key_algorithm=SHA512withRSA/PSS

### ADMIN USER PARAMETERS
pkispawn creates a bootstrap administrative user that is a member of all the necessary groups to administer the installed subsystem. On a security domain CA, the CA administrative user is also a member of the groups required to register a new subsystem on the security domain. The certificate and keys for this administrative user are stored in a PKCS #12 file in pki_client_dir, and can be imported into a browser to administer the system.

pki_admin_name, pki_admin_uid

Name and UID of this administrative user. Defaults to caadmin for CA, kraadmin for KRA, etc.

pki_admin_password

Password for the admin user. This password is used to log into the pki-console (unless client authentication is enabled), as well as log into the security domain CA.

pki_admin_email

Email address for the admin user.

pki_admin_dualkey, pki_admin_key_size, pki_admin_key_type, pki_admin_key_algorithm

Settings for the administrator certificate and keys.

pki_admin_subject_dn

Subject DN for the administrator certificate. Defaults to cn=PKI Administrator, e=%(pki_admin_email)s, o=%(pki_security_domain_name)s.

pki_admin_nickname

Nickname for the administrator certificate.

pki_import_admin_cert

Set to True to import an existing admin certificate for the admin user, rather than generating a new one. A subsystem-specific administrator will still be created within the subsystem's LDAP tree. This is useful to allow multiple subsystems within the same instance to be more easily administered from the same browser by using a single certificate.

By default, this is set to False for CA subsystems and true for KRA, OCSP, TKS, and TPS subsystems. In this case, the admin certificate is read from the file ca_admin.cert in pki_client_dir.

Note that cloned subsystems do not create a new administrative user. The administrative user of the master subsystem is used instead, and the details of this master user are replicated during the install.

pki_client_admin_cert_p12

Location for the PKCS #12 file containing the administrative user's certificate and keys. For a CA, this defaults to ca_admin_cert.p12 in the pki_client_dir directory.

### BACKUP PARAMETERS
pki_backup_keys, pki_backup_file, pki_backup_password

Set pki_backup_keys to True to back up the subsystem certificates and keys to a PKCS #12 file specified in pki_backup_file (default is /var/lib/pki/instance_name/conf/alias/subsystem_backup_keys.p12). pki_backup_password is the password of the PKCS#12 file.

Important: Keys in HSM may not be extractable, so they may not be able to be exported into a PKCS #12 file. Therefore, if pki_hsm_enable is set to True, pki_backup_keys should be set to False and pki_backup_password should be left unset (the default values in /usr/share/pki/server/etc/default.cfg). Failure to do so will result in pkispawn reporting this error and exiting.

### CLIENT DIRECTORY PARAMETERS
pki_client_dir

This is the location where all client data used during the installation is stored. At the end of the invocation of pkispawn, the administrative user's certificate and keys are stored in a PKCS #12 file in this location.

Note: When using an HSM, it is currently recommended to NOT specify a value for pki_client_dir that is different from the default value.

pki_client_database_dir, pki_client_database_password

Location where an NSS token database is created in order to generate a key for the administrative user. Usually, the data in this location is removed at the end of the installation, as the keys and certificates are stored in a PKCS #12 file in pki_client_dir.

pki_client_database_purge

Set to True to remove pki_client_database_dir at the end of the installation. Defaults to True.

### INTERNAL DATABASE PARAMETERS
pki_ds_url

URL for the internal database. For plain LDAP connection use ldap://<hostname>:<port>. For secure LDAP connection use ldaps://<hostname>:<port>. Defaults to ldap://localhost:389.

pki_ds_hostname, pki_ds_ldap_port, pki_ds_ldaps_port

Hostname and ports for the internal database. Defaults to localhost, 389, and 636, respectively. NOTE Deprecated in favor of pki_ds_url.

pki_ds_bind_dn, pki_ds_password

Credentials to connect to the database during installation. Directory Manager-level access is required during installation to set up the relevant schema and database. During the installation, a more restricted PKI user is set up to client authentication connections to the database. Some additional configuration is required, including setting up the directory server to use SSL. See the documentation for details.

pki_ds_secure_connection

Sets whether to require connections to the Directory Server using LDAPS. This requires SSL to be set up on the Directory Server first. Defaults to false. NOTE Deprecated in favor of pki_ds_url.

pki_ds_secure_connection_ca_nickname

Once a Directory Server CA certificate has been imported into the PKI security databases (see pki_ds_secure_connection_ca_pem_file), pki_ds_secure_connection_ca_nickname will contain the nickname under which it is stored. The default.cfg file contains a default value for this nickname. This parameter is only utilized when pki_ds_secure_connection has been set to true.

pki_ds_secure_connection_ca_pem_file

The pki_ds_secure_connection_ca_pem_file parameter will consist of the fully-qualified path including the filename of a file which contains an exported copy of a Directory Server's CA certificate. While this parameter is only utilized when pki_ds_secure_connection has been set to true, a valid value is required for this parameter whenever this condition exists.

pki_ds_remove_data

Sets whether to remove any data from the base DN before starting the installation. Defaults to True.

pki_ds_base_dn

The base DN for the internal database. It is advised that the Certificate Server have its own base DN for its internal database. If the base DN does not exist, it will be created during the running of pkispawn. For a cloned subsystem, the base DN for the clone subsystem MUST be the same as for the master subsystem.

pki_ds_database

Name of the back-end database. It is advised that the Certificate Server have its own base DN for its internal database. If the back-end does not exist, it will be created during the running of pkispawn.

### ISSUING CA PARAMETERS
pki_issuing_ca_hostname, pki_issuing_ca_https_port, pki_issuing_ca_uri

Hostname and port, or URI of the issuing CA. Required for installations of subordinate CA and non-CA subsystems. This should point to the CA that will issue the relevant system certificates for the subsystem. In a default install, this defaults to the CA subsystem within the same instance. The URI has the format https://ca_hostname:ca_https_port.

### MISCELLANEOUS PARAMETERS
pki_enable_access_log

Located in the [Tomcat] section, this variable determines whether the instance will enable (True) or disable (False) Tomcat access logging. Defaults to True.

pki_enable_java_debugger

Sets whether to attach a Java debugger such as Eclipse to the instance for troubleshooting. Defaults to False.

pki_enable_on_system_boot

Sets whether or not PKI instances should be started upon system boot.

Currently, if this PKI subsystem exists within a shared instance, and it has been configured to start upon system boot, then ALL other previously configured PKI subsystems within this shared instance will start upon system boot.

Similarly, if this PKI subsystem exists within a shared instance, and it has been configured to NOT start upon system boot, then ALL other previously configured PKI subsystems within this shared instance will NOT start upon system boot.

Additionally, if more than one PKI instance exists, no granularity exists which allows one PKI instance to be enabled while another PKI instance is disabled (i.e. PKI instances are either all enabled or all disabled). To provide this capability, the PKI instances must reside on separate machines.

Defaults to True (see the following note on why this was previously 'False').

Note: Since this parameter did not exist prior to Dogtag 10.2.3, the default behavior of PKI instances in Dogtag 10.2.2 and prior was False. To manually enable this behavior, obtain superuser privileges, and execute 'systemctl enable pki-tomcatd.target'; to manually disable this behavior, execute 'systemctl disable pki-tomcatd.target'.

pki_security_manager

Enables the Java security manager policies provided by the JDK to be used with the instance. Defaults to False.

### SECURITY DOMAIN PARAMETERS
The security domain is a component that facilitates communication between subsystems. The first CA installed hosts this component and is used to register subsequent subsystems with the security domain. These subsystems can communicate with each other using their subsystem certificate, which is issued by the security domain CA. For more information about the security domain component, see the Red Hat Certificate System documentation ⟨https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System⟩.

pki_security_domain_hostname, pki_security_domain_https_port

Location of the security domain. Required for KRA, OCSP, TKS, and TPS subsystems and for CA subsystems joining a security domain. Defaults to the location of the CA subsystem within the same instance.

pki_security_domain_user, pki_security_domain_password

Administrative user of the security domain. Required for KRA, OCSP, TKS, and TPS subsystems, and for CA subsystems joining a security domain. Defaults to the administrative user for the CA subsystem within the same instance (caadmin).

pki_security_domain_name

The name of the security domain. This is required for the security domain CA.

### CLONE PARAMETERS
pki_clone

Installs a clone, rather than original, subsystem.

pki_clone_pkcs12_password, pki_clone_pkcs12_path

Location and password of the PKCS #12 file containing the system certificates for the master subsystem being cloned. This file should be readable by the user that the Certificate Server is running as (default of pkiuser), and have the correct selinux context (pki_tomcat_cert_t). This can be achieved by placing the file in /var/lib/pki/instance_name/alias.

Important: Keys in HSM may not be extractable, so they may not be able to be exported into a PKCS #12 file. For the case of clones using an HSM, this means that the HSM keys must be shared between the master and its clones. Therefore, if pki_hsm_enable is set to True, both pki_clone_pkcs12_path and pki_clone_pkcs12_password should be left unset (the default values in /usr/share/pki/server/etc/default.cfg). Failure to do so will result in pkispawn reporting this error and exiting.

pki_clone_setup_replication

Defaults to True. If set to False, the installer does not set up replication agreements from the master to the clone as part of the subsystem configuration. In this case, it is expected that the top level suffix already exists, and that the data has already been replicated. This option is useful if you want to use other tools to create and manage your replication topology, or if the baseDN is already replicated as part of a top-level suffix.

pki_clone_reindex_data

Defaults to False. If set to True, the installer rebuilds the search indexes on the clone.

pki_clone_replication_master_port, pki_clone_replication_clone_port

Ports on which replication occurs. These are the ports on the master and clone databases respectively. Defaults to the internal database port.

pki_clone_replicate_schema

Replicate schema when the replication agreement is set up and the new instance (consumer) is initialized. Otherwise, the schema must be installed in the clone as a separate step beforehand. This does not usually have to be changed. Defaults to True.

pki_clone_replication_security

The type of security used for the replication data. This can be set to SSL (using LDAPS), TLS, or None. Defaults to None. For SSL and TLS, SSL must be set up for the database instances beforehand.

pki_master_hostname, pki_master_https_port, pki_clone_uri

Hostname and port, or URI of the subsystem being cloned. The URI format is https://master_hostname:master_https_port where the default master hostname and https port are set to be the security domain's hostname and https port.

### CA SERIAL NUMBER PARAMETERS
pki_serial_number_range_start, pki_serial_number_range_end

Sets the range of serial numbers to be used when issuing certificates. Values here are hexadecimal (without the 0x prefix). It is useful to override these values when migrating data from another CA, so that serial number conflicts do not occur. Defaults to 1 and 10000000 respectively.

pki_request_number_range_start, pki_request_number_range_end

Sets the range of request numbers to be used by the CA. Values here are decimal. It is useful to override these values when migrating data from another CA, so that request number conflicts do not occur. Defaults to 1 and 10000000 respectively.

pki_replica_number_range_start, pki_replica_number_range_end

Sets the range of replica numbers to be used by the CA. These numbers are used to identify database replicas in a replication topology. Values here are decimal. Defaults to 1 and 100 respectively.

### EXTERNAL CA CERTIFICATE PARAMETERS
pki_external

Sets whether the new CA will have a signing certificate that will be issued by an external CA. This is a two step process. In the first step, a CSR to be presented to the external CA is generated. In the second step, the issued signing certificate and certificate chain are provided to the pkispawn utility to complete the installation. Defaults to False.

pki_ca_signing_csr_path

Required in the first step of the external CA signing process. The CSR will be printed to the screen and stored in this location.

pki_req_ski

Include a Subject Key Identifier extension in the CSR. The value is either a hex-encoded byte string (without leading "0x"), or the string "DEFAULT" which will derive a value from the public key.

pki_external_step_two

Specifies that this is the second step of the external CA process. Defaults to False.

pki_ca_signing_cert_path, pki_cert_chain_path

Required for the second step of the external CA signing process. This is the location of the CA signing cert (as issued by the external CA) and the external CA's certificate chain.

### SUBORDINATE CA CERTIFICATE PARAMETERS
pki_subordinate

Specifies whether the new CA which will be a subordinate of another CA. The master CA is specified by pki_issuing_ca. Defaults to False.

pki_subordinate_create_new_security_domain

Set to True if the subordinate CA will host its own security domain. Defaults to False.

pki_subordinate_security_domain_name

Used when pki_subordinate_create_security_domain is set to True. Specifies the name of the security domain to be hosted on the subordinate CA.

### STANDALONE PKI PARAMETERS
A stand-alone PKI subsystem is defined as a non-CA PKI subsystem that does not contain a CA as a part of its deployment, and functions as its own security domain. Currently, only stand-alone KRAs are supported.

pki_standalone

Sets whether or not the new PKI subsystem will be stand-alone. This is a two step process. In the first step, CSRs for each of this stand-alone PKI subsystem's certificates will be generated so that they may be presented to the external CA. In the second step, the issued certificates, external CA certificate, and external CA certificate chain are provided to the pkispawn utility to complete the installation. Defaults to False.

pki_admin_csr_path

Will be generated by the first step of a stand-alone PKI process. This is the location of the file containing the administrator's CSR (which will be presented to the external CA). Defaults to empty.

pki_audit_signing_csr_path

Will be generated by the first step of a stand-alone PKI process. This is the location of the file containing the audit signing CSR (which will be presented to the external CA). Defaults to empty.

pki_sslserver_csr_path

Will be generated by the first step of a stand-alone PKI process. This is the location of the file containing the SSL server CSR (which will be presented to the external CA). Defaults to empty.

pki_storage_csr_path

[KRA ONLY] Will be generated by the first step of a stand-alone KRA process. This is the location of the file containing the storage CSR (which will be presented to the external CA). Defaults to empty.

pki_subsystem_csr_path

Will be generated by the first step of a stand-alone PKI process. This is the location of the file containing the subsystem CSR (which will be presented to the external CA). Defaults to empty.

pki_transport_csr_path

[KRA ONLY] Will be generated by the first step of a stand-alone KRA process. This is the location of the file containing the transport CSR (which will be presented to the external CA). Defaults to empty.

pki_external_step_two

Specifies that this is the second step of a standalone PKI process. Defaults to False.

pki_cert_chain_path

Required for the second step of a stand-alone PKI process. This is the location of the file containing the external CA signing certificate (as issued by the external CA). Defaults to /var/lib/pki/instance_name/conf/external_ca.cert.

pki_ca_signing_cert_path

Required for the second step of a stand-alone PKI process. This is the location of the file containing the external CA's certificate chain (as issued by the external CA). Defaults to empty.

pki_admin_cert_path

Required for the second step of a stand-alone PKI process. This is the location of the file containing the administrator's certificate (as issued by the external CA). Defaults to empty.

pki_audit_signing_cert_path

Required for the second step of a stand-alone PKI process. This is the location of the file containing the audit signing certificate (as issued by the external CA). Defaults to empty.

pki_sslserver_cert_path

Required for the second step of a stand-alone PKI process. This is the location of the file containing the sslserver certificate (as issued by the external CA). Defaults to empty.

pki_storage_cert_path

[KRA ONLY] Required for the second step of a stand-alone KRA process. This is the location of the file containing the storage certificate (as issued by the external CA). Defaults to empty.

pki_subsystem_cert_path

Required for the second step of a stand-alone PKI process. This is the location of the file containing the subsystem certificate (as issued by the external CA). Defaults to empty.

pki_transport_cert_path

[KRA ONLY] Required for the second step of a stand-alone KRA process. This is the location of the file containing the transport certificate (as issued by the external CA). Defaults to empty.

### KRA PARAMETERS
pki_kra_ephemeral_requests

Specifies to use ephemeral requests for archivals and retrievals. Defaults to False.

### TPS PARAMETERS
pki_authdb_basedn

Specifies the base DN of TPS authentication database.

pki_authdb_url

URL of TPS authentication database. For plain LDAP connection use ldap://<hostname>:<port>. For secure LDAP connection use ldaps://<hostname>:<port>. Defaults to ldap://localhost:389.

pki_authdb_hostname

Specifies the hostname of TPS authentication database. Defaults to localhost. NOTE Deprecated in favor of pki_authdb_url.

pki_authdb_port

Specifies the port number of TPS authentication database. Defaults to 389. NOTE Deprecated in favor of pki_authdb_url.

pki_authdb_secure_conn

Specifies whether to use a secure connection to TPS authentication database. Defaults to False. NOTE Deprecated in favor of pki_authdb_url.

pki_enable_server_side_keygen

Specifies whether to enable server-side key generation. Defaults to False. The location of the KRA instance should be specified in the pki_kra_uri parameter.

pki_ca_uri

Specifies the URI of the CA instance used by TPS to create and revoke user certificates. Defaults to the instance in which the TPS is running.

pki_kra_uri

Specifies the URI of the KRA instance used by TPS to archive and recover keys. Required if server-side key generation is enabled using the pki_enable_server_side_keygen parameter. Defaults to the instance in which the TPS is running.

pki_tks_uri

Specifies the URI of the TKS instance used by TPS to generate symmetric keys. Defaults to the instance in which the TPS is running.

## SEE ALSO
pkispawn(8)

## AUTHORS
Ade Lee <alee@redhat.com>.

## COPYRIGHT
Copyright (c) 2012 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at ⟨http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt⟩.


pki-tps-connector

package: dogtag-pki-tps

title: pki-tps-connector(5)

summary: PKI TPS Connector Configuration

text:
# pki-tps-connector(5)

## NAME
pki-tps-connector - PKI TPS Connector Configuration

## LOCATION
/var/lib/pki/instance/conf/tps/CS.cfg

## DESCRIPTION
TPS connector provides a mechanism for TPS to communicate with other PKI subsystems. There are three supported connector types: CA, KRA, and TKS. The connectors are defined using properties in the TPS configuration file.

## CA CONNECTOR
A CA connector is defined using properties that begin with tps.connector.ca<n> where n is a positive integer indicating the ID of the CA connector.

tps.connector.ca<n>.enable

This property contains a boolean value indicating whether the connector is enabled.

tps.connector.ca<n>.host

In no-failover configuration, the property contains the hostname of the CA.

In failover configuration, the property contains a list of hostnames and port numbers of the CA subsystems. The format is hostname:port separated by spaces.

tps.connector.ca<n>.port

In no-failover configuration, the property contains the port number of the CA.

tps.connector.ca<n>.nickName

This property contains the nickname of the TPS subsystem certificate for SSL client authentication to the CA.

tps.connector.ca<n>.minHttpConns

This property contains the minimum number of HTTP connections.

tps.connector.ca<n>.maxHttpConns

This property contains the maximum number of HTTP connections.

tps.connector.ca<n>.uri.<op>

This property contains the URI to contact CA for the operation <op>. Example ops: enrollment, renewal, revoke, unrevoke, getcert.

tps.connector.ca<n>.timeout

This property contains the connection timeout.

tps.connCAList

This property is used for Revocation Routing. It contains a list of ordered ca id's separated by ',' that the revocation attempt should be made to. Example: tps.connCAList=ca1,ca2

tps.connector.ca<n>.caNickname

This property is used for Revocation Routing. It contains the nickname of the CA signing certificate that represents this ca<n>.

tps.connector.ca<n>.caSKI

This property is used for Revocation Routing. It contains the Subject Key Identifier of the CA signing certificate of this ca<n>. This value is automatically calculated by TPS once and should not need handling by the administrator.

## KRA CONNECTOR
A KRA connector is defined using properties that begin with tps.connector.kra<n> where n is a positive integer indicating the ID of the KRA connector.

tps.connector.kra<n>.enable

This property contains a boolean value indicating whether the connector is enabled.

tps.connector.kra<n>.host

In no-failover configuration, the property contains the hostname of the KRA.

In failover configuration, the property contains a list of hostnames and port numbers of the KRA subsystems. The format is hostname:port separated by spaces.

tps.connector.kra<n>.port

In no-failover configuration, the property contains the port number of the KRA.

tps.connector.kra<n>.nickName

This property contains the nickname of the TPS subsystem certificate for SSL client authentication to the KRA.

tps.connector.kra<n>.minHttpConns

This property contains the minimum number of HTTP connections.

tps.connector.kra<n>.maxHttpConns

This property contains the maximum number of HTTP connections.

tps.connector.kra<n>.uri.<op>

This property contains the URI to contact KRA for the operation <op>. Example ops: GenerateKeyPair, TokenKeyRecovery.

tps.connector.kra<n>.timeout

This property contains the connection timeout.

## TKS CONNECTOR
A TKS connector is defined using properties that begin with tps.connector.tks<n> where n is a positive integer indicating the ID of the TKS connector.

tps.connector.tks<n>.enable

This property contains a boolean value indicating whether the connector is enabled.

tps.connector.tks<n>.host

In no-failover configuration, the property contains the hostname of the TKS.

In failover configuration, the property contains a list of hostnames and port numbers of the TKS subsystems. The format is hostname:port separated by spaces.

tps.connector.tks<n>.port

In no-failover configuration, the property contains the port number of the TKS.

tps.connector.tks<n>.nickName

This property contains the nickname of the TPS subsystem certificate for SSL client authentication to the TKS.

tps.connector.tks<n>.minHttpConns

This property contains the minimum number of HTTP connections.

tps.connector.tks<n>.maxHttpConns

This property contains the maximum number of HTTP connections.

tps.connector.tks<n>.uri.<op>

This property contains the URI to contact TKS for the operation <op>. Example ops: computeRandomData, computeSessionKey, createKeySetData, encryptData.

tps.connector.tks<n>.timeout

This property contains the connection timeout.

tps.connector.tks<n>.generateHostChallenge

This property contains a boolean value indicating whether to generate host challenge.

tps.connector.tks<n>.serverKeygen

This property contains a boolean value indicating whether to generate keys on server side.

tps.connector.tks<n>.keySet

This property contains the key set to be used on TKS.

tps.connector.tks<n>.tksSharedSymKeyName

This property contains the shared secret key name.

## EXAMPLE

```
tps.connector.ca1.enable=true
tps.connector.ca1.host=pki.example.com
tps.connector.ca1.port=8443
tps.connector.ca1.minHttpConns=1
tps.connector.ca1.maxHttpConns=15
tps.connector.ca1.nickName=subsystemCert cert-pki-tomcat TPS
tps.connector.ca1.timeout=30
tps.connector.ca1.uri.enrollment=/ca/ee/ca/profileSubmitSSLClient
tps.connector.ca1.uri.renewal=/ca/ee/ca/profileSubmitSSLClient
tps.connector.ca1.uri.revoke=/ca/ee/subsystem/ca/doRevoke
tps.connector.ca1.uri.unrevoke=/ca/ee/subsystem/ca/doUnrevoke
# in case of Revocation Routing
# note that caSKI is automatically calculated by TPS
tps.connCAList=ca1,ca2
tps.connector.ca1.caNickname=caSigningCert cert-pki-tomcat CA
tps.connector.ca1.caSKI=hAzNarQMlzit4BymAlbduZMwVCc
# ca2 connector in case of Revocation Routing
tps.connector.ca2.<etc.>
tps.connector.kra1.enable=true
tps.connector.kra1.host=pki.example.com
tps.connector.kra1.port=8443
tps.connector.kra1.minHttpConns=1
tps.connector.kra1.maxHttpConns=15
tps.connector.kra1.nickName=subsystemCert cert-pki-tomcat TPS
tps.connector.kra1.timeout=30
tps.connector.kra1.uri.GenerateKeyPair=/kra/agent/kra/GenerateKeyPair
tps.connector.kra1.uri.TokenKeyRecovery=/kra/agent/kra/TokenKeyRecovery
tps.connector.tks1.enable=true
tps.connector.tks1.host=pki.example.com
tps.connector.tks1.port=8443
tps.connector.tks1.minHttpConns=1
tps.connector.tks1.maxHttpConns=15
tps.connector.tks1.nickName=subsystemCert cert-pki-tomcat TPS
tps.connector.tks1.timeout=30
tps.connector.tks1.generateHostChallenge=true
tps.connector.tks1.serverKeygen=false
tps.connector.tks1.keySet=defKeySet
tps.connector.tks1.tksSharedSymKeyName=sharedSecret
tps.connector.tks1.uri.computeRandomData=/tks/agent/tks/computeRandomData
tps.connector.tks1.uri.computeSessionKey=/tks/agent/tks/computeSessionKey
tps.connector.tks1.uri.createKeySetData=/tks/agent/tks/createKeySetData
tps.connector.tks1.uri.encryptData=/tks/agent/tks/encryptData
```

## AUTHORS
Dogtag PKI Team <devel@lists.dogtagpki.org>.

## COPYRIGHT
Copyright (c) 2014 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at ⟨http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt⟩.


pki-tps-profile

title: pki-tps-profile(5)

summary: PKI TPS Profile Configuration

text:
# pki-tps-profile(5)

## NAME
pki-tps-profile - PKI TPS Profile Configuration

## LOCATION
/var/lib/pki/instance/conf/tps/CS.cfg

## DESCRIPTION
Token profiles are defined using properties in the TPS configuration file.

### Enrollment Operation For CoolKey
The following property sets the size of the key the token should generate:

```
op.enroll.<tokenType>.keyGen.<keyType>.keySize=1024
```

The maximum value is 1024.

The following properties specify the PKCS11 attributes to set on the token:

```
op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.encrypt=false
op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.sign=true
op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.signRecover=true
op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.decrypt=false
op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.derive=false
op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.unwrap=false
op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.wrap=false
op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.verifyRecover=true
op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.verify=true
op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.sensitive=true
op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.private=true
op.enroll.<tokenType>.keyGen.<keyType>.keyCapabilities.token=true
```

The following property specifies the CUID shown in the certificate:

```
op.enroll.<tokenType>.keyGen.<keyType>.cuid_label
```

The following property specifies the token name:

```
op.enroll.<tokenType>.keyGen.<keyType>.label
```

The following variables can be used in the token name:

- $pretty_cuid$ - Pretty Print CUID (i.e. 4090-0062-FF02-0000-0B9C)

- $cuid$ - CUID (i.e. 40900062FF0200000B9C)

- $msn$ - MSN

- $userid$ - User ID

- $profileId$ - Profile ID

All resulting labels for co-existing keys on the same token must be unique.

The following property determines whether TPS will overwrite key and certificate if they already exist:

```
op.enroll.<tokenType>.keyGen.<keyType>.overwrite=true|false
```

The following properties specify name PKCS11 object IDs:

```
op.enroll.<tokenType>.keyGen.<keyType>.certId=C1
op.enroll.<tokenType>.keyGen.<keyType>.certAttrId=c1
op.enroll.<tokenType>.keyGen.<keyType>.privateKeyAttrId=k2
op.enroll.<tokenType>.keyGen.<keyType>.publicKeyAttrId=k3
op.enroll.<tokenType>.keyGen.<keyType>.privateKeyNumber=2
op.enroll.<tokenType>.keyGen.<keyType>.publicKeyNumber=3
```

Lower case letters signify objects containing PKCS11 object attributes in the format described below:

- c - An object containing PKCS11 attributes for a certificate.

- k - An object containing PKCS11 attributes for a public or private key

- r - An object containing PKCS11 attributes for an "reader".

Upper case letters signify objects containing raw data corresponding to the lower case letters described above. For example, object C0 contains raw data corresponding to object c0.

- C - This object contains an entire DER cert, and nothing else.

- K - This object contains a MUSCLE "key blob". TPS does not use this.

The following properties specify the algorithm, the key size, the key usage, and which PIN user should be granted:

```
op.enroll.<tokenType>.keyGen.<keyType>.alg=2
op.enroll.<tokenType>.keyGen.<keyType>.keySize=1024
op.enroll.<tokenType>.keyGen.<keyType>.keyUsage=0
op.enroll.<tokenType>.keyGen.<keyType>.keyUser=0
```

The valid algorithms are:

- 2 - RSA

- 5 - ECC

For ECC, the valid key sizes are 256 and 384.

Use privilege of the generated private key, or 15 if all users have use privilege for the private key. Valid usages: (only specifies the usage for the private key)

- 0 - default usage (Signing only for this APDU)

- 1 - signing only

- 2 - decryption only

- 3 - signing and decryption

The following property determines whether to enable writing of PKCS11 cache object to the token:

```
op.enroll.<tokenType>.pkcs11obj.enable=true|false
```

The following property determines whether to enable compression for writing of PKCS11 cache object to the token:

```
op.enroll.<tokenType>.pkcs11obj.compress.enable=true|false
```

The following property determines the maximum number of retries before blocking the token:

```
op.enroll.<tokenType>.pinReset.pin.maxRetries=127
```

The maximum value is 127.

There is a special case of tokenType userKeyTemporary. Make sure the profile specified by the profileId to have short validity period (e.g. 7 days) for the certificate.

```
op.enroll.userKey.keyGen.<keyType>.publisherId=fileBasedPublisher
op.enroll.userKeyTemporary.keyGen.<keyType>.publisherId=fileBasedPublisher
```

The folowing property describes the scheme used for recovery:

```
op.enroll.<tokenType>.keyGen.<keyType>.recovery.<tokenState>.scheme=GenerateNewKey
```

The three recovery schemes supported are:

- GenerateNewKey - Generate a new cert for the encryption cert.

- RecoverLast - Recover the most recent cert for the encryption cert.

- GenerateNewKeyandRecoverLast - Generate new cert AND recover last for encryption cert.

### Token Renewal
The following properties are used to define token renewal:

```
op.enroll.<tokenType>.renewal.*
```

For each token in TPS UI, set the following to trigger renewal operations:

```
RENEW=YES
```

Optional grace period enforcement must coincide exactly with what the CA enforces.

In case of renewal, encryption certId values are for completeness only, server code calculates actual values used.

### Format Operation For tokenKey
The following property determines whether to update applet if the token is empty:

```
op.format.<tokenType>.update.applet.emptyToken.enable=false
```

The property is applicable to:

- CoolKey

- HouseKey

- HouseKey with Legacy Applet

### Certificate Chain Imports

```
op.enroll.certificates.num=1
op.enroll.certificates.value.0=caCert
op.enroll.certificates.caCert.nickName=caCert0 pki-tps
op.enroll.certificates.caCert.certId=C5
op.enroll.certificates.caCert.certAttrId=c5
op.enroll.certificates.caCert.label=caCert Label
```

### Pin Reset Operation For CoolKey
The following property determines whether to update applet if the token is empty:

```
op.pinReset.<tokenType>.update.applet.emptyToken.enable=false
```

The property is not applicable to:

- HouseKey

- HouseKey with Legacy Applet

## SEE ALSO
pki-tps-profile(1)

## AUTHORS
Dogtag PKI Team <devel@lists.dogtagpki.org>.

## COPYRIGHT
Copyright (c) 2014 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at ⟨http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt⟩.


apt-cudf.conf

title: apt-cudf.conf(5)

summary: Configuration file for apt\-cudf

text:
# apt-cudf.conf(5)

## NAME
apt-cudf.conf - Configuration file for apt-cudf

## DESCRIPTION
The configuration file allows one to define default optimization criteria for all solvers known by apt-cudf

## SYNTAX

```
  solver: <solver list> | '*'
```

A comma-separated list of solvers. The character will make the optimization criteria as default for all solvers without a more specific definition.

```
  upgrade: <optimization criteria>
  dist-upgrade: <optimization criteria>
  install: <optimization criteria>
  remove: <optimization criteria>
```

Default optimization criteria associated to apt-get actions. The optimization criteria is solver specific. Specifying a incorrect criteria will result in an error from the underlying cudf solver. Please refere to the solver man page for the correct syntax

```
  trendy: <optimization criteria>
  paranoid: <optimization criteria>
  <keyword>: <optimization criteria>
```

Define a shortcut for an optimization criteria. The shortcut can then be used by apt-get to pass a specific optimization criteria for a cudf solver

```
  apt-get install gnome --solver aspcud -o "APT::Solver::aspcud::Preferences=trendy"
```

## EXAMPLE

```
  solver: mccs-cbc , mccs-lpsolve
  upgrade: -lex[-new,-removed,-notuptodate]
  dist-upgrade: -lex[-notuptodate,-new]
  install: -lex[-removed,-changed]
  remove: -lex[-removed,-changed]
  trendy: -lex[-removed,-notuptodate,-unsat_recommends,-new]
  paranoid: -lex[-removed,-changed]
  solver: *
  upgrade: -new,-removed,-notuptodate
  dist-upgrade: -notuptodate,-new
  install: -removed,-changed
  remove: -removed,-changed
  trendy: -removed,-notuptodate,-unsat_recommends,-new
  paranoid: -removed,-changed
```

## SEE ALSO
apt-cudf(8), apt-get(8), update-cudf-solvers(8), README.cudf-solvers <file:///usr/share/doc/apt-cudf/README.cudf-solvers>, README.Debian <file:///usr/share/doc/apt-cudf/README.Debian>

## AUTHOR
Copyright: (C) 2011 Pietro Abate <pietro.abate@pps.jussieu.fr> Copyright: (C) 2011 Stefano Zacchiroli <zack@debian.org>

License: GNU Lesser General Public License (GPL), version 3 or above


deb

package: dpkg

title: deb(5)

summary: Debian binary package format

text:
# deb(5)

## NAME
deb - Debian binary package format

## SYNOPSIS
filename.deb

## DESCRIPTION
The .deb format is the Debian binary package file format. It is understood since dpkg 0.93.76, and is generated by default since dpkg 1.2.0 and 1.1.1elf (i386/ELF builds).

The format described here is used since Debian 0.93; details of the old format are described in deb-old(5).

## FORMAT
The file is an ar archive with a magic value of !<arch>. Only the common ar archive format is supported, with no long file name extensions, but with file names containing an optional trailing slash, which limits their length to 15 characters (from the 16 allowed). File sizes are limited to 10 ASCII decimal digits, allowing for up to approximately 9536.74 MiB member files.

The tar archives currently allowed are, the old-style (v7) format, the pre-POSIX ustar format, a subset of the GNU format (new style long pathnames and long linknames, supported since dpkg 1.4.1.17; large file metadata since dpkg 1.18.24), and the POSIX ustar format (long names supported since dpkg 1.15.0). Unrecognized tar typeflags are considered an error. Each tar entry size inside a tar archive is limited to 11 ASCII octal digits, allowing for up to 8 GiB tar entries. The GNU large file metadata support permits 95-bit tar entry sizes and negative timestamps, and 63-bit UID, GID and device numbers.

The first member is named debian-binary and contains a series of lines, separated by newlines. Currently only one line is present, the format version number, 2.0 at the time this manual page was written. Programs which read new-format archives should be prepared for the minor number to be increased and new lines to be present, and should ignore these if this is the case.

If the major number has changed, an incompatible change has been made and the program should stop. If it has not, then the program should be able to safely continue, unless it encounters an unexpected member in the archive (except at the end), as described below.

The second required member is named control.tar. It is a tar archive containing the package control information, either not compressed (supported since dpkg 1.17.6), or compressed with gzip (with .gz extension) or xz (with .xz extension, supported since 1.17.6), zstd (with .zst extension, supported since dpkg 1.21.18), as a series of plain files, of which the file control is mandatory and contains the core control information, the md5sums, conffiles, triggers, shlibs and symbols files contain optional control information, and the preinst, postinst, prerm and postrm files are optional maintainer scripts. The control tarball may optionally contain an entry for ‘.’, the current directory.

The third, last required member is named data.tar. It contains the filesystem as a tar archive, either not compressed (supported since dpkg 1.10.24), or compressed with gzip (with .gz extension), xz (with .xz extension, supported since dpkg 1.15.6), zstd (with .zst extension, supported since dpkg 1.21.18), bzip2 (with .bz2 extension, supported since dpkg 1.10.24) or lzma (with .lzma extension, supported since dpkg 1.13.25).

These members must occur in this exact order. Current implementations should ignore any additional members after data.tar. Further members may be defined in the future, and (if possible) will be placed after these three. Any additional members that may need to be inserted after debian-binary and before control.tar or data.tar and which should be safely ignored by older programs, will have names starting with an underscore, ‘_’.

Those new members which won't be able to be safely ignored will be inserted before data.tar with names starting with something other than underscores, or will (more likely) cause the major version number to be increased.

## MEDIA TYPE

### Current
application/vnd.debian.binary-package

### Deprecated
application/x-debian-package

application/x-deb

## SEE ALSO
deb-old(5), dpkg-deb(1), deb-control(5), deb-conffiles(5), deb-md5sums(5), deb-triggers(5), deb-shlibs(5), deb-symbols(5), deb-preinst(5), deb-postinst(5), deb-prerm(5), deb-postrm(5).


deb-buildinfo

title: deb-buildinfo(5)

summary: Debian build information file format

text:
# deb-buildinfo(5)

## NAME
deb-buildinfo - Debian build information file format

## SYNOPSIS
filename.buildinfo

## DESCRIPTION
Each Debian source package build can record the build information in a .buildinfo control file, which contains a number of fields in deb822(5) format.

Each field begins with a tag, such as Source or Binary (case insensitive), followed by a colon, and the body of the field (case sensitive unless stated otherwise). Fields are delimited only by field tags. In other words, field text may be multiple lines in length, but the installation tools will generally join lines when processing the body of the field (except in case of the multiline fields Binary-Only-Changes, Installed-Build-Depends, Environment, Checksums-Md5, Checksums-Sha1 and Checksums-Sha256, see below).

The control data might be enclosed in an OpenPGP ASCII Armored signature, as specified in RFC4880.

The name of the .buildinfo file will depend on the type of build and will be as specific as necessary but not more; for a build that includes any the name will be source-name_binary-version_arch.buildinfo, or otherwise for a build that includes all the name will be source-name_binary-version_all.buildinfo, or otherwise for a build that includes source the name will be source-name_source-version_source.buildinfo.

## FIELDS
Format: format-version (required)

The value of this field declares the format version of the file. The syntax of the field value is a version number with a major and minor component. Backward incompatible changes to the format will bump the major version, and backward compatible changes (such as field additions) will bump the minor version. The current format version is 1.0.

Source: source-name [(source-version)] (required)

The name of the source package. If the source version differs from the binary version, then the source-name will be followed by a source-version in parenthesis. This can happen when the build is for a binary-only non-maintainer upload.

Binary: binary-package-list (required in context)

This folded field is a space-separated list of binary packages built. If the build is source-only, then the field is omitted (since dpkg 1.20.0).

Architecture: arch-list (required)

This space-separated field lists the architectures of the files currently being built. Common architectures are amd64, armel, i386, etc. Note that the all value is meant for packages that are architecture independent. If the source for the package is also being built, the special entry source is also present. Architecture wildcards must never be present in the list.

Version: version-string (required)

Typically, this is the original package's version number in whatever form the program's author uses. It may also include a Debian revision number (for non-native packages). The exact format and sorting algorithm are described in deb-version(7).

Binary-Only-Changes:

changelog-entry

This multiline field contains the concatenated text of the changelog entry for a binary-only non-maintainer upload (binNMU) if that is the case. To make this a valid multiline field empty lines are replaced with a single full stop (‘.’) and all lines are indented by one space character. The exact content depends on the changelog format.

Checksums-Md5: (required)

Checksums-Sha1: (required)

Checksums-Sha256: (required)

checksum size filename

These multiline fields contain a list of files with a checksum and size for each one. These fields have the same syntax and differ only in the checksum algorithm used: MD5 for Checksums-Md5, SHA-1 for Checksums-Sha1 and SHA-256 for Checksums-Sha256. The first line of the field value (the part on the same line as the field name followed by a colon) is always empty. The content of the field is expressed as continuation lines, one line per file. Each line consists of space-separated entries describing the file: the checksum, the file size, and the file name.

These fields list all files that make up the build.

Build-Origin: name

The name of the distribution this package is originating from.

Build-Architecture: arch (required)

The Debian architecture for the installation the packages is being built in. Common architectures are amd64, armel, i386, etc.

Build-Date: build-date

The date the package was built. It must be in the same format as the date in a deb-changelog(5) entry.

Build-Kernel-Version: build-kernel-version

The release and version (in an unspecified format) of the kernel running on the build system. This field is only going to be present if the builder has explicitly requested it, to avoid leaking possibly sensitive information.

Build-Path: build-path

The absolute build path, which correspond to the unpacked source tree. This field is only going to be present if the vendor has allowed it via some pattern match to avoid leaking possibly sensitive information. On Debian and derivatives only build paths starting with /build/ will emit this field.

Build-Tainted-By:

taint-reason-list

This folded field contains a space-separated list of non-exhaustive reason tags (formed by alphanumeric and dash characters) which identify why the current build has been tainted (since dpkg 1.19.5). On Debian and derivatives the following reason tags can be emitted:

merged-usr-via-aliased-dirs

The system has a merged /usr via aliased directories (previously known as merged-usr-via-symlinks). This will confuse dpkg-query, dpkg-statoverride, dpkg-trigger, update-alternatives and any other tool using pathnames as keys into their databases, as it creates filesystem aliasing problems, and messes with the understanding of the filesystem that dpkg has recorded in its database. For build systems that hardcode pathnames to specific binaries or libraries on the resulting artifacts, it can also produce packages that will be incompatible with non-/usr-merged filesystems.

usr-local-has-configs

The system has configuration files under /usr/local/etc.

usr-local-has-includes

The system has header files under /usr/local/include.

usr-local-has-programs

The system has programs under /usr/local/bin or /usr/local/sbin.

usr-local-has-libraries

The system has libraries, either static or shared under /usr/local/lib.

can-execute-cross-built-programs

The system can execute cross built programs, either directly or via some emulation layer. Since dpkg 1.21.10.

Installed-Build-Depends: (required)

package-list

The list of installed and configured packages that might affect the package build process. The list consists of each package name, optionally arch-qualified for foreign architectures, with an exact version restriction, separated by commas.

The list includes all essential packages, packages listed in Build-Depends, Build-Depends-Arch, Build-Depends-Indep source control fields, any vendor specific builtin dependencies, and all their recursive dependencies. On Debian and derivatives the dependency builtin is build-essential.

For dependencies coming from the source control fields, all dependency alternatives and all providers of virtual packages depended on will be included.

Environment:

variable-list

The list of environment variables that are known to affect the package build process, with each environment variable followed by an equal sign (‘=’) and the variable's quoted value, using double quotes (‘"’), and backslashes escaped (‘\\’).

## SEE ALSO
deb822(5), deb-changes(5), deb-version(7), dpkg-genbuildinfo(1).


deb-changelog

title: deb-changelog(5)

text:
# deb-changelog(5)

## NAME
deb-changelog - dpkg source packages' changelog file format

## SYNOPSIS
debian/changelog

## DESCRIPTION
Changes in the packaged version of a project are explained in the changelog file debian/changelog. This includes modifications made in the source package compared to the upstream one as well as other changes and updates to the package.

The format of the debian/changelog allows the package building tools to discover which version of the package is being built and find out other release-specific information.

That format is a series of entries like this:

package (version) distributions; metadata

[optional blank line(s), stripped]

* change-details

more-change-details

[blank line(s), included in dpkg-parsechangelog(1) output]

* even-more-change-details

[optional blank line(s), stripped]

-- maintainer-name <email-address> date

package and version are the source package name and version number. version is delimited by parenthesis U+00028 ‘(’ and U+0029 ‘)’.

distributions lists one or more space-separated distributions where this version should be installed when it is uploaded; it is copied to the Distribution field in the .changes file. distributions must be terminated by a semicolon (U+003B ‘;’).

metadata lists zero or more comma-separated keyword=value items. Each keyword can contain only minus and case insensitive alphanumeric characters, as they need to be mapped to deb822(5) field names. The only keywords currently supported by dpkg are urgency and binary-only. urgency's value is used for the Urgency field in the .changes file for the upload. binary-only with a yes value, is used to denote that this changelog entry is for a binary-only non-maintainer upload (an automatic binary rebuild with the only change being the changelog entry).

The change details may in fact be any series of lines starting with at least two spaces (U+0020 SPACE), but conventionally each change starts with an asterisk and a separating space and continuation lines are indented so as to bring them in line with the start of the text above. Blank lines may be used here to separate groups of changes, if desired.

If this upload resolves bugs recorded in the distribution bug tracking system, they may be automatically closed on the inclusion of this package into the distribution archive by including the string:

Closes: #nnnnn

in the change details, where #nnnnn is the bug number. The exact Perl regular expression is:

/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i

That is, the string should consist of the word closes: followed by a comma-separated list of bug numbers. Bug numbers may be preceded by the word bug and/or a # sign, as in "Closes: 42, bug#43, #44, bug 45". The words closes: and bug are not case sensitive. The list of bug numbers may span multiple lines.

This information is conveyed via the Closes field in the .changes file. Where, depending on the archive maintenance software, all the bug numbers listed might get automatically closed.

The maintainer name and email address used in the changelog should be the details of the person who prepared this release of the package. They are not necessarily those of the uploader or usual package maintainer. The information here will be copied to the Changed-By field in the .changes file, and then later might be used to send an acknowledgment when the upload has been installed in the distribution archive.

The date has the following format (compatible and with the same semantics of RFC2822 and RFC5322, or what «date -R» generates):

day-of-week, dd month yyyy hh:mm:ss +zzzz

where:

day-of-week

Is one of: Mon, Tue, Wed, Thu, Fri, Sat, Sun.

dd

Is a one- or two-digit day of the month (01-31), where the leading zero is optional, but conventionally does not get omitted.

month

Is one of: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.

yyyy

Is the four-digit year (e.g. 2010).

hh

Is the two-digit hour (00-23).

mm

Is the two-digit minutes (00-59).

ss

Is the two-digit seconds (00-60).

[+-]zzzz

Is the time zone offset from Coordinated Universal Time (UTC). ‘+’ indicates that the time is ahead of (i.e., east of) UTC and ‘-’ indicates that the time is behind (i.e., west of) UTC. The first two digits indicate the hour difference from UTC and the last two digits indicate the number of additional minutes difference from UTC. The last two digits must be in the range 00-59.

The first “title” line with the package name must start at the left hand margin. The “trailer” line with the maintainer and date details must be preceded by exactly one space (U+0020 SPACE). The maintainer details and the date must be separated by exactly two spaces (U+0020 SPACE). Each part of the date can be separated by one or more spaces (U+0020 SPACE), except after the comma where it can be separated by zero or more spaces (U+0020 SPACE).

Any line that consists entirely (i.e., no leading whitespace) of # or /* */ style comments or RCS keywords.

Vim modelines or Emacs local variables, and ancient changelog entries with other formats at the end of the file should be accepted and preserved on output, but their contents might be otherwise ignored and parsing stopped at that point.

The entire changelog must be encoded in UTF-8.

## FILES
debian/changelog

## EXAMPLES

```
 dpkg (1.17.18) unstable; urgency=low
  [ Guillem Jover ]
  * Handle empty minimum versions when initializing dependency versions,
    as the code is mapping the minimum version 0 to '' to avoid outputting
    useless versions. Regression introduced in dpkg 1.17.17. Closes: #764929
  [ Updated programs translations ]
  * Catalan (Guillem Jover).
  [ Updated dselect translations ]
  * Catalan (Guillem Jover).
  * German (Sven Joachim).
  -- Guillem Jover <guillem@debian.org>  Sun, 12 Oct 2014 15:47:44 +0200
```

## SEE ALSO
deb822(5), deb-version(7), deb-changes(5), dpkg-parsechangelog(1).


deb-changes

title: deb-changes(5)

summary: Debian changes file format

text:
# deb-changes(5)

## NAME
deb-changes - Debian changes file format

## SYNOPSIS
filename.changes

## DESCRIPTION
Each Debian upload is composed of a .changes control file, which contains a number of fields in deb822(5) format.

Each field begins with a tag, such as Source or Binary (case insensitive), followed by a colon, and the body of the field (case sensitive unless stated otherwise). Fields are delimited only by field tags. In other words, field text may be multiple lines in length, but the installation tools will generally join lines when processing the body of the field (except in case of the multiline fields Description, Changes, Files, Checksums-Sha1 and Checksums-Sha256, see below).

The control data might be enclosed in an OpenPGP ASCII Armored signature, as specified in RFC4880.

## FIELDS
Format: format-version (required)

The value of this field declares the format version of the file. The syntax of the field value is a version number with a major and minor component. Backward incompatible changes to the format will bump the major version, and backward compatible changes (such as field additions) will bump the minor version. The current format version is 1.8.

Date: release-date (required)

The date the package was built or last edited. It must be in the same format as the date in a deb-changelog(5) entry. The value of this field is usually extracted from the debian/changelog file.

Source: source-name [(source-version)] (required)

The name of the source package. If the source version differs from the binary version, then the source-name will be followed by a source-version in parenthesis. This can happen when the upload is a binary-only non-maintainer upload.

Binary: binary-package-list (required in context)

This folded field is a space-separated list of binary packages to upload. If the upload is source-only, then the field is omitted (since dpkg 1.19.3).

Architecture: arch-list

Lists the architectures of the files currently being uploaded. Common architectures are amd64, armel, i386, etc. Note that the all value is meant for packages that are architecture independent. If the source for the package is also being uploaded, the special entry source is also present. Architecture wildcards must never be present in the list.

Version: version-string (required)

Typically, this is the original package's version number in whatever form the program's author uses. It may also include a Debian revision number (for non-native packages). The exact format and sorting algorithm are described in deb-version(7).

Distribution: distributions (required)

Lists one or more space-separated distributions where this version should be installed when it is uploaded to the archive.

Urgency: urgency (recommended)

The urgency of the upload. The currently known values, in increasing order of urgency, are: low, medium, high, critical and emergency.

Maintainer: fullname-email (required)

Should be in the format “Joe Bloggs <jbloggs@example.org>”, and is typically the person who created the package, as opposed to the author of the software that was packaged.

Changed-By: fullname-email

Should be in the format “Joe Bloggs <jbloggs@example.org>”, and is typically the person who prepared the package changes for this release.

Description: (recommended)

binary-package-name - binary-package-summary

This multiline field contains a list of binary package names followed by a space, a dash (‘-’) and their possibly truncated short descriptions. If the upload is source-only, then the field is omitted (since dpkg 1.19.3).

Closes: bug-number-list

A space-separated list of bug report numbers for bug reports that have been resolved with this upload. The distribution archive software might use this field to automatically close the referred bug numbers in the distribution bug tracking system.

Binary-Only: yes

This field denotes that the upload is a binary-only non-maintainer build. It originates from the binary-only=yes key/value from the changelog metadata entry.

Built-For-Profiles: profile-list

This field specifies a whitespace separated list of build profiles that this upload was built with.

Changes: (required)

changelog-entries

This multiline field contains the concatenated text of all changelog entries that are part of the upload. To make this a valid multiline field empty lines are replaced with a single full stop (‘.’) and all lines are indented by one space character. The exact content depends on the changelog format.

Files: (required)

md5sum size section priority filename

This multiline field contains a list of files with an md5sum, size, section and priority for each one. The first line of the field value (the part on the same line as the field name followed by a colon) is always empty. The content of the field is expressed as continuation lines, one line per file. Each line consists of space-separated entries describing the file: the md5sum, the file size, the file section, the file priority, and the file name.

This field lists all files that make up the upload. The list of files in this field must match the list of files in the other related Checksums fields.

Checksums-Sha1: (required)

Checksums-Sha256: (required)

checksum size filename

These multiline fields contain a list of files with a checksum and size for each one. These fields have the same syntax and differ only in the checksum algorithm used: SHA-1 for Checksums-Sha1 and SHA-256 for Checksums-Sha256. The first line of the field value (the part on the same line as the field name followed by a colon) is always empty. The content of the field is expressed as continuation lines, one line per file. Each line consists of space-separated entries describing the file: the checksum, the file size, and the file name.

These fields list all files that make up the upload. The list of files in these fields must match the list of files in the Files field and the other related Checksums fields.

## BUGS
The Files field is inconsistent with the other Checksums fields. The Changed-By and Maintainer fields have confusing names. The Distribution field contains information about what is commonly referred to as a suite.

## SEE ALSO
deb822(5), deb-src-control(5), deb-version(7).


deb-conffiles

title: deb-conffiles(5)

summary: package conffiles

text:
# deb-conffiles(5)

## NAME
deb-conffiles - package conffiles

## SYNOPSIS
DEBIAN/conffiles

## DESCRIPTION
A package declares its list of conffiles by including a conffiles file in its control archive (i.e. DEBIAN/conffiles during package creation).

This file contains a list of files, one per line, with an optional leading flag separated by whitespace. The conffiles must be listed as absolute pathnames. Trailing whitespace will be trimmed, but empty or whitespace-only lines are not accepted.

Files without a flag should exist in the binary package, otherwise dpkg(1) will ignore them.

There is currently only one flag supported, remove-on-upgrade, to mark that a conffile needs to be removed on the next upgrade (since dpkg 1.20.6). These files must not exist in the binary package, as both dpkg(1) and dpkg-deb(1) will not accept building nor processing such binary packages.

## EXAMPLE

```
 /etc/alternatives/README
 /etc/cron.daily/dpkg
 /etc/dpkg/dpkg.cfg
 /etc/logrotate.d/dpkg
 remove-on-upgrade /etc/some-old-file.conf
```

## SEE ALSO
dpkg-deb(1), dpkg(1).


deb-control

title: deb-control(5)

text:
# deb-control(5)

## NAME
deb-control - Debian binary packages' master control file format

## SYNOPSIS
DEBIAN/control

## DESCRIPTION
Each Debian binary package contains a control file in its control member, and its deb822(5) format is a subset of the master debian/control file in Debian source packages, see deb-src-control(5).

This file contains a number of fields. Each field begins with a tag, such as Package or Version (case insensitive), followed by a colon, and the body of the field (case sensitive unless stated otherwise). Fields are delimited only by field tags. In other words, field text may be multiple lines in length, but the installation tools will generally join lines when processing the body of the field (except in the case of the Description field, see below).

## FIELDS
Package: package-name (required)

The value of this field determines the package name, and is used to generate file names by most installation tools.

Package-Type: deb|udeb|type

This field defines the type of the package. udeb is for size-constrained packages used by the debian installer. deb is the default value, it is assumed if the field is absent. More types might be added in the future.

Version: version-string (required)

Typically, this is the original package's version number in whatever form the program's author uses. It may also include a Debian revision number (for non-native packages). The exact format and sorting algorithm are described in deb-version(7).

Maintainer: fullname-email (recommended)

Should be in the format “Joe Bloggs <jbloggs@foo.com>”, and is typically the person who created the package, as opposed to the author of the software that was packaged.

Description: short-description (recommended)

long-description

The format for the package description is a short brief summary on the first line (after the Description field). The following lines should be used as a longer, more detailed description. Each line of the long description must be preceded by a space, and blank lines in the long description must contain a single ‘.’ following the preceding space.

Section: section

This is a general field that gives the package a category based on the software that it installs. Some common sections are utils, net, mail, text, x11, etc.

Priority: priority

Sets the importance of this package in relation to the system as a whole. Common priorities are required, standard, optional, extra, etc.

The Section and Priority fields usually have a defined set of accepted values based on the specific distribution policy.

Installed-Size: size

The approximate total size of the package's installed files, in KiB units. The algorithm to compute the size is described in deb-substvars(5).

Protected: yes|no

This field is usually only needed when the answer is yes. It denotes a package that is required mostly for proper booting of the system or used for custom system-local meta-packages. dpkg(1) or any other installation tool will not allow a Protected package to be removed (at least not without using one of the force options). Supported since dpkg 1.20.1.

Essential: yes|no

This field is usually only needed when the answer is yes. It denotes a package that is required for the packaging system, for proper operation of the system in general or during boot (although the latter should be converted to Protected field instead). dpkg(1) or any other installation tool will not allow an Essential package to be removed (at least not without using one of the force options).

Build-Essential: yes|no

This field is usually only needed when the answer is yes, and is commonly injected by the archive software. It denotes a package that is required when building other packages.

Architecture: arch|all (required)

The architecture specifies which type of hardware this package was compiled for. Common architectures are amd64, armel, i386, powerpc, etc. Note that the all value is meant for packages that are architecture independent. Some examples of this are shell and Perl scripts, and documentation.

Origin: name

The name of the distribution this package is originating from.

Bugs: url

The url of the bug tracking system for this package. The current used format is bts-type://bts-address, like debbugs://bugs.debian.org.

Homepage: url

The upstream project home page url.

Tag: tag-list

List of tags describing the qualities of the package. The description and list of supported tags can be found in the debtags package.

Multi-Arch: no|same|foreign|allowed

This field is used to indicate how this package should behave on a multi-arch installations.

no

This value is the default when the field is omitted, in which case adding the field with an explicit no value is generally not needed.

same

This package is co-installable with itself, but it must not be used to satisfy the dependency of any package of a different architecture from itself.

foreign

This package is not co-installable with itself, but should be allowed to satisfy a non-arch-qualified dependency of a package of a different arch from itself (if a dependency has an explicit arch-qualifier then the value foreign is ignored).

allowed

This allows reverse-dependencies to indicate in their Depends field that they accept this package from a foreign architecture by qualifying the package name with :any, but has no effect otherwise.

Source: source-name [(source-version)]

The name of the source package that this binary package came from, if it is different than the name of the package itself. If the source version differs from the binary version, then the source-name will be followed by a source-version in parenthesis. This can happen for example on a binary-only non-maintainer upload, or when setting a different binary version via «dpkg-gencontrol -v».

Subarchitecture: value

Kernel-Version: value

Installer-Menu-Item: value

These fields are used by the debian-installer and are usually not needed. For more details about them, see <https://salsa.debian.org/installer-team/debian-installer/-/raw/master/doc/devel/modules.txt>.

Depends: package-list

List of packages that are required for this package to provide a non-trivial amount of functionality. The package maintenance software will not allow a package to be installed if the packages listed in its Depends field aren't installed (at least not without using the force options). In an installation, the postinst scripts of packages listed in Depends fields are run before those of the packages which depend on them. On the opposite, in a removal, the prerm script of a package is run before those of the packages listed in its Depends field.

Pre-Depends: package-list

List of packages that must be installed and configured before this one can be installed. This is usually used in the case where this package requires another package for running its preinst script.

Recommends: package-list

Lists packages that would be found together with this one in all but unusual installations. The package maintenance software will warn the user if they install a package without those listed in its Recommends field.

Suggests: package-list

Lists packages that are related to this one and can perhaps enhance its usefulness, but without which installing this package is perfectly reasonable.

The syntax of Depends, Pre-Depends, Recommends and Suggests fields is a list of groups of alternative packages. Each group is a list of packages separated by vertical bar (or “pipe”) symbols, ‘|’. The groups are separated by commas. Commas are to be read as “AND”, and pipes as “OR”, with pipes binding more tightly. Each package name is optionally followed by an architecture qualifier appended after a colon ‘:’, optionally followed by a version number specification in parentheses.

An architecture qualifier name can be a real Debian architecture name (since dpkg 1.16.5) or any (since dpkg 1.16.2). If omitted, the default is the current binary package architecture. A real Debian architecture name will match exactly that architecture for that package name, any will match any architecture for that package name if the package has been marked as Multi-Arch: allowed.

A version number may start with a ‘>>’, in which case any later version will match, and may specify or omit the Debian packaging revision (separated by a hyphen). Accepted version relationships are ‘>>’ for greater than, ‘<<’ for less than, ‘>=’ for greater than or equal to, ‘<=’ for less than or equal to, and ‘=’ for equal to.

Breaks: package-list

Lists packages that this one breaks, for example by exposing bugs when the named packages rely on this one. The package maintenance software will not allow broken packages to be configured; generally the resolution is to upgrade the packages named in a Breaks field.

Conflicts: package-list

Lists packages that conflict with this one, for example by containing files with the same names. The package maintenance software will not allow conflicting packages to be installed at the same time. Two conflicting packages should each include a Conflicts line mentioning the other.

Replaces: package-list

List of packages files from which this one replaces. This is used for allowing this package to overwrite the files of another package and is usually used with the Conflicts field to force removal of the other package, if this one also has the same files as the conflicted package.

The syntax of Breaks, Conflicts and Replaces is a list of package names, separated by commas (and optional whitespace). In the Breaks and Conflicts fields, the comma should be read as “OR”. An optional architecture qualifier can also be appended to the package name with the same syntax as above, but the default is any instead of the binary package architecture. An optional version can also be given with the same syntax as above for the Breaks, Conflicts and Replaces fields.

Enhances: package-list

This is a list of packages that this one enhances. It is similar to Suggests but in the opposite direction.

Provides: package-list

This is a list of virtual packages that this one provides. Usually this is used in the case of several packages all providing the same service. For example, sendmail and exim can serve as a mail server, so they provide a common package (“mail-transport-agent”) on which other packages can depend. This will allow sendmail or exim to serve as a valid option to satisfy the dependency. This prevents the packages that depend on a mail server from having to know the package names for all of them, and using ‘|’ to separate the list.

The syntax of Provides is a list of package names, separated by commas (and optional whitespace). An optional architecture qualifier can also be appended to the package name with the same syntax as above. If omitted, the default is the current binary package architecture. An optional exact (equal to) version can also be given with the same syntax as above (honored since dpkg 1.17.11).

Built-Using: package-list

This dependency field lists extra source packages that were used during the build of this binary package, for license compliance purposes. This is an indication to the archive maintenance software that these extra source packages must be kept whilst this binary package is maintained. This field must be a comma-separated list of source package names with strict ‘=’ version relationships enclosed within parenthesis. Note that the archive maintenance software is likely to refuse to accept an upload which declares a Built-Using relationship which cannot be satisfied within the archive.

Static-Built-Using: package-list

This dependency field lists extra source packages that were used during the build of this binary package, for static building purposes (for example linking against static libraries, builds for source-centered languages such as Go or Rust, usage of header-only C/C++ libraries, injecting data blobs into code, etc.). This is useful to track whether this package might need to be rebuilt when source packages listed here have been updated, for example due to security updates. This field must be a comma-separated list of source package names with strict ‘=’ version relationships enclosed within parenthesis. Supported since dpkg 1.21.3.

Built-For-Profiles: profile-list (obsolete)

This field used to specify a whitespace separated list of build profiles that this binary packages was built with (since dpkg 1.17.2 until 1.18.18). The information previously found in this field can now be found in the .buildinfo file, which supersedes it.

Auto-Built-Package: reason-list

This field specifies a whitespace separated list of reasons why this package was auto-generated. Binary packages marked with this field will not appear in the debian/control master source control file. The only currently used reason is debug-symbols.

Build-Ids: elf-build-id-list

This field specifies a whitespace separated list of ELF build-ids. These are unique identifiers for semantically identical ELF objects, for each of these within the package. The format or the way to compute each build-id is not defined by design.

## EXAMPLE

```
 Package: grep
 Essential: yes
 Priority: required
 Section: base
 Maintainer: Wichert Akkerman <wakkerma@debian.org>
 Architecture: sparc
 Version: 2.4-1
 Pre-Depends: libc6 (>= 2.0.105)
 Provides: rgrep
 Conflicts: rgrep
 Description: GNU grep, egrep and fgrep.
  The GNU family of grep utilities may be the "fastest grep in the west".
  GNU grep is based on a fast lazy-state deterministic matcher (about
  twice as fast as stock Unix egrep) hybridized with a Boyer-Moore-Gosper
  search for a fixed string that eliminates impossible text from being
  considered by the full regexp matcher without necessarily having to
  look at every character. The result is typically many times faster
  than Unix grep or egrep. (Regular expressions containing backreferencing
  will run more slowly, however).
```

## BUGS
The Build-Ids field uses a rather generic name out of its original context within an ELF object, which serves a very specific purpose and executable format.

## SEE ALSO
deb822(5), deb-src-control(5), deb(5), deb-version(7), debtags(1), dpkg(1), dpkg-deb(1).


deb-extra-override

title: deb-extra-override(5)

summary: Debian archive extra override file

text:
# deb-extra-override(5)

## NAME
deb-extra-override - Debian archive extra override file

## SYNOPSIS
override

## DESCRIPTION
While most information about a binary/source package can be found in the control/.dsc file, all of it can be overridden when it's exported to Packages/Sources files. The extra override file contains those overrides.

The extra override file has a simple whitespace-delimited format. Comments are allowed (denoted with a #).

package field-name value

package is the name of the binary/source package.

field-name is the name of the field that is overridden.

value is the value to put in the field. It can contain spaces as the line is split in no more than 3 columns when it's parsed.

The extra override files used to make the official Packages lists may be found in the indices directory on any Debian mirror.

## SEE ALSO
dpkg-scanpackages(1), dpkg-scansources(1), apt-ftparchive(1).


title: deb-md5sums(5)

summary: package MD5 file digests

text:
# deb-md5sums(5)

## NAME
deb-md5sums - package MD5 file digests

## SYNOPSIS
DEBIAN/md5sums

## DESCRIPTION
A package declares the MD5 digests for the package file contents by including an md5sums file in its control archive (i.e. DEBIAN/md5sums during package creation). This file is used for integrity verification and deduplication purposes, and not for any kind of security purpose.

This file contains a list of MD5 digests (as 32 case-insensitive hexadecimal characters) followed by two spaces (U+0020 SPACE) and the absolute pathname of a plain file, one per line.

Trailing slashes (U+002F /) in the pathname will be trimmed. Neither trailing whitespace nor empty or whitespace-only lines are accepted.

If the control file does not exist in the binary package, dpkg(1) will generate the matching information at unpack time (since dpkg 1.16.3).

## EXAMPLE

```
 53c0d4afe4bc4eccb5cb234d2e06ef4d  usr/bin/dpkg
 f8da2bc74cdcad8b81c48a4f0d7bb0a8  usr/bin/dpkg-deb
 70b913132de56e95e75de504979309b4  usr/bin/dpkg-divert
 […]
```

## SEE ALSO
md5sum(1), dpkg-deb(1), dpkg(1).


deb-old

title: deb-old(5)

summary: old style Debian binary package format

text:
# deb-old(5)

## NAME
deb-old - old style Debian binary package format

## SYNOPSIS
filename.deb

## DESCRIPTION
The .deb format is the Debian binary package file format. This manual page describes the old format, used before Debian 0.93. Please see deb(5) for details of the new format.

## FORMAT
The file is two lines of format information as ASCII text, followed by two concatenated gzipped ustar files.

The first line is the format version number padded to 8 digits, and is 0.939000 for all old-format archives.

The second line is a decimal string (without leading zeroes) giving the length of the first gzipped tarfile.

Each of these lines is terminated with a single newline character.

The first tarfile contains the control information, as a series of ordinary files. The file control must be present, as it contains the core control information.

In some very old archives, the files in the control tarfile may optionally be in a DEBIAN subdirectory. In that case, the DEBIAN subdirectory will be in the control tarfile too, and the control tarfile will have only files in that directory. Optionally the control tarfile may contain an entry for ‘.’, that is, the current directory.

The second gzipped tarfile is the filesystem archive, containing pathnames relative to the root directory of the system to be installed on. The pathnames do not have leading slashes.

## SEE ALSO
deb(5), dpkg-deb(1), deb-control(5).


deb-origin

title: deb-origin(5)

summary: Vendor\-specific information files

text:
# deb-origin(5)

## NAME
deb-origin - Vendor-specific information files

## SYNOPSIS
/etc/dpkg/origins/filename

## DESCRIPTION
The files in /etc/dpkg/origins can provide information about various vendors who are providing Debian packages.

They contain a number of fields, or comments when the line starts with ‘#’. Each field begins with a tag, such as Vendor or Parent, followed by a colon and the body of the field. Fields are delimited only by field tags. In other words, field text may be multiple lines in length, but the tools will join lines when processing the body of the field.

The file should be named according to the vendor name. The usual convention is to name the vendor file using the vendor name in all lowercase, but some variation is permitted.

Namely (since dpkg 1.21.10), first, non-alphanumeric characters (‘[^A-Za-z0-9]’) are mapped to dashes (‘-’), then the resulting name will be tried in sequence by lower-casing it, keeping it as is, lower-casing then capitalizing it (that is upper-casing the first character), and only capitalizing it.

In addition, for historical and backwards compatibility, the name will be tried keeping it as is without non-alphanumeric characters remapping, then the resulting name will be tried in sequence by lower-casing it, keeping it as is, lower-casing then capitalizing it, and only capitalizing it. And finally the name will be tried by remapping spaces to dashes (‘-’), then the resulting name will be tried in sequence by lower-casing it, keeping it as is, lower-casing then capitalizing it, and only capitalizing it.

But these backwards compatible module lookups will be removed during the dpkg 1.22.x release cycle.

## FIELDS
Vendor: vendor-name (required)

The value of this field determines the vendor name.

Vendor-URL: vendor-url

The value of this field determines the vendor URL.

Bugs: bug-url

The value of this field determines the type and address of the bug tracking system used by this vendor. It can be a mailto URL or a debbugs URL (e.g., debbugs://bugs.debian.org/).

Parent: vendor-name

The value of this field determines the vendor name of the vendor that this vendor derives from.

## EXAMPLE

```
 Vendor: Debian
 Vendor-URL: https://www.debian.org/
 Bugs: debbugs://bugs.debian.org
```

## SEE ALSO
dpkg-vendor(1)


deb-override

title: deb-override(5)

summary: Debian archive override file

text:
# deb-override(5)

## NAME
deb-override - Debian archive override file

## SYNOPSIS
override

## DESCRIPTION
While most information about a package can be found in the control file, some is managed centrally by the distribution czars rather than by the maintainer in order to offer some global consistency. This information is found in the override file.

The override file has a simple whitespace-delimited format. Comments are allowed (denoted with a #).

package priority section [maintainer-info]

package is the name of the package. Entries in the override file for packages not found in the tree of binary packages are ignored.

priority and section correspond to the respective control fields available in the .deb. The allowed values are specific to each distribution archive.

maintainer-info, if present, can be either the name of a maintainer for an unconditional override, or else old-maintainer => new-maintainer to perform a substitution.

The override files used to make the official Packages lists may be found in the indices directory on any Debian mirror.

## SEE ALSO
dpkg-scanpackages(1), dpkg-scansources(1), apt-ftparchive(1).