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 /etc/pki/instance_name/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_hostname, pki_ds_ldap_port, pki_ds_ldaps_port

Hostname and ports for the internal database. Defaults to localhost, 389, and 636, respectively.

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.

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_restart_configured_instance

Sets whether to restart the instance after configuration is complete. Defaults to True.

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 True.

### 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. This parameter is only relevant when pki_clone_setup_replication is set to False. In this case, it is expected that the database has been prepared and replicated as noted above. Part of that preparation could involve adding indexes and indexing the data. If you would like the Dogtag installer to add the indexes and reindex the data instead, set pki_clone_reindex_data to True.

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_external_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 '%(pki_instance_configuration_path)s/%(pki_subsystem_type)s_admin.csr'.

pki_external_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 '%(pki_instance_configuration_path)s/%(pki_subsystem_type)s_audit_signing.csr'.

pki_external_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 '%(pki_instance_configuration_path)s/%(pki_subsystem_type)s_sslserver.csr'.

pki_external_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 '%(pki_instance_configuration_path)s/kra_storage.csr'.

pki_external_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 '%(pki_instance_configuration_path)s/%(pki_subsystem_type)s_subsystem.csr'.

pki_external_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 '%(pki_instance_configuration_path)s/kra_transport.csr'.

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 '%(pki_instance_configuration_path)s/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_external_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 '%(pki_instance_configuration_path)s/%(pki_subsystem_type)s_admin.cert'.

pki_external_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 '%(pki_instance_configuration_path)s/%(pki_subsystem_type)s_audit_signing.cert'.

pki_external_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 '%(pki_instance_configuration_path)s/%(pki_subsystem_type)s_sslserver.cert'.

pki_external_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 '%(pki_instance_configuration_path)s/kra_storage.cert'.

pki_external_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 '%(pki_instance_configuration_path)s/%(pki_subsystem_type)s_subsystem.cert'.

pki_external_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 '%(pki_instance_configuration_path)s/kra_transport.cert'.

### 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_hostname

Specifies the hostname of TPS authentication database. Defaults to localhost.

pki_authdb_port

Specifies the port number of TPS authentication database. Defaults to 389.

pki_authdb_secure_conn

Specifies whether to use a secure connection to TPS authentication database. Defaults to False.

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: 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=server.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=server.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=server.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⟩.


pksd.conf

package: pks

title: pksd.conf(5)

text:
# pksd.conf(5)

## NAME
pksd.conf - Public Key Server Daemon configuration file

## DESCRIPTION
The pksd.conf file contains all the configuration information for the programs which comprise the public key server system (pks-intro(8)). It contains a list of configuration variables of the form

word value

If the first character of a line is #, the line is a comment, and ignored. The variables are as follows:

pks_bin_dir

This defines the location of the executeables which form the public key server system. In particular, pksdctl(8) must be in this directory.

db_dir

This is the directory where the database files keydbXXX, worddb, and timedb , and the key database file counter num_keydb are stored.

www_port

This is the port number on which pksd(8) accepts HTTP connections. If it is 0, then HTTP connections are not accepted on any port.

www_readonly

This controls key updates/submissions via HTTP. If it is 0, then keys may be submitted via HTTP. The DEFAULT is 1, which DOES NOT allow key updates/submissions via HTTP.

max_reply_keys

This controls how many keys are returned at the most for keyserver queries. You'll want to set this. The default is 0, so the keyserver will not return any keys.

socket_name

This is the name of the unix domain socket on which pksd(8) will listen for control messages from pksdctl(8), including notification of new mail messages.

mail_delivery_client

This is a command which will be executed whenever mail needs to be delivered. This value is used as the command argument to the shell (/bin/sh -c value), so appropriate care should be taken to avoid security problems. The mail message to be delivered is passed to the standard input of this command, so options to the program should be used to parse the input for delivery addresses.

maintainer_email

This address is used as the From: address for all mail sent out.

mail_intro_file

This is the filename of a file which, if present, is inserted at the head of each mail message sent out by pksd(8). This file is used as a part of a MIME message. If MIME headers, such as content-type:, are required, they precede the body, separated by a blank line. If no headers are required, then the first line of the file must be blank.

help_dir

This is the name of a directory in which the key server help files should be found. The files in this directory should be named pks_help.LANG, where LANG is the language of the help file, in lower-case. These files are also used as MIME parts, so they are subject to the same formatting requirements as the mail_intro_file .

default_language

This is a string containing the default language for help responses from the server. The help file for this language, as described above, should exist.

this_site

This is the email address for this public key server. See the description of incremental messages in pksd(8) for more details.

syncsite

This command gives the email address of a peer public key server to this one. This is the only command which can be specified more than once. It should be specified once for each peer server.

## FILES
pksd.conf

## SEE ALSO
pks-intro(8), pksd(8)

## AUTHOR
Marc Horowitz, Massachusetts Institute of Technology


podman-systemd.unit

package: podman

title: podman-systemd.unit(5)

text:
# podman-systemd.unit(5)

## NAME
podman-systemd.unit - systemd units using Podman Quadlet

## SYNOPSIS
name.container, name.volume, name.network, name.kube name.image

### Podman unit search path

- /etc/containers/systemd/

- /usr/share/containers/systemd/

### Podman user unit search path

- $XDG_CONFIG_HOME/containers/systemd/ or ~/.config/containers/systemd/

- /etc/containers/systemd/users/$(UID)

- /etc/containers/systemd/users/

### Using symbolic links
Quadlet supports using symbolic links for the base of the search paths. Symbolic links below the search paths are not supported.

## DESCRIPTION
Podman supports starting containers (and creating volumes) via systemd by using a systemd generator. These files are read during boot (and when systemctl daemon-reload is run) and generate corresponding regular systemd service unit files. Both system and user systemd units are supported. All options and tables available in standard systemd unit files are supported. For example, options defined in the [Service] table and [Install] tables pass directly to systemd and are handled by it. See systemd.unit(5) man page for more information.

The Podman generator reads the search paths above and reads files with the extensions .container .volume and *.kube, and for each file generates a similarly named .service file. Be aware that existing vendor services (i.e., in /usr/) are replaced if they have the same name. The generated unit files can be started and managed with systemctl like any other systemd service. systemctl {--user} list-unit-files lists existing unit files on the system.

Files with the .network extension are only read if they are mentioned in a .container file. See the Network= key.

The Podman files use the same format as regular systemd unit files. Each file type has a custom section (for example, [Container]) that is handled by Podman, and all other sections are passed on untouched, allowing the use of any normal systemd configuration options like dependencies or cgroup limits.

For rootless containers, when administrators place Quadlet files in the /etc/containers/systemd/users directory, all users' sessions execute the Quadlet when the login session begins. If the administrator places a Quadlet file in the /etc/containers/systemd/users/${UID}/ directory, then only the user with the matching UID execute the Quadlet when the login session gets started. For unit files placed in subdirectories within /etc/containers/systemd/user/${UID}/ and the other user unit search paths, Quadlet will recursively search and run the unit files present in these subdirectories.

Note: When a Quadlet is starting, Podman often pulls one more container images which may take a considerable amount of time. Systemd defaults service start time to 90 seconds, or fails the service. Pre-pulling the image or extending the systemd timeout time for the service using the TimeoutStartSec Service option can fix the problem.

Adding the following snippet to a Quadlet file extends the systemd timeout to 15 minutes.

```
[Service]
TimeoutStartSec=900
```

Quadlet requires the use of cgroup v2, use podman info --format {{.Host.CgroupsVersion}} to check on the system.

### Service Type
By default, the Type field of the Service section of the Quadlet file does not need to be set. Quadlet will set it to notify for .container and .kube files and to oneshot for .volume, .network and .image files.

However, Type may be explicitly set to oneshot for .container and .kube files when no containers are expected to run once podman exits.

When setting Type=oneshot, it is recommended to also set RemainAfterExit=yes to prevent the service state from becoming inactive (dead)

Examples for such cases: - .container file with an image that exits after their entrypoint has finished ` -.kube` file pointing to a Kubernetes Yaml file that does not define any containers. E.g. PVCs only

### Enabling unit files
The services created by Podman are considered transient by systemd, which means they don't have the same persistence rules as regular units. In particular, it is not possible to "systemctl enable" them in order for them to become automatically enabled on the next boot.

To compensate for this, the generator manually applies the [Install] section of the container definition unit files during generation, in the same way systemctl enable does when run later.

For example, to start a container on boot, add something like this to the file:

```
[Install]
WantedBy=default.target
```

Currently, only the Alias, WantedBy and RequiredBy keys are supported.

NOTE: To express dependencies between containers, use the generated names of the service. In other words WantedBy=other.service, not WantedBy=other.container. The same is true for other kinds of dependencies, too, like After=other.service.

### Debugging unit files
After placing the unit file in one of the unit search paths (mentioned above), you can start it with systemctl start {--user}. If it fails with "Failed to start example.service: Unit example.service not found.", then it is possible that you used incorrect syntax or you used an option from a newer version of Podman Quadlet and the generator failed to create a service file.

View the generated files and/or error messages with:

```
/usr/lib/systemd/system-generators/podman-system-generator {--user} --dryrun
```

### Debugging a limited set of unit files
If you would like to debug a limited set of unit files, you can copy them to a separate directory and set the QUADLET_UNIT_DIRS environment variable to this directory when running the command below:

```
QUADLET_UNIT_DIRS=<Directory> /usr/lib/systemd/system-generators/podman-system-generator {--user} --dryrun
```

This will instruct Quadlet to look for units in this directory instead of the common ones and by that limit the output to only the units you are debugging.

## Container units [Container]
Container units are named with a .container extension and contain a [Container] section describing the container that is run as a service. The resulting service file contains a line like ExecStart=podman run … image-name, and most of the keys in this section control the command-line options passed to Podman. However, some options also affect the details of how systemd is set up to run and interact with the container.

By default, the Podman container has the same name as the unit, but with a systemd- prefix, i.e. a $name.container file creates a $name.service unit and a systemd-$name Podman container. The ContainerName option allows for overriding this default name with a user-provided one.

There is only one required key, Image, which defines the container image the service runs.

Valid options for [Container] are listed below:

[Container] options

podman run equivalent

AddCapability=CAP

--cap-add CAP

AddDevice=/dev/foo

--device /dev/foo

Annotation="XYZ"

--annotation "XYZ"

AutoUpdate=registry

--label "io.containers.autoupdate=registry"

ContainerName=name

--name name

ContainersConfModule=/etc/nvd.conf

--module=/etc/nvd.conf

DNS=192.168.55.1

--dns=192.168.55.1

DNSSearch=foo.com

--dns-search=foo.com

DNSOption=ndots:1

--dns-option=ndots:1

DropCapability=CAP

--cap-drop=CAP

Environment=foo=bar

--env foo=bar

EnvironmentFile=/tmp/env

--env-file /tmp/env

EnvironmentHost=true

--env-host

Exec=/usr/bin/command

Command after image specification - /usr/bin/command

ExposeHostPort=50-59

--expose 50-59

GIDMap=0:10000:10

--gidmap=0:10000:10

Group=1234

--user UID:1234

GlobalArgs=--log-level=debug

--log-level=debug

HealthCmd="/usr/bin/command"

--health-cmd="/usr/bin/command"

HealthInterval=2m

--health-interval=2m

HealthOnFailure=kill

--health-on-failure=kill

HealthRetries=5

--health-retries=5

HealthStartPeriod=1m

--health-start-period=period=1m

HealthStartupCmd="command"

--health-startup-cmd="command"

HealthStartupInterval=1m

--health-startup-interval=1m

HealthStartupRetries=8

--health-startup-retries=8

HealthStartupSuccess=2

--health-startup-success=2

HealthStartupTimeout=1m33s

--health-startup-timeout=1m33s

HealthTimeout=20s

--health-timeout=20s

HostName=new-host-name

--hostname="new-host-name"

Image=ubi8

Image specification - ubi8

IP=192.5.0.1

--ip 192.5.0.1

IP6=2001:db8::1

--ip6 2001:db8::1

Label="XYZ"

--label "XYZ"

LogDriver=journald

--log-driver journald

Mount=type=...

--mount type=...

Network=host

--net host

NoNewPrivileges=true

--security-opt no-new-privileges

Rootfs=/var/lib/rootfs

--rootfs /var/lib/rootfs

Notify=true

--sdnotify container

PidsLimit=10000

--pids-limit 10000

PodmanArgs=--add-host foobar

--add-host foobar

PublishPort=50-59

--publish 50-59

Pull=never

--pull=never

ReadOnly=true

--read-only

ReadOnlyTmpfs=true

--read-only-tmpfs

RunInit=true

--init

SeccompProfile=/tmp/s.json

--security-opt seccomp=/tmp/s.json

SecurityLabelDisable=true

--security-opt label=disable

SecurityLabelFileType=usr_t

--security-opt label=filetype:usr_t

SecurityLabelLevel=s0:c1,c2

--security-opt label=level:s0:c1,c2

SecurityLabelNested=true

--security-opt label=nested

SecurityLabelType=spc_t

--security-opt label=type:spc_t

ShmSize=100m

--shm-size=100m

SubGIDMap=gtest

--subgidname=gtest

SubUIDMap=utest

--subuidname=utest

Sysctl=name=value

--sysctl=name=value

Timezone=local

--tz local

Tmpfs=/work

--tmpfs /work

UIDMap=0:10000:10

--uidmap=0:10000:10

Ulimit=nofile:1000:10000

--ulimit nofile:1000:10000

User=bin

--user bin

UserNS=keep-id:uid=200,gid=210

--userns keep-id:uid=200,gid=210

Volume=/source:/dest

--volume /source:/dest

WorkingDir=$HOME

--workdir $HOME

Description of [Container] section are:

### AddCapability=
Add these capabilities, in addition to the default Podman capability set, to the container.

This is a space separated list of capabilities. This key can be listed multiple times.

For example:

```
AddCapability=CAP_DAC_OVERRIDE CAP_IPC_OWNER
```

### AddDevice=
Adds a device node from the host into the container. The format of this is HOST-DEVICE[:CONTAINER-DEVICE][:PERMISSIONS], where HOST-DEVICE is the path of the device node on the host, CONTAINER-DEVICE is the path of the device node in the container, and PERMISSIONS is a list of permissions combining 'r' for read, only if it exists on the host.

This key can be listed multiple times.

### Annotation=
Set one or more OCI annotations on the container. The format is a list of key=value items, similar to Environment.

This key can be listed multiple times.

### AutoUpdate=
Indicates whether the container will be auto-updated (podman-auto-update(1)). The following values are supported:

- registry: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which image to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore.

- local: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the container.

### ContainerName=
The (optional) name of the Podman container. If this is not specified, the default value of systemd-%N is used, which is the same as the service name but with a systemd- prefix to avoid conflicts with user-managed containers.

### ContainersConfModule=
Load the specified containers.conf(5) module. Equivalent to the Podman --module option.

This key can be listed multiple times.

### DNS=
Set network-scoped DNS resolver/nameserver for containers in this network.

This key can be listed multiple times.

### DNSOption=
Set custom DNS options.

This key can be listed multiple times.

### DNSSearch=
Set custom DNS search domains. Use DNSSearch=. to remove the search domain.

This key can be listed multiple times.

### DropCapability=
Drop these capabilities from the default podman capability set, or all to drop all capabilities.

This is a space separated list of capabilities. This key can be listed multiple times.

For example:

```
DropCapability=CAP_DAC_OVERRIDE CAP_IPC_OWNER
```

### Environment=
Set an environment variable in the container. This uses the same format as services in systemd and can be listed multiple times.

### EnvironmentFile=
Use a line-delimited file to set environment variables in the container. The path may be absolute or relative to the location of the unit file. This key may be used multiple times, and the order persists when passed to podman run.

### EnvironmentHost=
Use the host environment inside of the container.

### Exec=
If this is set then it defines what command line to run in the container. If it is not set the default entry point of the container image is used. The format is the same as for systemd command lines.

### ExposeHostPort=
Exposes a port, or a range of ports (e.g. 50-59), from the host to the container. Equivalent to the Podman --expose option.

This key can be listed multiple times.

### GIDMap=
Run the container in a new user namespace using the supplied GID mapping. Equivalent to the Podman --gidmap option.

This key can be listed multiple times.

### GlobalArgs=
This key contains a list of arguments passed directly between podman and run in the generated file (right before the image name in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.

This key can be listed multiple times.

### Group=
The (numeric) GID to run as inside the container. This does not need to match the GID on the host, which can be modified with UsersNS, but if that is not specified, this GID is also used on the host.

### HealthCmd=
Set or alter a healthcheck command for a container. A value of none disables existing healthchecks. Equivalent to the Podman --health-cmd option.

### HealthInterval=
Set an interval for the healthchecks. An interval of disable results in no automatic timer setup. Equivalent to the Podman --health-interval option.

### HealthOnFailure=
Action to take once the container transitions to an unhealthy state. The "kill" action in combination integrates best with systemd. Once the container turns unhealthy, it gets killed, and systemd restarts the service. Equivalent to the Podman --health-on-failure option.

### HealthRetries=
The number of retries allowed before a healthcheck is considered to be unhealthy. Equivalent to the Podman --health-retries option.

### HealthStartPeriod=
The initialization time needed for a container to bootstrap. Equivalent to the Podman --health-start-period option.

### HealthStartupCmd=
Set a startup healthcheck command for a container. Equivalent to the Podman --health-startup-cmd option.

### HealthStartupInterval=
Set an interval for the startup healthcheck. An interval of disable results in no automatic timer setup. Equivalent to the Podman --health-startup-interval option.

### HealthStartupRetries=
The number of attempts allowed before the startup healthcheck restarts the container. Equivalent to the Podman --health-startup-retries option.

### HealthStartupSuccess=
The number of successful runs required before the startup healthcheck succeeds and the regular healthcheck begins. Equivalent to the Podman --health-startup-success option.

### HealthStartupTimeout=
The maximum time a startup healthcheck command has to complete before it is marked as failed. Equivalent to the Podman --health-startup-timeout option.

### HealthTimeout=
The maximum time allowed to complete the healthcheck before an interval is considered failed. Equivalent to the Podman --health-timeout option.

### HostName=
Sets the host name that is available inside the container. Equivalent to the Podman --hostname option.

### Image=
The image to run in the container. It is recommended to use a fully qualified image name rather than a short name, both for performance and robustness reasons.

The format of the name is the same as when passed to podman pull. So, it supports using :tag or digests to guarantee the specific image version.

As a special case, if the name of the image ends with .image, Quadlet will use the image pulled by the corresponding .image file, and the generated systemd service contains a dependency on the $name-image.service. Note that the corresponding .image file must exist.

### IP=
Specify a static IPv4 address for the container, for example 10.88.64.128. Equivalent to the Podman --ip option.

### IP6=
Specify a static IPv6 address for the container, for example fd46:db93:aa76:ac37::10. Equivalent to the Podman --ip6 option.

### Label=
Set one or more OCI labels on the container. The format is a list of key=value items, similar to Environment.

This key can be listed multiple times.

### LogDriver=
Set the log-driver used by Podman when running the container. Equivalent to the Podman --log-driver option.

### Mount=
Attach a filesystem mount to the container. This is equivalent to the Podman --mount option, and generally has the form type=TYPE,TYPE-SPECIFIC-OPTION[,...].

As a special case, for type=volume if source ends with .volume, a Podman named volume called systemd-$name is used as the source, and the generated systemd service contains a dependency on the $name-volume.service. Such a volume can be automatically be lazily created by using a $name.volume Quadlet file.

This key can be listed multiple times.

### Network=
Specify a custom network for the container. This has the same format as the --network option to podman run. For example, use host to use the host network in the container, or none to not set up networking in the container.

As a special case, if the name of the network ends with .network, a Podman network called systemd-$name is used, and the generated systemd service contains a dependency on the $name-network.service. Such a network can be automatically created by using a $name.network Quadlet file.

This key can be listed multiple times.

### NoNewPrivileges= (defaults to no)
If enabled, this disables the container processes from gaining additional privileges via things like setuid and file capabilities.

### Rootfs=
The rootfs to use for the container. Rootfs points to a directory on the system that contains the content to be run within the container. This option conflicts with the Image option.

The format of the rootfs is the same as when passed to podman run --rootfs, so it supports overlay mounts as well.

Note: On SELinux systems, the rootfs needs the correct label, which is by default unconfined_u:object_r:container_file_t:s0.

### Notify= (defaults to no)
By default, Podman is run in such a way that the systemd startup notify command is handled by the container runtime. In other words, the service is deemed started when the container runtime starts the child in the container. However, if the container application supports sd_notify, then setting Notify to true passes the notification details to the container allowing it to notify of startup on its own.

### PidsLimit=
Tune the container's pids limit. This is equivalent to the Podman --pids-limit option.

### PodmanArgs=
This key contains a list of arguments passed directly to the end of the podman run command in the generated file (right before the image name in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.

This key can be listed multiple times.

### PublishPort=
Exposes a port, or a range of ports (e.g. 50-59), from the container to the host. Equivalent to the Podman --publish option. The format is similar to the Podman options, which is of the form ip:hostPort:containerPort, ip::containerPort, hostPort:containerPort or containerPort, where the number of host and container ports must be the same (in the case of a range).

If the IP is set to 0.0.0.0 or not set at all, the port is bound on all IPv4 addresses on the host; use [::] for IPv6.

Note that not listing a host port means that Podman automatically selects one, and it may be different for each invocation of service. This makes that a less useful option. The allocated port can be found with the podman port command.

This key can be listed multiple times.

### Pull=
Set the image pull policy. This is equivalent to the Podman --pull option

### ReadOnly= (defaults to no)
If enabled, makes the image read-only.

### ReadOnlyTmpfs= (defaults to yes)
If ReadOnly is set to yes, mount a read-write tmpfs on /dev, /dev/shm, /run, /tmp, and /var/tmp.

### RunInit= (default to no)
If enabled, the container has a minimal init process inside the container that forwards signals and reaps processes.

### SeccompProfile=
Set the seccomp profile to use in the container. If unset, the default podman profile is used. Set to either the pathname of a json file, or unconfined to disable the seccomp filters.

### SecurityLabelDisable=
Turn off label separation for the container.

### SecurityLabelFileType=
Set the label file type for the container files.

### SecurityLabelLevel=
Set the label process level for the container processes.

### SecurityLabelNested=
Allow SecurityLabels to function within the container. This allows separation of containers created within the container.

### SecurityLabelType=
Set the label process type for the container processes.

### Secret=
Use a Podman secret in the container either as a file or an environment variable. This is equivalent to the Podman --secret option and generally has the form secret[,opt=opt ...]

### ShmSize=
Size of /dev/shm.

This is equivalent to the Podman --shm-size option and generally has the form number[unit]

### SubGIDMap=
Run the container in a new user namespace using the map with name in the /etc/subgid file. Equivalent to the Podman --subgidname option.

### SubUIDMap=
Run the container in a new user namespace using the map with name in the /etc/subuid file. Equivalent to the Podman --subuidname option.

### Sysctl=
Configures namespaced kernel parameters for the container. The format is Sysctl=name=value.

This is a space separated list of kernel parameters. This key can be listed multiple times.

For example:

```
Sysctl=net.ipv6.conf.all.disable_ipv6=1 net.ipv6.conf.all.use_tempaddr=1
```

### Tmpfs=
Mount a tmpfs in the container. This is equivalent to the Podman --tmpfs option, and generally has the form CONTAINER-DIR[:OPTIONS].

This key can be listed multiple times.

### Timezone= (if unset uses system-configured default)
The timezone to run the container in.

### UIDMap=
Run the container in a new user namespace using the supplied UID mapping. Equivalent to the Podman --uidmap option.

This key can be listed multiple times.

### Ulimit=
Ulimit options. Sets the ulimits values inside of the container.

### User=
The (numeric) UID to run as inside the container. This does not need to match the UID on the host, which can be modified with UserNS, but if that is not specified, this UID is also used on the host.

### UserNS=
Set the user namespace mode for the container. This is equivalent to the Podman --userns option and generally has the form MODE[:OPTIONS,...].

### Volume=
Mount a volume in the container. This is equivalent to the Podman --volume option, and generally has the form [[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]].

If SOURCE-VOLUME starts with ., Quadlet resolves the path relative to the location of the unit file.

As a special case, if SOURCE-VOLUME ends with .volume, a Podman named volume called systemd-$name is used as the source, and the generated systemd service contains a dependency on the $name-volume.service. Such a volume can be automatically be lazily created by using a $name.volume Quadlet file.

This key can be listed multiple times.

### WorkingDir=
Working directory inside the container.

The default working directory for running binaries within a container is the root directory (/). The image developer can set a different default with the WORKDIR instruction. This option overrides the working directory by using the -w option.

## Kube units [Kube]
Kube units are named with a .kube extension and contain a [Kube] section describing how podman kube play runs as a service. The resulting service file contains a line like ExecStart=podman kube play … file.yml, and most of the keys in this section control the command-line options passed to Podman. However, some options also affect the details of how systemd is set up to run and interact with the container.

There is only one required key, Yaml, which defines the path to the Kubernetes YAML file.

Valid options for [Kube] are listed below:

[Kube] options

podman kube play equivalent

AutoUpdate=registry

--annotation "io.containers.autoupdate=registry"

ConfigMap=/tmp/config.map

--config-map /tmp/config.map

ContainersConfModule=/etc/nvd.conf

--module=/etc/nvd.conf

GlobalArgs=--log-level=debug

--log-level=debug

KubeDownForce=true

--force (for podman kube down)

LogDriver=journald

--log-driver journald

Network=host

--net host

PodmanArgs=--annotation=key=value

--annotation=key=value

PublishPort=59-60

--publish=59-60

SetWorkingDirectory=yaml

Set WorkingDirectory of unit file to location of the YAML file

UserNS=keep-id:uid=200,gid=210

--userns keep-id:uid=200,gid=210

Yaml=/tmp/kube.yaml

podman kube play /tmp/kube.yaml

Supported keys in the [Kube] section are:

### AutoUpdate=
Indicates whether containers will be auto-updated (podman-auto-update(1)). AutoUpdate can be specified multiple times. The following values are supported:

- registry: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which images to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore.

- local: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the Kubernetes Quadlet.

- name/(local|registry): Tells Podman to perform the local or registry autoupdate on the specified container name.

### ConfigMap=
Pass the Kubernetes ConfigMap YAML path to podman kube play via the --configmap argument. Unlike the configmap argument, the value may contain only one path but it may be absolute or relative to the location of the unit file.

This key may be used multiple times

### ContainersConfModule=
Load the specified containers.conf(5) module. Equivalent to the Podman --module option.

This key can be listed multiple times.

### ExitCodePropagation=
Control how the main PID of the systemd service should exit. The following values are supported: - all: exit non-zero if all containers have failed (i.e., exited non-zero) - any: exit non-zero if any container has failed - none: exit zero and ignore failed containers

The current default value is none.

### GlobalArgs=
This key contains a list of arguments passed directly between podman and kube in the generated file (right before the image name in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.

This key can be listed multiple times.

### KubeDownForce=
Remove all resources, including volumes, when calling podman kube down. Equivalent to the Podman --force option.

### LogDriver=
Set the log-driver Podman uses when running the container. Equivalent to the Podman --log-driver option.

### Mask=
Specify the paths to mask separated by a colon. Mask=/path/1:/path/2. A masked path cannot be accessed inside the container.

### Network=
Specify a custom network for the container. This has the same format as the --network option to podman kube play. For example, use host to use the host network in the container, or none to not set up networking in the container.

As a special case, if the name of the network ends with .network, a Podman network called systemd-$name is used, and the generated systemd service contains a dependency on the $name-network.service. Such a network can be automatically created by using a $name.network Quadlet file.

This key can be listed multiple times.

### PodmanArgs=
This key contains a list of arguments passed directly to the end of the podman kube play command in the generated file (right before the path to the yaml file in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, is not recommended to use this option.

The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.

This key can be listed multiple times.

### PublishPort=
Exposes a port, or a range of ports (e.g. 50-59), from the container to the host. Equivalent to the podman kube play's --publish option. The format is similar to the Podman options, which is of the form ip:hostPort:containerPort, ip::containerPort, hostPort:containerPort or containerPort, where the number of host and container ports must be the same (in the case of a range).

If the IP is set to 0.0.0.0 or not set at all, the port is bound on all IPv4 addresses on the host; use [::] for IPv6.

The list of published ports specified in the unit file is merged with the list of ports specified in the Kubernetes YAML file. If the same container port and protocol is specified in both, the entry from the unit file takes precedence

This key can be listed multiple times.

### SetWorkingDirectory=
Set the WorkingDirectory field of the Service group of the Systemd service unit file. Used to allow podman kube play to correctly resolve relative paths. Supported values are yaml and unit to set the working directory to that of the YAML or Quadlet Unit file respectively.

Alternatively, users can explicitly set the WorkingDirectory field of the Service group in the .kube file. Please note that if the WorkingDirectory field of the Service group is set, Quadlet will not set it even if SetWorkingDirectory is set

### Unmask=
Specify the paths to unmask separated by a colon. unmask=ALL or /path/1:/path/2, or shell expanded paths (/proc/*):

If set to ALL, Podman will unmask all the paths that are masked or made read-only by default.

The default masked paths are /proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, and /sys/fs/selinux.

The default paths that are read-only are /proc/asound, /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup.

### UserNS=
Set the user namespace mode for the container. This is equivalent to the Podman --userns option and generally has the form MODE[:OPTIONS,...].

### Yaml=
The path, absolute or relative to the location of the unit file, to the Kubernetes YAML file to use.

## Network units [Network]
Network files are named with a .network extension and contain a section [Network] describing the named Podman network. The generated service is a one-time command that ensures that the network exists on the host, creating it if needed.

By default, the Podman network has the same name as the unit, but with a systemd- prefix, i.e. for a network file named $NAME.network, the generated Podman network is called systemd-$NAME, and the generated service file is $NAME-network.service. The NetworkName option allows for overriding this default name with a user-provided one.

Please note that stopping the corresponding service will not remove the podman network. In addition, updating an existing network is not supported. In order to update the network parameters you will first need to manually remove the podman network and then restart the service.

Using network units allows containers to depend on networks being automatically pre-created. This is particularly interesting when using special options to control network creation, as Podman otherwise creates networks with the default options.

Valid options for [Network] are listed below:

[Network] options

podman network create equivalent

ContainersConfModule=/etc/nvd.conf

--module=/etc/nvd.conf

DisableDNS=true

--disable-dns

DNS=192.168.55.1

--dns=192.168.55.1

Driver=bridge

--driver bridge

Gateway=192.168.55.3

--gateway 192.168.55.3

GlobalArgs=--log-level=debug

--log-level=debug

Internal=true

--internal

IPAMDriver=dhcp

--ipam-driver dhcp

IPRange=192.168.55.128/25

--ip-range 192.168.55.128/25

IPv6=true

--ipv6

Label="XYZ"

--label "XYZ"

NetworkName=foo

podman network create foo

Options=isolate

--opt isolate

PodmanArgs=--dns=192.168.55.1

--dns=192.168.55.1

Subnet=192.5.0.0/16

--subnet 192.5.0.0/16

Supported keys in [Network] section are:

### ContainersConfModule=
Load the specified containers.conf(5) module. Equivalent to the Podman --module option.

This key can be listed multiple times.

### DisableDNS= (defaults to no)
If enabled, disables the DNS plugin for this network.

This is equivalent to the Podman --disable-dns option

### DNS=
Set network-scoped DNS resolver/nameserver for containers in this network.

This key can be listed multiple times.

### Driver= (defaults to bridge)
Driver to manage the network. Currently bridge, macvlan and ipvlan are supported.

This is equivalent to the Podman --driver option

### Gateway=
Define a gateway for the subnet. If you want to provide a gateway address, you must also provide a subnet option.

This is equivalent to the Podman --gateway option

This key can be listed multiple times.

### GlobalArgs=
This key contains a list of arguments passed directly between podman and network in the generated file (right before the image name in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.

This key can be listed multiple times.

### Internal= (defaults to no)
Restrict external access of this network.

This is equivalent to the Podman --internal option

### IPAMDriver=
Set the ipam driver (IP Address Management Driver) for the network. Currently host-local, dhcp and none are supported.

This is equivalent to the Podman --ipam-driver option

### IPRange=
Allocate container IP from a range. The range must be a either a complete subnet in CIDR notation or be in the <startIP>-<endIP> syntax which allows for a more flexible range compared to the CIDR subnet. The ip-range option must be used with a subnet option.

This is equivalent to the Podman --ip-range option

This key can be listed multiple times.

### IPv6=
Enable IPv6 (Dual Stack) networking.

This is equivalent to the Podman --ipv6 option

### Label=
Set one or more OCI labels on the network. The format is a list of key=value items, similar to Environment.

This key can be listed multiple times.

### NetworkName=
The (optional) name of the Podman network. If this is not specified, the default value of systemd-%N is used, which is the same as the unit name but with a systemd- prefix to avoid conflicts with user-managed networks.

### Options=
Set driver specific options.

This is equivalent to the Podman --opt option

### PodmanArgs=
This key contains a list of arguments passed directly to the end of the podman network create command in the generated file (right before the name of the network in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, is not recommended to use this option.

The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.

This key can be listed multiple times.

### Subnet=
The subnet in CIDR notation.

This is equivalent to the Podman --subnet option

This key can be listed multiple times.

## Volume units [Volume]
Volume files are named with a .volume extension and contain a section [Volume] describing the named Podman volume. The generated service is a one-time command that ensures that the volume exists on the host, creating it if needed.

By default, the Podman volume has the same name as the unit, but with a systemd- prefix, i.e. for a volume file named $NAME.volume, the generated Podman volume is called systemd-$NAME, and the generated service file is $NAME-volume.service. The VolumeName option allows for overriding this default name with a user-provided one.

Using volume units allows containers to depend on volumes being automatically pre-created. This is particularly interesting when using special options to control volume creation, as Podman otherwise creates volumes with the default options.

Valid options for [Volume] are listed below:

[Volume] options

podman volume create equivalent

ContainersConfModule=/etc/nvd.conf

--module=/etc/nvd.conf

Copy=true

--opt copy

Device=tmpfs

--opt device=tmpfs

Driver=image

--driver=image

GlobalArgs=--log-level=debug

--log-level=debug

Group=192

--opt group=192

Image=quay.io/centos/centos:latest

--opt image=quay.io/centos/centos:latest

Label="foo=bar"

--label "foo=bar"

Options=XYZ

--opt XYZ

PodmanArgs=--driver=image

--driver=image

VolumeName=foo

podman volume create foo

Supported keys in [Volume] section are:

### ContainersConfModule=
Load the specified containers.conf(5) module. Equivalent to the Podman --module option.

This key can be listed multiple times.

### Copy= (default to yes)
If enabled, the content of the image located at the mountpoint of the volume is copied into the volume on the first run.

### Device=
The path of a device which is mounted for the volume.

### Driver=
Specify the volume driver name. When set to image, the Image key must also be set.

This is equivalent to the Podman --driver option.

### GlobalArgs=
This key contains a list of arguments passed directly between podman and volume in the generated file (right before the image name in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.

This key can be listed multiple times.

### Group=
The host (numeric) GID, or group name to use as the group for the volume

### Image=
Specifies the image the volume is based on when Driver is set to the image. It is recommended to use a fully qualified image name rather than a short name, both for performance and robustness reasons.

The format of the name is the same as when passed to podman pull. So, it supports using :tag or digests to guarantee the specific image version.

As a special case, if the name of the image ends with .image, Quadlet will use the image pulled by the corresponding .image file, and the generated systemd service contains a dependency on the $name-image.service. Note that the corresponding .image file must exist.

### Label=
Set one or more OCI labels on the volume. The format is a list of key=value items, similar to Environment.

This key can be listed multiple times.

### Options=
The mount options to use for a filesystem as used by the mount(8) command -o option.

### PodmanArgs=
This key contains a list of arguments passed directly to the end of the podman volume create command in the generated file (right before the name of the network in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, is not recommended to use this option.

The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.

This key can be listed multiple times.

### Type=
The filesystem type of Device as used by the mount(8) commands -t option.

### User=
The host (numeric) UID, or user name to use as the owner for the volume

### VolumeName=
The (optional) name of the Podman volume. If this is not specified, the default value of systemd-%N is used, which is the same as the unit name but with a systemd- prefix to avoid conflicts with user-managed volumes.

## Image units [Image]
Image files are named with a .image extension and contain a section [Image] describing the container image pull command. The generated service is a one-time command that ensures that the image exists on the host, pulling it if needed.

Using image units allows containers and volumes to depend on images being automatically pulled. This is particularly interesting when using special options to control image pulls.

Valid options for [Image] are listed below:

[Image] options

podman image pull equivalent

AllTags=true

--all-tags

Arch=aarch64

--arch=aarch64

AuthFile=/etc/registry/auth.json

--authfile=/etc/registry/auth.json

CertDir=/etc/registry/certs

--cert-dir=/etc/registry/certs

ContainersConfModule=/etc/nvd.conf

--module=/etc/nvd.conf

Creds=myname:mypassword

--creds=myname:mypassword

DecryptionKey=/etc/registry.key

--decryption-key=/etc/registry.key

GlobalArgs=--log-level=debug

--log-level=debug

Image=quay.io/centos/centos:latest

podman image pull quay.io/centos/centos:latest

ImageTag=quay.io/centos/centos:latest

Use this name when resolving .image references

OS=windows

--os=windows

PodmanArgs=--os=linux

--os=linux

TLSVerify=false

--tls-verify=false

Variant=arm/v7

--variant=arm/v7

### AllTags=
All tagged images in the repository are pulled.

This is equivalent to the Podman --all-tags option.

### Arch=
Override the architecture, defaults to hosts, of the image to be pulled.

This is equivalent to the Podman --arch option.

### AuthFile=
Path of the authentication file.

This is equivalent to the Podman --authfile option.

### CertDir=
Use certificates at path (*.crt, *.cert, *.key) to connect to the registry.

This is equivalent to the Podman --cert-dir option.

### ContainersConfModule=
Load the specified containers.conf(5) module. Equivalent to the Podman --module option.

This key can be listed multiple times.

### Creds=
The [username[:password]] to use to authenticate with the registry, if required.

This is equivalent to the Podman --creds option.

### DecryptionKey=
The [key[:passphrase]] to be used for decryption of images.

This is equivalent to the Podman --decryption-key option.

### GlobalArgs=
This key contains a list of arguments passed directly between podman and image in the generated file (right before the image name in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.

This key can be listed multiple times.

### Image=
The image to pull. It is recommended to use a fully qualified image name rather than a short name, both for performance and robustness reasons.

The format of the name is the same as when passed to podman pull. So, it supports using :tag or digests to guarantee the specific image version.

### ImageTag=
Actual FQIN of the referenced Image. Only meaningful when source is a file or directory archive.

For example, an image saved into a docker-archive with the following Podman command:

podman image save --format docker-archive --output /tmp/archive-file.tar quay.io/podman/stable:latest

requires setting - Image=docker-archive:/tmp/archive-file.tar - ImageTag=quay.io/podman/stable:latest

### OS=
Override the OS, defaults to hosts, of the image to be pulled.

This is equivalent to the Podman --os option.

### PodmanArgs=
This key contains a list of arguments passed directly to the end of the podman image pull command in the generated file (right before the image name in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.

This key can be listed multiple times.

### TLSVerify=
Require HTTPS and verification of certificates when contacting registries.

This is equivalent to the Podman --tls-verify option.

### Variant=
Override the default architecture variant of the container image.

This is equivalent to the Podman --variant option.

## EXAMPLES
Example test.container:

```
[Unit]
Description=A minimal container
[Container]
# Use the centos image
Image=quay.io/centos/centos:latest
# Use volume and network defined below
Volume=test.volume:/data
Network=test.network
# In the container we just run sleep
Exec=sleep 60
[Service]
# Restart service when sleep finishes
Restart=always
# Extend Timeout to allow time to pull the image
TimeoutStartSec=900
# ExecStartPre flag and other systemd commands can go here, see systemd.unit(5) man page.
ExecStartPre=/usr/share/mincontainer/setup.sh
[Install]
# Start by default on boot
WantedBy=multi-user.target default.target
```

Example test.kube:

```
[Unit]
Description=A kubernetes yaml based service
Before=local-fs.target
[Kube]
Yaml=/opt/k8s/deployment.yml
[Install]
# Start by default on boot
WantedBy=multi-user.target default.target
```

Example test.volume:

```
[Volume]
User=root
Group=root
Label=org.test.Key=value
```

Example test.network:

```
[Network]
Subnet=172.16.0.0/24
Gateway=172.16.0.1
IPRange=172.16.0.0/28
Label=org.test.Key=value
```

## SEE ALSO
systemd.unit(5), systemd.service(5), podman-run(1), podman-network-create(1), podman-auto-update(1) [systemd.unit(5)]


package: policycoreutils

title: selinux_config(5)

text:
# selinux_config(5)

## NAME
config - The SELinux sub-system configuration file.

## DESCRIPTION
The SELinux config file controls the state of SELinux regarding:

1.

The policy enforcement status - enforcing, permissive or disabled.

2.

The policy name or type that forms a path to the policy to be loaded and its supporting configuration files.

3.

How SELinux-aware login applications should behave if no valid SELinux users are configured.

4.

Whether the system is to be relabeled or not.

The entries controlling these functions are described in the FILE FORMAT section.

The fully qualified path name of the SELinux configuration file is /etc/selinux/config.

If the config file is missing or corrupt, then no SELinux policy is loaded (i.e. SELinux is disabled).

The sestatus (8) command and the libselinux function selinux_path (3) will return the location of the config file.

## FILE FORMAT
The config file supports the following parameters:

SELINUX = enforcing | permissive | disabled

SELINUXTYPE = policy_name

REQUIREUSERS = 0 | 1

AUTORELABEL = 0 | 1

Where:

SELINUX

This entry can contain one of three values: enforcing

SELinux security policy is enforced.

permissive

SELinux security policy is not enforced but logs the warnings (i.e. the action is allowed to proceed).

disabled

No SELinux policy is loaded. This option was used to disable SELinux completely, which is now deprecated. Use the selinux=0 kernel boot option instead (see selinux(8)).

The entry can be determined using the sestatus(8) command or selinux_getenforcemode(3).

SELINUXTYPE

The policy_name entry is used to identify the policy type, and becomes the directory name of where the policy and its configuration files are located. The entry can be determined using the sestatus(8) command or selinux_getpolicytype(3).

The policy_name is relative to a path that is defined within the SELinux subsystem that can be retrieved by using selinux_path(3). An example entry retrieved by selinux_path(3) is:

/etc/selinux/

The policy_name is then appended to this and becomes the 'policy root' location that can be retrieved by selinux_policy_root_path(3). An example entry retrieved is:

/etc/selinux/targeted

The actual binary policy is located relative to this directory and also has a policy name pre-allocated. This information can be retrieved using selinux_binary_policy_path(3). An example entry retrieved by selinux_binary_policy_path(3) is:

/etc/selinux/targeted/policy/policy

The binary policy name has by convention the SELinux policy version that it supports appended to it. The maximum policy version supported by the kernel can be determined using the sestatus(8) command or security_policyvers(3). An example binary policy file with the version is:

/etc/selinux/targeted/policy/policy.24

REQUIRESEUSERS

This optional entry can be used to fail a login if there is no matching or default entry in the seusers(5) file or if the seusers file is missing. It is checked by getseuserbyname(3) that is called by SELinux-aware login applications such as PAM(8).

If set to 0 or the entry missing:

getseuserbyname(3) will return the GNU / Linux user name as the SELinux user.

If set to 1:

getseuserbyname(3) will fail.

The getseuserbyname(3) man page should be consulted for its use. The format of the seusers file is shown in seusers(5).

AUTORELABEL

This is an optional entry that allows the file system to be relabeled. If set to 0 and there is a file called .autorelabel in the root directory, then on a reboot, the loader will drop to a shell where a root login is required. An administrator can then manually relabel the file system.

If set to 1 or no entry present (the default) and there is a .autorelabel file in the root directory, then the file system will be automatically relabeled using fixfiles -F restore

In both cases the /.autorelabel file will be removed so that relabeling is not done again.

## EXAMPLE
This example config file shows the minimum contents for a system to run SELinux in enforcing mode, with a policy_name of 'targeted':

SELINUX = enforcing

SELINUXTYPE = targeted

## SEE ALSO
selinux(8), sestatus(8), selinux_path(3), selinux_policy_root_path(3), selinux_binary_policy_path(3), getseuserbyname(3), PAM(8), fixfiles(8), selinux_mkload_policy(3), selinux_getpolicytype(3), security_policyvers(3), selinux_getenforcemode(3), seusers(5)