pkispawn

title: pkispawn(8)

summary: Sets up a PKI subsystem.

text:
# pkispawn(8)

## NAME
pkispawn - Sets up a PKI subsystem.

## SYNOPSIS
pkispawn -s subsystem -f config_file [-h] [-v]

## 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).

pkispawn supersedes and combines the functionality of pkicreate and pkisilent, which were available in earlier releases of Certificate Server. It is now possible to completely create and configure the Certificate Server subsystem in a single step using pkispawn.

Note: Previously, as an alternative to using pkisilent to perform a non-interactive batch configuration, a PKI instance could be interactively configured by a GUI-based configuration wizard via a Firefox browser. GUI-based configuration of a PKI instance is unavailable in this version of the product.

## 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/log/pki/pki-tomcat, 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
# Optionally keep client databases
pki_client_database_purge=False
```

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
# Optionally keep client databases
pki_client_database_purge=False
# Separated CA instance name and ports
pki_instance_name=pki-ca
pki_http_port=18080
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
# Optionally keep client databases
pki_client_database_purge=False
# Separated KRA instance name and ports
pki_instance_name=pki-kra
pki_http_port=28080
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
# Optionally keep client databases
pki_client_database_purge=False
# 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
# Optionally keep client databases
pki_client_database_purge=False
# 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
# Optionally keep client databases
pki_client_database_purge=False
# 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
# Optionally keep client databases
pki_client_database_purge=False
# 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 /etc/pki/pki-tomcat/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 /etc/pki/pki-tomcat/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_secure_connection=True
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⟩.


pks-intro

package: pks

title: pks-intro(8)

summary: OpenPGP Public Key Server Introduction

text:
# pks-intro(8)

## NAME
pks-intro - OpenPGP Public Key Server Introduction

## DESCRIPTION
The OpenPGP Public Key Server system is a set of programs which manages and provides general access to a database of OpenPGP public keys.

The database itself is not a standard OpenPGP keyring. Instead, the keys which are managed by the server are stored in a set of Berkeley DB 2.x format database files. Most operations only take a fraction of a second, and even large operations involving tens of thousands of keys usually take only a few minutes.

### Programs
pksclient(8)

This is a command-line program for managing the database. It supports All the operations of the daemon, and a few more.

pksd(8)

This is the public key server daemon. It processes HTTP requests and mail requests to add keys to the database and query the database contents.

pksdctl(8)

This is a helper program used by pksd-mail.sh and pksd-queue-run.sh.

pks-mail.sh

This script is run for each mail message received to queue the message.

pks-queue-run.sh

This script is used to process the queue of incoming mail messages.

### Configuration files and data files
pksd.conf(5)

This file contains all the configuration data needed to run the system.

<db_dir>/keydbXXX

These files contain the actual database. The first files contain the OpenPGP key information, indexed by the key ID. The XXX is 000, 001, 002, up to the number of key database files minus 1.

<db_dir>/num_keydb

This file contains the number of key database files. In order to handle very large databases on operating systems with limited file sizes, the key database can be split into up to 1000 separate files.

<db_dir>/timedb

This file indexes the key ID's by the time they were added to the database.

<db_dir>/worddb

This file indexes the key ID's by the words in the key's user ID's.

## SEARCHING
The search engine is not the same as that used by the gpg(1) or pgp(1) programs. It will return information for all keys which contain all the words in the search string. A ``word'' in this context is a string of consecutive alphabetic characters. For example, in the string user@example.com, the words are user, example, and com.

## DATABASE ADMINISTRATION
pksd uses the locking, logging, and transaction facilities of Berkeley DB. This provides for added safety in the event of a server crash, and also allows for multiple pksd and/or pksclient processes to access the database at the same time.

This does make management of a key server a little more complicated. The Berkeley DB reference section on Berkeley DB Transactional Access Methods Applications

```
<http://www.sleepycat.com/docs/ref/toc.html#transapp>
```

describes the procedures and commands which are used for checkpointing, archive (backup), and recovery. You should familiarize yourself with this information before running a key server.

## DESIGN
The key server was Marc Horowitz's Advanced Undergraduate Project (which is really a thesis, but with a different name) for his Bachelor's degree in Computer Science and Engineering at the Massachusetts Institute of Technology. You can read detailed discussion of the internals of this key server, you can read the his AUP at

```
<http://www.mit.edu/people/marc/pks/thesis.html>.
```

## FILES
pksd.conf, <db_dir>/keydbXXX, <db_dir>/num_keydb, <db_dir>/timedb, <db_dir>/worddb

## AUTHOR
Marc Horowitz, Massachusetts Institute of Technology

## BUGS
Visit the bug tracking system linked from http://sourceforge.net/projects/pks to view or report bugs.

## COPYRIGHT
Copyright (c) 1996, 1997, 1998, 1999, Marc Horowitz. All rights reserved.

This software doesn't have a warranty, express or implied. See the LICENSE file in the source distribution for full conditions.

## SEE ALSO
gpg(1), pgp(1), pksclient(8), pksd(8), pksd.conf(5), pksdctl(8),pks-mail.sh(8), pks-queue-run(8)


pksclient

title: pksclient(8)

summary: Public Key Server Client

text:
# pksclient(8)

## NAME
pksclient - Public Key Server Client

## SYNOPSIS
pksclient /db/path cmd [args ...]

## DESCRIPTION
pksclient is a command line interface which allows the administrator to perform key server operations directly instead of through the daemon. The software will use locking and transaction semantics unless you specify otherwise. Never do this if another process has the database open. Once the command is completed, pksclient will attempt to checkpoint the database and remove any excess log files.

Each command takes the path to the directory which contains the database files, a command name, and possibly a list of arguments to the command. Some commands take an optional flags argument. Flags are single letters as described for each command, concatenated into a single argument.

pksclient /db/path create [num_files]

Create an empty database. If a database exists in the directory, it is destroyed. If num_files is specified, then the key database will be split into that many files. If it is not specified, then three key database files will be created.

pksclient /db/path recover

Recover an inconsistent database. This is equivalent to the db_recover(8) command, but it uses a larger cache for better performance.

pksclient /db/path add filename [flags]

Add a keyring to the database. The filename may refer to a keyring file (.pgp format), or an ASCII-armored keyring (.asc format). If the 'n' flag is specified, then an incremental for the new keyring relative to the database is generated to stdout. If the 'd' flag is specified, then the disabled flag will not be stripped from the input file. This is useful if you are initializing the database for the first time with a keyring from another key server which includes disabled keys. If the 't' flag is specified, the operation will take place without logging and transactions. This is faster, but less safe.

pksclient /db/path get userid [flags]

An ASCII-armored keyring containing all the keys matching the userid is printed to stdout. If the 'e' flag is specified, then the key's user id must be an exact case-insensitive substring of the userid argument. If the 'a' flag is specified, then the userid argument is ignored, and all keys in the database are returned. If the 'b' flag is specified, then the output keyring will be in binary format instead of ASCII-armor format. If the 'i' flag is specified, then errors will be ignored. This is used when recovering from a corrupt database. If the 'd' flag is specified, then disabled keys will be returned. If the 's' flag is specified, the selected keys will be output unsorted to stdout. This flag implies the 'b' flag. If the 't' flag is specified, the operation will take place without logging and transactions. This is faster, but less safe.

pksclient /db/path index userid [flags]

An index listing for all the keys matching the userid is printed to stdout. If the 'v' flag is specified, then signatures are included in the output. If the 'f' flag is specified, then the key fingerprint is included in the output. If the 'e' flag is specified, then the key's user id must be an exact case-insensitive substring of the userid argument. If the 'a' flag is specified, then the userid argument is ignored, and all keys in the database are indexed. If the 'i' flag is specified, then errors will be ignored. This is used when recovering from a corrupt database. If the 'd' flag is specified, then disabled keys will be returned. If the 's' flag is specified, the index will be output unsorted to stdout. If the 't' flag is specified, the operation will take place without logging and transactions. This is faster, but less safe.

pksclient /db/path since time [flags]

An ASCII-armored keyring containing all the keys added to the database or changed since the unix timestamp since is printed to stdout. The timestamp that the database was last modified is printed to stderr. If the 'b' flag is specified, then the output keyring will be in binary format instead of ASCII-armor format. If the 'r' flag is specified, then the time given is taken as the number of seconds the in the past the dump should start ( since 86400 r is thus equivalent to the LAST 1 mail command). If the 't' flag is specified, the operation will take place without logging and transactions. This is faster, but less safe.

pksclient /db/path delete userid [flags]

All keys matching the userid are deleted from the database. If the 't' flag is specified, the operation will take place without logging and transactions. This is faster, but less safe.

pksclient /db/path disable userid [flags]

All keys matching the userid have the disabled flag set. If the 'c' flag is specified, then the flag is cleared instead of set. If the 't' flag is specified, the operation will take place without logging and transactions. This is faster, but less safe.

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

## AUTHOR
Marc Horowitz, Massachusetts Institute of Technology


pksd

title: pksd(8)

summary: OpenPGP Public Key Server Daemon

text:
# pksd(8)

## NAME
pksd - OpenPGP Public Key Server Daemon

## SYNOPSIS
pksd FILE

## DESCRIPTION
pksd is a daemon which implements the functions of an OpenPGP public key server. It supports key searches, requests, additions, and modifications via web and e-mail interfaces.

The server takes a single argument, which is the name of the configuration file. The format of this file is documented in pksd.conf(5).

The server supports queries via a modified version of HTTP known as HKP (which allows for queries via web browsers), MRHKP (the machine-readable HKP format), and an e-mail interface. HKP is implemented by a few form URI's which are described in the accompanying design document. MRHKP has its own design document. The e-mail interface is described in the pks_help documents.

In order to control the running daemon, the pksdctl(8) program is used to send messages to the running server via a unix domain socket. The type and syntax of these messages is documented in the pksdctl(8) man page.

## INCREMENTAL MESSAGES
The mail server is also used for incremental distribution of modifications between peer key servers. When a key server receives an update (meaning new keys, signatures, revocations, etc.), this update is forwarded to the servers listed as peers (with the syncsite keyword) in the pksd.conf(5) file. In order to avoid updates looping forever, the servers which have processed the update are listed in the message.

To improve performance, when an incremental or add is received, only the part(s) of that request which are not already part of the key server database are included. If an incremental or add contains no new data, no incremental is generated at all.

## DISABLED KEYS
It is not useful to remove a key from the key server database. Keys in use will likely be sent to a key server again. Keys not in use are best left on the key server for archival purposes. In the future, someone might need to verify a signature from such a key, for example. In order to remove a key from circulation for whatever reason, the key can be made "disabled". This server uses the disabled flag in the OpenPGP file format. To prevent this flag from being misused, the disabled flag is treated as a special case. When a keyring is merged into the database, the disabled flags are ignored. Disabled keys in the database cannot be retrieved from the database, but they are returned by searches.

## FILES
pksd.conf

## AUTHOR
Marc Horowitz, Massachusetts Institute of Technology

## BUGS
Visit the bug tracking system linked from http://sourceforge.net/projects/pks to view or report bugs.

## COPYRIGHT
Copyright (c) 1996, 1997, 1998, 1999, Marc Horowitz. All rights reserved.

This software doesn't have a warranty, express or implied. See the LICENSE file in the source distribution for full conditions.

## SEE ALSO
pksclient(8), pksd.conf(5), pksdctl(8), pks-intro(8)


pksdctl

title: pksdctl(8)

summary: Public Key Server Control program

text:
# pksdctl(8)

## NAME
pksdctl - Public Key Server Control program

## SYNOPSIS
pksdctl socket string

## DESCRIPTION
pksdctl sends strings to a running pksd via a UNIX domain socket. The strings (which must be a single argument in the shell) are interpreted by the running pksd process as commands. Three string forms are supported:

backup

The backup command from previous versions is no longer supported. The procedures referred to in pks-intro(8) should be followed to make a backup.

disable userid

All keys matching the userid will have the disabled flag set.

mail msg

The file msg will be parsed as a mail server request. If the file is a valid request, the request succeeds, and the response can be enqueued, then the file is removed.

shutdown

The key server shuts down cleanly and exits.

## AUTHOR
Marc Horowitz, Massachusetts Institute of Technology

## BUGS
Visit the bug tracking system linked from http://sourceforge.net/projects/pks to view or report bugs.

## COPYRIGHT
Copyright (c) 1996, 1997, 1998, 1999, Marc Horowitz. All rights reserved.

This software doesn't have a warranty, express or implied. See the LICENSE file in the source distribution for full conditions.

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


ploop

package: ploop

title: ploop(8)

summary: ploop device management utility

text:
# ploop(8)

## NAME
ploop - ploop device management utility

## SYNOPSIS
ploop init

-s size [-f format] [-v version] [-t fstype] [-b blocksize] [-B fsblocksize] [--nolazy] delta_file

ploop mount

[-r] [-F] [-f format] [-b blocksize] [-d device] [-m mount_point] [-o mount_options] [-t fstype] base_delta [... top_delta]

ploop mount

[-r] [-F] [-d device] [-m mount_point] [-o mount_options] [-t fstype] [-u uuid] DiskDescriptor.xml

ploop umount

{ -d device | -m mount_point | DiskDescriptor.xml | image_file }

ploop replace

{ -u uuid | -l level | -o cur_image_file } [--keep-name] -i image_file DiskDescriptor.xml

ploop resize

-s size DiskDescriptor.xml

ploop convert

{ -f format | -v version } DiskDescriptor.xml

ploop check

[-u uuid] DiskDescriptor.xml

ploop check

[--force] [--hard-force] [--check] [--ro] [--silent] [--drop-inuse] [--raw] [--blocksize size] [--repair-sparse] image_file

ploop info

[-s] [-d] DiskDescriptor.xml

ploop list

[-a]

ploop snapshot

[-u uuid] DiskDescriptor.xml

ploop snapshot-merge

[-u uuid | -A] [-n new_delta] DiskDescriptor.xml

ploop snapshot-switch

-u uuid DiskDescriptor.xml

ploop snapshot-delete

-u uuid DiskDescriptor.xml

ploop snapshot-list

[-H] [-u uuid] [-s] [-o field[,field...]] DiskDescriptor.xml

ploop copy

-s device [-F stop_command] { [-d file] | [-o output_fd] [-f feedback_fd] }

ploop copy

-d file [-i input_fd] [-f feedback_fd]

ploop balloon discard

[--automount] [--to-free size] [--min-block min_size] [--defrag] DiskDescriptor.xml

ploop restore-descriptor

-f format [-b blocksize] disk_dir delta_file

ploop encrypt

-k KEYID [-r] [-w] DiskDescriptor.xml

## DESCRIPTION
ploop is a kernel block device, similar to the traditional loop device (which is controlled by losetup(8)) but with more features added, such as dynamic disk space allocation, stackable images, online resize, snapshotting, and live migration helper (write tracker). This manual page describes the ploop user space tool which is used to perform various operations related to ploop devices and images.

Note that this ploop tool is not aware of container entities. Commands that have DiskDescriptor.xml as an argument work with an XML file that contains meta-information about a particular ploop device configuration: device characteristics (block size etc.), storage information (names and formats of images used for the device), snapshot information, etc. If a particular command can be used both with and without the DiskDescriptor.xml argument, it is strongly advised to use the form with DiskDescriptor.xml.

## OPTIONS
Run ploop without any options to show a short synopsis, including a list of commands.

Run ploop command to show synopsis and a short description for a particular command.

### Basic commands

init

Create and initialize a ploop image file and a corresponding DiskDescriptor.xml file.

ploop init

-s size [-f format] [-v version] [-t fstype] [-b blocksize] [-B fsblocksize] [--nolazy] delta_file

-s size

Image size. If no suffix is specified, the size is in sector units (one sector is 512 bytes). One can specify optional K, M, G or T suffix to set the size in kilo-, mega-, giga- or terabytes.

-f format

Image format. See Image formats below.

-v version

Image version, can be 1 or 2. Default is 2, if supported by the kernel.

-t none|ext3|ext4

File system type to create, default is ext4. Unless none is specified, a partition, a filesystem, and a balloon file will be created inside the image. Using ext3 is not recommended.

-b blocksize

Device block size, in 512 byte sectors. Default block size is 2048 sectors, or 1 megabyte.

-B fsblocksize

Filesystem block size, in bytes. Default is 4096 bytes.

-n, --nolazy

Disable lazy mkfs initialization (which is enabled by default). Currently that means if this flag is set, mkfs.ext4(8) is called with -Elazy_itable_init=0,lazy_journal_init=0 options.

delta_file

Path to a non-existent image file to be created.

mount

Assemble a ploop device from one or more delta images, start it, and optionally mount the file system residing on the device.

Two forms of this command are provided. The first one accepts a list of delta images to be used for assembling the ploop device, while the second one is using information from a DiskDescriptor.xml file. Please note that not all mount options are applicable to both forms.

ploop mount

[-r] [-F] [-f format] [-b blocksize] [-d device] [-m mount_point] [-o mount_options] [-t fstype] base_delta [... top_delta]

ploop mount

[-r] [-F] [-d device] [-m mount_point] [-o mount_options] [-t fstype] [-u uuid] DiskDescriptor.xml

-r

Mount as read-only.

-F

Run fsck(8) on inner filesystem before mounting it. This option is ignored if -m is not used.

-f format

Image format. Ignored if DiskDescriptor.xml is specified. Otherwise, one need to specify raw as an argument, if raw image format is used.

-b blocksize

Device block size, in 512 byte sectors. Ignored if DiskDescriptor.xml is specified. Otherwise, required for raw images.

-d device

Ploop device to use, e.g. /dev/ploop0. If not specified, a randomly numbered ploop device will be used.

-m mount_point

If this option is specified, ploop goes on to mount the file system to directory denoted by mount_point.

-o mount_options

Any additional mount options, comma-separated. Used if -m is set.

-t fstype

File system type used for mounting. Used if -m is set. The default is ext4.

-u uuid | base

GUID of the image from the DiskDescriptor.xml to be mounted. By default, top GUID is used. The special 'base' value can be used to mount the base (lower-level) image.

base_delta [... top_delta]

List of image files to mount, with the first one being the base delta and the last one being the top delta (i.e. the one that will be writable unless -r is specified).

DiskDescriptor.xml

Path to the DiskDescriptor.xml file with information about images.

umount

Unmount a ploop device. Since a mounted ploop device consists of an image (or multiple images), a device, and (optionally) a file system mounted to a directory, one can refer to any of the above entities to specify what to unmount. The recommended way is to use DiskDescriptor.xml.

ploop umount

{ -d device | -m mount_point | DiskDescriptor.xml | image_file }

-d device

Ploop device, e.g., /dev/ploop0.

-m mount_point

Mount point of a ploop device to unmount.

DiskDescriptor.xml

Path to the DiskDescriptor.xml file with information about images.

image_file

Path to a mounted image file.

replace

Replaces a ploop image by a different (but identical) one, on a running ploop device. Only a read-only image (e.g. a non-top one in a stacked configuration) can be replaced. An image to be replaced is specified by either one of level, UUID, or the current image file.

If a new image is not identical to the old one (i.e. its content differs) or not suitable for ploop in any other way (e.g. it is sparse, or resides on a file system not supported by ploop), the result is undefined.

ploop replace

{ -u uuid | -l level | -o cur_image_file } [--keep-name] -i image_file DiskDescriptor.xml

-u uuid

A uuid of an image to be replaced.

-l level

A level of image to be replaced. A level is a distance of an image from the base delta.

-o cur_image_file

A current image file (the one to replace).

-k, --keep-name

A flag to keep the same image file name. If this flag is set, after the image is replaced, a new image_file is renamed to the old one (removing the old, now unused, image), so no modification to DiskDescriptor.xml is required.

-i image_file

A new replacement image.

DiskDescriptor.xml

Path to the DiskDescriptor.xml file with information about images.

resize

Resize a ploop image. Both online (i.e. when ploop is mounted and used) and offline resize is supported, and the tool can either grow or shrink both the ploop image and the underlying file system.

ploop resize

-s size DiskDescriptor.xml

-s size

Image size. If no suffix is specified, size is in sector units (one sector is 512 bytes). One can specify optional K, M, G or T suffix to set the size in kilo-, mega-, giga- or terabytes.

DiskDescriptor.xml

Path to the DiskDescriptor.xml file with information about images.

convert

Convert either ploop image format or version (but not both at the same time). Conversion can only be performed offline (i.e. image should not be in use).

ploop convert

{ -f format | -v version } DiskDescriptor.xml

-f format

Image format. See Image formats below.

-v version

Image version, can be 1 or 2.

check

Check the internal consistency of (and possibly repair) a ploop image (or images). Note that image(s) to be tested should not be in use.

ploop check

[-u uuid] DiskDescriptor.xml

Check all the images in DiskDescriptor.xml up to the one denoted by the uuid (or default top delta, if UUID is not specified). Default built-in check options are used, and the ones specified on the command line, if any, are ignored.

ploop check

[--force] [--hard-force] [--check] [--ro] [--silent] [--drop-inuse] [--raw] [--blocksize size] [--repair-sparse] DiskDescriptor.xml | image_file

-f, --force

Force check even if image's dirty flag is not set.

-F, --hard-force

Same as -f, plus try to fix even fatal errors (can be dangerous).

-c, --check

Check for duplicated blocks and holes.

-r, --ro

Read-only access, do not modify image(s).

-s, --silent

Be more silent, only report errors.

-d, --drop-inuse

Drop image "in use" flag.

-R, --raw

Specifies that image_file is a raw ploop image.

-b, --blocksize size

Image cluster block size, in sectors (for raw images).

-S, --repair-sparse

Repair sparse image(s).

encrypt

Encrypt the ploop image contents with an encryption key

ploop encrypt

-k keyid [-r] [-w] DiskDescriptor.xml

-k keyid

The identifier of a key used to encrypt the ploop image

-r

Re-encrypt the entire disk contents when changing the encryption key identifier.

-w

Securely remove the original ploop image after it had been encrypted.

### Miscellaneous commands

info

ploop info

DiskDescriptor.xml

When run without any options, show information about disk space and inodes usage and limits on the inner ploop filesystem, somewhat similar to vzquota(8) stat or show commands.

ploop info

[-s] [-d] DiskDescriptor.xml

Either one or both options can be used together. Option -s is used to show information about ploop device size, block size, and format version. Option -d is used to show a corresponding ploop block device, it available. file.

list

ploop list

[-a]

Shows a list of running ploop devices (first column) and their corresponding base images. With option -a it also shows a mount point (third column).

restore-descriptor

Create DiskDescriptor.xml file suitable for delta_file and put it into disk_dir.

ploop restore-descriptor

-f format [-b blocksize] disk_dir delta_file

Read image header in case of ploop1 format or check raw image size and generate proper DiskDescriptor.xml file. You can specify blocksize for raw images. If it's not specified it will be chosen automatically - largest possible value between 32K and 1M. Raw image size must be aligned to blocksize.

This command works only for base images. Snapshots are not supported.

### Working with snapshots
Ploop snapshots is a mechanism for creating and managing instant states of a running file system. Creating a snapshot leads to creating a new empty ploop image which is layered on top of an old one, then all writes are ending up in the top image, and reads are falling through to a lower level. There can be up to 126) stacked ploop images (or snapshots). Online snapshot merging is also supported.

Snapshots are identified by a unique UUID. A snapshot can be mounted using ploop mount -u uuid command, see above.

snapshot

Create a ploop snapshot.

ploop snapshot

[-u uuid] DiskDescriptor.xml

-u uuid

Specify a uuid for a new snapshot. If option is not given, uuid is generated automatically. To generate uuid manually, one can use the uuidgen(1) utility. Note that UUID must be enclosed in curly brackets.

snapshot-merge

Merge a snapshot with its parent. That is, contents of the delta file corresponding to the snapshot is merged to a parent delta, then the file is removed. Parent snapshot UUID is lost (as it is replaced with the uuid specified). All snapshots having the lost one as a parent are updated to have the uuid as its parent.

ploop snapshot-merge

[-u uuid | -A] [-n new_delta] DiskDescriptor.xml

-u uuid

Specify a snapshot uuid to merge. If this option is not specified, the top delta will be used.

-A

Merge all snapshots down to base delta. If some snapshots have more than a single child, they will be impossible to merge.

-n new_delta

If this option is set, instead of merging the child delta into its parent, both the parent and the child deltas are merged into a newly created file new_delta, which replaces the parent delta. Both deltas are then removed.

snapshot-switch

Switch to the specified snapshot. This operation can only be performed while ploop is not running (i.e. is unmounted). The current top delta image will be removed.

ploop snapshot-switch

-u uuid DiskDescriptor.xml

-u uuid

Specify a snapshot uuid to switch to.

snapshot-delete

Delete the specifed snapshot. This operation can only be performed if the specified snapshot is not active. In case snapshot doesn't have any children, it will simply be removed. In case snapshot has a single child, it will be merged to that child. Deleting a snapshot that has multiple children is currently not supported (but can be performed manually in an iterative fashion).

ploop snapshot-delete

-u uuid DiskDescriptor.xml

-u uuid

Specify a snapshot uuid to be deleted.

snapshot-list

List available snapshots.

ploop snapshot-list

[-H] [-u uuid] [-s] [-o field[,field...]] DiskDescriptor.xml

-H, --no-header

Suppress displaying the header row. Usable for scripts.

-u, --uuid, --id uuid

Filter the output to a specified uuid.

-s, --snapshot

List in terms of snapshots. By default (i.e. without this option) the command lists all deltas, and top delta is marked as current. When this option is used, top delta is not listed, and the snapshot which is the parent of top delta is marked as current.

-o, --output field[,field...]

Display only the specified fields. Possible fields are:

• uuid - snapshot's UUID;

• parent_uuid - snapshot's parent UUID;

• current - if this snapshot is the current one;

• fname - snapshot image file name.

### Image copying
ploop copy is a mechanism of effective copying of a top ploop image with the help of build-in ploop kernel driver feature called write tracker. Write tracker is a feature that lets ploop copy to iteratively obtain a list of modified image blocks from the kernel. Two ploop copy processes are required for iterative top delta transfer. These are used by vzmigrate(8).

copy (sending)

ploop copy

-s device [-F stop_command] { [-d file] | [-o output_fd] [-f feedback_fd] }

This command enables the in-kernel write tracker for the specified ploop device, then sends all the data blocks from the top delta image to a pipe specified by the output_fd argument (stdout, i.e. 1 by default), supposedly read by destination ploop copy, or a file. After that, it iteratively gets the list of the modified data blocks from the kernel and sends those blocks again. After a number of iterations (or when the list is empty), it executes the stop_command (this could be vzctl stop or vzctl chkpnt) and does the last iteration of sending the modified data blocks. Finally, it checks that the data were not modified, error is returned otherwise.

If feedback_fd is specified, it is used to read back from the ploop copy receiving side. The feedback channel is currently used to wait for fdatasync(2) completion.

copy (receiving)

ploop copy

-d file [-i input_fd] [-f feedback_fd]

Reads the data blocks (provided by the source ploop copy) from the file descriptor input_fd (stdin, i.e. 0 by default) and writes them to the file.

If feedback_fd is specified, it is used to send status back to the ploop copy sending side.

### Ballooning
Since there is no online shrink support in ext4 file system, ploop internally uses a technique called "ballooning" as a work around to shrink its images.

Ballooning operation consists of inflating a special balloon file (invisible for ordinary users), loading fiemap info of the inflated balloon to the kernel, relocating blocks of the image file from the tail to the space specified by fiemap info, and truncating the tail of the image file. Result is the image file of a smaller size.

However, it is quite possible that inflated balloon file will only span blocks that were never touched before. Those will look like "not allocated" space from the kernel ploop point of view. In this case nothing will be relocated and nothing truncated.

So, if balloon operation succeeded, it's only guaranteed that a user of ploop device won't be able to consume more space than the initial block device size minus the size of the inflated balloon. On the other hand, if a user of block device used a lot of space on it, then freed the significant part of used space, balloon operation will result in significant truncate of image file.

All the ploop ballooning logic is hidden from the end user, so while a number of low-level commands exist for working with ploop ballooning, those are not needed and therefore are not documented here, except for a single command.

balloon discard

In a situation when a lot of disk space were freed on an in-ploop filesystem, use ploop balloon discard to optimize the ploop image size.

ploop balloon discard

[--automount] [--to-free size] [--min-block min_size] [--defrag] DiskDescriptor.xml

Iteratively try to relocate and discard unused blocks from a ploop image, reducing its size.

Note that ploop device and its inner file system should be mounted. If not, one can use --automount option to automatically mount ploop for the duration of the operation.

Option --defrag can be used to run a filesystem defragmentation utility (currently e4defrag2 on ext4 only) before the main operation.

Option --to-free can be used to specify a maximum disk space to be freed. In other words, stop the process once freed space exceeded requested size. Default is 0, meaning to try to free as much space as possible.

Option --min-block can be used to specify a minimum size of an extent to free. The smallest possible extent is 1 cluster (currently 1 MB), one can specify higher value to speed up the whole discarding operation.

Note that the same functionality is available by means of vzctl compact command.

### Image formats
The following image formats are currently supported.

raw

Raw format, with 1:1 mapping between the image file and the ploop device.

ploop1, expanded

Expanded format. The image will grow according to the needs of the underlying file system. This format is the default. Names 'ploop1' and 'expanded' are aliases.

preallocated

This is the same as 'ploop1' or 'expanded', the only difference is all the file blocks are allocated during creation.

## EXIT STATUS
ploop exits with status 0 in case of successful execution. Any status greater than 0 signifies an error.

1, SYSEXIT_CREAT

Error creating a file.

2, SYSEXIT_DEVICE

Error getting or opening a ploop device.

3, SYSEXIT_DEVIOC

Error doing ioctl(2) on ploop device.

4, SYSEXIT_OPEN

Error opening a file.

5, SYSEXIT_MALLOC

Not enough memory (error from malloc(3), realloc(3), calloc(3), or posix_memalign(3)).

6, SYSEXIT_READ

Error during read.

7, SYSEXIT_WRITE

Error during write.

9, SYSEXIT_SYSFS

Error reading from a sysfs file (usually under /sys/block/ploop...).

11, SYSEXIT_PLOOPFMT

Corrupted ploop image detected.

12, SYSEXIT_SYS

Other system error.

13, SYSEXIT_PROTOCOL

Broken protocol (unexpected value received).

14, SYSEXIT_LOOP

pcopy command can't finalize copying (frozen filesystem is changing).

15, SYSEXIT_FSTAT

Error from stat(2), fstat(2), or statfs(2).

16, SYSEXIT_FSYNC

Error from fsync(2) or syncfs(2).

17, SYSEXIT_EBUSY

Can't continue, another operation is in progress.

18, SYSEXIT_FLOCK

Error from flock(2).

19, SYSEXIT_FTRUNCATE

Error from ftruncate(2) or truncate(2).

20, SYSEXIT_FALLOCATE

Error from fallocate(2).

21, SYSEXIT_MOUNT

Can't mount ploop image or file system.

22, SYSEXIT_UMOUNT

Can't unmount ploop image or file system.

23, SYSEXIT_LOCK

Locking failed (another operation in progress?).

24, SYSEXIT_MKFS

Can't create file system.

26, SYSEXIT_RESIZE_FS

Utility resizefs failed.

27, SYSEXIT_MKDIR

Error from mkdir(2).

28, SYSEXIT_RENAME

Error from rename(2).

29, SYSEXIT_ABORT

Operation aborted.

30, SYSEXIT_RELOC

Block relocation failed.

33, SYSEXIT_CHANGE_GPT

Error resizing GPT partition table.

35, SYSEXIT_UNLINK

Error from unlink(2).

36, SYSEXIT_MKNOD

Error from mknod(2).

37, SYSEXIT_PLOOPINUSE

Image is already in use.

38, SYSEXIT_PARAM

Invalid parameter.

39, SYSEXIT_DISKDESCR

Problem with DiskDescriptor.xml file.

40, SYSEXIT_DEV_NOT_MOUNTED

Ploop image is not mounted.

41, SYSEXIT_FSCK

Error from fsck(8).

43, SYSEXIT_NOSNAP

Can't find specified snapshot UUID.

## SEE ALSO
vzctl(8), vzmigrate(8), http://openvz.org/Ploop.


plymouth

package: plymouth

title: plymouth(8)

summary: A graphical boot system and logger

text:
# plymouth(8)

## NAME
plymouth - A graphical boot system and logger

## DESCRIPTION
plymouth is a graphical boot system for Linux which takes advantage of the kernel-based mode setting (KMS) available for modern graphic cards to provide a seamless, flickerfree and attractive boot screen. It allows to choose between various, static or animated graphical themes to spruce up the startup and avoid the noise generated by the vast amount of kernel messages while the machine boots into X. On systems where kernel-based mode setting is not available, plymouth falls back to a text mode boot screen which provides a simple progress bar to pro‐ vide feedback during boot.

In order for the configured default plymouth theme to be loaded during boot, the option `splash' (or `rhgb' for backward compatibility with the RHGB boot splash) must be provided at the kernel command line. Without this command line option, plymouth will default to showing detailed boot output.

During the boot process, the user can switch between the graphical theme and the detailed boot output using the Escape key.

## SEE ALSO
grub(8), plymouth-set-default-theme(1), plymouthd(8), plymouth(1), http://www.freedesktop.org/wiki/Software/Plymouth

## AUTHORS
plymouth was originally prototyped and named by Kristian Høgsberg, originally written by Ray Strode and has had significant contributions from Charlie Brej. It has also had contributions from Peter Jones, Adam Jackson, Frederic Crozat and others.


plymouthd

title: plymouthd(8)

summary: The plymouth daemon

text:
# plymouthd(8)

## NAME
plymouthd - The plymouth daemon

## SYNOPSIS
plymouthd [OPTION...]

## DESCRIPTION
The plymouthd daemon is usually run out of the initrd. It does the heavy lifting of the plymouth system, logging the session and showing the splash screen.

The plymouth is used to send commands to plymouthd that control its behaviour.

## OPTIONS
The following options are understood:

--help

Show summary of options.

--attach-to-session

Redirect console messages from screen to log.

--no-daemon

Do not daemonize.

--debug

Output debugging information.

--debug-file=STRING

File to write debugging information to.

--mode=MODE

Set mode to either boot or shutdown.

--pid-file=STRING

Write the PID of the daemon to a file.

--kernel-command-line=STRING

Fake kernel commandline to use.

--tty=STRING

TTY to use instead of default.

## SEE ALSO
grub(8), plymouth(8), plymouth(1), http://www.freedesktop.org/wiki/Software/Plymouth


pm-action

package: pm-utils

title: pm-action(8)

summary: Suspend or Hibernate your computer

text:
# pm-action(8)

## NAME
pm-action - Suspend or Hibernate your computer

## SYNOPSIS
pm-hibernate [--help]

pm-suspend [--quirk-*] [--help]

pm-suspend-hybrid [--quirk-*] [--help]

## DESCRIPTION
This manual page documents briefly the pm-action, pm-hibernate, pm-suspend and pm-suspend-hybrid commands. This manual page was originally written for the Debian(TM) distribution and has been adopted by the pm-utils project.

These commands can be used to put the machine in a sleep state. The precise way how this is done can be influenced by installing executables and configuration snippets. For some options external programs are needed.

These commands will usually be called by UPower or hald when triggered to do so by a program in a desktop session such as gnome-power-manager. Calling them from the command line is also possible, but it is not guaranteed that all programs in your desktop session keep working as expected.

pm-suspend

During suspend most devices are shutdown, and system state is saved in RAM. The system still requires power in this state. Most modern systems require 3 to 5 seconds to enter and leave suspend, and most laptops can stay in suspend mode for 1 to 3 days before exhausting their battery.

pm-hibernate

During hibernate the system is fully powered off, and system state is saved to disk. The system does not require power, and can stay in hibernate mode indefinitely. Most modern systems require 15 to 45 seconds to enter and leave hibernate, and entering and leaving hibernate takes longer when you have more memory.

pm-suspend-hybrid

Hybrid-suspend is the process where the system does everything it needs to hibernate, but suspends instead of shutting down. This means that your computer can wake up quicker than for normal hibernation if you do not run out of power, and you can resume even if you run out of power. s2both(8) is an hybrid-suspend implementation.

## OPTIONS
On some hardware putting the video card in the suspend state and recovering from it needs some special quirk handling. With the --quirk-* options of the pm-suspend and pm-suspend-hybrid commands you can select which quirks should be used.

If pm-suspend, pm-hibernate, or pm-suspend-hybrid are invoked without any commandline parameters, they will try to grab the correct quirks from the internal quirk database.

--quirk-dpms-on

This option forces the video hardware to turn on the screen during resume. Most video adapters turn on the screen themselves, but if you get a blank screen on resume that can be turned back on by moving the mouse or typing then this option may be useful.

--quirk-dpms-suspend

This option forces the video hardware to turn off the screen when suspending. Most video adapters seem to do this correctly, but some do not, which wastes lots of power. If your screen is still on after successfully suspending you may need to use this option.

--quirk-radeon-off

This option forces Radeon hardware to turn off the display during suspend and turn it back on during resume. You only need to do this on some old ThinkPads of the '30 series (T30, X31, R32,... ) with Radeon video hardware.

--quirk-s3-bios

This option calls the video BIOS during S3 resume. Unfortunately, it is not always allowed to call the video BIOS at this point, so sometimes adding this option can actually break resume on some systems.

--quirk-s3-mode

This option initializes the video card into a VGA text mode, and then uses the BIOS to set the video mode. On some systems S3 BIOS only initializes the video BIOS to text mode, and so both S3 BIOS and S3 MODE are needed.

--quirk-vbe-post

This option will attempt to reinitialize the video card when resuming from suspend, using the same code the system BIOS uses at boot in order to initialize the video hardware. Not all video cards need this, and using this option on systems where it is not needed can cause a system to lock up when resuming.

--quirk-vbemode-restore

This option will save and restore the current VESA mode which may be necessary to avoid X screen corruption. Using this feature on Intel graphics hardware is probably a bad idea.

--quirk-vbestate-restore

This option saves and restores some low level hardware state which may be invalid after suspend.

--quirk-vga-mode-3

This option will try to force the video card into a standard text mode on resume.

--quirk-save-pci

Save the PCI config space for the VGA card.

--store-quirks-as-lkw

Save the quirks the video adaptor required by pm-suspend or pm-suspend-hybrid as an .quirkdb file that is specific to this system. The file will be saved in /etc/pm/last_known_working.quirkdb. This parameter will only save the actual quirks that were used to successfully suspend/resume a system, and will be specific to the exact configuration of that system, including the video hardware, video driver, and whether or not kernel modesetting was used.

## FILES
/etc/pm/config.d

The files in this directory are evaluated in C sort order. These files can be provided by individual packages outside of pm-utils. If a global configuration variable is set, the value set to will be appended to the previous value. If any other variable is set, it will be ignored. The syntax is simply: VAR_NAME=value. See the CONFIGURATION VARIABLES section for valid variables defined by pm-utils. External packages can define others, see their respective documentation for more information.

/etc/pm/sleep.d, /usr/lib/pm-utils/sleep.d

Programs in these directories (called hooks) are combined and executed in C sort order before suspend and hibernate with as argument 'suspend' or 'hibernate'. Afterwards they are called in reverse order with argument 'resume' and 'thaw' respectively. If both directories contain a similar named file, the one in /etc/pm/sleep.d will get preference. It is possible to disable a hook in the distribution directory by putting a non-executable file in /etc/pm/sleep.d, or by adding it to the HOOK_BLACKLIST configuration variable.

/var/log/pm-suspend.log

The log file shows what was done on the last suspend/hibernate and resume/thaw.

## SLEEP HOOK ORDERING CONVENTION
00 - 49

User and most package supplied hooks. If a hook assumes that all of the usual services and userspace infrastructure is still running, it should be here.

50 - 74

Service handling hooks. Hooks that start or stop a service belong in this range. At or before 50, hooks can assume that all services are still enabled.

75 - 89

Module and non-core hardware handling. If a hook needs to load/unload a module, or if it needs to place non-video hardware that would otherwise break suspend or hibernate into a safe state, it belongs in this range. At or before 75, hooks can assume all modules are still loaded.

90 - 99

Reserved for critical suspend hooks.

## CONFIGURATION VARIABLES
Configuration variables defined by pm-utils. These can be set in any file in /etc/pm/config.d/.

SLEEP_MODULE [=kernel]

The default suspend backend to use. Valid values are: kernel

The built-in kernel suspend/resume support. Use this if nothing else is supported on your system. The kernel backend is always used if nothing else is available.

uswsusp

If your system has support for the userspace suspend programs (s2ram/s2disk/s2both), then use this.

tuxonice

If your system has support for tuxonice/suspend2, use this.

HIBERNATE_RESUME_POST_VIDEO [=no]

If video should be posted after hibernate, just like after suspend. You should not normally need to set this.

SUSPEND_MODULES

Space separated list of modules to unload before suspend.

HOOK_BLACKLIST

Space separated list of hooks that should be disabled.

HIBERNATE_MODE

Default method to power down the system when hibernating. If not set, the system will use the kernel default as a default value. Check /sys/power/disk for valid values. The default value will be surrounded by [square brackets].

NEED_CLOCK_SYNC

If your system clock drifts across a suspend/resume or hibernate/thaw cycle, you should set this to true. This will cause pm-utils to synchronize the system clock whenever going through a sleep/wake cycle at the expense of making suspend/resume take longer.

PM_HIBERNATE_DELAY [=900]

If you are using kernel suspend/resume and invoke pm-suspend-hybrid, this environment variable controls how many seconds the system will wait after going into suspend before waking back up and hibernating. By default, this is set to 900 seconds (15 minutes).

## RETURN VALUES
Return values less than 128 mean that pm-action failed before trying to put the system in the requested power saving state. A return value of 128 means that pm-action tried to put the machine in the requested power state but failed. A return value greater than 128 means pm-action encountered an error and also failed to enter the requested power saving state.

## DEBUGGING
Debugging suspend/resume can be a tricky process, and is covered in more detail in /usr/share/doc/pm-utils/README.debugging.

## BUGS
The upstream BTS can be found at https://bugs.freedesktop.org/. Select 'pm-utils' as product.

## SEE ALSO
s2ram(8), s2disk(8), s2both(8), pm-is-supported(1), pm-powersave(8), vbetool(8), radeontool(8)

## AUTHOR
Tim Dijkstra <tim@famdijkstra.org>

Manpage author.

## COPYRIGHT
Copyright © 2007 Tim Dijkstra

This manual page was originally written for the Debian(TM) system, and has been adopted by the pm-utils project.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or (at your option) any later version published by the Free Software Foundation.


pm-pmu

title: pm-pmu(8)

summary: suspend the computer on machines using a Macintosh\-style PMU

text:
# pm-pmu(8)

## NAME
pm-pmu - suspend the computer on machines using a Macintosh-style PMU

## SYNOPSIS
pm-pmu

## DESCRIPTION
This manual page documents briefly the pm-pmu command.

pm-pmu is a command line program to suspend a computer on machines using a Macintosh-style PMU

## EXIT CODES
The command succeeds (status 0) if the machine uses a Macintosh-style PMU, and suspended successfully. The command fails (status other than 0) otherwise. It is designed to be easy to use in shell scripts.

0 (true)

System was suspended using PMU.

1 (false)

System could not be suspended using PMU.

## OPTIONS
This program follows the usual GNU command line syntax, with long options starting with two dashes (`-'). A summary of options is included below.

--suspend

Suspend the computer.

--help

Show help message.

## SEE ALSO
pm-suspend(8)

## AUTHOR
This manual page was written by Richard Hughes <richard@hughsie.com>.

## AUTHOR
Richard Hughes

Author.

## COPYRIGHT
Copyright © 2006 Richard Hughes


pm-powersave

title: pm-powersave(8)

summary: Put your computer into low power mode

text:
# pm-powersave(8)

## NAME
pm-powersave - Put your computer into low power mode

## SYNOPSIS
pm-powersave [{true | false}]

## DESCRIPTION
This manual page documents briefly the pm-powersave command.

pm-powersave can be used to set your system into low power mode.

## OPTIONS
true

Put the computer into low power mode to reduce energy consumption and extend your laptop's battery life.

false

Turn off low power mode.

## FILES
/etc/pm/power.d/, /usr/lib/pm-utils/power.d/

When you run pm-powersave it combines the scripts in these two directories and executes them in sorted order. If both directories contain a script with the same name, the one in /etc/pm/power.d/ has a higher precedence and only this one will be executed. Therefore to disable a script from /usr/lib/pm-utils/power.d/ simply create an empty file in /etc/pm/power.d/ with the same name and without the executable bit set.

## SEE ALSO
pm-suspend(8), pm-hibernate(8)

## AUTHOR
Michael Biebl <biebl@debian.org>

Manpage author.

## COPYRIGHT
Copyright © 2007 Michael Biebl

This manual page was originally written for the Debian(TM) system, and has been adopted by the pm-utils project.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or (at your option) any later version published by the Free Software Foundation.