swtpm

package: swtpm

title: swtpm(8)

summary: TPM Emulator for TPM 1.2 and 2.0

text:
# swtpm(8)

## NAME
swtpm - TPM Emulator for TPM 1.2 and 2.0

## SYNOPSIS
swtpm socket [OPTIONS]

swtpm chardev [OPTIONS]

swtpm cuse [OPTIONS]

## DESCRIPTION
swtpm implements a TPM software emulator built on libtpms. It provides access to TPM functionality over a TCP/IP socket interface or it can listen for commands on a character device, or create a CUSE (character device in userspace) interface for receiving of TPM commands.

Unless corresponding command line parameters are used, the swtpm socket version requires that the environment variable TPM_PORT be set to the TCP/IP port the process is supposed to listen on for TPM request messages.

Similarly, the environment variable TPM_PATH can be set and contain the name of a directory where the TPM can store its persistent state into.

The swtpm process can be gracefully terminated by sending a SIGTERM signal to it.

The swtpm cuse version requires root rights to start the TPM.

## Options for socket interface
The following options are supported if the socket interface is chosen:

-p|--port <port>

Use the given port rather than using the environment variable TPM_PORT.

-t|--terminate

Terminate the TPM after the client has closed the data channel connection (TCP only).

--server [type=tcp][,port=<port>[,bindaddr=<address> [,ifname=<ifname>]]][,fd=<fd>][,disconnect]

Expect TCP connections on the given port; if a port is not provided a file descriptor must be passed with the fd parameter and the commands are read from this file descriptor then. If a port is provided the bind address on which to listen for TCP connections can be provided as well; the default bind address is 127.0.0.1. If a link local IPv6 address is provided, the name of the interface to bind to must be provided with ifname. This parameter enables a persistent connection by default unless the disconnect option is given. This parameter should be used rather than the -p and --fd options.

--server type=unixio[,path=<path>][,fd=<fd>] [,mode=<0...>][,uid=<uid>][,gid=<gid>]

Expect UnixIO connections on the given path. If no path is provided, a file descriptor must be passed instead. The mode parameter allows a user to set the file mode bits of the UnixIO path. The mode bits value must be given as an octal number starting with a '0'. The default value is 0770. uid and gid set the ownership of the UnixIO socket's path. This operation requires root privileges.

## Options for character device interface
The following options are supported if the chardev interface is chosen:

-c|--chardev <device path>

Use the given device to listen for TPM commands and send response on.

--vtpm-proxy

Create a Linux vTPM proxy device instance and read TPM commands from its backend device.

## Options for the CUSE interface
The following options are supported if the cuse interface is chosen:

-n|--name <NAME>

The TPM will use a device with the given name. A device with the given name will be created in /dev. This is a mandatory option.

-M|--maj <MAJOR>

Create the device with the given major number.

-m|--min <MINOR>

Create the device with the given minor number.

## Options for socket and character device interfaces:
The following options are supported by the socket and character device interfaces:

-f|--fd <fd>

Use the given socket file descriptor or character device file descriptor for receiving TPM commands and sending responses. For the socket interface, this option automatically assumes -t.

-d|--daemon

Daemonize the process.

--ctrl type=[unixio|tcp][,path=<path>] [,port=<port>[,bindaddr=<address>[,ifname=<ifname>]]] [,fd=<filedescriptor>|clientfd=<filedescriptor>] [,mode=<0...>][,uid=<uid>][,gid=<gid>][,terminate]

This option adds a control channel to the TPM. The control channel can either use a UnixIO socket with a given path or filedescriptor or it can use a TCP socket on the given port or filedescriptor. If a port is provided the bind address on which to listen for TCP connections can be provided as well; the default bind address is 127.0.0.1. If a link local IPv6 address is provided, the name of the interface to bind to must be provided with ifname. The mode parameter allows a user to set the file mode bits of the UnixIO path. The mode bits value must be given as an octal number starting with a '0'. The default value is 0770. uid and gid set the ownership of the UnixIO socket's path. This operation requires root privileges.

The terminate parameter enables the automatic termination of swtpm when the control channel connection has been lost. This is useful in scenarios where the control channel connection is held permanently, such as by QEMU, and swtpm should terminate upon abnormal termination of the client that could not send a CMD_SHUTDOWN via the control channel anymore.

The control channel enables out-of-band control of the TPM, such as resetting the TPM.

## Options for all interfaces
The following options are support by all interfaces:

--tpmstate dir=<dir>|backend-uri=<uri>[,mode=<0...>][,lock]

Use the given path rather than using the environment variable TPM_PATH. If dir is specified, the TPM state files will be written to the dir with the given file mode bits. This value must be given as an octal number starting with a '0'. The default value is 0640.

If backend-uri is specified, the TPM state data will be stored to the URI. Currently backend-uri=dir://<path_to_dir> and backend-uri=file://<path_to_dir> are available. For 'dir://', the URI should specify the path to the directory where files are stored. If path_to_dir starts with a '/' then the path is interpreted as an absolute path, otherwise it is a path relative to the current directory. For 'file://', the URI should specify a single file or block device where TPM state will be stored. A blockdevice must exist already and be big enough to store all state. (since v0.7)

If lock is specified then the TPM storage backend will lock the TPM state file to avoid concurrent access to it by another swtpm instance. The default value, if this option parameter is missing, depends on the storage backend. For the directory-backend the default is that locking is always enabled, and therefore this option parameter does not need to be given. For the file backend it is required since the default is that locking is not automatically enabled. To avoid locking, lock=false can be used.

--tpm2

Choose TPM 2 functionality; by default a TPM 1.2 is chosen.

--log [fd=<fd>|file=<path>][,level=<n>] [,prefix=<prefix>][,truncate]

Enable logging to a file given its file descriptor or its path. Use '-' for path to suppress the logging. The level parameter allows a user to choose the level of logging. Starting at log level 5, libtpms debug logging is activated.

All logged lines will be prefixed with prefix. By default no prefix is prepended.

If truncate is passed, the log file will be truncated.

--locality reject-locality-4[,allow-set-locality]

The reject-locality-4 parameter will cause TPM error messages to be returned for requests to set the TPM into locality 4. The allow-set-locality parameter allows the swtpm to receive TPM/TPM2_SetLocality commands. This is parameter is useful if the Linux VTPM proxy driver access is enabled by file descriptor passing. This option is implied by the --vtpm-proxy option and therefore need not be explicitly set if this option is passed. In all other cases care should be taken as to who can send the TPM/TPM2_SetLocality command.

--key file=<keyfile>|fd=<fd> [,format=<hex|binary>][,mode=aes-cbc|aes-256-cbc], [remove[=true|false]]

Enable encryption of the state files of the TPM. The keyfile must contain an AES key of supported size; 128 bit (16 bytes) and 256 bit (32 bytes) keys are supported. The key may be in binary format, in which case the file size must be 16 or 32 bytes. If the key is in hex format (default), the key may consist of 32 or 64 hex digits starting with an optional '0x'.

The mode parameter indicates which block chaining mode is to be used. Currently aes-cbc (aes-128-cbc) and aes-256-cbc are supported. The encrypted data is integrity protected using encrypt-then-mac.

The remove parameter will attempt to remove the given keyfile once the key has been read.

--key pwdfile=<passphrase file>|pwdfd=<fd> [,mode=aes-cbc|aes-256-cbc][remove[=true|false]][,kdf=sha512|pbkdf2]

This variant of the key parameter allows a user to provide a passphrase in a file. The file is read and a key is derived from it using either a SHA512 hash or PBKDF2. By default PBKDF2 is used.

--migration-key file=<keyfile>|fd=<fd> [,format=<hex|binary>][,mode=aes-cbc|aes-256-cbc] [,remove[=true|false]]

The availability of a migration key ensures that the state of the TPM will not be revealed in unencrypted form when the TPM state blobs are retrieved through the ioctl interface. The migration key is not used for encrypting TPM state written to files, this is what the --key parameter is used for. The migration key and the key used for encrypting the TPM state files may be the same.

While the key for the TPM state files needs to stay with those files it encrypts, the migration key needs to stay with the TPM state blobs. If for example the state of the TPM is migrated between hosts in a data center, then the TPM migration key must be available at all the destinations, so in effect it may have to be a key shared across all machines in the datacenter. In contrast to that, the key used for encrypting the TPM state files can be different for each TPM and need only be available on the host where the TPM state resides.

The migration key enables the encryption of the TPM state blobs. The keyfile must contain an AES key of supported size; 128 bit (16 bytes) and 256 bit (32 bytes) keys are supported.

The key may be in binary format, in which case the file size must be 16 or 32 bytes. If the key is in hex format (default), the key may consist of 32 or 64 hex digits starting with an optional '0x'.

The mode parameter indicates which block chaining mode is to be used. Currently aes-cbc (aes-128-cbc) and aes-256-cbc are supported. The encrypted data is integrity protected using encrypt-then-mac.

The remove parameter will attempt to remove the given keyfile once the key has been read.

--migration-key pwdfile=<passphrase file>|pwdfd=<fd> [,mode=aes-cbc|aes-256-cbc][,remove[=true|false]][,pdf=sha512|pbkdf2]

This variant of the key parameter allows a user to provide a passphrase in a file. The file is read and a key is derived from it using either a SHA512 hash or PBKDF2. By default PBKDF2 is used.

--pid file=<pidfile>|fd=<filedescriptor>

This options allows a user to set the name of file where the process ID (pid) of the TPM will be written into. It is also possible to pass a file descriptor to a file that has been opened for writing.

-r|--runas <owner>

Switch to the given user. This option can only be used when swtpm is started as root.

-R|--chroot <path<gt>

Chroot to the given directory at startup. This option can only be used when swtpm is started as root.

--seccomp action=none|log|kill (since v0.2)

This option allows a user to select the action to take by the seccomp profile when a syscall is executed that is not allowed. The default is kill. To disable the seccomp profile, choose none. The log action logs offending syscalls. The log action is only available if libseccomp supports logging. This option is only available on Linux and only if swtpm was compiled with libseccomp support.

--flags [not-need-init][,startup-clear|startup-state|startup-deactivated|startup-none][,disable-auto-shutdown]

The not-need-init flag enables the TPM to accept TPM commands right after start without requiring an INIT to be sent to it through the command channel (see the '-i' option of swtpm_ioctl). The startup options cause a TPM_Startup or TPM2_Startup command to automatically be sent. The startup-deactivated option is only valid for a TPM 1.2. These options imply not-need-init, except for the startup-none option, which results in no command being sent.

If --vtpm-proxy is used, startup-clear is automatically chosen but this can be changed with this option.

The disable-auto-shutdown flag prevents swtpm from automatically sending a TPM2_Shutdown() before the reset of a TPM 2 or before the swtpm process is terminated. When this flag is not provide swtpm will send this command to avoid increasing the dictionary attack (DA) lockout counter and ultimately a DA lockout by the TPM 2 due to omission of sending a required TPM2_Shutdown() before TPM 2 reset or swtpm process termination.

--print-capabilities (since v0.2)

Print capabilities that were added to swtpm after version 0.1. The output may contain the following:

```
    {
      "type": "swtpm",
      "features": [
        "tpm-1.2",
        "tpm-2.0",
        "tpm-send-command-header",
        "flags-opt-startup",
        "flags-opt-disable-auto-shutdown",
        "cmdarg-seccomp",
        "cmdarg-key-fd",
        "cmdarg-pwd-fd",
        "cmdarg-print-states",
        "cmdarg-chroot",
        "cmdarg-migration",
        "nvram-backend-dir",
        "nvram-backend-file",
        "rsa-keysize-1024",
        "rsa-keysize-2048",
        "rsa-keysize-3072",
        "cmdarg-profile",
        "cmdarg-print-profiles",
        "profile-opt-remove-disabled",
        "cmdarg-print-info",
        "tpmstate-opt-lock"
      ],
      "version": "0.7.0"
    }

```

The version field is available since v0.7.

The meaning of the feature verbs is as follows:

tpm-1.2 (since v0.7)

TPM 1.2 emulation is supported (libtpms is compiled with 1.2 support).

tpm-2.0 (since v0.7)

TPM 2 emulation is supported (libtpms is compiled with 2.0 support). (the --tpm2 option is supported)

cmdarg-seccomp (since v0.2)

The --seccomp option is supported.

cmdarg-key-fd (since v0.2)

The --key option supports the fd= parameter.

cmdarg-pwd-fd (since v0.2)

The --key option supports the pwdfd= parameter.

cmdarg-print-states (since v0.7)

The --print-states option is supported.

cmdarg-chroot (since v0.8)

The --chroot option is supported.

cmdarg-migration (since v0.8)

The --migration option is supported.

nvram-backend-dir (since v0.7)

The --tpmstate option supports the backend-uri=dir://... parameter.

nvram-backend-file (since v0.7)

The --tpmstate option supports the backend-uri=file://... parameter.

tpm-send-command-header (since v0.2)

The TPM 2 commands may be prefixed by a header that carries a 4-byte command, 1 byte for locality, and 4-byte TPM 2 command length indicator. The TPM 2 will respond by prepending a 4-byte response indicator and a 4-byte trailer. All data is sent in big endian format.

flags-opt-startup (since v0.3)

The --flags option supports the startup-... options.

flags-opt-disable-auto-shutdown (since v0.8)

The --flags option supports the disable-auto-shutdown flag.

rsa-keysize-2048 (since v0.4)

The TPM 2 supports the shown RSA key sizes. If none of the rsa-keysize verbs is shown then only RSA 2048 bit keys are supported.

cmdarg-profile (since v0.10)

The option --profile is supported to set a profile for a TPM 2 with either one of the option parameters name=, profile=, fd=, or file=.

cmdarg-print-profiles (since v0.10)

The option --print-profiles is supported.

profile-opt-remove-disabled (since v0.10)

The --profile option supports the remove-disabled option parameter.

cmdard-print-info (since v0.10)

The option --print-info is supported.

tpmstate-opt-lock (since v0.10)

The option parameter lock for the --tpmstate option is supported.

--print-states (since v0.7)

This option allows to print out the TPM 1.2 or TPM 2 state blobs that are currently stored in a storage backend. This option requires that the storage backend be specified using the --tpmstate option and if TPM 2 state blobs are supposed to be shown, the --tpm2 option must be passed. The following shows the JSON output of this option. It indicates that the 'permall' and 'volatile' states are available.

```
    {
      "type": "swtpm",
      "states": [
        {
          "name": "permall",
          "size": 6013
        }, {
          "name": "volatile",
          "size": 1087
        }
      ]
    }

```

--migration [incoming][,release-lock-outgoing]

This option allows to control the locking of the NVRAM storage for the purpose of supporting migration between hosts that have shared storage setup for the swtpm's state directory and if locking is supported by the storage backend. The directory storage backend for example supports locking and therefore requires usage of this option in case of shared storage. When providing the incoming option parameter swtpm defers the locking of the NVRAM until the state blobs are received or until the first TPM command is processed if no state blobs were received. The release-lock-outgoing option parameter causes swtpm to release any NVRAM lock once the TPM's 'savestate' blob is received from swtpm. To avoid releasing the lock too early the 'permanent' and 'volatile' state blobs must be received before the 'savestate' blob.

--profile name=<profile-name>|profile=<json-profile>|file=<filename>|fd=<fd>[,remove-disabled=check|fips-host] (since v0.10)

This option allows to set a profile for a TPM 2. A built-in profile can be selected by its name using the option parameter name=. With the profile= option parameter a JSON-formatted profile can be passed directly. With the file= option parameter a JSON-formatted profile will be read from a file. The fd= option parameter allows to read it from a file descriptor. Profiles must reference the name of a built-in profile. Note that only the 'custom' profile, or profiles whose name starts with 'custom:', may be modified and provide a list of algorithms, commands, or attributes that control which crypto algorithms a TPM 2 enables. If either one of these lists is not given then the corresponding list from the built-in 'custom' profile is used.

The following command line option selects the 'custom' profile under the new name 'custom:test' with the 'fips-host' attribute set:

```
  [...] --profile '{"Name":"custom:test", "Attributes":"fips-host"}'
```

The profile can only be set the very first time that a TPM 2 instance is started and for as long as no state file exists. The profile cannot be changed anymore afterwards and, if passed again using this option, an error will occur.

The remove-disabled option parameter tells swtpm to remove those algorithms from the profile that are disabled when FIPS is enabled on a host (fips-host parameter; reference is RHEL 9.4+ FIPS mode) and OpenSSL's access to crypto algorithms is restricted. The check parameter can be used to check that an algorithm is in fact disabled before removing it. This option is only supported if the custom profile is chosen. In this case it will (currently) do the following:

- remove camellia, tdes, and rsaes (RSA encryption with PKCS#1 v1.5 padding)

- disable signature support (RSA and EC) over SHA1

- disable unpadded RSA encryption

- set the minimum size for RSA keys to 2048 bits

- set the minimum size for EC keys to 224 bits

All other algorithms remain enabled, including those that FIPS may normally not allow, such as ecdaa and ecschnorr and others. The list of disabled algorithms will be extended in the future when FIPS mode on the host disables more algorithms. Since in this case swtpm may add Attributes to the profile that require a certain StateFormatLevel, it is recommended to omit the StateFormatLevel field from the profile.

To see the list of algorithms that are supported and can be disabled, one may use swtpm as follows.

```
    $ swtpm socket --tpmstate dir=./ --tpm2 --print-info 0x08 | jq
    {
      "RuntimeAlgorithms": {
        "Implemented": "rsa,rsa-min-size=1024,tdes,tdes-min-size=128,sha1,\
                        hmac,aes,aes-min-size=128,mgf1,keyedhash,xor,sha256,\
                        sha384,sha512,null,rsassa,rsaes,rsapss,oaep,ecdsa,\
                        ecdh,ecdaa,sm2,ecschnorr,ecmqv,kdf1-sp800-56a,kdf2,\
                        kdf1-sp800-108,ecc,ecc-min-size=192,ecc-nist,ecc-bn,\
                        ecc-nist-p192,ecc-nist-p224,ecc-nist-p256,\
                        ecc-nist-p384,ecc-nist-p521,ecc-bn-p256,ecc-bn-p638,\
                        ecc-sm2-p256,symcipher,camellia,camellia-min-size=128,\
                        cmac,ctr,ofb,cbc,cfb,ecb",
        "CanBeDisabled": "tdes,sha1,sha512,rsassa,rsaes,rsapss,ecmqv,\
                          ecc-nist-p192,ecc-nist-p224,ecc-nist-p521,\
                          ecc-bn-p256,ecc-bn-p638,ecc-sm2-p256,camellia,cmac,\
                          ctr,ofb,cbc,ecb",
        "Enabled": "rsa,rsa-min-size=1024,tdes,tdes-min-size=128,sha1,hmac,\
                    aes,aes-min-size=128,mgf1,keyedhash,xor,sha256,sha384,\
                    sha512,null,rsassa,rsaes,rsapss,oaep,ecdsa,ecdh,ecdaa,sm2,\
                    ecschnorr,ecmqv,kdf1-sp800-56a,kdf2,kdf1-sp800-108,ecc,\
                    ecc-min-size=192,ecc-nist,ecc-bn,symcipher,camellia,\
                    camellia-min-size=128,cmac,ctr,ofb,cbc,cfb,ecb",
        "Disabled": ""
      }
    }
```

To see the list of supported commands:

```
    $ swtpm socket --tpmstate dir=./ --tpm2 --print-info 0x10 | jq
    {
      "RuntimeCommands": {
        "Implemented": "0x11f-0x122,0x124-0x12e,0x130-0x140,0x142-0x159,\
                        0x15b-0x15e,0x160-0x165,0x167-0x174,0x176-0x178,\
                        0x17a-0x193,0x197,0x199-0x19c",
        "CanBeDisabled": "0x11f,0x121-0x122,0x124-0x128,0x12a,0x12c-0x12e,\
                          0x130,0x132-0x13b,0x13d-0x140,0x142,0x146-0x147,\
                          0x149-0x14d,0x14f-0x152,0x154-0x155,0x159,0x15b,\
                          0x15d-0x15e,0x160-0x164,0x167-0x168,0x16a-0x172,\
                          0x174,0x177-0x178,0x17b,0x17f-0x181,0x183-0x184,\
                          0x187-0x193,0x197,0x199-0x19c",
        "Enabled": "0x11f-0x122,0x124-0x12e,0x130-0x140,0x142-0x159,\
                    0x15b-0x15e,0x160-0x165,0x167-0x174,0x176-0x178,\
                    0x17a-0x193,0x197,0x199-0x19c",
        "Disabled": ""
      }
    }
```

To see the list of supported attributes:

```
    $ swtpm socket --tpmstate dir=./ --tpm2 --print-info 0x80 | jq
    {
      "RuntimeAttributes": {
        "Implemented": "no-unpadded-encryption,no-sha1-signing,\
                        no-sha1-verification,no-sha1-hmac-creation,\
                        no-sha1-hmac-verification,no-sha1-hmac,fips-host",
        "CanBeDisabled": "no-unpadded-encryption,no-sha1-signing,\
                          no-sha1-verification,no-sha1-hmac-creation,\
                          no-sha1-hmac-verification,no-sha1-hmac,fips-host",
        "Enabled": "no-unpadded-encryption,no-sha1-signing,\
                    no-sha1-verification,no-sha1-hmac",
        "Disabled": "no-sha1-hmac-creation,no-sha1-hmac-verification,fips-host"
      }
    }
```

The above attributes may be added to a profile under an "Attributes" map entry, which is similar to the "Algorithms" and "Commands" entries.

To see the list of available profiles:

```
    $ swtpm socket --tpm2 --print-info 0x40 | jq
    {
      "AvailableProfiles": [
        {
          "Name": "default-v1",
          "StateFormatLevel": 4,
          "Commands": "0x11f-0x122,0x124-0x12e,0x130-0x140,0x142-0x159,\
                       0x15b-0x15e,0x160-0x165,0x167-0x174,0x176-0x178,\
                       0x17a-0x193,0x197,0x199-0x19a",
          "Algorithms": "rsa,rsa-min-size=1024,tdes,tdes-min-size=128,sha1,\
                         hmac,aes,aes-min-size=128,mgf1,keyedhash,xor,sha256,\
                         sha384,sha512,null,rsassa,rsaes,rsapss,oaep,ecdsa,\
                         ecdh,ecdaa,sm2,ecschnorr,ecmqv,kdf1-sp800-56a,kdf2,\
                         kdf1-sp800-108,ecc,ecc-min-size=192,ecc-nist,ecc-bn,\
                         symcipher,camellia,camellia-min-size=128,cmac,ctr,\
                         ofb,cbc,cfb,ecb",
          "Description": "This profile enables all currently supported \
                          commands and algorithms. It is applied when the \
                          user chooses no profile."
        },
        {
          "Name": "null",
          "StateFormatLevel": 1,
          "Commands": "0x11f-0x122,0x124-0x12e,0x130-0x140,0x142-0x159,\
                       0x15b-0x15e,0x160-0x165,0x167-0x174,0x176-0x178,\
                       0x17a-0x193,0x197",
          "Algorithms": "rsa,rsa-min-size=1024,tdes,tdes-min-size=128,sha1,\
                         hmac,aes,aes-min-size=128,mgf1,keyedhash,xor,sha256,\
                         sha384,sha512,null,rsassa,rsaes,rsapss,oaep,ecdsa,\
                         ecdh,ecdaa,sm2,ecschnorr,ecmqv,kdf1-sp800-56a,kdf2,\
                         kdf1-sp800-108,ecc,ecc-min-size=192,ecc-nist,ecc-bn,\
                         symcipher,camellia,camellia-min-size=128,cmac,ctr,\
                         ofb,cbc,cfb,ecb",
          "Description": "The profile enables the commands and algorithms \
                          that were enabled in libtpms v0.9. This profile is \
                          automatically used when the state does not have a \
                          profile, for example when it was created by \
                          libtpms v0.9 or before."
        },
        {
          "Name": "custom",
          "StateFormatLevel": 2,
          "Commands": "0x11f-0x122,0x124-0x12e,0x130-0x140,0x142-0x159,\
                       0x15b-0x15e,0x160-0x165,0x167-0x174,0x176-0x178,\
                       0x17a-0x193,0x197",
          "Algorithms": "rsa,rsa-min-size=1024,tdes,tdes-min-size=128,sha1,\
                         hmac,aes,aes-min-size=128,mgf1,keyedhash,xor,sha256,\
                         sha384,sha512,null,rsassa,rsaes,rsapss,oaep,ecdsa,\
                         ecdh,ecdaa,sm2,ecschnorr,ecmqv,kdf1-sp800-56a,kdf2,\
                         kdf1-sp800-108,ecc,ecc-min-size=192,ecc-nist,ecc-bn,\
                         ecc-sm2-p256,symcipher,camellia,\
                         camellia-min-size=128,cmac,ctr,ofb,cbc,cfb,ecb",
          "Description": "This profile allows customization of enabled \
                          algorithms and commands. This profile requires at \
                          least libtpms v0.10."
        }
      ]
    }
```

To see the current active profile querying swtpm listening for control message on port 2322:

```
    $ swtpm_ioctl --tcp :2322 --info 0x20 | jq
    {
      "ActiveProfile": {
        "Name": "default-v1",
        "StateFormatLevel": 4,
        "Commands": "0x11f-0x122,0x124-0x12e,0x130-0x140,0x142-0x159,\
                     0x15b-0x15e,0x160-0x165,0x167-0x174,0x176-0x178,\
                     0x17a-0x193,0x197,0x199-0x19a",
        "Algorithms": "rsa,rsa-min-size=1024,tdes,tdes-min-size=128,sha1,\
                       hmac,aes,aes-min-size=128,mgf1,keyedhash,xor,sha256,\
                       sha384,sha512,null,rsassa,rsaes,rsapss,oaep,ecdsa,\
                       ecdh,ecdaa,sm2,ecschnorr,ecmqv,kdf1-sp800-56a,kdf2,\
                       kdf1-sp800-108,ecc,ecc-min-size=192,ecc-nist,ecc-bn,\
                       symcipher,camellia,camellia-min-size=128,cmac,ctr,\
                       ofb,cbc,cfb,ecb",
        "Description": "This profile enables all currently supported \
                        commands and algorithms. It is applied when the \
                        user chooses no profile."
      }
    }
```

The only profile that a user may modify is the 'custom' profile. Here a user may choose to disable algorithms, commands, and attributes that are allowed to be disabled. To avoid failing TPM 2 applications, care must be taken that none of them relies on disabled commands or algorithms.

--print-profiles (since v0.10)

Display the profiles supported by libtpms. Use with --tpm2 option.

--print-info (since v0.10)

Display information about the TPM from libtpms TPMLIB_GetInfo call and exit. Use the --tpm2 option for information about TPM 2. If the --tpmstate option is also provided then the output will show information about the profile as well. Note that with this option a TPM state may be created if none existed before. The following values can be provided. All of the values can be or'ed (or added) together to get information about all of them in one query.

- 0x1: information about the specification the TPM implementation followed

- 0x2: information about the manufacturer, model and version of the TPM

- 0x4: lists supported RSA and Camellia key sizes

- 0x8: describes supported and enabled algorithms

- 0x10: describes supported and enabled commands

- 0x20: describes the active profile

- 0x40: lists all built-in profiles

- 0x80: describes supported attributes

-h|--help

Display usage info.

## NOTES
If a TPM 2 is used, the user is typically required to send a TPM2_Shutdown() command to a TPM 2 to avoid possibly increasing the TPM_PT_LOCKOUT_COUNTER that may lead to a dictionary attack (DA) lockout upon next startup (TPM2_Startup()) of the TPM 2. Whether the TPM_PT_LOCKOUT_COUNTER is increased depends on previous commands sent to the TPM 2 as well as internal state of the TPM 2. One example that will trigger the counter to increase is the omission of a password when trying to access a password-protected object or NVRAM location that has the DA attribute set, followed by termination of swtpm without sending TPM2_Shutdown(). To avoid a DA lockout swtpm will make a best-effort and send a TPM2_Shutdown(SU_STATE) or TPM2_Shutdown(SU_CLEAR) if found necessary.

## SEE ALSO
swtpm_bios, swtpm_cuse


package: swtpm-tools

title: swtpm_bios(8)

summary: BIOS simulation tool for swtpm

text:
# swtpm_bios(8)

## NAME
swtpm_bios - BIOS simulation tool for swtpm

## SYNOPSIS
swtpm_bios [OPTIONS]

## DESCRIPTION
swtpm_bios is a tool that can send the commands to the TPM (swtpm program) that typically are used by the BIOS to initialize the TPM. The user can choose among several command line options to choose the state the TPM should be set to.

This command requires the environment variable TCSD_USE_TCP_DEVICE to be set for communication via TCP. Otherwise it will use the device set in the environment variable TPM_DEVICE or fall back to use /dev/tpm0 to send the commands to. In TCP mode, the environment variable TCSD_TCP_DEVICE_HOSTNAME is used to indicate the host to send the commands to. By default localhost is assumed. The default TCP port is 6545 unless the environment variable TCSD_TCP_DEVICE_PORT indicates another port.

In case of success 0 will be returned. In case a TPM error was encountered the return code will be 128. In case of communication failure 255 is returned. In case the TPM needs to be reset to become activated, 129 will be returned.

This command will send the following sequence of commands to the TPM.

TPM_Startup(chosen mode) -- startup TPM

TSC_PhysicalPresence(0x20) -- PhysicalPresenceCMDEnable

TSC_PhysicalPresence(0x08) -- turn on physical presence

TPM_GetCapability -- get permanent flags

TPM_PhysicalEnable -- enable the TPM

TPM_PhysicalSetDeactivated(0x0) -- activate TPM

TPM_ContinueSelfTest -- continue self test

TSC_PhysicalPresence(0x20) -- PhysicalPresenceCMDEnable

TSC_PhysicalPresence(0x14) -- turn off physical presence & lock it

The following options are supported:

--tpm-device <device>

Use the given device rather than the default /dev/tpm0. This option overrides the TPM_DEVICE environment variable.

--tcp <server>:<port>

Connect to the given server and port; if no server is given, 127.0.0.1 is used; if port is not given, the default port 6545 is used.

--unix <path>

Connect to the given UnixIO path.

-tpm2

The device is a TPM 2.

-c

Send TPM_Startup(ST_CLEAR) (default). This instructs the TPM to start with clear state.

-s

Send TPM_Startup(ST_STATE). This instructs the TPM to start by restoring previously saved state.

-d

Send TPM_Startup(ST_DEACTIVATED). This instructs the TPM to start in deactivated mode. This option has no effect on a TPM 2.

-n

Don't send a TPM_Startup command.

-o

Only send the startup command and nothing else.

-ea

Make sure that the TPM is activated; if the TPM requires a reset, the program will exist and return a return code of 129.

-cs

Send a TPM_ContinueSelfTest command to a TPM 1.2 and a TPM2_IncrementalSelfTest command to a TPM 2.

-u

Give up physical presence on a TPM 1.2. In case of a TPM 2 set the platform hierarchy to a random password.

-v

Display version and exit.

-h

Display the help screen and exit.

## REPORTING BUGS
Report bugs to Stefan Berger <stefanb@linux.vnet.ibm.com>

branch: sisyphus


title: swtpm_cert(8)

text:
# swtpm_cert(8)

## NAME
swtpm_cert - Tool to create EK and platform certs for swtpm (1.2 & 2.0)

## SYNOPSIS
swtpm_cert [OPTIONS]

## DESCRIPTION
swtpm_cert is a local CA tool for creating X.509v3 certificates for the TPM's Endorsement Key. The reason for this specific tool is that it works without access to the Endorsement Key's private key. Typically tools require either a self-signed certificate request or access to the private key to issue a certificate. This tool works with only the public key part.

The following options are supported:

--type {ek|platform}

The type of certificate to create; by default an EK certificate is created.

--pubkey <filename>

The public key (EK) in PEM format.

--modulus <hex digits>

The modulus of the public key as a string of hex digits. This option can be used in place of the --pubkey option.

--ecc-x <hex digits>

The elliptic curve parameter x as string of hex digits.

--ecc-y <hex digits>

The elliptic curve parameter y as string of hex digits.

--ecc-curveid <curve id>

The elliptic curve's id. secp256r1, secp384r1, and secp521r1 are supported. If this option is not given, secp256r1 is assumed.

--exponent <exponent>

The exponent of the public key. By default 0x10001 is assumed.

--signkey <filename>

The key used for signing the certificate. The file must be in PEM format.

--signkey-password <password>

Optional password for the signing key.

--signkey-pwd <pwd>

This is an alternative option for passing the signing key password. The following formats are supported for pwd:

```
  - <password>                   : direct password
  - pass:<password>              : direct password
  - file:<filename>              : password in file
  - fd:<file descriptor>         : read password from file descriptor
  - env:<environment variable>   : read password from env. variable

```

All passwords read from files and file descriptors must be a maximum of 255 bytes (plus one byte for terminating NUL byte).

--parentkey-password <password>

Optional password for a parent key. In case a TPM key is used for signing this would be the password for the TPM's storage root key (SRK).

--parentkey-pwd <pwd>

This is an alternative option for passing the parentkey password. See the description above for supported pwd formats.

--issuercert <filename>

The X.509 certificate of this signer that takes on the role of a local CA.

--out-cert <filename>

The name of the file to write the X.509v3 certificate into. The output will be in PEM format.

--serial <serial number>

Optional 32bit serial number for the certificate.

--days <number>

The number of days the certificate is valid; by default it is valid for 365 days.

--pem

Write the resulting certificate in PEM format; DER format is the default.

--tpm-manufacturer <name>

The name of the TPM manufacturer.

--tpm-model <model>

The TPM model (part number).

--tpm-version <version>

The TPM's firmware version.

--platform-manufacturer <name>

The name of the platform manufacturer.

--platform-model <model>

The platform model.

--platform-version <version>

The platform's version.

--subject <subject>

Subject to for example provide the location of the TPM in the format of C=<country>,ST=<state>,L=<location>. Note that the location must no contain any spaces.

--tpm2

Issue TPM 2 compliant certificates.

--allow-signing

Create an EK that can also be used for signing. Without this option, the EK can only be used for key encipherment. This option requires --tpm2.

--decryption

If --allow-signing is passed and the EK should also be usable for key encipherment, this option must be passed. Otherwise key encipherment is the default. This option requires --tpm2.

--print-capabilities (since v0.3)

Print capabilities that were added to swtpm_cert after version 0.2. The output may contain the following:

```
    {
      "type": "swtpm_cert",
      "features": [
        "cmdarg-signkey-pwd",
        "cmdarg-parentkey-pwd"
      ],
      "version": "0.7.0"
    }

```

The version field is available since 0.7.

The meaning of the feature verbs is as follows:

cmdarg-signkey-pwd

The --signkey-pwd option is supported.

cmdarg-parentkey-pwd

The --parentkey-pwd option is supported.

--help, -h

Display the help screen

## REPORTING BUGS
Report bugs to Stefan Berger <stefanb@linux.vnet.ibm.com>


title: swtpm_ioctl(8)

text:
# swtpm_ioctl(8)

## NAME
swtpm_ioctl - Utility for sending control commands to swtpm

## SYNOPSIS
swtpm_ioctl [COMMAND] [<device>]

## DESCRIPTION
swtpm_ioctl implements a client tool for controlling the swtpm_cuse and swtpm TPM software emulators, such as for example their initialization and shutdown. Once it has been initialized, TPM commands can be sent to it.

Note: The environment variable SWTPM_IOCTL_BUFFERSIZE can be set to the size for the buffer for state blob transfer to use. If it is not set, the ioctl() interface is used for transferring the state. This environment variable is primarily used for testing purposes.

The following commands are supported:

--tpm-device <device>

Use the given device. The full path to the character device must be provided, such as for example /dev/vtpm-200. This option can be used instead of providing the device as the last parameter.

--tcp <server>:<port>

Connect to the given server and port; if no server is given, 127.0.0.1 is used; if port is not given, the default port 6545 is used.

--unix <path>

Connect to the given UnixIO path.

-c

Get the capability flags indicating which commands are supported.

-i

Send a hardware initialization signal to the swtpm_cuse/swtpm. Volatile state previously written by the TPM will be read and the file automatically delete.

-s

Initiate a graceful shut down.

--stop

Stop the swtpm_cuse/swtpm. This does not shut it down. The -i command can again be sent to it. After a stop it is also possible to load TPM stateblobs into the TPM using the --load command.

-e

Get the tpmEstablished bit.

-r locality

Reset the tpmEstablished bit using the given locality. Only localities 3 and 4 work. This operation will not permanently change the locality that was previously set using the -l option.

-l locality

Set the locality for the subsequent TPM commands.

-v

Have the TPM write the volatile state to a file. Upon a TPM_Init (-i) the TPM state will be read and the TPM can then resume operation without further initialization.

-C

Cancel an ongoing TPM command.

-h data

Reset and extend PCR 17 with the hash of the given data. If data is the single character '-', then all data are read from stdin.

--save <TPM state blob name> <filename>

Save the TPM state blob into the given file. Valid TPM state blob names are 'permanent', 'volatile', and 'savestate'. Note that this command can be executed at any time. However, to retrieve the latest volatile state, the -v command should have been run immediately before running this command. The savestate blob will only be returned if a TPM_SaveState command was executed in the TPM (TPM 1.2).

--load <TPM state blob name> <filename>

Load the given TPM state blob from the given file. Valid TPM state blob names are 'permanent', 'volatile', and 'savestate'. Note that this command can only be executed on a TPM that is shut down. To then start the TPM with the uploaded state, the -i command must be issued.

-g

Get configuration flags that for example indicate which keys (file encryption or migration key) are in use by the TPM.

--info <flags>

Get information about the TPM implementation and its configuration in JSON format. The following values can be provided. All of the values can be or'ed (or added) together to get information about all of them in one query.

- 0x1: information about the specification the TPM implementation followed

- 0x2: information about the manufacturer, model and version of the TPM

- 0x4: lists supported RSA and Camellia key sizes

- 0x8: describes supported and enabled algorithms

- 0x10: describes supported and enabled commands

- 0x20: describes the active profile

- 0x40: lists all built-in profiles

- 0x80: describes supported attributes

--lock-storage <retries>

Lock the storage and retry a given number of times with 10ms delay in between. Locking the storage may be necessary to do after the state of the TPM has been migrated out and the lock on the storage has been released when the 'savestate' blob was received and now the storage should be locked again.

## EXAMPLE
Start swtpm on port 10000 for the control port and emulate a TPM 1.2:

```
   #> swtpm socket --tpmstate dir=/tmp/myvtpm1 --log level=4 --ctrl type=tcp,port=10000 --server type=tcp,port=10001 --flags not-need-init
```

Get information about the TPM implementation in JSON:

```
   #> swtpm_ioctl --tcp :10000 --info 1
   {"TPMSpecification":{"family":"1.2","level":2,"revision":116}}
   #> swtpm_ioctl --tcp :10000 --info 2
   {"TPMAttributes":{"manufacturer":"id:00001014","version":"id:00740001","model":"swtpm"}}
```

Shut down the swtpm

```
   #> swtpm_ioctl --tcp :10000 -s
```

## SEE ALSO
swtpm_cuse


title: swtpm_localca(8)

text:
# swtpm_localca(8)

## NAME
swtpm_localca - Local CA to create EK and platform certs for swtpm

## SYNOPSIS
swtpm_localca [OPTIONS]

## DESCRIPTION
swtpm_localca is a tool to create TPM Endorsement Key (EK) and platform certificates on the host. It uses the swtpm_cert program to create the certificates.

The program will typically be invoked by the swtpm_setup program that uses the /etc/swtpm_setup.conf configuration file where a variable needs to be set that points to this program. It implements command line options that the swtpm_setup program uses to provide the necessary parameters to it.

swtpm_localca will automatically try to create the signing key and certificate if the configuration points to a missing signing key. Since this certificate must be signed by a CA, a root certificate authority will also be created and will sign this certificate. The root CA's private key and certificate will be located in the same directory as the signing key and have the names swtpm-localca-rootca-privkey.pem and swtpm-localca-rootca-cert.pem respectively. The environment variable SWTPM_ROOTCA_PASSWORD can be set for the password of the root CA's private key.

Note: Due to limitations of 'certtool', the possible passwords used for securing the root CA's private key and the intermediate CA's private key have to be passed over the command line and therefore will be visible to others on the system. If you are concerned about this, you should create the CAs elsewhere and copy them onto the target system.

The following options are supported:

--type type

This parameter indicates the type of certificate to create. The type parameter may be one of the following: ek, or platform

--dir dir

This parameter indicates the directory into which the certificate is to be stored. The EK certificate is stored in this directory under the name ek.cert and the platform certificate under the name platform.cert.

--ek ek or --key key

This parameter indicates the modulus of the public key of the endorsement key (EK). The public key is provided as a sequence of ASCII hex digits. The --key option is an alias for --ek and should be used if key parameters for another key than an endorsement key are passed.

In case ECC (elliptic curve cryptography) keys are used, the parameter must have the format --ek x=<hex digits>,y=<hex digits>,id=<curve id>. The id=<curve id> part is optional and only necessary for ECC curves other than secp256r1.

--vmid ID

This parameter indicates the ID of the VM for which to create the certificate.

--logfile <logfile>

The log file to log output to; by default logging goes to stdout and stderr on the console.

--configfile <configuration file>

The configuration file to use. If omitted, the default configuration file /etc/swtpm-localca.conf will be used.

--optsfile <options file>

The options file to use. If omitted, the default options file /etc/swtpm-localca.options will be used.

--tpm-spec-family, --tpm-spec-revision, --tpm-spec-level

TPM specification parameters that describe the specification that was followed for the TPM implementation. The parameters will be passed to swtpm_cert for the creation of the EK certificate.

--tpm2

Create TPM 2 compliant certificates.

--allow-signing

Create an EK that can also be used for signing. Without this option, the EK can only be used for key encipherment. This option requires --tpm2.

--decryption

If --allow-signing is passed and the EK should also be usable for key encipherment, this option must be passed. Otherwise key encipherment is the default. This option requires --tpm2.

## SEE ALSO
swtpm-localca.conf, swtpm-localca.options, swtpm_setup, swtpm_setup.conf

## REPORTING BUGS
Report bugs to Stefan Berger <stefanb@linux.vnet.ibm.com>


title: swtpm_setup(8)

text:
# swtpm_setup(8)

## NAME
swtpm_setup - Swtpm tool to simulate the manufacturing of a TPM 1.2 or 2.0

## SYNOPSIS
swtpm_setup [OPTIONS]

## DESCRIPTION
swtpm_setup is a tool that prepares the initial state for a libtpms-based TPM.

The following options are supported:

--runas <userid>

Use this userid to run swtpm_setup as. Only 'root' can use this option.

--config <file>

Path to configuration file containing the tool to use for creating certificates; see also swtpm_setup.conf If this parameter is not provided, the default configuration file will be used. The search order for the default configuration file is as follows. If the environment variable XDG_CONFIG_HOME is set, ${XDG_CONFIG_HOME}/swtpm_setup.conf will be used if available, otherwise if the environment variable HOME is set, ${HOME}/.config/swtpm_setup.conf will be used if available. If none of the previous ones are available, /etc/swtpm_setup.conf will be used.

--tpm-state <dir> or --tpmstate <dir>

Path where the TPM's state will be written to; this is a mandatory argument. Prefix with dir:// to use directory backend, or file:// to use linear file.

--tpm <path to executable>

Path to the TPM executable; this is an optional argument and by default the swtpm executable found in the PATH will be used.

--tpm2

Do setup on a TPM 2; by default a TPM 1.2 is setup.

--createek

Create an endorsement key (EK).

--allow-signing

Create an EK that can sign. This option requires --tpm2. This option will create a non-standard EK. When re-creating the EK, TPM 2 tools have to use the EK Template that is written at an NV index corresponding to the created EK (e.g., NV index 0x01c00004 for RS 2048 EK). Otherwise the tool-created EK will not correspond to the actual key being used or the modulus shown in the EK certificate.

Note that the TCG specification "EK Credential Profile For TPM Family 2.0; Level 0" suggests in its section on "EK Usage" that "the Endorsement Key can be a created as a decryption or signing key." However, some platforms will not accept an EK as a signing key, or as a signing and encryption key, and therefore this option should be used very carefully.

--decryption

Create an EK that can be used for key encipherment. This is the default unless --allow-signing is passed. This option requires --tpm2.

--ecc

Create elliptic curve crypto (ECC) keys; by default RSA keys are generated.

--take-ownership

Take ownership; this option implies --createek. This option is only available for TPM 1.2.

--ownerpass <password>

Provide custom owner password; default is 'ooo'. This option is only available for TPM 1.2.

--owner-well-known

Use a password of all zeros (20 bytes of zeros) as the owner password. This option is only available for TPM 1.2.

--srkpass <password>

Provide custom SRK password; default is 'sss'. This option is only available for TPM 1.2.

--srk-well-known

Use a password of all zeros (20 bytes of zeros) as the SRK password. This option is only available for TPM 1.2.

--create-ek-cert

Create an EK certificate; this implies --createek.

--create-platform-cert

Create a platform certificate; this implies --create-ek-cert.

--lock-nvram

Lock NVRAM access to all NVRAM locations that were written to.

--display

At the end display as much info as possible about the configuration of the TPM.

--logfile <logfile>

The logfile to log to. By default logging goes to stdout and stderr.

--keyfile <keyfile>

The key file contains an ASCII hex key consisting of 32 hex digits with an optional leading '0x'. This is the key to be used by the TPM emulator for encrypting the state of the TPM.

--keyfile-fd <file descriptor>

Like --keyfile but the key will be read from the file descriptor.

--pwdfile <passphrase file>

The passphrase file contains a passphrase from which the TPM emulator will derive the encryption key from and use the key for encrypting the TPM state.

--pwdfile-fd <file descriptor>

Like --pwdfile but the passphrase will be read from the file descriptor.

--ciper <cipher>

The cipher may be either aes-cbc or aes-128-cbc for 128 bit AES encryption, or aes-256-cbc for 256 bit AES encryption. The same cipher must be used on the swtpm command line later on.

--overwrite

Overwrite existing TPM state. All previous state will be erased. If this option is not given and an existing state file is found, an error code is returned.

--not-overwrite

Do not overwrite existing TPM state. If existing TPM state is found, the program ends without an error.

--vmid <VM ID>

Optional VM ID that can be used to keep track of certificates issued for VMs (or containers). This parameter will be passed through to the tool used for creating the certificates and may be required by that tool.

--pcr-banks <PCR banks>

Optional comma-separated list of PCR banks to activate. Providing '-' allows a user to skip the selection and activates all PCR banks. If this option is not provided, the swtpm_setup.conf configuration file will be consulted for the active_pcr_banks entry. If no such entry is found then the default set of PCR banks will be activated. The default set of PCR banks can be determined using the --help option.

--swtpm_ioctl <executable>

Pass the path to the swtpm_ioctl executable. By default the swtpm_ioctl in the PATH is used.

--tcsd-system-ps-file <file>

This option is deprecated and has no effect (since v0.4).

--rsa-keysize <keysize> (since v0.4)

This option allows to pass the size of a TPM 2 RSA EK key, such as 2048 or 3072. The supported keysizes for a TPM 2 can be queried for using the --print-capabilities option. The default size is 2048 bits for both TPM 1.2 and TPM 2. If 'max' is passed, the largest possible key size is used.

--reconfigure (since v0.7)

This option allows the reconfiguration of the active PCR banks of a TPM 2 using the --pcr-banks option.

--profile <json-profile> (since v0.10)

Configure a TPM 2 with the given profile. Example profiles look like this:

```
    {"Name": "null"}
    {"Name": "default-v1"}
    {
     "Name": "custom",
     "Algorithms":"rsa,rsa-min-size=1024,tdes-min-size=128,hmac,aes,\
                   aes-min-size=128,mgf1,keyedhash,xor,sha256,sha384,\
                   sha512,null,rsassa,rsaes,rsapss,oaep,ecdsa,ecdh,ecdaa,\
                   sm2,ecschnorr,ecmqv,kdf1-sp800-56a,kdf2,kdf1-sp800-108,\
                   ecc,ecc-min-size=192,ecc-nist,ecc-bn,symcipher,camellia,\
                   camellia-min-size=128,cmac,ctr,ofb,cbc,cfb,ecb"
    }

```

The JSON profile must contain the 'name' field with a name of a profile supported by libtpms. Only the 'custom' profile, or profiles whose name starts with 'custom:', are modifiable and may contain Algorithms, Commands, or Attributes fields with user selections. Unknown fields in the JSON profile will be ignored. For further information see the swtpm man page.

--profile-name <profile filename| built-in profile name (since v0.10)

Configure a TPM 2 with a profile loaded from either one of the following locations in the shown order, unless qualified by a prefix:

- local profiles dir specified in swtpm_setup.conf as 'local_profiles_dir'; to force loading the profile from this directory, prefix the name with 'local:'

- distro profile dir, which is typically /usr/share/swtpm/profiles; to force loading the profile from this directory prefix the name with 'distro:'

- instantiate a libtpms built-in profile; to force a built-in profile prefix the name with 'builtin:'

All profiles loaded from the above mentioned directories require that the file is available under the given name with '.json' appended.

Use the --print-profiles and --tpm2 options to display all available profiles.

--profile-file <file> (since v0.10)

Configure a TPM 2 with a profile from a file.

--profile-file-fd <fd> (since v0.10)

Configure a TPM 2 with a profile read from a file descriptor.

--profile-remove-disabled check|fips-host (since v0.10)

When this option is passed then swtpm will remove algorithms from the given profile that OpenSSL cannot use when FIPS mode is enabled on the host. If the check parameter is given then algorithms are tested before they are removed while the fips-host parameter forces the removal of all potentially disabled algorithms without testing them. This option only works if the 'custom' profile is referenced by passing --profile '{"Name":"custom:test"}' for example.

This option passes the remove-disable option parameter as part of the --profile option to swtpm. For further information see the man page for swtpm.

--print-profiles (since v0.10)

Print all profiles found in the local and disto profiles directories and display the built-in ones. All profiles stored in files must have the .json extension. The names in the displayed JSON will show the name under which these profiles can be loaded with the --profile-name option, i.e., they will show their filename without the .json extension. Therefore, a profile with filename myprofile.json will show the Name 'myprofile'. The author of the profile may want to set the Name in the profile's JSON to 'custom:myprofile'.

--print-capabilities (since v0.2)

Print capabilities that were added to swtpm_setup after version 0.1. The output may contain the following:

```
    {
      "type": "swtpm_setup",
      "features": [
        "tpm-1.2",
        "tpm-2.0",
        "cmdarg-keyfile-fd",
        "cmdarg-pwdfile-fd",
        "tpm12-not-need-root",
        "cmdarg-write-ek-cert-files",
        "cmdarg-create-config-files",
        "cmdarg-reconfigure-pcr-banks",
        "tpm2-rsa-keysize-2048",
        "tpm2-rsa-keysize-3072",
        "cmdarg-profile",
        "cmdarg-profile-remove-disabled"
      ],
      "version": "0.7.0"
    }

```

The version field is available since v0.7.

The meaning of the feature verbs is as follows:

cmdarg-key-fd (since v0.2)

The --keyfile-fd option is supported.

cmdarg-pwd-fd (since v0.2)

The --pwdfile-fd option is supported.

cmdarg-write-ek-cert-files (since v0.7)

The --write-ek-cert-files option is supported.

cmdarg-create-config-files (since v0.7)

The --create-config-files option is supported.

cmdarg-reconfigure-pcr-banks (since v0.7)

The --reconfigure option is supported and allows the reconfiguration of the active PCR banks.

tpm2-rsa-keysize-2048, ... (since v0.4)

The shown RSA key sizes are supported for a TPM 2's EK key. If none of the tpm2-rsa-keysize verbs is shown then only RSA 2048 bit keys are supported.

tpm12-not-need-root (since v0.4)

This option implies that any user can setup a TPM 1.2. Previously only root or the 'tss' user, depending on configuration and availability of this account, could do that.

tpm-1.2 (since v0.7)

TPM 1.2 setup is supported (libtpms is compiled with TPM 1.2 support).

tpm-2.0 (since v0.7)

TPM 2 setup is supported (libtpms is compiled with TPM 2 support).

cmdarg-profile (since v0.10)

The --profile, profile-file, and --profile-file-fd options are supported.

cmdarg-profile-remove-disabled (since v0.10)

The --profile-remove-disabled option is supported.

--write-ek-cert-files <directory> (since v0.7)

This option causes endorsement key (EK) files to be written into the provided directory. The files contain the DER-formatted EKs that were written into the NVRAM locations of the TPM 1.2 or TPM 2. The EK files have the filename pattern of ek-<key type>.crt. Example for filenames are ek-rsa2048.crt, ek-rsa3072.crt, and ek-secp384r1.crt. The keys that are written for a TPM 2 may change over time as the default strength of the EK keys changes. This means that one should look for all files with the above filename pattern when looking for the EKs.

--create-config-files [[overwrite][,root][,skip-if-exist]] (since v0.7)

This option allows a user to create configuration files for swtpm_setup and swtpm-localca under the $XDG_CONFIG_HOME or $HOME/.config directories. The configuration files will not be created if any one of them already exists and in this case the program will report the first file it finds and exit with an error code.

The meaning of the options is as follows:

overwrite

Overwrite any existing configuration files.

root

Create the configuration files even under the root account. These configuration files may then shadow any other existing configuration files, such as /etc/swtpm-localca.conf for example.

skip-if-exist

Do nothing if any one of the configuration files that would be created already exists. The program will exit without error code.

Note: The case when a user is part of the group that is allowed to access the default configuration files' paths is currently not handled. On many systems this may be the case when a user is part of the 'tss' group. In this case it is recommended that the user replace the swtpm-localca.conf created with this command with a symbolic link to /etc/swtpm-localca.conf.

--help, -h

Display the help screen

## EXAMPLE USAGE
To simulate manufacturing of a TPM, one would typically run the following command:

```
  #> sudo swtpm_setup --tpmstate /tmp/mytpm1/ \
      --create-ek-cert --create-platform-cert --lock-nvram
```

Note: since v0.4 TPM 1.2 setup does not require root rights anymore.

Any user can also simulate the manufacturing of a TPM using the swtpm_localca utility. The following example assumes that the user has set the environment variable XDG_CONFIG_HOME as follows (using bash for example):

```
    export XDG_CONFIG_HOME=~/.config
```

Note: The XDG_CONFIG_HOME variable is part of the XDG Base Directory Specification.

The following configuration files need to be created:

~/.config/swtpm_setup.conf:

```
    # Program invoked for creating certificates
    create_certs_tool= /usr/share/swtpm/swtpm-localca
    create_certs_tool_config = ${XDG_CONFIG_HOME}/swtpm-localca.conf
    create_certs_tool_options = ${XDG_CONFIG_HOME}/swtpm-localca.options
```

~/.config/swtpm-localca.conf:

```
    statedir = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca
    signingkey = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/signkey.pem
    issuercert = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/issuercert.pem
    certserial = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/certserial
```

~/.config/swtpm-localca.options:

```
    --platform-manufacturer Fedora
    --platform-version 2.12
    --platform-model QEMU
```

Note: The tool swtpm-create-user-config-files can be used to create such files (with different content):

```
  #> /usr/share/swtpm/swtpm-create-user-config-files
  Writing /home/stefanb/.config/swtpm_setup.conf.
  Writing /home/stefanb/.config/swtpm-localca.conf.
  Writing /home/stefanb/.config/swtpm-localca.options.
```

The following commands now create a TPM 2 with an EK and platform certificate. The state of the TPM 2 will be stored in the directory ${XDG_CONFIG_HOME}/mytpm1.

```
  #> mkdir -p ${XDG_CONFIG_HOME}/mytpm1
  #> swtpm_setup --tpm2 --tpmstate ${XDG_CONFIG_HOME}/mytpm1 \
      --create-ek-cert --create-platform-cert --lock-nvram
```

## SEE ALSO
swtpm_setup.conf

## REPORTING BUGS
Report bugs to Stefan Berger <stefanb@linux.ibm.com>


swtpm-create-tpmca

title: swtpm-create-tpmca(8)

text:
# swtpm-create-tpmca(8)

## NAME
swtpm-create-tpmca - Tool to create a local CA for swtpm_localca

## SYNOPSIS
swtpm-create-tpmca [OPTIONS]

## DESCRIPTION
swtpm-create-tpmca is a tool to create a TPM 1.2 or TPM 2 based CA that can be used by swtpm_localca to sign EK and platform certificates. The CA uses a GnuTLS key to sign certificates. If a TPM 1.2 is used then GnuTLS will talk to the TPM 1.2 using the tcsd (TrouSerS) daemon. If a TPM 2 is used then the Intel pkcs11 driver and its tools (tpm2_ptool) are also required.

Since the TPM CA's certificate must be signed by a CA, a root certificate authority will also be created and will sign this certificate. The root CA's private key and certificate will be located in the same directory as the signing key and have the names swtpm-localca-rootca-privkey.pem and swtpm-localca-rootca-cert.pem respectively. The environment variable SWTPM_ROOTCA_PASSWORD can be set for the password of the root CA's private key.

Note: This tool is experimental. See the section on known issues below.

The following options are supported:

--dir dir

The directory where the keys will be written to. An existing root CA with the files swtpm-localca-rootca-privkey.pem and swtpm-localca-rootca-cert.pem in this directory will be reused. If either one of these files does not exist, a new root CA will be created.

--overwrite

Overwrite the contents of the output directory.

--register

Register the key with TCSD. For the key to be available for signing, the same user that created the TPM CA has to run the swtpm_localca tool later on. If this option is not passed, the private key is written into a file and can be used by others as well.

--key-password s

The new signing key will get this password. Note: Due to a bug in GnuTLS certtool it may be necessary to use the same password for the signing key as for the SRK.

--srk-password s

The TPM SRK password. Note: Since GnuTLS tpmtool does not support the 'well known' password of 20 zero bytes, the SRK password must be set.

--outfile filename

The name of a file where to write the swtpm-localca.conf configuration to.

--owner owner

The name or uid number of the owner who will own the directory and outfile file. This option only has an effect if this swtpm-create-tpmca is run by the root user.

--group group

The name or gid number of the group who will own the directory and outfile file. This option only has an effect if this swtpm-create-tpmca is run by the root user.

--tss-tcsd-hostname

The hostname where tcsd is running on. The default hostname is 'localhost'.

-tss-tcsd-port

The TCP port on which tcsd is listening for messages. The default port is 30003.

--tpm2

The TPM to use for signing the certificates is a TPM 2 and Intel's TSS stack must be running (tpm2-abrmd) along with its PKCS11 module. The TPM 2 PKCS11 module must have been initialized using the tpm2_ptool. The environment variables SWTPM_PKCS11_PIN and SWTPM_PKCS11_SO_PIN should be set to hold the PINs. If SWTPM_PKCS11_PIN is not set then the default PIN 'swtpm-tpmca' will be used. SWTPM_PKCS11_SO_PIN is needed for creating the token and must be explicitly set as an environment variable.

--pid pimary-object-id

The primary object id that the tpm2_ptool returns upon 'init'.

-help, -h, -?

Display the help screen and exit.

## EXAMPLE
The following example creates an intermediate TPM CA and writes the keys into /var/lib/swtpm-localca and the swtpm_localca configuration to /etc/swtpm-localca.conf. It can then be used for signing certificates of newly created swtpm TPMs.

If the host's TPM is a TPM 1.2, we need to start the tcsd first and can then create the TPM key and TPM CA certificate:

```
 #> sudo systemctl start tcsd
 #> sudo /usr/share/swtpm/swtpm-create-tpmca \
                --dir /var/lib/swtpm-localca \
                --overwrite \
                --outfile /etc/swtpm-localca.conf \
                --srk-password password \
                --key-password password \
                --group tss
 statedir = /var/lib/swtpm-localca
 signingkey = tpmkey:file=/var/lib/swtpm-localca/swtpm-localca-tpmca-privkey.pem
 issuercert = /var/lib/swtpm-localca/swtpm-localca-tpmca-cert.pem
 certserial = /var/lib/swtpm-localca/certserial
 TSS_TCSD_HOSTNAME = localhost
 TSS_TCSD_PORT = 30003
 signingkey_password = password
 parentkey_password = password
```

Alternatively, if the host's TPM is a TPM 2 and Intel's TPM 2 stack is installed, we need to start tpm2-abrmd first and can then create the TPM key and TPM CA certificate:

```
 #> sudo systemctl start tpm2-abrmd     # may not be required with recent Intel TPM 2 tools
 #> sudo tpm2_ptool init
 action: Created
 id: 1                   # this is the --pid parameter below
 #> sudo SWTPM_PKCS11_PIN="mypin 123" SWTPM_PKCS11_SO_PIN=123 /usr/share/swtpm/swtpm-create-tpmca \
                --dir /var/lib/swtpm-localca \
                --overwrite \
                --outfile /etc/swtpm-localca.conf \
                --group tss \
                --tpm2 \
                --pid 1
 statedir = /var/lib/swtpm-localca
 signingkey = pkcs11:model=SW%20%20%20TPM\;manufacturer=IBM\;serial=0000000000000000\;token=swtpm-tpmca-1\;id=%31\;object=swtpm-tpmca-key\;type=private
 issuercert = /var/lib/swtpm-localca/swtpm-localca-tpmca-cert.pem
 certserial = /var/lib/swtpm-localca/certserial
 SWTPM_PKCS11_PIN = mypin 123
```

Note: This also works for non-root users by adapting the --dir and --outfile parameters here and below by changing the --dir parameter and adding a --config parameter.

To test either one of the above TPM CAs, run the following command:

```
 #> swtpm_localca \
        --type ek --ek x=11,y=13 \
        --dir /tmp --vmid test --tpm2 \
        --tpm-spec-family 2.0 --tpm-spec-revision 146 --tpm-spec-level 00 \
        --tpm-model swtpm --tpm-version 20170101 --tpm-manufacturer IBM
```

The --tpm2 in this command indicates that the TPM for which the certificate is created is a TPM 2.

## KNOWN ISSUES
The interaction of GnuTLS certtool with the TPM TCSD daemon may cause so many TPM (key) authentication failures that the TPM refuses to accept any more authenticated commands until the TPM's owner sends it the TPM_ORD_ResetLockValue command. The reason for this is that certtool first tries to use 20 zero bytes for the SRK password and only then prompts for and uses the required SRK password. The GnuTLS tpmtool does not support 20 zero bytes for the SRK password, so forces the usage of a 'real' password.

The effect of the authentication failures may be that the TPM CA cannot sign certificates since the TPM does not accept authenticated commands.

## SEE ALSO
swtpm_localca, swtpm-localca.conf, tcsd

## REPORTING BUGS
Report bugs to Stefan Berger <stefanb@linux.ibm.com>


package: sympa

title: alias_manager(8)

summary: Manage Sympa aliases (Obsoleted)

text:
# alias_manager(8)

## NAME
alias_manager, alias_manager.pl - Manage Sympa aliases (Obsoleted)

## OBSOLETED
alias_manager.pl was obsoleted as of Sympa 6.2.24, and will be removed in the future. To manage aliases based on template, setting ""alias_manager Template"" in sympa.conf or robot.conf is recommended.

## SYNOPSIS
"alias_manager.pl" "add" listname domain [ file ]

"alias_manager.pl" "del" listname domain [ file ]

## DESCRIPTION
Alias_manager is a program that helps in installing aliases for newly created lists and deleting aliases for closed lists.

Alias management is performed only if it was setup in /etc/sympa/sympa.conf ("sendmail_aliases" configuration parameter).

Administrators using MTA functionalities to manage aliases (i.e. virtual_regexp and transport_regexp with postfix) can disable alias management by setting "sendmail_aliases" configuration parameter to "none".

## OPTIONS
"add" listname domain [ file ]

Add the set of aliases for the mailing list listname in the domain domain.

"del" listname domain [ file ]

Remove the set of aliases for the mailing list listname in the domain domain.

## FILES
$SENDMAIL_ALIASES sendmail aliases file.

## DOCUMENTATION
The full documentation in HTML formats can be found in <https://www.sympa.community/manual/>.

The mailing lists (with web archives) can be accessed at <https://www.sympa.community/community/lists.html>.

## HISTORY
This program was originally written by:

Serge Aumont

Comité Réseau des Universités

Olivier Salaün

Comité Réseau des Universités

This manual page was initially written by Jérôme Marant <jerome.marant@IDEALX.org> for the Debian GNU/Linux system.

## LICENSE
You may distribute this software under the terms of the GNU General Public License Version 2. For more details see README file.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license can be found under <http://www.gnu.org/licenses/fdl.html>.

## BUGS
Report bugs to Sympa bug tracker. See <https://github.com/sympa-community/sympa/issues>.

## SEE ALSO
Sympa::Aliases::Template.


archived

title: archived(8)

summary: Mailing List Archiving Daemon for Sympa

text:
# archived(8)

## NAME
archived, archived.pl - Mailing List Archiving Daemon for Sympa

## SYNOPSIS
"archived.pl" [ "--foreground" ] [ "--debug" ]

## DESCRIPTION
Archived is a program which scan permanently the archive spool and feeds the web archives, converting messages to the HTML format and linking them. Original mails are also kept (in arctxt/ directory> for later rebuilding of archives.

The HTML conversion is achieved by the means of the MHonArc program.

Archives are accessed via wwsympa.fcgi and sympa_msg.pl, which proposes access control; therefore archives should not be located in a public web directory.

## OPTIONS
These programs follow the usual GNU command line syntax, with long options starting with two dashes ("--"). A summary of options is included below.

"-F", "--foreground"

Do not detach TTY.

"-f", "--config="file

Force archived to use an alternative configuration file instead of /etc/sympa/sympa.conf.

"-d", "--debug"

Run the program in a debug mode.

"-h", "--help"

Print this help message.

## FILES
$SPOOLDIR/outgoing/ outgoing Sympa directory.

$DEFAULTDIR/mhonarc_rc.tt2 template of MHonArc resource file.

•

mhonarc-ressources.tt2 was replaced with mhonarc_rc.tt2 on Sympa 6.2.61b.1.

/etc/sympa/sympa.conf Sympa configuration file.

$PIDDIR/archived.pid this file contains the process ID of archived.pl.

## MORE DOCUMENTATION
The full documentation in HTML format can be found in <https://www.sympa.community/manual/>.

The mailing lists (with web archives) can be accessed at <https://www.sympa.community/community/lists.html>.

## HISTORY
This program was originally written by:

Serge Aumont

Comité Réseau des Universités

Olivier Salaün

Comité Réseau des Universités

This manual page was initially written by Jérôme Marant <jerome.marant@IDEALX.org> for the Debian GNU/Linux system.

## LICENSE
You may distribute this software under the terms of the GNU General Public License Version 2. For more details see README file.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license can be found under <http://www.gnu.org/licenses/fdl.html>.

## BUGS
Report bugs to Sympa bug tracker. See <https://github.com/sympa-community/sympa/issues>.

## SEE ALSO
sympa_msg(8), bounced(8), mhonarc(1), sympa_config(5).

Sympa::Spindle::ProcessArchive.


bounced

title: bounced(8)

text:
# bounced(8)

## NAME
bounced, bounced.pl - Mailing List Bounce Processing Daemon for Sympa

## SYNOPSIS
"bounced.pl" [ "--foreground" ] [ "--debug" ]

## DESCRIPTION
Bounced is a program which scans permanently the bounce spool and processes bounces (non-delivery messages), looking or bad addresses. Bouncing addresses are tagged in database ; last bounce is kept for each bouncing address.

List owners will be able to access information about the bounces via WWSympa after they have been processed by bounced.

## OPTIONS
These programs follow the usual GNU command line syntax, with long options starting with two dashes ("--"). A summary of options is included below.

"-F", "--foreground"

Do not detach TTY.

"-f", "--config="file

Force bounced to use an alternative configuration file instead of /etc/sympa/sympa.conf.

"-d", "--debug"

Run the program in a debug mode.

"-h", "--help"

Print this help message.

"--log_level="level

Sets daemon log level.

## FILES
/etc/sympa/sympa.conf Sympa configuration file.

$LIBEXECDIR/bouncequeue bounce spooler, referenced from sendmail alias file

$SPOOLDIR/bounce incoming bounces directory

$PIDDIR/bounced.pid this file contains the process ID of bounced.pl.

## MORE DOCUMENTATION
The full documentation can be found in <https://www.sympa.community/manual/>.

The mailing lists (with web archives) can be accessed at <https://www.sympa.community/community/lists.html>.

## HISTORY
This program was originally written by:

Serge Aumont

Comité Réseau des Universités

Olivier Salaün

Comité Réseau des Universités

This manual page was initially written by Jérôme Marant <jerome.marant@IDEALX.org> for the Debian GNU/Linux system.

## LICENSE
You may distribute this software under the terms of the GNU General Public License Version 2. For more details see README file.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license can be found under <http://www.gnu.org/licenses/fdl.html>.

## BUGS
Report bugs to Sympa bug tracker. See <https://github.com/sympa-community/sympa/issues>.

## SEE ALSO
sympa_msg(8), wwsympa(8), mhonarc(1), sympa_config(5).

Sympa::Spindle::ProcessBounce.


bulk

title: bulk(8)

text:
# bulk(8)

## NAME
bulk, bulk.pl - Daemon for submitting messages to SMTP engine

## SYNOPSIS
"bulk.pl" [ "--foreground" ] [ "--debug" ]

## DESCRIPTION
This daemon must be run along with sympa_msg.pl(8). It regularly checks the content of outgoing (bulk) spool and submit the messages it finds in it to the sendmail engine. Several daemons may be used on deferent server for huge traffic.

## OPTIONS
"-d", "--debug"

Sets the debug mode

"-f", "--config="file

Force bulk to use an alternative configuration file instead of /etc/sympa/sympa.conf.

"-F", "--foreground"

Prevents the script from being daemonized

"-h", "--help"

Prints this help message.

"--log_level="level

Set log level.

"-m", "--mail"

Logs every sendmail calls.

## FILES
$PIDDIR/bulk.pid this file contains the process IDs of bulk.pl.

## SEE ALSO
sympa_config(5), sympa_msg(8).

Sympa::Spindle::ProcessOutgoing.

## HISTORY
bulk.pl initially written by Serge Aumont appeared on Sympa 6.0.


title: sympa_automatic(8)

summary: Automatic list creation daemon

text:
# sympa_automatic(8)

## NAME
sympa_automatic, sympa_automatic.pl - Automatic list creation daemon

## SYNOPSIS
"sympa_automatic.pl" [ "-d, --debug" ] [ "-f, --file"=another.sympa.conf ] [ "-k, --keepcopy"=directory ] [ [ "-m, --mail" ] [ "-h, --help" ] [ "-v, --version" ]

## DESCRIPTION
Sympa_automatic.pl is a program which scans permanently the automatic creation spool and processes each message.

If the list a message is bound for has not been there and list creation is authorized, it will be created. Then the message is stored into incoming message spool again and wait for processing by sympa_msg.pl.

## OPTIONS
sympa_automatic.pl may run with following options in general.

"-d", "--debug"

Enable debug mode.

"-f", "--config="file

Force Sympa to use an alternative configuration file instead of /etc/sympa/sympa.conf.

"--log_level="level

Sets Sympa log level.

sympa_automatic.pl may run in daemon mode with following options.

"--foreground"

The process remains attached to the TTY.

"-k", "--keepcopy="directory

This option tells Sympa to keep a copy of every incoming message, instead of deleting them. `directory' is the directory to store messages.

"-m", "--mail"

Sympa will log calls to sendmail, including recipients. This option is useful for keeping track of each mail sent (log files may grow faster though).

With following options sympa_automatic.pl will print some information and exit.

"-h", "--help"

Print this help message.

"-v", "--version"

Print the version number.

## FILES
/etc/sympa/sympa.conf main configuration file.

$PIDDIR/sympa_automatic.pid this file contains the process ID of sympa_automatic.pl.

## SEE ALSO
sympa_config(5), sympa_msg(8).

Sympa::Spindle::ProcessAutomatic.

## HISTORY
sympa.pl was originally written by:

Serge Aumont

Comité Réseau des Universités

Olivier Salaün

Comité Réseau des Universités

As of Sympa 6.2b.4, it was split into three programs: sympa.pl (later renamed to sympa) command line utility, sympa_automatic.pl daemon and sympa_msg.pl daemon.


title: sympa_msg(8)

summary: Daemon to handle incoming messages

text:
# sympa_msg(8)

## NAME
sympa_msg, sympa_msg.pl - Daemon to handle incoming messages

## SYNOPSIS
"sympa_msg.pl" [ "-d", "--debug" ] [ "-f", "--file"=another.sympa.conf ] [ "-k", "--keepcopy"=directory ] [ "-l", "--lang"=lang ] [ "-m", "--mail" ] [ "-h", "--help" ] [ "-v", "--version" ]

## DESCRIPTION
Sympa_msg.pl is a program which scans permanently the incoming message spool and processes each message.

Messages bound for the lists and authorized sending are modified as necessity and at last stored into digest spool, archive spool and outgoing spool. Those bound for command addresses are interpreted and appropriate actions are taken. Those bound for listmasters or list admins are forwarded to them.

## OPTIONS
Sympa_msg.pl follows the usual GNU command line syntax, with long options starting with two dashes ("--"). A summary of options is included below.

"-d", "--debug"

Enable debug mode.

"-f", "--config="file

Force Sympa to use an alternative configuration file instead of /etc/sympa/sympa.conf.

"-l", "--lang="lang

Set this option to use a language for Sympa. The corresponding gettext catalog file must be located in $LOCALEDIR directory.

"--log_level="level

Sets Sympa log level.

sympa_msg.pl may run in daemon mode with following options.

"--foreground"

The process remains attached to the TTY.

"-k", "--keepcopy="directory

This option tells Sympa to keep a copy of every incoming message, instead of deleting them. `directory' is the directory to store messages.

"-m", "--mail"

Sympa will log calls to sendmail, including recipients. This option is useful for keeping track of each mail sent (log files may grow faster though).

"--service="service

Note: This option was deprecated. Process is dedicated to messages distribution ("process_message"), commands ("process_command") or to automatic lists creation ("process_creation", default three of them).

With following options sympa_msg.pl will print some information and exit.

"-h", "--help"

Print this help message.

"-v", "--version"

Print the version number.

## FILES
/etc/sympa/sympa.conf main configuration file.

$PIDDIR/sympa_msg.pid this file contains the process ID of sympa_msg.pl.

## SEE ALSO
sympa_config(5), sympa(1).

archived(8), bulk(8), bounced(8), sympa_automatic(8), task_manager(8).

Sympa::Spindle::ProcessDigest, Sympa::Spindle::ProcessIncoming.

## HISTORY
sympa.pl was originally written by:

Serge Aumont

Comité Réseau des Universités

Olivier Salaün

Comité Réseau des Universités

As of Sympa 6.2b.4, it was split into three programs: sympa.pl (later renamed to sympa) command line utility, sympa_automatic.pl daemon and sympa_msg.pl daemon.


title: sympa_soap_server(8)

summary: Sympa SOAP server

text:
# sympa_soap_server(8)

## NAME
sympa_soap_server, sympa_soap_server.fcgi - Sympa SOAP server

## DESCRIPTION
Sympa SOAP server allows one to access Sympa service though SOAP.

To know details on Sympa SOAP server, see Sympa Administration Manual: <https://www.sympa.community/manual/customize/soap-api.html>.

## HISTORY
Sympa SOAP server appeared on Sympa 4.0.


title: task_manager(8)

text:
# task_manager(8)

## NAME
task_manager, task_manager.pl - Daemon to process periodical Sympa tasks

## SYNOPSIS
"task_manager.pl" [ "--foreground" ] [ "--debug" ]

## DESCRIPTION
Task_manager is a program which scans permanently the task spool and processes tasks. It also checks configuration of site and every list to create necessary tasks.

## OPTIONS
"-d", "--debug"

Sets the debug mode

"-f", "--config="file

Force task_manager to use an alternative configuration file instead of /etc/sympa/sympa.conf.

"-F", "--foreground"

Prevents the script from being daemonized

"-h", "--help"

Prints this help message.

"--log_level="level

Set log level.

## FILES
$SPOOLDIR/task/ directory for task spool.

$PIDDIR/task_manager.pid this file contains the process ID of task_manager.pl.

## SEE ALSO
sympa_msg(8), wwsympa(8).

Sympa::Spindle::ProcessTask.

## HISTORY
task_manager.pl was contributed by F. Guilleux. It appeared on Sympa 3.3a-vhost.10.


wwsympa

title: wwsympa(8)

summary: WWSympa, Sympa\*(Aqs web interface

text:
# wwsympa(8)

## NAME
wwsympa, wwsympa.fcgi - WWSympa, Sympa's web interface

## DESCRIPTION
This FastCGI script completely handles all aspects of the Sympa web interface.

To know details on WWSympa, see Sympa Administration Manual: <https://www.sympa.community/manual/>.

## HISTORY
WWSympa was initially written by:

- Serge Aumont <sa AT cru.fr>

- Olivier Salaün <os AT cru.fr>

The first alpha version of WWSympa appeared on Sympa 2.3.4.


synaptic

package: synaptic

title: synaptic(8)

text:
# synaptic(8)

## NAME
synaptic - graphical management of software packages

## SYNOPSIS
synaptic [options]

## DESCRIPTION
Synaptic is a frontend for the apt package managent system. It allows you to perform all actions of the command line tool apt-get in a graphical environemnt. This includes installing, upgrading, downgrading and removing of single packages or even upgrading your whole system.

A manual with detailed instructions can be found in the help menu of Synaptic.

## OPTIONS
Synaptic accepts all of the standard Gtk+ toolkit command line options as well as the following:

-f, --filter-file=filename

specify an alternative filter settings file

-i, --initial-filter=int

apply the filter with number int at startup

-o, --option=option

set an internal option (experts only)

## AUTHORS
Synaptic was originally developed by Alfredo K. Kojima <kojima@conectiva.com.br>. His last official release was 0.16. Michael Vogt <mvo@debian.org> took over his CVS version, that already included a nearly complete port to Gtk+. Michael completed the port and added new features. See the NEWS file for the user visible changes from that point on. Conectiva is still involved in the development of synaptic. Gustavo Niemeyer <niemeyer@conectiva.com> is doing a great deal of work.

All development is done at http://savannah.gnu.org/projects/synaptic

This manual page was originally written by Wybo Dekker <wybo@servalys.nl> and Michael Vogt <mvo@debian.org> and modified by Sebastian Heinlein <sebastian.heinlein@campus.lmu.de>.

## COPYRIGHT
Copyright (C) 2001-2004 Conectiva S/A

Copyright (C) 2002-2004 Michael Vogt

There is NO warranty. You may redistribute this software under the terms of the GNU General Public License. For more information about these matters, see the files named COPYING.


csysdig

package: sysdig

title: csysdig(8)

text:
# csysdig(8)

### NAME
csysdig - the ncurses user interface for sysdig

### SYNOPSIS
csysdig [option]... [filter]

### DESCRIPTION
csysdig exports sysdig's functionality through an intuitive and powerful ncurses-based user interface.

csysdig has been designed to mimic tools like top and htop, but it offers richer functionality, including:

•

Support for both live analysis and sysdig trace files. Trace files can come from the same machine or from another machine.

•

Visibility into a broad range of metrics, including CPU, memory, disk I/O, network I/O.

•

Ability to observe input/output activity for processes, files, network connections and more.

•

Ability to drill down into processes, files, network connections and more to further explore their behavior.

•

Full customization support.

•

Support for sysdig's filtering language.

•

Container support by design.

csysdig works on any terminal, and has support for colors and mouse input.

Views

csysdig is based on the concept of 'views', little Lua scripts that determine how metrics are collected, processed and represented on screen. Including a new visualization to csysdig doesn't require to update the program, and is simply a matter of adding a new view. Views rely on the sysdig processing engine, and this means that they can include any sysdig filter field. Views are located in the sysdig chisel directory path, usually /usr/share/sysdig/chisels and ~/.chisels.

### BASIC USAGE
Here are some basic tips to get you started with sysdig:

1.

If you run csysdig without arguments, it will display live system data, updating every 2 seconds. To analyze a trace file, use the -r command line flag.

2.

You can switch to a different view by using the F2 key.

3.

You can drill down into a selection by clicking enter. You can navigate back by typing backspace.

4.

You can observe input/output for the currently selected entity by typing F5

5.

You can see sysdig events for the currently selected entity by typing F6

### DRILLING DOWN
You drill down by selecting an element in a view and then clicking enter. Once inside a selection, you can switch to a different view, and the new view will be applied in the context of the selection. For example, if you drill down into a process called foo and then switch to the Connections view, the output will include only the connections made or received by foo.

To drill down multiple times, keep clicking enter. For example, you can click on a container in the Containers view to get the processes running inside it, and then click on one of the processes to see its threads.

### ACTIONS AND HOTKEYS
Each view has a list of command lines that can be executed in the context of the current selection by pressing 'hotkeys'. For example, pressing 'k' in the Processes view kills the selected process, pressing 'b' in the Containers view opens a bash shell in the selected container.

Each view supports different actions. You can see which actions a view supports by pressing F8. You can customize the view's actions by editing the view's Lua file.

### CONTAINERS SUPPORT
Starting csysdig with the -pc command line switch will cause many of the views to include additional container information. For example, the Processes will include a column showing the container the process belongs to. Similarly, the Connections view will show which container each connection belongs to.

### Views Window
Arrows, PgUP, PgDn, Home, End

Change the selection and scroll view content, both vertically and horizontally.

Enter

Drill down into the currently highlighted entry.

Backspace

Navigate back to the previous view.

F2

Show the view picker. This will let you switch to another view.

CTRL+F /

Incremental search in the list of view entries.

F4

Incremental filtering of the view entries.

F5, e

'echo FDs' for the selection, i.e. view FD input/output for the currently highlighted entry.

F6, d

'dig' into the selection, i.e. view sysdig events for the currently highlighted entry. Refer to the sysdig man page to learn about interpreting the content of this window.

F7

Show the help page for the currently displayed view.

F8

Open the view's actions panel.

F9, >

Open the column sort panel.

F10, q

Quit.

DEL, c

For views that are listing elements without aggregating them by key (identifiable by yellow column headers), this command clears the view content.

p

Pause screen updates.

<shift> <1-9>

sort column <n>

F1, h, ?

Show the help screen.

### Echo and sysdig Windows
Arrows, PgUP, PgDn, Home, End

Scroll the page content.

Backspace

Navigate back to the previous view.

CTRL+F /

Search inside the window content.

F3

Find Next.

F2

Chose the output rendering format. Options are 'Dotted ASCII' (non-printable binary bytes are rendered as dots), 'Printable ASCII' (non-printable binary bytes are not included and line endings are rendered accurately) and 'Hex' (dotted ASCII representation is included together with the Hexadecimal rendering of the buffers).

DEL, c

Clear the screen content.

p

Pause screen updates.

CTRL+G

Go to line.

### Spectrogram Window
F2

Show the view picker. This will let you switch to another view.

p

Pause/Resume the visualization.

Backspace

Navigate back to the previous view.

### MOUSE USAGE
•

Clicking on column headers lets you sort the table.

•

Double clicking on row entries performs a drill down.

•

Clicking on the filter string at the top of the screen (the text after 'Filter:') lets you change the sysdig filter and customize the view content.

•

You can use the mouse on the entries in the menu at the bottom of the screen to perform their respective actions.

### COMMAND LINE OPTIONS
-d period, --delay=period

Set the delay between updates, in milliseconds (by default = 2000). This works similarly to the -d option in top.

-E, --exclude-users

Don't create the user/group tables by querying the OS when sysdig starts. This also means that no user or group info will be written to the tracefile by the -w flag. The user/group tables are necessary to use filter fields like user.name or group.name. However, creating them can increase sysdig's startup time.

--force-term-compat

Try to configure simple terminal settings (xterm-1002) that work better with terminals like putty. Try to use this flag if you experience terminal issues like the mouse not working.

-h, --help

Print this page

-k, --k8s-api Enable Kubernetes support by connecting to the API server specified as argument. E.g. "<http://admin:password@127.0.0.1:8080>". The API server can also be specified via the environment variable SYSDIG_K8S_API.

-K btfile | certfile:keyfile[#password][:cacertfile], --k8s-api-cert=_btfile | certfile:keyfile[#password][:cacertfile]_ Use the provided files names to authenticate user and (optionally) verify the K8S API server identity. Each entry must specify full (absolute, or relative to the current directory) path to the respective file. Private key password is optional (needed only if key is password protected). CA certificate is optional. For all files, only PEM file format is supported. Specifying CA certificate only is obsoleted - when single entry is provided for this option, it will be interpreted as the name of a file containing bearer token. Note that the format of this command-line option prohibits use of files whose names contain ':' or '#' characters in the file name. Option can also be provided via the environment variable SYSDIG_K8S_API_CERT.

-l, --list

List all the fields that can be used in views.

--logfile file

Print program logs into the given file.

-m url[,marathon-url], --mesos-api=_url[,marathon-url]_ Enable Mesos support by connecting to the API server specified as argument (e.g. <http://admin:password@127.0.0.1:5050>). Mesos url is required. Marathon url is optional, defaulting to auto-follow - if Marathon API server is not provided, csysdig will attempt to retrieve (and subsequently follow, if it migrates) the location of Marathon API server from the Mesos master. Note that, with auto-follow, csysdig will likely receive a cluster internal IP address for Marathon API server, so running csysdig with Marathon auto-follow from a node that is not part of Mesos cluster may not work. Additionally, running csysdig with Mesos support on a node that has no containers managed by Mesos is of limited use because, although cluster metadata will be collected, there will be no Mesos/Marathon filtering capability. The API servers can also be specified via the environment variable SYSDIG_MESOS_API.

-n num, --numevents=num

Stop capturing after num events

--page-faults Capture user/kernel major/minor page faults

-pc, -pcontainers_

Instruct csysdig to use a container-friendly format in its views. This will cause several of the views to contain additional container-related columns.

-R, --resolve-ports Resolve port numbers to names.

-r readfile, --read=readfile

Read the events from readfile.

-s len, --snaplen=len

Capture the first len bytes of each I/O buffer. By default, the first 80 bytes are captured. Use this option with caution, it can generate huge trace files.

-T, --force-tracers-capture

Tell the driver to make sure full buffers are captured from /dev/null, to make sure that tracers are completely captured. Note that sysdig will enable extended /dev/null capture by itself after detecting that tracers are written there, but that could result in the truncation of some tracers at the beginning of the capture. This option allows preventing that.

-v view_id, --views=view_id

Run the view with the given ID when csysdig starts. View IDs can be found in the view documentation pages in csysdig. Combine this option with a command line filter for complete output customization.

--version

Print version number.

### FILTERING
Similarly to what you do with sysdig, you can specify a filter on the command line to restrict the events that csysdig processes. To modify the filter while the program is running, or to add a filter at runtime, click on the filter text in the UI with the mouse.

### CUSTOMIZING CSYSDIG
csysdig is completely customizable. This means that you can modify any of the csysdig views, and even create your own views. Like sysdig chisels, csysdig views are Lua scripts. Full information can be found at the following github wiki page: <https://github.com/draios/sysdig/wiki/csysdig-View-Format-Reference>.

### FILES
/usr/share/sysdig/chisels

The global views directory.

~/.chisels

The personal views directory.

### AUTHOR
Draios Inc. (dba Sysdig) <info@sysdig.com>

### SEE ALSO
sysdig(8), strace(8), tcpdump(8), lsof(8)