pkispawn

title: pkispawn(8)

summary: Sets up a PKI subsystem.

text:
# pkispawn(8)

## NAME
pkispawn - Sets up a PKI subsystem.

## SYNOPSIS
pkispawn [OPTIONS]

## DESCRIPTION
Sets up a PKI subsystem (CA, KRA, OCSP, TKS, or TPS) in a Tomcat instance.

Note: A 389 Directory Server instance must be configured and running before this script can be run. PKI server requires an internal directory database. The default configuration assumes a Directory Server instance running on the same machine on port 389. For more information on creating a Directory Server instance, see dscreate(8).

An instance can contain multiple subsystems, although it may contain at most one of each type of subsystem on a single machine. So, for example, an instance could contain CA and KRA subsystems, but not two CA subsystems. To create an instance with a CA and a KRA, simply run pkispawn twice, with values -s CA and -s KRA respectively.

The instances are created based on values for configuration parameters in the default configuration (i.e. /usr/share/pki/server/etc/default.cfg) and the user-provided configuration file. The user-provided configuration file is read after the default configuration file, so any parameters defined in that file will override parameters in the default configuration file. In general, most users will store only those parameters which are different from the default configuration in their user-provided configuration file.

This configuration file 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 system-specific customization.

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.

At a minimum, the user-defined configuration file must provide some passwords needed for the install. An example configuration file is provided in the EXAMPLES section below. For more information on the default configuration file and the parameters it contains (and can be customized), see pki_default.cfg(5).

The pkispawn run creates several different installation files that can be referenced later, if need be:

- For Tomcat-based instances, a Tomcat instance is created at /var/lib/pki/pki_instance_name, where pki_instance_name is defined in the configuration file.

- A log file of pkispawn operations is written to /var/log/pki/pki-subsystem-spawn.timestamp.log.

- A .p12 (PKCS #12) file containing a certificate for a subsystem administrator is stored in pki_client_dir defined in the configuration file.

When the utility is done running, the CA can be accessed by pointing a browser to https://hostname:pki_https_port/. The agent pages can be accessed by importing the CA certificate and administrator certificate into the browser.

The PKI server instance can also be accessed using the pki command line interface. See pki(1). For more extensive documentation on how to use PKI features, see the Red Hat Certificate System Documentation at ⟨https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System⟩.

Instances created using pkispawn can be removed using pkidestroy. See pkidestroy(8).

## OPTIONS
-s subsystem

Specifies the subsystem to be installed and configured, where subsystem is CA, KRA, OCSP, TKS, or TPS.

-f config_file

Specifies the path to the user-defined configuration file.

This file contains differences between the default configuration and the custom configuration.

--precheck

Execute pre-checks and exit.

--skip-configuration

Run the first step of the installation (i.e. skipping the instance configuration step).

--skip-installation

Run the second step of the installation (i.e. skipping the instance installation step).

-h, --help

Prints additional help information.

-v

Displays verbose information about the installation.

This flag can be provided multiple times to increase verbosity.

See pkispawn -h for details.

## SEPARATE VERSUS SHARED INSTANCES

### Separate PKI instances
As described above, this version of PKI continues to support separate PKI instances for all subsystems.

Separate PKI instances run as a single Java-based Apache Tomcat instance, contain a single PKI subsystem (CA, KRA, OCSP, TKS, or TPS), and must utilize unique ports if co-located on the same machine.

### Shared PKI instances
Additionally, this version of PKI introduces the notion of a shared PKI instance.

Shared PKI instances also run as a single Java-based Apache Tomcat instance, but may contain any combination of up to one of each type of PKI subsystem:

- CA

- TKS

- CA, KRA

- CA, OCSP

- TKS, TPS

- CA, KRA, TKS, TPS

- CA, KRA, OCSP, TKS, TPS

- etc.

Shared PKI instances allow all of their subsystems contained within that instance to share the same ports, and must utilize unique ports if more than one shared PKI instance is co-located on the same machine.

Semantically, a shared PKI instance that contains a single PKI subsystem is identical to a separate PKI instance.

## INTERACTIVE MODE
If no options are specified, pkispawn will provide an interactive menu to collect the parameters needed to install the Certificate Server instance. Note that only the most basic installation options are provided. This includes root CA, KRA, OCSP, TKS, and TPS connecting to an existing directory server. More advanced setups such as cloned subsystems, subordinate or externally signed CA, subsystems that connect to the directory server using LDAPS, and subsystems that are customized beyond the options described below require the use of a configuration file with the -f option.

The interactive option is most useful for those users getting familiar with Certificate Server. The parameters collected are written to the installation file of the subsystem, which can be found at /etc/sysconfig/pki/tomcat/instance_name/subsystem/deployment.cfg.

The following parameters are queried interactively during the installation process.

### Subsystem Type
Subsystem (CA/KRA/OCSP/TKS/TPS):

The type of subsystem to be installed.

Prompted when the -s option is not specified.

The default value chosen is CA.

### Instance Specific Parameters
Instance name:

The name of the tomcat instance in which the subsystem is to be installed. The default value is pki-tomcat.

Note: Only one subsystem of a given type (CA, KRA, OCSP, TKS, TPS) can exist within a given instance.

HTTP port:

The HTTP port of the Tomcat instance. The default value is 8090.

Secure HTTP port:

The HTTPS port of the Tomcat instance. The default value is 8443.

AJP port:

The AJP port of the Tomcat instance. The default value is 8009.

Management port:

The management port of the Tomcat instance. The default value is 8005.

Note: When deploying a new subsystem into an existing instance, pkispawn will attempt to read the ports from deployment.cfg files stored for previously installed subsystems for this instance. If successful, the installer will not prompt for these ports.

### Administrative User Parameters
Username:

The username of the administrator of this subsystem. The default value is <ca/kra/ocsp/tks/tps>admin.

Password:

Password for the administrator user.

Import certificate:

An optional parameter that can be used to import an already available CA admin certificate into this instance.

Export certificate:

Setup the path where the admin certificate of this <subsystem> should be stored.

The default value is $HOME/.dogtag/pki-tomcat/<ca/kra/ocsp/tks/tps>_admin.cert.

### Directory Server Parameters
Hostname:

Hostname of the directory server instance. The default value is the hostname of the system.

Use a secure LDAPS connection?

Answering yes to this question will cause prompts for Secure LDAPS Port: and Directory Server CA certificate pem file:.

Answering no to this question will cause a prompt for LDAP Port.

The initial default value for this question is no.

Secure LDAPS Port:

Secure LDAPS port for the directory server instance. The default value is 636.

Directory Server CA certificate PEM file:

The fully-qualified path including the filename of the file which contains an exported copy of the Directory Server's CA certificate (e.g. $HOME/dscacert.pem).

This file must exist prior to pkispawn being able to utilize it.

For details on creation of this file see the EXAMPLES section below entitled Installing PKI Subsystem with Secure LDAP Connection.

LDAP Port:

LDAP port for the directory server instance. The default value is 389.

Base DN:

The Base DN to be used for the internal database for this subsystem.

The default value is o=pki-tomcat-<subsystem>.

Bind DN:

The bind DN required to connect for the directory server.

This user must have sufficient permissions to install the required schema and database.

The default value is cn=Directory Manager.

Password:

Password for the bind DN.

### Security Domain Parameters
Name:

The name of the security domain. Required only if installing a root CA.

Default value: <DNS domain name> Security Domain.

Hostname:

The hostname for the security domain CA. Required only for non-CA subsystems.

The default value is the hostname of this system.

Secure HTTP port:

The https port for the security domain. Required only for non-CA subsystems. The default value is 8443.

Username:

The username of the security domain administrator of the CA.

Required only for non-CA subsystems.

The default value is caadmin.

Password:

Password for the security domain administrator. Required for all subsystems that are not root CAs.

## PRE-CHECK MODE
This option is only available when pkispawn is invoked in a non-interactive mode. When the --precheck option is provided, a set of basic tests are performed to ensure that the parameters provided to pkispawn are valid and consistent.

pkispawn will then exit with an exit code of 0 on success, or 1 on failure. This mode can be used to perform basic tests prior to doing any actual installation of the PKI server instance.

Flags are available to disable specific tests. For instance, one might want to disable validation of the credentials for the internal database user if the directory server instance has not yet been created.

See pki_default.cfg(5) for more details about available flags.

## TWO-STEP INSTALLATION MODE
pkispawn provides a number of parameters to customize an instance before it is created. Usually, most other customization can be done after the server is created. However, sometimes certain types of customization need to be done before the server is created, but there are no parameters for that. For example, configuring session timeout, adding CSR extensions, customizing certificate profiles, configuring TLS ciphers, etc. To support such customization, pkispawn provides a two-step installation mode.

Generally, instance creation happens in one step (except for the external CA case). Internally, the process happens in two stages. In the first stage, pkispawn will install the instance files (e.g. CS.cfg, NSS database, profiles, etc.) in the instance directory and customize them based on pkispawn parameters. In the second stage, pkispawn will start the instance and configure the instance based on the instance configuration files (e.g. initializing database, generating certificates, configuring connectors, etc.). The two-step process allows the process to be stopped after the first stage, allowing further customization to be done before running the second stage.

To use two-step installation mode, prepare a normal pkispawn configuration file, then run pkispawn with the --skip-configuration parameter. For example:

```
$ pkispawn -s CA -f myconfig.txt --skip-configuration
```

Then customize the files in the instance directory as needed. Finally, finish the installation by running pkispawn again with the --skip-installation parameter. For example:

```
$ pkispawn -s CA -f myconfig.txt --skip-installation
```

## EXAMPLES

### Installing Root CA
To install a root CA in a new instance execute the following command:

```
$ pkispawn -s CA -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
```

Prior to running this command, a Directory Server instance should be created and running. This command assumes that the Directory Server instance is using its default configuration:

- Installed on the local machine

- Listening on port 389

- The user is cn=Directory Manager, with the password specified in pki_ds_password

This invocation of pkispawn creates a Tomcat instance containing a CA running on the local machine with secure port 8443 and unsecure port 8090. To access this CA, simply point a browser to https://hostname:8443.

The instance name (defined by pki_instance_name) is pki-tomcat, and it is located at /var/lib/pki/pki-tomcat. Logs for the instance are located at /var/lib/pki/pki-tomcat/logs, and an installation log is written to /var/log/pki/pki-subsystem-spawn.timestamp.log.

A PKCS #12 file containing the administrator certificate is created in $HOME/.dogtag/pki-tomcat. This PKCS #12 file uses the password designated by pki_client_pkcs12_password in the configuration file.

To access the agent pages, first import the CA certificate by accessing the CA End Entity Pages and clicking on the Retrieval Tab. Be sure to trust the CA certificate. Then, import the administrator certificate in the PKCS #12 file.

### Installing Root CA using ECC
To install a root CA in a new instance using ECC execute the following command:

```
$ pkispawn -s CA -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_admin_key_algorithm=SHA256withEC
pki_admin_key_size=nistp256
pki_admin_key_type=ecc
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_sslserver_key_algorithm=SHA256withEC
pki_sslserver_key_size=nistp256
pki_sslserver_key_type=ecc
pki_subsystem_key_algorithm=SHA256withEC
pki_subsystem_key_size=nistp256
pki_subsystem_key_type=ecc
[CA]
pki_ca_signing_key_algorithm=SHA256withEC
pki_ca_signing_key_size=nistp256
pki_ca_signing_key_type=ecc
pki_ca_signing_signing_algorithm=SHA256withEC
pki_ocsp_signing_key_algorithm=SHA256withEC
pki_ocsp_signing_key_size=nistp256
pki_ocsp_signing_key_type=ecc
pki_ocsp_signing_signing_algorithm=SHA256withEC
```

In order to utilize ECC, the SSL Server and Subsystem key algorithm, key size, and key type should be changed from SHA256withRSA to SHA256withEC, 2048 to nistp256, and rsa to ecc, respectively. To use an ECC admin key size and key type, the values should also be changed from 2048 to nistp256, and rsa to ecc.

Additionally, for a CA subsystem, both the CA and OCSP Signing key algorithm, key size, key type, and signing algorithm should be changed from SHA256withRSA to SHA256withEC, 2048 to nistp256, rsa to ecc, and SHA256withRSA to SHA256withEC, respectively.

Note: For all PKI subsystems including the CA, ECC is not supported for the corresponding Audit Signing parameters. Similarly, for KRA subsystems, ECC is not supported for either of the corresponding Storage or Transport parameters.

### Installing KRA, OCSP, TKS, or TPS in Shared Instance
For this example, assume that a new CA instance has been installed by executing the following command:

```
$ pkispawn -s CA -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
```

To install a shared KRA in the same instance used by the CA execute the following command:

```
$ pkispawn -s KRA -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
```

To install a shared OCSP in the same instance used by the CA execute the following command:

```
$ pkispawn -s OCSP -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
```

To install a shared TKS in the same instance used by the CA execute the following command:

```
$ pkispawn -s TKS -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
```

To install a shared TPS in the same instance used by the CA execute the following command:

```
$ pkispawn -s TPS -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
[TPS]
# Shared TPS instances optionally utilize their shared KRA
# for server-side keygen
pki_enable_server_side_keygen=True
pki_authdb_basedn=dc=example,dc=com
```

Note: For this particular example, the computed default values for a PKI instance name including its ports, URLs, machine names, etc. were utilized as defined in /usr/share/pki/server/etc/default.cfg. Each subsystem in this example will reside under the /var/lib/pki/pki-tomcat instance housed within their own ca, kra, ocsp, tks, and tps subdirectories, utilizing the same default port values of 8090 (http), 8443 (https), 8009 (ajp), 8005 (tomcat), using the same computed hostname and URL information, and sharing a single common PKI Administrator Certificate.

The pki_security_domain_password is the admin password of the CA installed in the same instance. This command should be run after a CA is installed. This installs another subsystem within the same instance using the certificate generated for the CA administrator for the subsystem's administrator. This allows a user to access both subsystems on the browser with a single administrator certificate. To access the new subsystem's functionality, simply point the browser to https://hostname:8443 and click the relevant top-level links.

To install TPS in a shared instance the following section must be added to myconfig.txt:

```
[TPS]
pki_authdb_basedn=dc=example,dc=com
```

TPS requires an authentication database. The pki_authdb_basedn specifies the base DN of the authentication database.

TPS also requires that a CA and a TKS subsystems are already installed in the same instance. Since they are in the same instance, a shared secret key will automatically be generated in TKS and imported into TPS.

Optionally, server-side key generation can be enabled in TPS by adding the following parameter in [TPS]:

```
pki_enable_server_side_keygen=True
```

Enabling server-side key generation requires that a KRA subsystem is already installed in the same instance.

### Installing KRA, OCSP, TKS, or TPS in Separate Instance
For this example, assume that a new CA instance has been installed by executing the following command:

```
$ pkispawn -s CA -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
# Separated CA instance name and ports
pki_instance_name=pki-ca
pki_http_port=18090
pki_https_port=18443
# This Separated CA instance will be its own security domain
pki_security_domain_https_port=18443
[Tomcat]
# Separated CA Tomcat ports
pki_ajp_port=18009
pki_tomcat_server_port=18005
```

To install a separate KRA which connects to this remote CA execute the following command:

```
$ pkispawn -s KRA -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Separated KRA instance name and ports
pki_instance_name=pki-kra
pki_http_port=28090
pki_https_port=28443
# Separated KRA instance security domain references
pki_issuing_ca=https://pki.example.com:18443
pki_security_domain_hostname=pki.example.com
pki_security_domain_https_port=18443
pki_security_domain_user=caadmin
[Tomcat]
# Separated KRA Tomcat ports
pki_ajp_port=28009
pki_tomcat_server_port=28005
[KRA]
# A Separated KRA instance requires its own
# PKI Administrator Certificate
pki_import_admin_cert=False
```

To install a separate OCSP which connects to this remote CA execute the following command:

```
$ pkispawn -s OCSP -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Separated OCSP instance name and ports
pki_instance_name=pki-ocsp
pki_http_port=29080
pki_https_port=29443
# Separated OCSP instance security domain references
pki_issuing_ca=https://pki.example.com:18443
pki_security_domain_hostname=pki.example.com
pki_security_domain_https_port=18443
pki_security_domain_user=caadmin
[Tomcat]
# Separated OCSP Tomcat ports
pki_ajp_port=29009
pki_tomcat_server_port=29005
[OCSP]
# A Separated OCSP instance requires its own
# PKI Administrator Certificate
pki_import_admin_cert=False
```

To install a separate TKS which connects to this remote CA execute the following command:

```
$ pkispawn -s TKS -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Separated TKS instance name and ports
pki_instance_name=pki-tks
pki_http_port=30080
pki_https_port=30443
# Separated TKS instance security domain references
pki_issuing_ca=https://pki.example.com:18443
pki_security_domain_hostname=pki.example.com
pki_security_domain_https_port=18443
pki_security_domain_user=caadmin
[Tomcat]
# Separated TKS Tomcat ports
pki_ajp_port=30009
pki_tomcat_server_port=30005
[TKS]
# A Separated TKS instance requires its own
# PKI Administrator Certificate
pki_import_admin_cert=False
```

To install a separate TPS which connects to this remote CA execute the following command:

```
$ pkispawn -s TPS -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Separated TPS instance name and ports
pki_instance_name=pki-tps
pki_http_port=31080
pki_https_port=31443
# Separated TPS instance security domain references
pki_issuing_ca=https://pki.example.com:18443
pki_security_domain_hostname=pki.example.com
pki_security_domain_https_port=18443
pki_security_domain_user=caadmin
[Tomcat]
# Separated TPS Tomcat ports
pki_ajp_port=31009
pki_tomcat_server_port=31005
[TPS]
# Separated TPS instances require specifying a remote CA
pki_ca_uri=https://pki.example.com:18443
# Separated TPS instances optionally utilize a remote KRA
# for server-side keygen
pki_kra_uri=https://pki.example.com:28443
pki_enable_server_side_keygen=True
pki_authdb_basedn=dc=example,dc=com
# Separated TPS instances require specifying a remote TKS
pki_tks_uri=https://pki.example.com:30443
pki_import_shared_secret=True
# A Separated TPS instance requires its own
# PKI Administrator Certificate
pki_import_admin_cert=False
```

Note: For this particular example, besides passwords, sample values were also utilized for PKI instance names, ports, URLs, machine names, etc. Under no circumstances should these demonstrative values be construed to be required literal values.

A remote CA is one where the CA resides in another PKI server instance, either on the local machine or a remote machine. In this case, myconfig.txt must specify the connection information for the remote CA and the information about the security domain (the trusted collection of subsystems within an instance).

The subsystem section is [KRA], [OCSP], [TKS], or [TPS]. This example assumes that the specified CA hosts the security domain. The CA must be running and accessible.

A new administrator certificate is generated for the new subsystem and stored in a PKCS #12 file in $HOME/.dogtag/pki_instance_name.

As in a shared instance, to install TPS in a separate instance the authentication database must be specified in the [TPS] section, and optionally the server-side key generation can be enabled. If the CA, KRA, or TKS subsystems required by TPS are running on a remote instance the following parameters must be added into the [TPS] section to specify their locations:

```
pki_ca_uri=https://<ca_hostname>:<ca_https_port>
pki_kra_uri=https://<kra_hostname>:<kra_https_port>
pki_tks_uri=https://<tks_hostname>:<tks_https_port>
```

If TPS and TKS are installed on separate instances the shared secret key should be imported over the wire between the TKS and TPS automatically.

If the automated procedure fails for any unlikely reason the following manual procedure will serve as a fallback. The key needs to be created on the TKS side and imported into the TPS side in this case.

Generate the shared secret key (if needed) in TKS with the following command:

```
$ tkstool -T -d /var/lib/pki/pki-tomcat/alias -n sharedSecret
```

Verify the shared secret key in TKS with the following command:

```
$ tkstool -L -d /var/lib/pki/pki-tomcat/alias
```

Once TPS is installed, shutdown TPS instance, then import the shared secret key into TPS with the following command:

```
$ tkstool -I -d /var/lib/pki/pki-tomcat/alias -n sharedSecret
```

Verify the shared secret key in TPS with the following command:

```
$ tkstool -L -d /var/lib/pki/pki-tomcat/alias
```

The shared secret key nickname should be stored in the following property in the TPS's CS.cfg:

```
conn.tks1.tksSharedSymKeyName=sharedSecret
```

Finally, restart the TPS instance.

### Installing CA, KRA, OCSP, TKS, or TPS using HSM
This section provides sample myconfig.txt files when a Hardware Security Module (HSM) is being utilized in a shared PKI instance.

For this example, assume that a new CA instance has been installed by executing the following command:

```
$ pkispawn -s CA -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
# Provide HSM parameters
pki_hsm_enable=True
pki_hsm_libfile=<hsm_libfile>
pki_hsm_modulename=<hsm_modulename>
pki_token_name=<hsm_token_name>
pki_token_password=<pki_token_password>
# Provide PKI-specific HSM token names
pki_audit_signing_token=<hsm_token_name>
pki_sslserver_token=<hsm_token_name>
pki_subsystem_token=<hsm_token_name>
[CA]
# Provide CA-specific HSM token names
pki_ca_signing_token=<hsm_token_name>
pki_ocsp_signing_token=<hsm_token_name>
```

To install a shared KRA in the same instance used by the CA execute the following command:

```
$ pkispawn -s KRA -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Provide HSM parameters
pki_hsm_enable=True
pki_hsm_libfile=<hsm_libfile>
pki_hsm_modulename=<hsm_modulename>
pki_token_name=<hsm_token_name>
pki_token_password=<pki_token_password>
# Provide PKI-specific HSM token names
pki_audit_signing_token=<hsm_token_name>
pki_sslserver_token=<hsm_token_name>
pki_subsystem_token=<hsm_token_name>
[KRA]
# Provide KRA-specific HSM token names
pki_storage_token=<hsm_token_name>
pki_transport_token=<hsm_token_name>
```

To install a shared OCSP in the same instance used by the CA execute the following command:

```
$ pkispawn -s OCSP -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Provide HSM parameters
pki_hsm_enable=True
pki_hsm_libfile=<hsm_libfile>
pki_hsm_modulename=<hsm_modulename>
pki_token_name=<hsm_token_name>
pki_token_password=<pki_token_password>
# Provide PKI-specific HSM token names
pki_audit_signing_token=<hsm_token_name>
pki_sslserver_token=<hsm_token_name>
pki_subsystem_token=<hsm_token_name>
[OCSP]
# Provide OCSP-specific HSM token names
pki_ocsp_signing_token=<hsm_token_name>
```

To install a shared TKS in the same instance used by the CA execute the following command:

```
$ pkispawn -s TKS -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Provide HSM parameters
pki_hsm_enable=True
pki_hsm_libfile=<hsm_libfile>
pki_hsm_modulename=<hsm_modulename>
pki_token_name=<hsm_token_name>
pki_token_password=<pki_token_password>
# Provide PKI-specific HSM token names
pki_audit_signing_token=<hsm_token_name>
pki_sslserver_token=<hsm_token_name>
pki_subsystem_token=<hsm_token_name>
```

To install a shared TPS in the same instance used by the CA execute the following command:

```
$ pkispawn -s TPS -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
# Provide HSM parameters
pki_hsm_enable=True
pki_hsm_libfile=<hsm_libfile>
pki_hsm_modulename=<hsm_modulename>
pki_token_name=<hsm_token_name>
pki_token_password=<pki_token_password>
# Provide PKI-specific HSM token names
pki_audit_signing_token=<hsm_token_name>
pki_sslserver_token=<hsm_token_name>
pki_subsystem_token=<hsm_token_name>
[TPS]
# Shared TPS instances optionally utilize their shared KRA
# for server-side keygen
pki_enable_server_side_keygen=True
pki_authdb_basedn=dc=example,dc=com
```

Important: Since HSM keys are stored in the HSM, they cannot be backed up, moved, or copied to a PKCS #12 file. For example, 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). Similarly, 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 comply with these rules will result in pkispawn reporting an appropriate error and exiting.

### Installing CA Clone
To install a CA clone execute the following command:

```
$ pkispawn -s CA -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_user=caadmin
pki_security_domain_post_login_sleep_seconds=5
[Tomcat]
pki_clone=True
pki_clone_pkcs12_password=Secret.123
pki_clone_pkcs12_path=<path_to_pkcs12_file>
pki_clone_replicate_schema=True
pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
```

A cloned CA is a CA which uses the same signing, OCSP signing, and audit signing certificates as the master CA, but issues certificates within a different serial number range. It has its own internal database -- separate from the master CA database -- but using the same base DN, that keeps in sync with the master CA through replication agreements between the databases. This is very useful for load sharing and disaster recovery. To create a clone, the myconfig.txt uses pkiclone* parameters in its [Tomcat] section which identify the original CA to use as a master template. Additionally, it connects to the master CA as a remote CA and uses its security domain.

Before the clone can be generated, the Directory Server must be created that is separate from the master CA's Directory Server. The example assumes that the master CA and cloned CA are on different machines, and that their Directory Servers are on port 389.

In addition, since this example does not utilize an HSM, the master's system certs and keys have been stored in a PKCS #12 file that is copied over to the clone subsystem in the location specified in <path_to_pkcs12_file>. This file needs to be readable by the user the Certificate Server runs as (by default, pkiuser) and be given the SELinux context pki_tomcat_cert_t.

The master's system certificates can be exported to a PKCS#12 file when the master is installed if the parameter pki_backup_keys is set to True and the pki_backup_password is set. The PKCS#12 file is then found under /var/lib/pki/<instance_name>/alias. Alternatively, the PKCS#12 file can be generated at any time post-installation using PKCS12Export.

The pki_security_domain_post_login_sleep_seconds config specifies sleep duration after logging into a security domain, to allow the security domain session data to be replicated to subsystems on other hosts. It is optional and defaults to 5 seconds.

An example invocation showing the export of the system certificates and keys, copying the keys to the replica subsystem, and setting the relevant SELinux and file permissions is shown below. pwfile is a text file containing the password for the masters NSS DB (found in /etc/pki/instance_name/password.conf). pkcs12_password_file is a text file containing the password selected for the generated PKCS12 file.

```
master# PKCS12Export -d /var/lib/pki/pki-tomcat/conf/alias -p pwfile \

        -w pkcs12_password_file -o backup_keys.p12
master# scp backup_keys.p12 clone:/backup_keys.p12
clone# chown pkiuser: /backup_keys.p12
clone# semanage -a -t pki_tomcat_cert_t /backup_keys.p12
```

Note: From Dogtag 10.3, a slightly different mechanism has been provided to create and specify the required PKCS#12 file to the clone subsystem. This new method is provided in addition to the method above, but will become the preferred method in future releases.

This method can be used if both master and clone are 10.3 or above.

To export the required keys from the master, use the pki-server command line tool.

```
master# pki-server ca-clone-prepare -i pki-tomcat \

        --pkcs12-file backup_keys.p12 \

        --pkcs12-password Secret123
master# scp backup_keys.p12 clone:/backup_keys.p12
master# scp /var/lib/pki/pki-tomcat/conf/external_certs.conf \

         clone:/external_certs.conf
```

The external_certs.conf file contains information about third party certificates that were added to the master's certificate database using the pki-server command. The certificates themselves are stored in the backup_keys.p12 file. If there are no third-party certifcates that have been added, then the external_certs.conf file may not exist and should be ignored.

The two files (backup_keys.p12 and external_certs.conf) are specified to pkispawn as below.

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_user=caadmin
[Tomcat]
pki_server_pkcs12_path=<path to pkcs12 file>
pki_server_pkcs12_password=Secret.123
pki_server_external_certs_path=<path to external_certs.conf file>
pki_clone=True
pki_clone_replicate_schema=True
pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
```

Note that the previous p12 parameters (pki_clonepkcs12*) are no longer needed, and will be ignored.

Note: One current cloning anomaly to mention is the following scenario:

1.

Create a clone of a CA or of any other subsystem.

2.

Remove that just created clone.

3.

Immediately attempt the exact same clone again, in place of the recently destroyed instance. Before recreating this clone, make sure the pki_ds_remove_data=True is used in the clone's deployment config file. This will remove the old data from the previous clone.

Here the Director Server instance may have worked itself in into a state where it no longer accepts connections, aborting the clone configuration quickly.

The fix to this is to simply restart the Directory Server instance before creating the clone for the second time. After restarting the Directory Server it should be possible to create the mentioned clone instance.

### Installing KRA or TKS Clone
To install a KRA or TKS (OCSP and TPS unsupported as of now) execute the following command:

```
$ pkispawn -s <subsystem> -f myconfig.txt
```

where subsystem is KRA or TKS and myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_user=caadmin
[Tomcat]
pki_clone=True
pki_clone_pkcs12_password=Secret.123
pki_clone_pkcs12_path=<path_to_pkcs12_file>
pki_clone_replicate_schema=True
pki_clone_uri=https://<master_subsystem_host>:<master_subsystem_https_port>
pki_issuing_ca=https://<ca_hostname>:<ca_https_port>
```

As with a CA clone, a KRA or TKS clone uses the same certificates and basic configuration as the original subsystem. The configuration points to the original subsystem to copy its configuration. This example also assumes that the CA is on a remote machine and specifies the CA and security domain information.

The parameter pki_clone_uri should be modified to point to the required master (KRA or TKS).

As of 10.3, a slightly different mechanism has been introduced to generate and specify the PKCS#12 file and any third-party certificates. See the Installing CA Clone section for details.

### Installing CA Clone on the Same Host
For testing purposes, it is useful to configure cloned CAs which exist (with their internal databases) on the same host as the master CA. To configure the cloned CA execute the following command:

```
$ pkispawn -s CA -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret123
pki_client_database_password=Secret123
pki_client_pkcs12_password=Secret123
pki_ds_password=Secret123
pki_ds_ldap_port=<unique port different from master>
pki_ds_ldaps_port=<unique port different from master>
pki_http_port=<unique port different from master>
pki_https_port=<unique port different from master>
pki_instance_name=<unique name different from master>
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_password=Secret123
[Tomcat]
pki_ajp_port=<unique port different from master>
pki_clone=True
pki_clone_pkcs12_password=Secret123
pki_clone_pkcs12_path=<path_to_pkcs12_file>
pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
pki_tomcat_server_port=<unique port different from master>
[CA]
pki_ds_base_dn=<identical value as master>
pki_ds_database=<identical value as master>
```

In this case, because both CA Tomcat instances are on the same host, they must have distinct ports. Similarly, each CA must use a distinct directory server instance for its internal database. Like the Tomcat instances, these are distinguished by distinct ports. The suffix being replicated (pki_ds_base), however, must be the same for both master and clone.

### Installing Subordinate CA in Existing Security Domain
To install a subordinate CA in an existing security domain execute the following command:

```
$ pkispawn -s CA -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
pki_security_domain_hostname=<security_domain_ca_hostname>
pki_security_domain_https_port=<security_domain_ca_https_port>
pki_security_domain_user=caadmin
[CA]
pki_subordinate=True
pki_issuing_ca=https://<master_ca_hostname>:<master_ca_https_port>
pki_ca_signing_subject_dn=cn=CA Subordinate Signing,o=example.com
```

A sub-CA derives its certificate configuration -- such as allowed extensions and validity periods -- from a superior or root CA. Otherwise, the configuration of the CA is independent of the root CA, so it is its own instance rather than a clone. A sub-CA is configured using the pki_subordinate parameter and a pointer to the CA which issues the sub-CA's certificates.

Note: The value of pki_ca_signing_subject_dn of a subordinate CA should be different from the root CA's signing subject DN.

### Installing Subordinate CA in New Security Domain
To install a subordinate CA in a new security domain execute the following command:

```
$ pkispawn -s CA -f myconfig.txt
```

where myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
pki_security_domain_hostname=<master CA security domain hostname>
pki_security_domain_https_port=<master CA security domain https port>
pki_security_domain_user=caadmin
[CA]
pki_subordinate=True
pki_issuing_ca=https://<master_ca_hostname>:<master_ca_https_port>
pki_ca_signing_subject_dn=cn=CA Subordinate Signing,o=example.com
pki_subordinate_create_new_security_domain=True
pki_subordinate_security_domain_name=Subordinate CA Security Domain
```

In this section, the subordinate CA logs onto and registers with the security domain CA (using parameters pki_security_domain_hostname, pki_security_domain_user and pki_security_domain_password) as in the previous section, but also creates and hosts a new security domain. To do this, pki_subordinate_create_new_security_domain must be set to True. The subordinate CA security domain name can also be specified by specifying a value for pki_subordinate_security_domain_name.

Note: The value of pki_ca_signing_subject_dn of a subordinate CA should be different from the root CA's signing subject DN.

### Installing Externally-Signed CA
To install an externally signed CA execute the following command:

```
$ pkispawn -s CA -f myconfig.txt
```

This is a two-step process.

In the first step, a certificate signing request (CSR) is generated for the signing certificate and myconfig.txt contains the following text:

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
[CA]
pki_external=True
pki_ca_signing_csr_path=/tmp/ca_signing.csr
pki_ca_signing_subject_dn=cn=CA Signing,ou=External,o=example.com
```

The CSR is written to pki_ca_signing_csr_path. The pki_ca_signing_subject_dn should be different from the subject DN of the external CA that is signing the request. The pki_ca_signing_subject_dn parameter can be used to specify the signing certificate's subject DN.

The CSR is then submitted to the external CA, and the resulting certificate and certificate chain are saved to files on the system.

In the second step, the configuration file has been modified to install the issued certificates. In place of the original CSR, the configuration file now points to the issued CA certificate and certificate chain. There is also a flag to indicate that this completes the installation process (pki_external_step_two).

```
[DEFAULT]
pki_admin_password=Secret.123
pki_client_database_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
pki_security_domain_password=Secret.123
[CA]
pki_external=True
pki_external_step_two=True
pki_cert_chain_path=/tmp/ca_cert_chain.cert
pki_ca_signing_cert_path=/tmp/ca_signing.cert
pki_ca_signing_subject_dn=cn=CA Signing Certificate,ou=External,o=example.com
```

Then, the pkispawn command is run again:

```
$ pkispawn -s CA -f myconfig.txt
```

### Installing PKI Subsystem with Secure LDAP Connection
There are three scenarios in which a PKI subsystem (e.g. a CA) needs to communicate securely via LDAPS with a directory server:

Scenario 1: A directory server exists which is already running LDAPS using a CA certificate that has been issued by some other CA. For this scenario, the CA certificate must be made available via a PEM file (e.g. $HOME/dscacert.pem) prior to running pkispawn such that the new CA may be installed and configured to communicate with this directory server using LDAPS.

Scenario 2: A directory server exists which is currently running LDAP. Once a CA has been created, there is a desire to use its CA certificate to issue an SSL certificate for this directory server so that this CA and this directory server can communicate via LDAPS. For this scenario, since there is no need to communicate securely during the pkispawn installation/configuration, simply use pkispawn to install and configure the CA using the LDAP port of the directory server, issue an SSL certificate from this CA for the directory server, and then reconfigure the CA and directory server to communicate with each other via LDAPS.

Scenario 3: Similar to the previous scenario, a directory server exists which is currently running LDAP, and the desire is to create a CA and use it to establish LDAPS communications between this CA and this directory server. However, for this scenario, there is a need for the CA and the directory server to communicate securely during pkispawn installation and configuration. For this to succeed, the directory server must generate a temporary self-signed certificate which then must be made available via a PEM file (e.g. $HOME/dscacert.pem) prior to running pkispawn. Once the CA has been created, swap things out to reconfigure the CA and directory server to utilize LDAPS through the desired certificates.

Set up a Directory Server instance with a self-signed CA certificate (see dscreate(8)), then export the certificate into a PEM file

Once the self-signed CA certificate is obtained, add the following parameters into the [DEFAULT] section in myconfig.txt:

```
pki_ds_url=ldaps://localhost:636
pki_ds_secure_connection_ca_pem_file=$HOME/dscacert.pem
```

Then execute pkispawn to create the CA subsystem.

### Managing PKI instance
To start a PKI instance named <pki_instance_name>:

```
$ systemctl start pki-tomcatd@<pki_instance_name>.service
```

To stop a PKI instance named <pki_instance_name>:

```
$ systemctl stop pki-tomcatd@<pki_instance_name>.service
```

To restart a PKI instance named <pki_instance_name>:

```
$ systemctl restart pki-tomcatd@<pki_instance_name>.service
```

To obtain the status of a PKI instance named <pki_instance_name>:

```
$ systemctl status pki-tomcatd@<pki_instance_name>.service
```

To obtain a detailed status of a Tomcat PKI instance named <pki_instance_name>:

```
$ pki-server status <pki_instance_name>
```

To list all available PKI instances installed on a system:

```
$ pki-server instance-find
```

## SEE ALSO
pkidestroy(8)

pki_default.cfg(5)

pki(1)

dscreate(8)

## AUTHORS
Ade Lee <alee@redhat.com> and Dinesh Prasanth M K <dmoluguw@redhat.com>

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


apt-cudf-get

title: apt-cudf-get(8)

summary: wrapper for calling apt\-get with external solvers

text:
# apt-cudf-get(8)

## NAME
apt-cudf-get - wrapper for calling apt-get with external solvers

## SYNOPSIS
apt-cudf-get [arguments]

## DESCRIPTION
apt-cudf-get is a wrapper that allows one to invoke apt-get with external solvers while ignoring apt's pinning.

All options are passed on to apt-get.

Normally, apt uses so-called pinning to select a candidate version of a package in case there are several versions available. This also holds when calling apt-get with external solvers. However, when it is not possible to find a solution under this constraint, it may be useful to relax pinning and to allow the external solver to choose among all available versions of packages in order to satisfy dependencies, not only those that are selected by the pinning. This is precisely what apt-cudf-get does.

Note that, when using an external solver, the proposed solution may contain any available version of the packages that are given as arguments to install on the command line without specifying a version qualifier.

For example

```
    apt-cudf-get --solver aspcud install ocaml
```

may propose to install any available version of ocaml, while

```
    apt-cudf-get --solver aspcud install ocaml=4.01.0
```

will only propose to install ocaml in version 4.01.0

## AUTHOR
Pietro Abate and Roberto Di Cosmo

## BUGS
Not all types of arguments to apt are correctly treated by this wrapper, in particular not the +pkg and -pkg shorthands for installation and removal requests.

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


fatlabel

package: dosfstools

title: fatlabel(8)

text:
# fatlabel(8)

## NAME
fatlabel - set or get MS-DOS filesystem label or volume ID

## SYNOPSIS
fatlabel [OPTIONS] DEVICE [NEW]

## DESCRIPTION
fatlabel will display or change the volume label or volume ID on the MS-DOS filesystem located on DEVICE. By default it works in label mode. It can be switched to volume ID mode with the option -i or --volume-id.

If NEW is omitted, then the existing label or volume ID is written to the standard output. A label can't be longer than 11 bytes and should be in all upper case for best compatibility. An empty string or a label consisting only of white space is not allowed. A volume ID must be given as a hexadecimal number (no leading "0x" or similar) and must fit into 32 bits.

## OPTIONS
-i, --volume-id

Switch to volume ID mode.

-r, --reset

Remove label in label mode or generate new ID in volume ID mode.

-c PAGE, --codepage=PAGE

Use DOS codepage PAGE to encode/decode label. By default codepage 850 is used.

-h, --help

Display a help message and terminate.

-V, --version

Show version number and terminate.

## COMPATIBILITY and BUGS
For historic reasons FAT label is stored in two different locations: in the boot sector and as a special volume label entry in the root directory. MS-DOS 5.00, MS-DOS 6.22, MS-DOS 7.10, Windows 98, Windows XP and also Windows 10 read FAT label only from the root directory. Absence of the volume label in the root directory is interpreted as empty or none label, even if boot sector contains some valid label.

When Windows XP or Windows 10 system changes a FAT label it stores it only in the root directory — letting boot sector unchanged. Which leads to problems when a label is removed on Windows. Old label is still stored in the boot sector but is removed from the root directory.

dosfslabel prior to the version 3.0.7 operated only with FAT labels stored in the boot sector, completely ignoring a volume label in the root directory.

dosfslabel in versions 3.0.7–3.0.15 reads FAT labels from the root directory and in case of absence, it fallbacks to a label stored in the boot sector. Change operation resulted in updating a label in the boot sector and sometimes also in the root directory due to the bug. That bug was fixed in dosfslabel version 3.0.16 and since this version dosfslabel updates label in both location.

Since version 4.2, fatlabel reads a FAT label only from the root directory (like MS-DOS and Windows systems), but changes a FAT label in both locations. In version 4.2 was fixed handling of empty labels and labels which starts with a byte 0xE5. Also in this version was added support for non-ASCII labels according to the specified DOS codepage and were added checks if a new label is valid.

It is strongly suggested to not use dosfslabel prior to version 3.0.16.

## DOS CODEPAGES
MS-DOS and Windows systems use DOS (OEM) codepage for encoding and decoding FAT label. In Windows systems DOS codepage is global for all running applications and cannot be configured explicitly. It is set implicitly by option Language for non-Unicode programs available in Regional and Language Options via Control Panel. Default DOS codepage for fatlabel is 850. See following mapping table between DOS codepage and Language for non-Unicode programs:

Codepage

Language

437

English (India), English (Malaysia), English (Republic of the Philippines), English (Singapore), English (South Africa), English (United States), English (Zimbabwe), Filipino, Hausa, Igbo, Inuktitut, Kinyarwanda, Kiswahili, Yoruba

720

Arabic, Dari, Persian, Urdu, Uyghur

737

Greek

775

Estonian, Latvian, Lithuanian

850

Afrikaans, Alsatian, Basque, Breton, Catalan, Corsican, Danish, Dutch, English (Australia), English (Belize), English (Canada), English (Caribbean), English (Ireland), English (Jamaica), English (New Zealand), English (Trinidad and Tobago), English (United Kingdom), Faroese, Finnish, French, Frisian, Galician, German, Greenlandic, Icelandic, Indonesian, Irish, isiXhosa, isiZulu, Italian, K'iche, Lower Sorbian, Luxembourgish, Malay, Mapudungun, Mohawk, Norwegian, Occitan, Portuguese, Quechua, Romansh, Sami, Scottish Gaelic, Sesotho sa Leboa, Setswana, Spanish, Swedish, Tamazight, Upper Sorbian, Welsh, Wolof

852

Albanian, Bosnian (Latin), Croatian, Czech, Hungarian, Polish, Romanian, Serbian (Latin), Slovak, Slovenian, Turkmen

855

Bosnian (Cyrillic), Serbian (Cyrillic)

857

Azeri (Latin), Turkish, Uzbek (Latin)

862

Hebrew

866

Azeri (Cyrillic), Bashkir, Belarusian, Bulgarian, Kyrgyz, Macedonian, Mongolian, Russian, Tajik, Tatar, Ukrainian, Uzbek (Cyrillic), Yakut

874

Thai

932

Japanese

936

Chinese (Simplified)

949

Korean

950

Chinese (Traditional)

1258

Vietnamese

## SEE ALSO
fsck.fat(8), mkfs.fat(8)

## HOMEPAGE
The home for the dosfstools project is its GitHub project page.

## AUTHORS
dosfstools were written by Werner Almesberger, Roman Hodek, and others. Current maintainers are Andreas Bombe and Pali Rohár.


fsck.fat

title: fsck.fat(8)

summary: check and repair MS-DOS FAT filesystems

text:
# fsck.fat(8)

## NAME
fsck.fat - check and repair MS-DOS FAT filesystems

## SYNOPSIS
fsck.fat [OPTIONS] DEVICE

## DESCRIPTION
fsck.fat verifies the consistency of MS-DOS filesystems and optionally tries to repair them.

The following filesystem problems can be corrected (in this order):

- FAT contains invalid cluster numbers. Cluster is changed to EOF.

- File's cluster chain contains a loop. The loop is broken.

- Bad clusters (read errors). The clusters are marked bad and they are removed from files owning them. This check is optional.

- Directories with a large number of bad entries (probably corrupt). The directory can be deleted.

- Files . and .. are non-directories. They can be deleted or renamed.

- Directories . and .. in root directory. They are deleted.

- Bad filenames. They can be renamed.

- Duplicate directory entries. They can be deleted or renamed.

- Directories with non-zero size field. Size is set to zero.

- Directory . does not point to parent directory. The start pointer is adjusted.

- Directory .. does not point to parent of parent directory. The start pointer is adjusted.

- . and .. are not the two first entries in a non-root directory. The entries are created, moving occupied slots if necessary.

- Start cluster number of a file is invalid. The file is truncated.

- File contains bad or free clusters. The file is truncated.

- File's cluster chain is longer than indicated by the size fields. The file is truncated.

- Two or more files share the same cluster(s). All but one of the files are truncated. If the file being truncated is a directory file that has already been read, the filesystem check is restarted after truncation.

- File's cluster chain is shorter than indicated by the size fields. The file is truncated.

- Volume label in root directory or label in boot sector is invalid. Invalid labels are removed.

- Volume label in root directory and label in boot sector are different. Volume label from root directory is copied to boot sector.

- Clusters are marked as used but are not owned by a file. They are marked as free.

Additionally, the following problems are detected, but not repaired:

•

Invalid parameters in boot sector

When fsck.fat checks a filesystem, it accumulates all changes in memory and performs them only after all checks are complete. This can be disabled with the -w option.

Two different variants of the FAT filesystem are supported. Standard is the FAT12, FAT16 and FAT32 filesystems as defined by Microsoft and widely used on hard disks and removable media like USB sticks and SD cards. The other is the legacy Atari variant used on Atari ST.

There are some minor differences in Atari format: Some boot sector fields are interpreted slightly different, and the special FAT entries for end-of-file and bad cluster can be different. Under MS-DOS 0xfff8 is used for EOF and Atari employs 0xffff by default, but both systems recognize all values from 0xfff8–0xffff as end-of-file. MS-DOS uses only 0xfff7 for bad clusters, where on Atari values 0xfff0–0xfff7 are for this purpose (but the standard value is still 0xfff7).

## OPTIONS
-a

Automatically repair the filesystem. No user intervention is necessary. Whenever there is more than one method to solve a problem, the least destructive approach is used.

-A

Select using the Atari variation of the FAT filesystem if that isn't active already, otherwise select standard FAT filesystem. This is selected by default if mkfs.fat is run on 68k Atari Linux.

-b

Make read-only boot sector check.

-c PAGE

Use DOS codepage PAGE to decode short file names. By default codepage 850 is used.

-d PATH

Delete the specified file. If more than one file with that name exist, the first one is deleted. This option can be given more than once.

-f

Salvage unused cluster chains to files. By default, unused clusters are added to the free disk space except in auto mode (-a).

-F NUM

Specify FAT table NUM for filesystem access. By default value 0 is assumed and then the first uncorrupted FAT table is chosen. Uncorrupted means that FAT table has valid first cluster. If default value 0 is used and all FAT tables are corrupted then fsck.fat gives up and does not try to repair FAT filesystem. If non-zero NUM value is specified then fsck.fat uses FAT table NUM for repairing FAT filesystem. If FAT table NUM has corrupted first cluster then fsck.fat will repair it. In any case, if FAT filesystem has more FAT tables then repaired content of chosen FAT table is copied to other FAT tables. To repair corrupted first cluster it is required to call fsck.fat with non-zero NUM value.

-l

List path names of files being processed.

-n

No-operation mode: non-interactively check for errors, but don't write anything to the filesystem.

-p

Same as -a, for compatibility with other *fsck.

-r

Interactively repair the filesystem. The user is asked for advice whenever there is more than one approach to fix an inconsistency. This is the default mode and the option is only retained for backwards compatibility.

-S

Consider short (8.3) file names with spaces in the middle to be invalid, like previous versions of this program did. While such file names are not forbidden by the FAT specification, and were never treated as errors by Microsoft file system checking tools, many DOS programs are unable to handle files with such names. Using this option can make them accessible to these programs.

Short file names which start with a space are considered invalid regardless of this option's setting.

Previous versions of this program exceptionally treated EA DATA. SF and WP ROOT. SF as valid short names; using this option does not preserve that exception.

-t

Mark unreadable clusters as bad.

-u PATH

Try to undelete the specified file. fsck.fat tries to allocate a chain of contiguous unallocated clusters beginning with the start cluster of the undeleted file. This option can be given more than once.

-U

Consider lowercase volume and boot label as invalid and allow only uppercase characters. Such labels are forbidden by the FAT specification, but they are widely used by Linux tools. Moreover MS-DOS and Windows systems do not have problems to read them. Therefore volume and boot labels with lowercase characters are by default permitted.

-v

Verbose mode. Generates slightly more output.

-V

Perform a verification pass. The filesystem check is repeated after the first run. The second pass should never report any fixable errors. It may take considerably longer than the first pass, because the first pass may have generated long list of modifications that have to be scanned for each disk read.

--variant TYPE

Create a filesystem of variant TYPE. Acceptable values are standard and atari (in any combination of upper/lower case). See above under DESCRIPTION for the differences.

-w

Write changes to disk immediately.

-y

Same as -a (automatically repair filesystem) for compatibility with other fsck tools.

--help

Display help message describing usage and options then exit.

## EXIT STATUS
0

No recoverable errors have been detected.

1

Recoverable errors have been detected or fsck.fat has discovered an internal inconsistency.

2

Usage error. fsck.fat did not access the filesystem.

## FILES
fsck0000.rec, fsck0001.rec, ...

When recovering from a corrupted filesystem, fsck.fat dumps recovered data into files named fsckNNNN.rec in the top level directory of the filesystem.

## BUGS

- Does not remove entirely empty directories.

- Should give more diagnostic messages.

- Undeleting files should use a more sophisticated algorithm.

## SEE ALSO
fatlabel(8), mkfs.fat(8)

## HOMEPAGE
The home for the dosfstools project is its GitHub project page.

## AUTHORS
dosfstools were written by Werner Almesberger, Roman Hodek, and others. Current maintainers are Andreas Bombe and Pali Rohár.


mkfs.fat

title: mkfs.fat(8)

summary: create an MS-DOS FAT filesystem

text:
# mkfs.fat(8)

## NAME
mkfs.fat - create an MS-DOS FAT filesystem

## SYNOPSIS
mkfs.fat [OPTIONS] DEVICE [BLOCK-COUNT]

## DESCRIPTION
mkfs.fat is used to create a FAT filesystem on a device or in an image file. DEVICE is the special file corresponding to the device (e.g. /dev/sdXX) or the image file (which does not need to exist when the option -C is given). BLOCK-COUNT is the number of blocks on the device and size of one block is always 1024 bytes, independently of the sector size or the cluster size. Therefore BLOCK-COUNT specifies size of filesystem in KiB unit and not in the number of sectors (like for all other mkfs.fat options). If omitted, mkfs.fat automatically chooses a filesystem size to fill the available space.

Two different variants of the FAT filesystem are supported. Standard is the FAT12, FAT16 and FAT32 filesystems as defined by Microsoft and widely used on hard disks and removable media like USB sticks and SD cards. The other is the legacy Atari variant used on Atari ST.

In Atari mode, if not directed otherwise by the user, mkfs.fat will always use 2 sectors per cluster, since GEMDOS doesn't like other values very much. It will also obey the maximum number of sectors GEMDOS can handle. Larger filesystems are managed by raising the logical sector size. An Atari-compatible serial number for the filesystem is generated, and a 12 bit FAT is used only for filesystems that have one of the usual floppy sizes (720k, 1.2M, 1.44M, 2.88M), a 16 bit FAT otherwise. This can be overridden with the -F option. Some PC-specific boot sector fields aren't written, and a boot message (option -m) is ignored.

## OPTIONS
-a

Normally, for any filesystem except very small ones, mkfs.fat will align all the data structures to cluster size, to make sure that as long as the partition is properly aligned, so will all the data structures in the filesystem. This option disables alignment; this may provide a handful of additional clusters of storage at the expense of a significant performance degradation on RAIDs, flash media or large-sector hard disks.

-A

Select using the Atari variation of the FAT filesystem if that isn't active already, otherwise select standard FAT filesystem. This is selected by default if mkfs.fat is run on 68k Atari Linux.

-b SECTOR-OF-BACKUP

Selects the location of the backup boot sector for FAT32. Default depends on number of reserved sectors, but usually is sector 6. If there is a free space available after the backup boot sector then backup of the FAT32 info sector is put after the backup boot sector, usually at sector 7. The backup must be within the range of reserved sectors. Value 0 completely disables creating of backup boot and info FAT32 sectors.

-c

Check the device for bad blocks before creating the filesystem.

-C

Create the file given as DEVICE on the command line, and write the to-be-created filesystem to it. This can be used to create the new filesystem in a file instead of on a real device, and to avoid using dd in advance to create a file of appropriate size. With this option, the BLOCK-COUNT must be given, because otherwise the intended size of the filesystem wouldn't be known. The file created is a sparse file, which actually only contains the meta-data areas (boot sector, FATs, and root directory). The data portions won't be stored on the disk, but the file nevertheless will have the correct size. The resulting file can be copied later to a floppy disk or other device, or mounted through a loop device.

-D DRIVE-NUMBER

Specify the BIOS drive number to be stored in the FAT boot sector. For hard disks and removable medias it is usually 0x80–0xFF (0x80 is first hard disk C:, 0x81 is second hard disk D:, ...), for floppy devices or partitions to be used for floppy emulation it is 0x00–0x7F (0x00 is first floppy A:, 0x01 is second floppy B:).

-f NUMBER-OF-FATS

Specify the number of file allocation tables in the filesystem. The default is 2.

-F FAT-SIZE

Specifies the type of file allocation tables used (12, 16 or 32 bit). If nothing is specified, mkfs.fat will automatically select between 12, 16 and 32 bit, whatever fits better for the filesystem size.

-g HEADS/SECTORS-PER-TRACK

Specify HEADS and SECTORS-PER-TRACK numbers which represents disk geometry of DEVICE. Both numbers are stored into the FAT boot sector. Number SECTORS-PER-TRACK is used also for aligning the total count of FAT sectors. By default disk geometry is read from DEVICE itself. If it is not available then LBA-Assist Translation and translation table from the SD Card Part 2 File System Specification based on total number of disk sectors is used.

-h NUMBER-OF-HIDDEN-SECTORS

Specify the number of so-called hidden sectors, as stored in the FAT boot sector: this number represents the beginning sector of the partition containing the file system. Normally this is an offset (in sectors) relative to the start of the disk, although for MBR logical volumes contained in an extended partition of type 0x05 (a non-LBA extended partition), a quirk in the MS-DOS implementation of FAT requires it to be relative to the partition's immediate containing Extended Boot Record. Boot code and other software handling FAT volumes may also rely on this field being set up correctly; most modern FAT implementations will ignore it. By default, if the DEVICE is a partition block device, mkfs.fat uses the partition offset relative to disk start. Otherwise, mkfs.fat assumes zero. Use this option to override this behaviour.

-i VOLUME-ID

Sets the volume ID of the newly created filesystem; VOLUME-ID is a 32-bit hexadecimal number (for example, 2e24ec82). The default is a number which depends on the filesystem creation time.

-I

Ignore and disable safety checks. By default mkfs.fat refuses to create a filesystem on a device with partitions or virtual mapping. mkfs.fat will complain and tell you that it refuses to work. This is different when using MO disks. One doesn't always need partitions on MO disks. The filesystem can go directly to the whole disk. Under other OSes this is known as the superfloppy format. This switch will force mkfs.fat to work properly.

-l FILENAME

Read the bad blocks list from FILENAME.

-m MESSAGE-FILE

Sets the message the user receives on attempts to boot this filesystem without having properly installed an operating system. The message file must not exceed 418 bytes once line feeds have been converted to carriage return-line feed combinations, and tabs have been expanded. If the filename is a hyphen (-), the text is taken from standard input.

-M FAT-MEDIA-TYPE

Specify the media type to be stored in the FAT boot sector. This value is usually 0xF8 for hard disks and is 0xF0 or a value from 0xF9 to 0xFF for floppies or partitions to be used for floppy emulation.

--mbr[=y|yes|n|no|a|auto]

Fill (fake) MBR table with disk signature one partition which starts at sector 0 (includes MBR itself) and spans whole disk device. It is needed only for non-removable disks used on Microsoft Windows systems and only when formatting whole unpartitioned disk. Location of the disk signature and partition table overlaps with the end of the first FAT sector (boot code location), therefore there is no additional space usage. Default is auto mode in which mkfs.fat put MBR table only for non-removable disks when formatting whole unpartitioned disk.

-n VOLUME-NAME

Sets the volume name (label) of the filesystem. The volume name can be up to 11 characters long. Supplying an empty string, a string consisting only of white space or the string "NO NAME" as VOLUME-NAME has the same effect as not giving the -n option. The default is no label.

--codepage=PAGE

Use DOS codepage PAGE to encode label. By default codepage 850 is used.

-r ROOT-DIR-ENTRIES

Select the minimal number of entries available in the root directory. The default is 112 or 224 for floppies and 512 for hard disks. Note that this is minimal number and it may be increased by mkfs.fat due to alignment of structures. See also mkfs.fat option -a.

-R NUMBER-OF-RESERVED-SECTORS

Select the minimal number of reserved sectors. With FAT32 format at least 2 reserved sectors are needed, the default is 32. Otherwise the default is 1 (only the boot sector). Note that this is minimal number and it may be increased by mkfs.fat due to alignment of structures. See also mkfs.fat option -a.

-s SECTORS-PER-CLUSTER

Specify the number of disk sectors per cluster. Must be a power of 2, i.e. 1, 2, 4, 8, ... 128.

-S LOGICAL-SECTOR-SIZE

Specify the number of bytes per logical sector. Must be a power of 2 and greater than or equal to 512, i.e. 512, 1024, 2048, 4096, 8192, 16384, or 32768. Values larger than 4096 are not conforming to the FAT file system specification and may not work everywhere.

-v

Verbose execution.

--offset SECTOR

Write the filesystem at a specific sector into the device file. This is useful for creating a filesystem in a partitioned disk image without having to set up a loop device.

--variant TYPE

Create a filesystem of variant TYPE. Acceptable values are standard and atari (in any combination of upper/lower case). See above under DESCRIPTION for the differences.

--help

Display option summary and exit.

--invariant

Use constants for normally randomly generated or time based data such as volume ID and creation time. Multiple runs of mkfs.fat on the same device create identical results with this option. Its main purpose is testing mkfs.fat.

## BUGS
mkfs.fat can not create boot-able filesystems. This isn't as easy as you might think at first glance for various reasons and has been discussed a lot already. mkfs.fat simply will not support it ;)

## SEE ALSO
fatlabel(8), fsck.fat(8)

## HOMEPAGE
The home for the dosfstools project is its GitHub project page.

## AUTHORS
dosfstools were written by Werner Almesberger, Roman Hodek, and others. Current maintainers are Andreas Bombe and Pali Rohár.


dpkg-fsys-usrunmess

package: dpkg

title: dpkg-fsys-usrunmess(8)

summary: undoes the merged\-/usr\-via\-aliased\-dirs mess

text:
# dpkg-fsys-usrunmess(8)

## NAME
dpkg-fsys-usrunmess - undoes the merged-/usr-via-aliased-dirs mess

## SYNOPSIS
dpkg-fsys-usrunmess [option...]

## DESCRIPTION
dpkg-fsys-usrunmess is a tool to fix up filesystems that have been installed anew with recent installers with unfortunate defaults or migrated to the broken merged /usr via aliased directories layout, which is not supported by dpkg. See the dpkg FAQ.

Note: In Debian its tech-ctte has decreed that on the release after bookworm the non-usrmerged layout is not going to be supported, and thus some of its maintainers might not fix issues or intentionally remove non-usrmerged support, so you will need decide and pick your poison.

The program will perform the following overall actions:

- Check whether the system needs to be switched, otherwise do nothing,

- Check for dpkg database consistency and otherwise abort.

- Generate and install a regression prevention package, if requested on the command-line or otherwise on the prompt.

- Get the list of files and alternatives that need to be restored.

- Look for untracked kernel modules files that need to be moved too.

- Create a shadow hierarchy under /.usrunmess, by creating the directories symlinks or hardlinking or copying the files as needed.

- Prompt for confirmation before proceeding, if requested on the command-line.

- Lock the dpkg database.

- Mark all packages as half-configured to force running maintainer scripts that might need to recreate files.

- Replace the aliased directories with the shadow ones, by creating a backup of the old symlinked directories and renaming the shadow ones over.

- Relabel MAC information for directories and symlinks if necessary.

- Remove backup symlinks.

- Remove old moved objects, but defer directory removal.

- Remove old deferred directories that are not referenced by dpkg-query.

- Remove shadow root directory.

- Register a policy-rc.d to disallow service actions, which means that services might need to be restarted afterwards, ideally via a reboot.

- Reconfigure all packages.

- Unregister the policy-rc.d and restore the alternatives state.

Note: When running the program from some shells such as bash(1) or zsh(1), after executing it, you might need to request the shell to forget all remembered executable locations with for example "hash -r".

Note: Some directories might linger after the migration in case they contain untracked files. A list is printed once the script has finished for further investigation.

Warning: Note that this operation has the potential to render the system unusable or broken in case of a sudden crash or reboot, unexpected state of the system, or possible bugs in the script. Be prepared with recovery media and consider doing backups beforehand.

## OPTIONS
-p, --prompt

Prompt at the time of no return, so that the debug output or the shadow hierarchy can be evaluated before proceeding.

--prevention

--no-prevention

Enables or disables generating and installing a regression prevention package into the system. If no option has been specified, the action to take will be prompted. The generated package contains the Protected field set to yes to protect against accidental removal of the package.

-n, --no-act

--dry-run

This option enables the dry-run mode, where no destructive action takes place, only the preparatory part.

-?, --help

Show the usage message and exit.

--version

Show the version and exit.

## ENVIRONMENT
DPKG_USRUNMESS_NOACT

This setting defines whether to enable dry-run mode.

## SEE ALSO
<https://wiki.debian.org/Teams/Dpkg/FAQ#broken-usrmerge>.