visudo

title: visudo(8)

summary: edit the sudoers file

text:
# visudo(8)

## NAME
visudo — edit the sudoers file

## SYNOPSIS
visudo

[-chIOPqsV] [[-f] sudoers]

## DESCRIPTION
visudo edits the sudoers file in a safe fashion, analogous to vipw(8). visudo locks the sudoers file against multiple simultaneous edits, performs basic validity checks, and checks for syntax errors before installing the edited file. If the sudoers file is currently being edited you will receive a message to try again later.

If the sudoers file does not exist, it will be created unless the editor exits without writing to the file.

visudo parses the sudoers file after editing and will not save the changes if there is a syntax error. Upon finding an error, visudo will print a message stating the line number(s) where the error occurred and the user will receive the “What now?” prompt. At this point the user may enter ‘e’ to re-edit the sudoers file, ‘x’ to exit without saving the changes, or ‘Q’ to quit and save changes. The ‘Q’ option should be used with extreme caution because if visudo believes there to be a syntax error, so will sudo. If ‘e’ is typed to edit the sudoers file after a syntax error has been detected, the cursor will be placed on the line where the error occurred (if the editor supports this feature).

There are two sudoers settings that determine which editor visudo will run.

editor

A colon (‘:’) separated list of editors allowed to be used with visudo. visudo will choose the editor that matches the user's SUDO_EDITOR, VISUAL, or EDITOR environment variable if possible, or the first editor in the list that exists and is executable. sudo does not preserve the SUDO_EDITOR, VISUAL, or EDITOR environment variables unless they are present in the env_keep list or the env_reset option is disabled in the sudoers file. The default editor path is /bin/vitmp which can be set at compile time via the --with-editor configure option.

env_editor

If set, visudo will use the value of the SUDO_EDITOR, VISUAL, or EDITOR environment variables before falling back on the default editor list. visudo is typically run as root so this option may allow a user with visudo privileges to run arbitrary commands as root without logging. An alternative is to place a colon-separated list of “safe” editors in the editor variable. visudo will then only use SUDO_EDITOR, VISUAL, or EDITOR if they match a value specified in editor. If the env_reset flag is enabled, the SUDO_EDITOR, VISUAL, and/or EDITOR environment variables must be present in the env_keep list for the env_editor flag to function when visudo is invoked via sudo. The default value is on, which can be set at compile time via the --with-env-editor configure option.

The options are as follows:

-c, --check

Enable check-only mode. The existing sudoers file (and any other files it includes) will be checked for syntax errors. If the path to the sudoers file was not specified, visudo will also check the file ownership and permissions (see the -O and -P options). A message will be printed to the standard output describing the status of sudoers unless the -q option was specified. If the check completes successfully, visudo will exit with a value of 0. If an error is encountered, visudo will exit with a value of 1.

-f sudoers, --file=sudoers

Specify an alternate sudoers file location, see below. As of version 1.8.27, the sudoers path can be specified without using the -f option.

-h, --help

Display a short help message to the standard output and exit.

-I, --no-includes

Disable the editing of include files unless there is a pre-existing syntax error. By default, visudo will edit the main sudoers file and any files included via @include or #include directives. Files included via @includedir or #includedir are never edited unless they contain a syntax error.

-O, --owner

Enforce the default ownership (user and group) of the sudoers file. In edit mode, the owner of the edited file will be set to the default. In check mode (-c), an error will be reported if the owner is incorrect. This option is enabled by default if the sudoers file was not specified.

-P, --perms

Enforce the default permissions (mode) of the sudoers file. In edit mode, the permissions of the edited file will be set to the default. In check mode (-c), an error will be reported if the file permissions are incorrect. This option is enabled by default if the sudoers file was not specified.

-q, --quiet

Enable quiet mode. In this mode details about syntax errors are not printed. This option is only useful when combined with the -c option.

-s, --strict

Enable strict checking of the sudoers file. If an alias is referenced but not actually defined or if there is a cycle in an alias, visudo will consider this a syntax error. It is not possible to differentiate between an alias and a host name or user name that consists solely of uppercase letters, digits, and the underscore (‘_’) character.

-V, --version

Print the visudo and sudoers grammar versions and exit.

A sudoers file may be specified instead of the default, /etc/sudoers. The temporary file used is the specified sudoers file with “.tmp” appended to it. In check-only mode only, ‘-’ may be used to indicate that sudoers will be read from the standard input. Because the policy is evaluated in its entirety, it is not sufficient to check an individual sudoers include file for syntax errors.

### Debugging and sudoers plugin arguments
visudo versions 1.8.4 and higher support a flexible debugging framework that is configured via Debug lines in the sudo.conf(5) file.

Starting with sudo 1.8.12, visudo will also parse the arguments to the sudoers plugin to override the default sudoers path name, user-ID, group-ID, and file mode. These arguments, if present, should be listed after the path to the plugin (i.e., after sudoers.so). Multiple arguments may be specified, separated by white space. For example:

```
Plugin sudoers_policy sudoers.so sudoers_mode=0400
```

The following arguments are supported:

sudoers_file=pathname

The sudoers_file argument can be used to override the default path to the sudoers file.

sudoers_uid=user-ID

The sudoers_uid argument can be used to override the default owner of the sudoers file. It should be specified as a numeric user-ID.

sudoers_gid=group-ID

The sudoers_gid argument can be used to override the default group of the sudoers file. It must be specified as a numeric group-ID (not a group name).

sudoers_mode=mode

The sudoers_mode argument can be used to override the default file mode for the sudoers file. It should be specified as an octal value.

For more information on configuring sudo.conf(5), refer to its manual.

## ENVIRONMENT
The following environment variables may be consulted depending on the value of the editor and env_editor sudoers settings:

SUDO_EDITOR

Invoked by visudo as the editor to use

VISUAL

Used by visudo if SUDO_EDITOR is not set

EDITOR

Used by visudo if neither SUDO_EDITOR nor VISUAL is set

## FILES
/etc/sudo.conf

Sudo front-end configuration

/etc/sudoers

List of who can run what

/etc/sudoers.tmp

Default temporary file used by visudo

## DIAGNOSTICS
In addition to reporting sudoers syntax errors, visudo may produce the following messages:

sudoers file busy, try again later.

Someone else is currently editing the sudoers file.

/etc/sudoers: Permission denied

You didn't run visudo as root.

you do not exist in the passwd database

Your user-ID does not appear in the system passwd database.

Warning: {User,Runas,Host,Cmnd}_Alias referenced but not defined

Either you are trying to use an undeclared {User,Runas,Host,Cmnd}_Alias or you have a user or host name listed that consists solely of uppercase letters, digits, and the underscore (‘_’) character. In the latter case, you can ignore the warnings (sudo will not complain). The message is prefixed with the path name of the sudoers file and the line number where the undefined alias was used. In -s (strict) mode these are errors, not warnings.

Warning: unused {User,Runas,Host,Cmnd}_Alias

The specified {User,Runas,Host,Cmnd}_Alias was defined but never used. The message is prefixed with the path name of the sudoers file and the line number where the unused alias was defined. You may wish to comment out or remove the unused alias.

Warning: cycle in {User,Runas,Host,Cmnd}_Alias

The specified {User,Runas,Host,Cmnd}_Alias includes a reference to itself, either directly or through an alias it includes. The message is prefixed with the path name of the sudoers file and the line number where the cycle was detected. This is only a warning unless visudo is run in -s (strict) mode as sudo will ignore cycles when parsing the sudoers file.

ignoring editor backup file

While processing a @includedir or #includedir, a file was found with a name that ends in ‘~’ or .bak. Such files are skipped by sudo and visudo.

ignoring file name containing '.'

While processing a @includedir or #includedir, a file was found with a name that contains a ‘.’ character. Such files are skipped by sudo and visudo.

unknown defaults entry "name"

The sudoers file contains a Defaults setting not recognized by visudo.

## SEE ALSO
vi(1), sudo.conf(5), sudoers(5), sudo(8), vipw(8)

## AUTHORS
Many people have worked on sudo over the years; this version consists of code written primarily by:

Todd C. Miller

See the CONTRIBUTORS.md file in the sudo distribution (https://www.sudo.ws/about/contributors/) for an exhaustive list of people who have contributed to sudo.

## CAVEATS
There is no easy way to prevent a user from gaining a root shell if the editor used by visudo allows shell escapes.

## BUGS
If you believe you have found a bug in visudo, you can either file a bug report in the sudo bug database, https://bugzilla.sudo.ws/, or open an issue at https://github.com/sudo-project/sudo/issues. If you would prefer to use email, messages may be sent to the sudo-workers mailing list, https://www.sudo.ws/mailman/listinfo/sudo-workers (public) or <sudo@sudo.ws> (private).

Please do not report security vulnerabilities through public GitHub issues, Bugzilla or mailing lists. Instead, report them via email to <Todd.Miller@sudo.ws>. You may encrypt your message with PGP if you would like, using the key found at https://www.sudo.ws/dist/PGPKEYS.

## SUPPORT
Limited free support is available via the sudo-users mailing list, see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search the archives.

## DISCLAIMER
visudo is provided “AS IS” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. See the LICENSE.md file distributed with sudo or https://www.sudo.ws/about/license/ for complete details.


package: sudo-logsrvd

title: sudo_logsrvd(8)

summary: sudo event and I/O log server

text:
# sudo_logsrvd(8)

## NAME
sudo_logsrvd — sudo event and I/O log server

## SYNOPSIS
sudo_logsrvd

[-hnV] [-f file] [-R percentage]

## DESCRIPTION
sudo_logsrvd is a high-performance log server that accepts event and I/O logs from sudo. It can be used to implement centralized logging of sudo logs. The server has two modes of operation: local and relay. By default, sudo_logsrvd stores the logs locally but it can also be configured to relay them to another server that supports the sudo_logsrv.proto(5) protocol.

When not relaying, event log entries may be logged either via syslog(3) or to a local file. I/O Logs stored locally by sudo_logsrvd can be replayed via the sudoreplay(8) utility in the same way as logs generated directly by the sudoers plugin.

The server also supports restarting interrupted log transfers. To distinguish completed I/O logs from incomplete ones, the I/O log timing file is set to be read-only when the log is complete.

Configuration parameters for sudo_logsrvd may be specified in the sudo_logsrvd.conf(5) file or the file specified via the -f option.

sudo_logsrvd rereads its configuration file when it receives SIGHUP and writes server state to the debug file (if one is configured) when it receives SIGUSR1.

The options are as follows:

-f file, --file=file

Read configuration from file instead of the default, /etc/sudo_logsrvd.conf.

-h, --help

Display a short help message to the standard output and exit.

-n, --no-fork

Run sudo_logsrvd in the foreground instead of detaching from the terminal and becoming a daemon.

-R percentage, --random-drop=percentage

For each message, there is a percentage chance that the server will drop the connection. This is only intended for debugging the ability of a client to restart a connection.

-V, --version

Print the sudo_logsrvd version and exit.

### Securing server connections
The I/O log data sent to sudo_logsrvd may contain sensitive information such as passwords and should be secured using Transport Layer Security (TLS). Doing so requires having a signed certificate on the server and, if tls_checkpeer is enabled in sudo_logsrvd.conf(5), a signed certificate on the client as well.

The certificates can either be signed by a well-known Certificate Authority (CA), or a private CA can be used. Instructions for creating a private CA are included below in the EXAMPLES section.

### Debugging sudo_logsrvd
sudo_logsrvd supports a flexible debugging framework that is configured via Debug lines in the sudo.conf(5) file.

For more information on configuring sudo.conf(5), refer to its manual.

## FILES
/etc/sudo.conf

Sudo front-end configuration

/etc/sudo_logsrvd.conf

Sudo log server configuration file

/var/log/sudo_logsrvd/incoming

Directory where new journals are stored when the store_first relay setting is enabled.

/var/log/sudo_logsrvd/outgoing

Directory where completed journals are stored when the store_first relay setting is enabled.

/var/log/sudo-io

Default I/O log file location

/run/sudo/sudo_logsrvd.pid

Process ID file for sudo_logsrvd

## EXAMPLES

### Creating self-signed certificates
Unless you are using certificates signed by a well-known Certificate Authority (or a local enterprise CA), you will need to create your own CA that can sign the certificates used by sudo_logsrvd, sudo_sendlog, and the sudoers plugin. The following steps use the openssl(1) command to create keys and certificates.

### Initial setup
First, we need to create a directory structure to store the files for the CA. We'll create a new directory hierarchy in /etc/ssl/sudo for this purpose.

```
# mkdir /etc/ssl/sudo
# cd /etc/ssl/sudo
# mkdir certs csr newcerts private
# chmod 700 private
# touch index.txt
# echo 1000 > serial
```

The serial and index.txt files are used to keep track of signed certificates.

Next, we need to make a copy of the openssl.conf file and customize it for our new CA. The path to openssl.cnf is system-dependent but /etc/ssl/openssl.cnf is the most common location. You will need to adjust the example below if it has a different location on your system.

```
# cp /etc/ssl/openssl.cnf .
```

Now edit the openssl.cnf file in the current directory and make sure it contains “ca”, “CA_default”, “v3_ca”, and “usr_cert” sections. Those sections should include at least the following settings:

```
[ ca ]
default_ca              = CA_default

[ CA_default ]
dir                     = /etc/ssl/sudo
certs                   = $dir/certs
database                = $dir/index.txt
certificate             = $dir/cacert.pem
serial                  = $dir/serial

[ v3_ca ]
subjectKeyIdentifier    = hash
authorityKeyIdentifier  = keyid:always,issuer
basicConstraints        = critical,CA:true
keyUsage                = cRLSign, keyCertSign

[ usr_cert ]
basicConstraints        = CA:FALSE
keyUsage                = nonRepudiation, digitalSignature, \
                          keyEncipherment
subjectKeyIdentifier    = hash
authorityKeyIdentifier  = keyid,issuer
```

If your openssl.conf file already has a “CA_default” section, you may only need to modify the “dir” setting and enable the “keyUsage” settings if they are commented out.

### Creating the CA key and certificate
In order to create and sign our own certificates, we need to create a private key and a certificate for the root of the CA. First, create the private key and protect it with a pass phrase:

```
# openssl genrsa -aes256 -out private/cakey.pem 4096
# chmod 400 private/cakey.pem
```

Next, generate the root certificate, using appropriate values for the site-specific fields:

```
# openssl req -config openssl.cnf -key private/cakey.pem \
    -new -x509 -days 7300 -sha256 -extensions v3_ca \
    -out cacert.pem

Enter pass phrase for private/cakey.pem:
You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name
or a DN.
There are quite a few fields but you can leave some blank.
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:Colorado
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgets Pty Ltd]:sudo
Organizational Unit Name (eg, section) []:sudo Certificate Authority
Common Name (e.g., server FQDN or YOUR name) []:sudo Root CA
Email Address []:

# chmod 444 cacert.pem
```

Finally, verify the root certificate:

```
# openssl x509 -noout -text -in cacert.pem
```

### Creating and signing certificates
The server and client certificates will be signed by the previously created root CA. Usually, the root CA is not used to sign server/client certificates directly. Instead, intermediate certificates are created and signed with the root CA and the intermediate certs are used to sign CSRs (Certificate Signing Request). In this example we'll skip this part for simplicity's sake and sign the CSRs with the root CA.

First, generate the private key without a pass phrase.

```
# openssl genrsa -out private/logsrvd_key.pem 2048
# chmod 400 private/logsrvd_key.pem
```

Next, create a certificate signing request (CSR) for the server's certificate. The organization name must match the name given in the root certificate. The common name should be either the server's IP address or a fully qualified domain name.

```
# openssl req -config openssl.cnf -key private/logsrvd_key.pem -new \
    -sha256 -out csr/logsrvd_csr.pem

Enter pass phrase for private/logsrvd_key.pem:
You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name
or a DN.
There are quite a few fields but you can leave some blank.
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:Colorado
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgets Pty Ltd]:sudo
Organizational Unit Name (eg, section) []:sudo log server
Common Name (e.g., server FQDN or YOUR name) []:logserver.example.com
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
```

Now sign the CSR that was just created:

```
# openssl ca -config openssl.cnf -days 375 -notext -md sha256 \
    -in csr/logsrvd_csr.pem -out certs/logsrvd_cert.pem

Using configuration from openssl.cnf
Enter pass phrase for ./private/cakey.pem:
Check that the request matches the signature
Signature ok
Certificate Details:
        Serial Number: 4096 (0x1000)
        Validity
            Not Before: Nov 11 14:05:05 2019 GMT
            Not After : Nov 20 14:05:05 2020 GMT
        Subject:
            countryName               = US
            stateOrProvinceName       = Colorado
            organizationName          = sudo
            organizationalUnitName    = sudo log server
            commonName                = logserve.example.com
        X509v3 extensions:
            X509v3 Basic Constraints:
                CA:FALSE
            X509v3 Key Usage:
                Digital Signature, Non Repudiation, Key Encipherment
            X509v3 Subject Key Identifier:
                4C:50:F9:D0:BE:1A:4C:B2:AC:90:76:56:C7:9E:16:AE:E6:9E:E5:B5
            X509v3 Authority Key Identifier:
                keyid:D7:91:24:16:B1:03:06:65:1A:7A:6E:CF:51:E9:5C:CB:7A:95:3E:0C

Certificate is to be certified until Nov 20 14:05:05 2020 GMT (375 days)
Sign the certificate? [y/n]:y

1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated
```

Finally, verify the new certificate:

```
# openssl verify -CAfile cacert.pem certs/logsrvd_cert.pem
certs/logsrvd_cert.pem: OK
```

The /etc/ssl/sudo/certs directory now contains a signed and verified certificate for use with sudo_logsrvd.

To generate a client certificate, repeat the process above using a different file name.

### Configuring sudo_logsrvd to use TLS
To use TLS for client/server communication, both sudo_logsrvd and the sudoers plugin need to be configured to use TLS. Configuring sudo_logsrvd for TLS requires the following settings, assuming the same path names used earlier:

```
# Listen on port 30344 for TLS connections to any address.
listen_address = *:30344(tls)

# Path to the certificate authority bundle file in PEM format.
tls_cacert = /etc/ssl/sudo/cacert.pem

# Path to the server's certificate file in PEM format.
tls_cert = /etc/ssl/sudo/certs/logsrvd_cert.pem

# Path to the server's private key file in PEM format.
tls_key = /etc/ssl/sudo/private/logsrvd_key.pem
```

The root CA cert (cacert.pem) must be installed on the system running sudo_logsrvd. If peer authentication is enabled on the client, a copy of cacert.pem must be present on the client system too.

## SEE ALSO
sudo.conf(5), sudo_logsrv.proto(5), sudo_logsrvd.conf(5), sudoers(5), sudo(8), sudo_sendlog(8), sudoreplay(8)

## AUTHORS
Many people have worked on sudo over the years; this version consists of code written primarily by:

Todd C. Miller

See the CONTRIBUTORS.md file in the sudo distribution (https://www.sudo.ws/about/contributors/) for an exhaustive list of people who have contributed to sudo.

## BUGS
If you believe you have found a bug in sudo_logsrvd, you can either file a bug report in the sudo bug database, https://bugzilla.sudo.ws/, or open an issue at https://github.com/sudo-project/sudo/issues. If you would prefer to use email, messages may be sent to the sudo-workers mailing list, https://www.sudo.ws/mailman/listinfo/sudo-workers (public) or <sudo@sudo.ws> (private).

Please do not report security vulnerabilities through public GitHub issues, Bugzilla or mailing lists. Instead, report them via email to <Todd.Miller@sudo.ws>. You may encrypt your message with PGP if you would like, using the key found at https://www.sudo.ws/dist/PGPKEYS.

## SUPPORT
Limited free support is available via the sudo-users mailing list, see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search the archives.

## DISCLAIMER
sudo_logsrvd is provided “AS IS” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. See the LICENSE.md file distributed with sudo or https://www.sudo.ws/about/license/ for complete details.


title: sudo_sendlog(8)

summary: send sudo I/O log to log server

text:
# sudo_sendlog(8)

## NAME
sudo_sendlog — send sudo I/O log to log server

## SYNOPSIS
sudo_sendlog

[-AnV] [-b ca_bundle] [-c cert_file] [-h host] [-i iolog-id] [-k key_file] [-p port] [-r restart-point] [-R reject-reason] [-s stop-point] [-t number] path

## DESCRIPTION
sudo_sendlog can be used to send the existing sudoers I/O log path to a remote log server such as sudo_logsrvd(8) for central storage.

The options are as follows:

-A, --accept-only

Only send the accept event, not the I/O associated with the log. This can be used to test the logging of accept events without any associated I/O.

-b, --ca-bundle

The path to a certificate authority bundle file, in PEM format, to use instead of the system's default certificate authority database when authenticating the log server. The default is to use the system's default certificate authority database.

-c, --cert

The path to the client's certificate file in PEM format. This setting is required when the connection to the remote log server is secured with TLS.

--help

Display a short help message to the standard output and exit.

-h, --host

Connect to the specified host instead of localhost.

-i, --iolog-id

Use the specified iolog-id when restarting a log transfer. The iolog-id is reported by the server when it creates the remote I/O log. This option may only be used in conjunction with the -r option.

-k, --key

The path to the client's private key file in PEM format. This setting is required when the connection to the remote log server is secured with TLS.

-n, --no-verify

If specified, the server's certificate will not be verified during the TLS handshake. By default, sudo_sendlog verifies that the server's certificate is valid and that it contains either the server's host name or its IP address. This setting is only supported when the connection to the remote log server is secured with TLS.

-p, --port

Use the specified network port when connecting to the log server instead of the default, port 30344.

-r, --restart

Restart an interrupted connection to the log server. The specified restart-point is used to tell the server the point in time at which to continue the log. The restart-point is specified in the form “seconds,nanoseconds” and is usually the last commit point received from the server. The -i option must also be specified when restarting a transfer.

-R, --reject

Send a reject event for the command using the specified reject-reason, even though it was actually accepted locally. This can be used to test the logging of reject events; no I/O will be sent.

-s, --stop-after

Stop sending log records and close the connection when stop-point is reached. This can be used for testing purposes to send a partial I/O log to the server. Partial logs can be restarted using the -r option. The stop-point is an elapsed time specified in the form “seconds,nanoseconds”.

-t, --test

Open number simultaneous connections to the log server and send the specified I/O log file on each one. This option is useful for performance testing.

-V, --version

Print the sudo_sendlog version and exit.

### Debugging sendlog
sudo_sendlog supports a flexible debugging framework that is configured via Debug lines in the sudo.conf(5) file.

For more information on configuring sudo.conf(5), refer to its manual.

## FILES
/etc/sudo.conf

Sudo front-end configuration

## SEE ALSO
sudo.conf(5), sudo_logsrv.proto(5), sudo(8), sudo_logsrvd(8)

## AUTHORS
Many people have worked on sudo over the years; this version consists of code written primarily by:

Todd C. Miller

See the CONTRIBUTORS.md file in the sudo distribution (https://www.sudo.ws/about/contributors/) for an exhaustive list of people who have contributed to sudo.

## BUGS
If you believe you have found a bug in sudo_sendlog, you can either file a bug report in the sudo bug database, https://bugzilla.sudo.ws/, or open an issue at https://github.com/sudo-project/sudo/issues. If you would prefer to use email, messages may be sent to the sudo-workers mailing list, https://www.sudo.ws/mailman/listinfo/sudo-workers (public) or <sudo@sudo.ws> (private).

Please do not report security vulnerabilities through public GitHub issues, Bugzilla or mailing lists. Instead, report them via email to <Todd.Miller@sudo.ws>. You may encrypt your message with PGP if you would like, using the key found at https://www.sudo.ws/dist/PGPKEYS.

## SUPPORT
Limited free support is available via the sudo-users mailing list, see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search the archives.

## DISCLAIMER
sudo_sendlog is provided “AS IS” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. See the LICENSE.md file distributed with sudo or https://www.sudo.ws/about/license/ for complete details.


package: suspend-utils

title: s2disk(8)

summary: program to suspend to disk (hibernate)

text:
# s2disk(8)

## NAME
s2disk - program to suspend to disk (hibernate)

## SYNOPSIS
s2disk [-h, --help] [-V, --version] [-f, --config config_file] [-r, --resume_device device] [-o, --resume_offset offset] [-s, --image_size size] [-P, --parameter parameter]

## DESCRIPTION
This manual page documents briefly the s2disk, s2both and resume commands.

s2disk is a program that will save the state of the whole system to disk and power off your system. After restarting your system it will be put back in the exact system state you left it (this is sometimes called hibernation).

s2both will do precisly the same as s2disk except that it will not power off the system, but will suspend it to ram (put the system in S3 mode). This has the advantage that resume will be faster, with the disadvantage that you still use batteries. If they batteries do deplete, you still have the system state saved to disk and can resume without data loss. The s2both command also inherits all command line arguments from s2ram.

You will need to set up an initramfs which calls the resume program for this to work. If you use a package distributed with your Linux distribution, the kernel package which was made with the --initrd option and you use mkinitramfs-tools, this package should include the necessary parts on your initramfs.

The suspend-utils system supports encrypting the image written to disk and features a splash system, see suspend.conf(8) for more information.

## OPTIONS
-f, --config [file]

Specify alternate configuration file.

-h, --help

Display help.

-r, --resume_device [device]

Device that contains swap area.

-o, --resume_offset [offset]

Offset of swap file in resume device.

-s, --image_size [size]

Desired size of the image.

-P, --parameter [key=value]

Override any config file parameter (see suspend.conf(8)).

For the meaning and use of the resume_size, resume_offset and image_size options see suspend.conf(8).

## SEE ALSO
suspend.conf(8), suspend-keygen(8), s2ram(8)

For more information see the README file.

## AUTHOR
This manual page was written by Tim Dijkstra <tim@famdijkstra>.org for the Debian(TM) system (but may be used by others). Was updated by Rodolfo García <kix@kix.es>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.

## COPYRIGHT
Copyright © 2006 Tim Dijkstra Copyright © 2012 Rodolfo García (kix)


title: s2ram(8)

summary: program to suspend to ram (suspend)

text:
# s2ram(8)

## NAME
s2ram - program to suspend to ram (suspend)

## DESCRIPTION
This manual page documents briefly the s2ram command.

s2ram is a program that will suspend your system to ram (put it in S3 mode). Which means that the system is in a lower power mode. It asked to do so it will wake up farely quickly. However, if the system will run out of energy entirely you will lose data. That is why it is recommended to use s2both(8) s2ram is only provided to find out any work around needed to make suspend to both work. See README.s2ram-whitelist and README.Debian for more information.

## OPTIONS
-V, --version

Version information.

-a, --acpi_sleep nr

set the acpi_sleep parameter before suspend. 1=s3_bios, 2=s3_mode, 3=both. Only for Intel platform (x86/amd64).

-f, --force

force suspending, even on unknown machines. the following options are only available with --force.

-h, --help

Short help text.

-i, --identify

prints a string that identifies the machine.

-k, --kmstest

test if the kernel supports KMS (Kernel Mode Set). Returns 0 if KMS is supported.

-m, --vbe_mode

get VBE mode before suspend and set it after resume. Only for Intel platform (x86/amd64).

-n, --test

test if the machine is in the database. Returns 0 if known and supported.

-p, --vbe_post

VBE POST the graphics card after resume. Only for Intel platform (x86/amd64).

-r, --radeontool

turn off the backlight on radeons before suspending. Only for Intel platform (x86/amd64).

-s, --vbe_save

save VBE state before suspending and restore after resume. Only for Intel platform (x86/amd64).

-v, --pci_save

Save the PCI config space of the VGA card before suspend and restore it after resume. Only for Intel platform (x86/amd64).

--nofbsuspend

do not suspend the framebuffer (for debugging purposes). Only for Intel platform (x86/amd64).

## SEE ALSO
s2both (8).

For more information see the README.s2ram-whitelist.

## AUTHOR
This manual page was written by Tim Dijkstra <tim@famdijkstra>.org for the Debian(TM) system (but may be used by others). Was updated by Rodolfo García <kix@kix.es>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.

## COPYRIGHT
Copyright © 2006 Tim Dijkstra Copyright © 2012 Rodolfo García (kix)


suspend-keygen

title: suspend-keygen(8)

text:
# suspend-keygen(8)

## NAME
suspend-keygen - program to generate a RSA key to be used by s2disk

## DESCRIPTION
This manual page documents briefly the suspend-keygen command.

suspend-keygen is a program that will generate a RSA key which can be used by the s2disk to encrypt the image written to disk. The program does not take any options, but will ask to give the size of the key in bits and to supply a passphrase. You will have to enter this passphrase on resume to decrypt the image.

To start using encryption, you will have to point the "RSA key file" option in suspend.conf(8) to the file suspend-keygen generated.

## SEE ALSO
s2disk(8), suspend.conf(8).

For more information see the README file.

## AUTHOR
This manual page was written by Tim Dijkstra <tim@famdijkstra>.org for the Debian(TM) system (but may be used by others). Was updated by Rodolfo García <kix@kix.es>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.

## COPYRIGHT
Copyright © 2006 Tim Dijkstra Copyright © 2012 Rodolfo García (kix)


swap-offset

title: swap-offset(8)

text:
# swap-offset(8)

## NAME
swap-offset - program to calculate the offset of a swap file in a partition

## DESCRIPTION
This manual page documents briefly the swap-offset.

The programs s2disk and s2both can be used to save the state of the whole system to a swap partition or file and power off or suspend your system. After restarting your system it will be put back in the exact system state you left it (this is sometimes called hibernation).

In the case of using a swap file you will have to specify the location of the swap file's header as the offset from the beginning of the partition that contains the swap file. The swap-offset utility can be used to determine this value.

## SEE ALSO
suspend.conf(8), s2disk(8)

For more information see the README file.

## AUTHOR
This manual page was written by Tim Dijkstra <tim@famdijkstra>.org for the Debian(TM) system (but may be used by others). Was updated by Rodolfo García <kix@kix.es>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.

## COPYRIGHT
Copyright © 2006 Tim Dijkstra Copyright © 2012 Rodolfo García (kix)


package: svgalib-utils

title: mode3(8)

summary: set a vesa mode.

text:
# mode3(8)

## NAME
mode3 - set a vesa mode.

## SYNOPSIS
mode3 [modenum]

## DESCRIPTION
The video card is set to vesa mode modenum (or 3 by default) using the (real mode) vesa bios calls.

## BUGS
Using this program is unsafe, and might (depending on the bios) result in a video card in a state that requires a hard reset to restore to normal, or even a hung computer.


title: vga_reset(8)

summary: reset video graphic board

text:
# vga_reset(8)

## NAME
vga_reset - reset video graphic board

## SYNOPSIS
vga_reset

## DESCRIPTION
Call real mode c000:0003, which should be the video card's initialization routine. Should work in some cases when mode3 fails to restore text mode.

## BUGS
Using this program is unsafe, and might (depending on the bios) result in a video card in a state that requires a hard reset to restore to normal, or even a hung computer.

## SEE ALSO
mode3(8).

## AUTHOR
This manual page was written by Guillem Jover <guillem@debian.org>.


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 listend 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>[,mode=<0...>]|backend-uri=<uri>

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)

--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 ulimately 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",
        "cmdarg-seccomp",
        "cmdarg-key-fd",
        "cmdarg-pwd-fd",
        "cmdarg-print-states",
        "cmdarg-chroot",
        "cmdarg-migration",
        "nvram-backend-dir",
        "nvram-backend-file",
        "tpm-send-command-header",
        "flags-opt-startup",
        "flags-opt-disable-auto-shutdown",
        "rsa-keysize-1024",
        "rsa-keysize-2048",
        "rsa-keysize-3072"
      ],
      "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 preprending 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.

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

-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 communcation 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>


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 useable 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 maining 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 localty 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 intialization.

-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 <flag>

Get information about the TPM implementation in JSON format. The flag TPMLIB_INFO_TPMSPECIFICATION, which has the value 1, returns information about the specification the TPM implementation followed. The flag TPMLIB_INFO_TPMATTRIBUTES, which has the value 2, returns information about the manufacturer, model, and version of the TPM.

--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 intermedia 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

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. In case ECC (elliptic curve crypography) 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 useable 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 witten 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.

--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": [
        "cmdarg-keyfile-fd",
        "cmdarg-pwdfile-fd",
        "cmdarg-write-ek-cert-files",
        "cmdarg-create-config-files",
        "cmdarg-reconfigure-pcr-banks",
        "tpm2-rsa-keysize-2048",
        "tpm2-rsa-keysize-3072",
        "tpm12-not-need-root",
        "tpm-1.2",
        "tpm-2.0"
      ],
      "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).

--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 based CA that can be used by swtpm_localca to sign EK and platform certificates. The CA uses a GnuTLS key to sign certificates. To do this, GnuTLS talks to the TPM 1.2 using the tcsd (TrouSerS) daemon.

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


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)