consolehelper

package: consolehelper

title: consolehelper(8)

text:
# consolehelper(8)

## NAME
consolehelper - A wrapper that helps console users run system programs

## SYNOPSIS
progname [ options ]

## DESCRIPTION
consolehelper is a tool that makes it easy for console users to run system programs, doing authentication via PAM (which can be set up to trust all console users or to ask for a password at the system administrator's discretion). When possible, the authentication is done graphically; otherwise, it is done within the text console from which consolehelper was started.

It is intended to be completely transparent. This means that the user will never run the consolehelper program directly. Instead, programs like /sbin/halt are paired with a link from /usr/bin/halt to /usr/lib/consolehelper/helper. Then when non-root users (specifically, users without /sbin in their path, or /sbin after /usr/bin) call the "halt" program, consolehelper will be invoked to authenticate the action and then invoke /sbin/halt. (consolehelper itself has no priviledges; it calls /usr/lib/consolehelper/priv/auth privileged helper program to do the real work.)

## MAKING YOUR PROGRAM MANAGED
consolehelper requires that a PAM configuration for every managed program exist. So to make /sbin/foo or /usr/sbin/foo managed, you need to create a link from /usr/bin/foo to /usr/lib/consolehelper/helper and create the file /etc/pam.d/foo, normally using the pam_console(8) PAM module.

Optional configuration file /etc/security/console.apps/foo could be used to tune consolehelper behaviour. This file usually has the following contents:

RUNAS=root

USER=root

PROGRAM=/usr/sbin/foo

SESSION=true

RUNAS is the user to run the program as (default is root). USER is the user whose authentication information to check (either root or the user invoking consolehelper, default is the latter). PROGRAM is a path to the program (default is to try /sbin/foo and /usr/sbin/foo). SESSION is whether to start the PAM session stack; it usually has to be true; if unsure, leave it that way.

## OPTIONS
This program has no command line options of its own; it passes all command line options on to the program it is calling.

## BUGS
No known bugs. Report any you find at http://bugs.altlinux.ru/

## AUTHOR
Originally written by Michael K. Johnson <johnsonm@redhat.com>


containerd

package: containerd

title: containerd(8)

text:
# containerd(8)

## NAME
containerd

## SYNOPSIS
containerd

```
[--address|-a]=[value]
[--config|-c]=[value]
[--log-level|-l]=[value]
[--root]=[value]
[--state]=[value]
```

## DESCRIPTION
containerd is a high performance container runtime whose daemon can be started by using this command. If none of the config, publish, oci-hook, or help commands are specified, the default action of the containerd command is to start the containerd daemon in the foreground.

A default configuration is used if no TOML configuration is specified or located at the default file location. The containerd config command can be used to generate the default configuration for containerd. The output of that command can be used and modified as necessary as a custom configuration.

Usage:

```
containerd [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
```

## GLOBAL OPTIONS
--address, -a="": Address for containerd's GRPC server

--config, -c="": Path to the configuration file (default: "/etc/containerd/config.toml")

--log-level, -l="": Set the logging level [trace, debug, info, warn, error, fatal, panic]

--root="": containerd root directory

--state="": containerd state directory

## config
Information on the containerd config

### default
See the output of the default config

### dump
See the output of the final main config with imported in subconfig files

### migrate
Migrate the current configuration file to the latest version (does not migrate subconfig files)

## publish
Binary to publish events to containerd

--namespace="": Namespace to publish to

--topic="": Topic of the event

## oci-hook
Provides a base for OCI runtime hooks to allow arguments to be injected.


containerd-config

title: containerd-config(8)

summary: information on the containerd config

text:
# containerd-config(8)

## NAME
containerd-config - information on the containerd config

## SYNOPSIS
containerd config [command]

## DESCRIPTION
The containerd config command has one subcommand, named default, which will display on standard output the default containerd config for this version of the containerd daemon.

This output can be piped to a containerd-config.toml(5) file and placed in /etc/containerd to be used as the configuration for containerd on daemon startup. The configuration can be placed in any filesystem location and used with the --config option to the containerd daemon as well.

See containerd-config.toml(5) for more information on the containerd configuration options.

## OPTIONS
default : This subcommand will output the TOML formatted containerd configuration to standard output

## BUGS
Please file any specific issues that you encounter at

⟨https://github.com/containerd/containerd⟩.

## AUTHOR
Phil Estes ⟨estesp@gmail.com⟩

## SEE ALSO
ctr(8), containerd(8), containerd-config.toml(5)


ctr

title: ctr(8)

text:
# ctr(8)

## NAME
ctr

## SYNOPSIS
ctr

```
[--address|-a]=[value]
[--connect-timeout]=[value]
[--debug]
[--namespace|-n]=[value]
[--timeout]=[value]
```

## DESCRIPTION
ctr is an unsupported debug and administrative client for interacting with the containerd daemon. Because it is unsupported, the commands, options, and operations are not guaranteed to be backward compatible or stable from release to release of the containerd project.

Usage:

```
ctr [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
```

## GLOBAL OPTIONS
--address, -a="": Address for containerd's GRPC server (default: "/run/containerd/containerd.sock")

--connect-timeout="": Timeout for connecting to containerd (default: 0s)

--debug: Enable debug output in logs

--namespace, -n="": Namespace to use with commands (default: "default")

--timeout="": Total timeout for ctr commands (default: 0s)

## plugins, plugin
Provides information about containerd plugins

### list, ls
Lists containerd plugins

--detailed, -d: Print detailed information about each plugin

--quiet, -q: Print only the plugin ids

### inspect-runtime
Display runtime info

--runc-binary="": Specify runc-compatible binary

--runc-root="": Specify runc-compatible root

--runc-systemd-cgroup: Start runc with systemd cgroup manager

--runtime="": Runtime name or absolute path to runtime binary (default: "io.containerd.runc.v2")

--runtime-config-path="": Optional runtime config path

## version
Print the client and server versions

## containers, c, container
Manage containers

### create
Create container

--allow-new-privs: Turn off OCI spec's NoNewPrivileges feature flag

--annotation="": Specify additional OCI annotations (e.g. foo=bar)

--apparmor-default-profile="": Enable AppArmor with the default profile with the specified name, e.g. "cri-containerd.apparmor.d"

--apparmor-profile="": Enable AppArmor with an existing custom profile

--blockio-class="": Name of the blockio class to associate the container with

--blockio-config-file="": File path to blockio class definitions. By default class definitions are not loaded.

--cap-add="": Add Linux capabilities (Set capabilities with 'CAP_' prefix)

--cap-drop="": Drop Linux capabilities (Set capabilities with 'CAP_' prefix)

--config, -c="": Path to the runtime-specific spec config file

--cpu-period="": Limit CPU CFS period (default: 0)

--cpu-quota="": Limit CPU CFS quota (default: -1)

--cwd="": Specify the working directory of the process

--device="": File path to a device to add to the container; or a path to a directory tree of devices to add to the container

--env="": Specify additional container environment variables (e.g. FOO=bar)

--env-file="": Specify additional container environment variables in a file(e.g. FOO=bar, one per line)

--gpus="": Add gpus to the container

--hostname="": Set the container's host name

--label="": Specify additional labels (e.g. foo=bar)

--memory-limit="": Memory limit (in bytes) for the container (default: 0)

--mount="": Specify additional container mount (e.g. type=bind,src=/tmp,dst=/host,options=rbind:ro)

--net-host: Enable host networking for the container

--no-pivot: Disable use of pivot-root (linux only)

--pid-file="": File path to write the task's pid

--privileged: Run privileged container

--rdt-class="": Name of the RDT class to associate the container with. Specifies a Class of Service (CLOS) for cache and memory bandwidth management.

--read-only: Set the containers filesystem as readonly

--rootfs: Use custom rootfs that is not managed by containerd snapshotter

--rootfs-propagation="": Set the propagation of the container rootfs

--runc-binary="": Specify runc-compatible binary

--runc-root="": Specify runc-compatible root

--runc-systemd-cgroup: Start runc with systemd cgroup manager

--runtime="": Runtime name or absolute path to runtime binary (default: "io.containerd.runc.v2")

--runtime-config-path="": Optional runtime config path

--sandbox="": Create the container in the given sandbox

--seccomp: Enable the default seccomp profile

--seccomp-profile="": File path to custom seccomp profile. seccomp must be set to true, before using seccomp-profile

--snapshotter="": Snapshotter name. Empty value stands for the default value.

--snapshotter-label="": Labels added to the new snapshot for this container.

--tty, -t: Allocate a TTY for the container

--user, -u="": Username or user id, group optional (format: [:])

--with-ns="": Specify existing Linux namespaces to join at container runtime (format ':')

### delete, del, remove, rm
Delete one or more existing containers

--keep-snapshot: Do not clean up snapshot with container

### info
Get info about a container

--spec: Only display the spec

### list, ls
List containers

--quiet, -q: Print only the container id

### label
Set and clear labels for a container

### checkpoint
Checkpoint a container

--image: Include the image in the checkpoint

--rw: Include the rw layer in the checkpoint

--task: Checkpoint container task

### restore
Restore a container from checkpoint

--live: Restore the runtime and memory data from the checkpoint

--rw: Restore the rw layer from the checkpoint

## content
Manage content

### active
Display active transfers

--root="": Path to content store root (default: "/tmp/content")

--timeout, -t="": Total timeout for fetch (default: 0s)

### delete, del, remove, rm
Permanently delete one or more blobs

### edit
Edit a blob and return a new digest

--editor="": Select editor (vim, emacs, etc.)

--validate="": Validate the result against a format (json, mediatype, etc.)

### fetch
Fetch all content for an image into containerd

--all-platforms: Pull content from all platforms

--hosts-dir="": Custom hosts configuration directory

--http-dump: Dump all HTTP request/responses when interacting with container registry

--http-trace: Enable HTTP tracing for registry interactions

--label="": Labels to attach to the image

--metadata-only: Pull all metadata including manifests and configs

--plain-http: Allow connections using plain HTTP

--platform="": Pull content from a specific platform

--refresh="": Refresh token for authorization server

--skip-metadata: Skips metadata for unused platforms (Image may be unable to be pushed without metadata)

--skip-verify, -k: Skip SSL certificate validation

--tlscacert="": Path to TLS root CA

--tlscert="": Path to TLS client certificate

--tlskey="": Path to TLS client key

--user, -u="": User[:password] Registry user and password

### fetch-object
Retrieve objects from a remote

--hosts-dir="": Custom hosts configuration directory

--http-dump: Dump all HTTP request/responses when interacting with container registry

--http-trace: Enable HTTP tracing for registry interactions

--plain-http: Allow connections using plain HTTP

--refresh="": Refresh token for authorization server

--skip-verify, -k: Skip SSL certificate validation

--tlscacert="": Path to TLS root CA

--tlscert="": Path to TLS client certificate

--tlskey="": Path to TLS client key

--user, -u="": User[:password] Registry user and password

### fetch-blob
Retrieve blobs from a remote

--hosts-dir="": Custom hosts configuration directory

--http-dump: Dump all HTTP request/responses when interacting with container registry

--http-trace: Enable HTTP tracing for registry interactions

--media-type="": Specify target mediatype for request header

--plain-http: Allow connections using plain HTTP

--refresh="": Refresh token for authorization server

--skip-verify, -k: Skip SSL certificate validation

--tlscacert="": Path to TLS root CA

--tlscert="": Path to TLS client certificate

--tlskey="": Path to TLS client key

--user, -u="": User[:password] Registry user and password

### get
Get the data for an object

### ingest
Accept content into the store

--expected-digest="": Verify content against expected digest

--expected-size="": Validate against provided size (default: 0)

### list, ls
List all blobs in the store

--quiet, -q: Print only the blob digest

### push-object
Push an object to a remote

--hosts-dir="": Custom hosts configuration directory

--http-dump: Dump all HTTP request/responses when interacting with container registry

--http-trace: Enable HTTP tracing for registry interactions

--plain-http: Allow connections using plain HTTP

--refresh="": Refresh token for authorization server

--skip-verify, -k: Skip SSL certificate validation

--tlscacert="": Path to TLS root CA

--tlscert="": Path to TLS client certificate

--tlskey="": Path to TLS client key

--user, -u="": User[:password] Registry user and password

### label
Add labels to content

### prune
Prunes content from the content store

### references
Prunes preference labels from the content store (layers only by default)

--async: Allow garbage collection to cleanup asynchronously

--dry: Just show updates without applying (enables debug logging)

## events, event
Display containerd events

## images, image, i
Manage images

### check
Check existing images to ensure all content is available locally

--quiet, -q: Print only the ready image refs (fully downloaded and unpacked)

--snapshotter="": Snapshotter name. Empty value stands for the default value.

### export
Export images

--all-platforms: Exports content from all platforms

--local: Run export locally rather than through transfer API

--platform="": Pull content from a specific platform

--skip-manifest-json: Do not add Docker compatible manifest.json to archive

--skip-non-distributable: Do not add non-distributable blobs such as Windows layers to archive

### import
Import images

--all-platforms: Imports content for all platforms, false by default

--base-name="": Base image name for added images, when provided only images with this name prefix are imported

--compress-blobs: Compress uncompressed blobs when creating manifest (Docker format only)

--digests: Whether to create digest images (default: false)

--discard-unpacked-layers: Allow the garbage collector to clean layers up from the content store after unpacking, cannot be used with --no-unpack, false by default

--index-name="": Image name to keep index as, by default index is discarded

--label="": Labels to attach to the image

--local: Run import locally rather than through transfer API

--no-unpack: Skip unpacking the images, cannot be used with --discard-unpacked-layers, false by default

--platform="": Imports content for specific platform

--skip-digest-for-named: Skip applying --digests option to images named in the importing tar (use it in conjunction with --digests)

--snapshotter="": Snapshotter name. Empty value stands for the default value.

--sync-fs: Synchronize the underlying filesystem containing files when unpack images, false by default

### inspect, i
inspect an image

--content: Show JSON content

### list, ls
List images known to containerd

--quiet, -q: Print only the image refs

### mount
Mount an image to a target path

--expiration, -x="": Set the expiration time for the mount and snapshots (default: 1h0m0s)

--hosts-dir="": Custom hosts configuration directory

--http-dump: Dump all HTTP request/responses when interacting with container registry

--http-trace: Enable HTTP tracing for registry interactions

--label="": Labels to attach to the image

--plain-http: Allow connections using plain HTTP

--platform="": Mount the image for the specified platform (default: "linux/amd64")

--refresh="": Refresh token for authorization server

--rw: Enable write support on the mount

--skip-verify, -k: Skip SSL certificate validation

--snapshotter="": Snapshotter name. Empty value stands for the default value.

--sync-fs: Synchronize the underlying filesystem containing files when unpack images, false by default

--tlscacert="": Path to TLS root CA

--tlscert="": Path to TLS client certificate

--tlskey="": Path to TLS client key

--user, -u="": User[:password] Registry user and password

### unmount
Unmount the image from the target

--hosts-dir="": Custom hosts configuration directory

--http-dump: Dump all HTTP request/responses when interacting with container registry

--http-trace: Enable HTTP tracing for registry interactions

--label="": Labels to attach to the image

--plain-http: Allow connections using plain HTTP

--refresh="": Refresh token for authorization server

--rm: Remove the snapshot after a successful unmount

--skip-verify, -k: Skip SSL certificate validation

--snapshotter="": Snapshotter name. Empty value stands for the default value.

--tlscacert="": Path to TLS root CA

--tlscert="": Path to TLS client certificate

--tlskey="": Path to TLS client key

--user, -u="": User[:password] Registry user and password

### pull
Pull an image from a remote

--all-platforms: Pull content and metadata from all platforms

--hosts-dir="": Custom hosts configuration directory

--http-dump: Dump all HTTP request/responses when interacting with container registry

--http-trace: Enable HTTP tracing for registry interactions

--label="": Labels to attach to the image

--local: Fetch content from local client rather than using transfer service

--max-concurrent-downloads="": Set the max concurrent downloads for each pull (default: 0)

--plain-http: Allow connections using plain HTTP

--platform="": Pull content from a specific platform

--print-chainid: Print the resulting image's chain ID

--refresh="": Refresh token for authorization server

--skip-metadata: Skips metadata for unused platforms (Image may be unable to be pushed without metadata)

--skip-verify, -k: Skip SSL certificate validation

--snapshotter="": Snapshotter name. Empty value stands for the default value.

--sync-fs: Synchronize the underlying filesystem containing files when unpack images, false by default

--tlscacert="": Path to TLS root CA

--tlscert="": Path to TLS client certificate

--tlskey="": Path to TLS client key

--user, -u="": User[:password] Registry user and password

### push
Push an image to a remote

--allow-non-distributable-blobs: Allow pushing blobs that are marked as non-distributable

--hosts-dir="": Custom hosts configuration directory

--http-dump: Dump all HTTP request/responses when interacting with container registry

--http-trace: Enable HTTP tracing for registry interactions

--local: Push content from local client rather than using transfer service

--manifest="": Digest of manifest

--manifest-type="": Media type of manifest digest (default: "application/vnd.oci.image.manifest.v1+json")

--max-concurrent-uploaded-layers="": Set the max concurrent uploaded layers for each push (default: 0)

--plain-http: Allow connections using plain HTTP

--platform="": Push content from a specific platform

--refresh="": Refresh token for authorization server

--skip-verify, -k: Skip SSL certificate validation

--tlscacert="": Path to TLS root CA

--tlscert="": Path to TLS client certificate

--tlskey="": Path to TLS client key

--user, -u="": User[:password] Registry user and password

### prune
Remove unused images

--all: Remove all unused images, not just dangling ones (if all is not specified no images will be pruned)

### delete, del, remove, rm
Remove one or more images by reference

--sync: Synchronously remove image and all associated resources

### tag
Tag an image

--force: Force target_ref to be created, regardless if it already exists

--local: Run tag locally rather than through transfer API

--skip-reference-check: Skip the strict check for reference names

### label
Set and clear labels for an image

--replace-all, -r: Replace all labels

### convert
Convert an image

--all-platforms: Exports content from all platforms

--oci: Convert Docker media types to OCI media types

--platform="": Pull content from a specific platform

--uncompress: Convert tar.gz layers to uncompressed tar layers

### usage
Display usage of snapshots for a given image ref

--snapshotter="": Snapshotter name. Empty value stands for the default value.

## leases
Manage leases

### list, ls
List all active leases

--quiet, -q: Print only the blob digest

### create
Create lease

--expires, -x="": Expiration of lease (0 value will not expire) (default: 24h0m0s)

--id="": Set the id for the lease, will be generated by default

### delete, del, remove, rm
Delete a lease

--sync: Synchronously remove leases and all unreferenced resources

## namespaces, namespace, ns
Manage namespaces

### create, c
Create a new namespace

### list, ls
List namespaces

--quiet, -q: Print only the namespace name

### remove, rm
Remove one or more namespaces

--cgroup, -c: Delete the namespace's cgroup

### label
Set and clear labels for a namespace

## pprof
Provide golang pprof outputs for containerd

--debug-socket, -d="": Socket path for containerd's debug server (default: "/run/containerd/debug.sock")

### block
Goroutine blocking profile

--debug="": Debug pprof args (default: 0)

### goroutines
Dump goroutine stack dump

--debug="": Debug pprof args (default: 2)

### heap
Dump heap profile

--debug="": Debug pprof args (default: 0)

### profile
CPU profile

--debug="": Debug pprof args (default: 0)

--seconds, -s="": Duration for collection (seconds) (default: 30s)

### threadcreate
Goroutine thread creating profile

--debug="": Debug pprof args (default: 0)

### trace
Collect execution trace

--debug="": Debug pprof args (default: 0)

--seconds, -s="": Trace time (seconds) (default: 5s)

## run
Run a container

--allow-new-privs: Turn off OCI spec's NoNewPrivileges feature flag

--annotation="": Specify additional OCI annotations (e.g. foo=bar)

--apparmor-default-profile="": Enable AppArmor with the default profile with the specified name, e.g. "cri-containerd.apparmor.d"

--apparmor-profile="": Enable AppArmor with an existing custom profile

--blockio-class="": Name of the blockio class to associate the container with

--blockio-config-file="": File path to blockio class definitions. By default class definitions are not loaded.

--cap-add="": Add Linux capabilities (Set capabilities with 'CAP_' prefix)

--cap-drop="": Drop Linux capabilities (Set capabilities with 'CAP_' prefix)

--cgroup="": Cgroup path (To disable use of cgroup, set to "" explicitly)

--cni: Enable cni networking for the container

--config, -c="": Path to the runtime-specific spec config file

--cpu-period="": Limit CPU CFS period (default: 0)

--cpu-quota="": Limit CPU CFS quota (default: -1)

--cpu-shares="": Set the cpu shares (default: 1024)

--cpus="": Set the CFS cpu quota (default: 0)

--cpuset-cpus="": Set the CPUs the container will run in (e.g., 1-2,4)

--cpuset-mems="": Set the memory nodes the container will run in (e.g., 1-2,4)

--cwd="": Specify the working directory of the process

--detach, -d: Detach from the task after it has started execution, cannot be used with --rm

--device="": File path to a device to add to the container; or a path to a directory tree of devices to add to the container

--env="": Specify additional container environment variables (e.g. FOO=bar)

--env-file="": Specify additional container environment variables in a file(e.g. FOO=bar, one per line)

--fifo-dir="": Directory used for storing IO FIFOs

--gidmap="": Run inside a user namespace with the specified GID mapping ranges; specified with the format container-gid:host-gid:length

--gpus="": Add gpus to the container

--hostname="": Set the container's host name

--label="": Specify additional labels (e.g. foo=bar)

--log-uri="": Log uri

--memory-limit="": Memory limit (in bytes) for the container (default: 0)

--mount="": Specify additional container mount (e.g. type=bind,src=/tmp,dst=/host,options=rbind:ro)

--net-host: Enable host networking for the container

--no-pivot: Disable use of pivot-root (linux only)

--null-io: Send all IO to /dev/null

--pid-file="": File path to write the task's pid

--platform="": Run image for specific platform

--privileged: Run privileged container

--privileged-without-host-devices: Don't pass all host devices to privileged container

--rdt-class="": Name of the RDT class to associate the container with. Specifies a Class of Service (CLOS) for cache and memory bandwidth management.

--read-only: Set the containers filesystem as readonly

--remap-labels: Provide the user namespace ID remapping to the snapshotter via label options; requires snapshotter support

--rm: Remove the container after running, cannot be used with --detach

--rootfs: Use custom rootfs that is not managed by containerd snapshotter

--rootfs-propagation="": Set the propagation of the container rootfs

--runc-binary="": Specify runc-compatible binary

--runc-root="": Specify runc-compatible root

--runc-systemd-cgroup: Start runc with systemd cgroup manager

--runtime="": Runtime name or absolute path to runtime binary (default: "io.containerd.runc.v2")

--runtime-config-path="": Optional runtime config path

--sandbox="": Create the container in the given sandbox

--seccomp: Enable the default seccomp profile

--seccomp-profile="": File path to custom seccomp profile. seccomp must be set to true, before using seccomp-profile

--snapshotter="": Snapshotter name. Empty value stands for the default value.

--snapshotter-label="": Labels added to the new snapshot for this container.

--sync-fs: Synchronize the underlying filesystem containing files when unpack images, false by default

--tty, -t: Allocate a TTY for the container

--uidmap="": Run inside a user namespace with the specified UID mapping ranges; specified with the format container-uid:host-uid:length

--user, -u="": Username or user id, group optional (format: [:])

--with-ns="": Specify existing Linux namespaces to join at container runtime (format ':')

## snapshots, snapshot
Manage snapshots

--snapshotter="": Snapshotter name. Empty value stands for the default value.

### commit
Commit an active snapshot into the provided name

### diff
Get the diff of two snapshots. the default second snapshot is the first snapshot's parent.

--keep: Keep diff content. up to creator to delete it.

--label="": Labels to attach to the image

--media-type="": Media type to use for creating diff (default: "application/vnd.oci.image.layer.v1.tar+gzip")

--ref="": Content upload reference to use

### info
Get info about a snapshot

### list, ls
List snapshots

### mounts, m, mount
Mount gets mount commands for the snapshots

--temp: Mounts the snapshot mounts as a temp mount and returns a bind mount

### prepare
Prepare a snapshot from a committed snapshot

--mounts: Print out snapshot mounts as JSON

--target, -t="": Mount target path, will print mount, if provided

### delete, del, remove, rm
Remove snapshots

### label
Add labels to content

### tree
Display tree view of snapshot branches

### unpack
Unpack applies layers from a manifest to a snapshot

--snapshotter="": Snapshotter name. Empty value stands for the default value.

--sync-fs: Synchronize the underlying filesystem containing files when unpack images, false by default

### usage
Usage snapshots

-b: Display size in bytes

### view
Create a read-only snapshot from a committed snapshot

--mounts: Print out snapshot mounts as JSON

--target, -t="": Mount target path, will print mount, if provided

## tasks, t, task
Manage tasks

### attach
Attach to the IO of a running container

### checkpoint
Checkpoint a container

--exit: Stop the container after the checkpoint

--image-path="": Path to criu image files

--work-path="": Path to criu work files and logs

### delete, del, remove, rm
Delete one or more tasks

--exec-id="": Process ID to kill

--force, -f: Force delete task process

### exec
Execute additional processes in an existing container

--cwd="": Working directory of the new process

--detach, -d: Detach from the task after it has started execution

--exec-id="": Exec specific id for the process

--fifo-dir="": Directory used for storing IO FIFOs

--log-uri="": Log uri for custom shim logging

--tty, -t: Allocate a TTY for the container

--user="": User id or name

### list, ls
List tasks

--quiet, -q: Print only the task id

### kill
Signal a container (default: SIGTERM)

--all, -a: Send signal to all processes inside the container

--exec-id="": Process ID to kill

--signal, -s="": Signal to send to the container

### metrics, metric
Get a single data point of metrics for a task with the built-in Linux runtime

--format="": "table" or "json" (default: "table")

### pause
Pause an existing container

### ps
List processes for container

### resume
Resume a paused container

### start
Start a container that has been created

--detach, -d: Detach from the task after it has started execution

--fifo-dir="": Directory used for storing IO FIFOs

--log-uri="": Log uri

--no-pivot: Disable use of pivot-root (linux only)

--null-io: Send all IO to /dev/null

--pid-file="": File path to write the task's pid

## install
Install a new package

--libs, -l: Install libs from the image

--path="": Set an optional install path other than the managed opt directory

--replace, -r: Replace any binaries or libs in the opt directory

## oci
OCI tools

### spec
See the output of the default OCI spec

--platform="": Platform of the spec to print (Examples: 'linux/arm64', 'windows/amd64')

## sandboxes, sandbox, sb, s
Manage sandboxes

### run, create, c, r
Run a new sandbox

--runtime="": Runtime name (default: "io.containerd.runc.v2")

### list, ls
List sandboxes

--filters="": The list of filters to apply when querying sandboxes from the store

### remove, rm
Remove sandboxes

--force, -f: Ignore shutdown errors when removing sandbox

### info, i
Get info about a sandbox

## info
Print the server info

## deprecations

### list
Print warnings for deprecations

--format="": output format to use (Examples: 'default', 'json')

## shim
Interact with a shim directly

--id="": shim ID

--shim-address="": shim address (default: computed from shim ID)

### delete
Delete a container with a task

### exec
Exec a new process in the task's container

--attach, -a: Stay attached to the container and open the fifos

--cwd="": Current working directory

--env, -e="": Add environment vars

--spec="": Runtime spec

--stderr="": Specify the path to the stderr fifo

--stdin="": Specify the path to the stdin fifo

--stdout="": Specify the path to the stdout fifo

--tty, -t: Enable tty support

### start
Start a container with a task

### state
Get the state of all main process of the task

--api-version="": shim API version {2,3} (default: 3)

--task-id, -t="": task ID

### shutdown
Shutdown shim if there is no active container

--api-version="": shim API version {2,3} (default: 3)

### pprof
Provide golang pprof outputs for containerd-shim

### block
Goroutine blocking profile

--debug="": Output format, value = 0: binary, value > 0: plaintext (default: 0)

### goroutines
Print goroutine stack dump

--debug="": Output format, value = 0: binary, value > 0: plaintext (default: 2)

### heap
Dump heap profile

--debug="": Output format, value = 0: binary, value > 0: plaintext (default: 0)

### profile
CPU profile

--debug="": Output format, value = 0: binary, value > 0: plaintext (default: 0)

--seconds, -s="": Duration for collection (seconds) (default: 30s)

### threadcreate
Goroutine thread creating profile

--debug="": Output format, value = 0: binary, value > 0: plaintext (default: 0)

### trace
Collect execution trace

--debug="": Output format, value = 0: binary, value > 0: plaintext (default: 0)

--seconds, -s="": Trace time (seconds) (default: 5s)


control

package: control

title: control(8)

summary: control installed system facilities

text:
# control(8)

## NAME
control - control installed system facilities

## SYNOPSIS
control [ FACILITY [help|list|status|summary|STATUS] ]

## DESCRIPTION
control provides a common interface to register and control system facilities.

This is intended primarily for facilities that can potentially be dangerous to system security, to let you enable, disable, or configure the facility independently from package installation.

When run with no arguments, control lists all available facilities, their current status, and their supported settings.

When a FACILITY name is specified, control may print facility summary, list its supported settings or print short help text for them, report its current status (default action), or switch it to a new STATUS.

## FILES

/etc/control.d/facilities/ - installed system facilities' control scripts to be invoked by control

/etc/control.d/functions - common shell functions used by the above scripts

## HISTORY
control first appeared in Openwall GNU/*/Linux 0.1.

## AUTHORS
Solar Designer <solar@owl.openwall.com>

## SEE ALSO
chkconfig(8), control-dump(8)


control-dump

title: control-dump(8)

summary: dump or restore state of

text:
# control-dump(8)

## NAME
control-dump, control-restore - dump or restore state of installed system facilities

## SYNOPSIS
control-dump [FACILITY...]

control-restore [FACILITY...]

## DESCRIPTION
control-dump and control-restore are intended to be used by package pre-install and post-install scripts, respectively, to dump and restore state of system facilities provided by those packages. This allows to keep the desired state of installed system facilities over package or OS upgrades.

## FILES

/var/run/control/* - shell pattern of saved status files created by control-dump, later used and removed by control-restore

/etc/control.d/facilities/ - installed system facilities' control scripts to be invoked by control(8)

/etc/control.d/functions - common shell functions used by the above scripts

## HISTORY
control-dump and control-restore first appeared in ALT Linux Sisyphus and Openwall GNU/*/Linux 1.0.

## AUTHORS
Dmitry V. Levin <ldv@altlinux.org>

Solar Designer <solar@owl.openwall.com>

## SEE ALSO
chkconfig(8), control(8)


corosync

package: corosync

title: corosync(8)

summary: The Corosync Cluster Engine.

text:
# corosync(8)

## NAME
corosync - The Corosync Cluster Engine.

## SYNOPSIS
corosync [-c config_file] [-f] [-t] [-v]

## DESCRIPTION
corosync Corosync provides clustering infrastructure such as membership, messaging and quorum.

## OPTIONS
-c

This specifies the fully qualified path to the corosync configuration file. Also used as a base directory for uidgid files. The default is /etc/corosync/corosync.conf.

-l

This specifies the fully qualified path to the corosync pid lock file. The default is /var/run/corosync.pid.

WARNING: This option is not intended for running multiple Corosync instances. Use it only if you know what you are doing.

-f

Start application in foreground.

-t

Test configuration and then exit.

-v

Display version, git revision, compiled features and available crypto and compression models and exit.

## SEE ALSO
corosync_overview(7), corosync.conf(5), cpg_overview(3), votequorum_overview(3), sam_overview(3), cmap_overview(3), quorum_overview(3)

## AUTHOR
Angus Salkeld


corosync-blackbox

title: corosync-blackbox(8)

summary: Dump live flight data from the corosync blackbox.

text:
# corosync-blackbox(8)

## NAME
corosync-blackbox - Dump live "flight data" from the corosync "blackbox".

## SYNOPSIS
corosync-blackbox

## DESCRIPTION
corosync-blackbox Trigger corosync to write it's "flight data" out to file and then run qb-blackbox which prints it out.

## EXAMPLES
Print the current "flight data".

$ corosync-blackbox

Starting replay: head [74205] tail [0]

rec=[1] Log Message=Corosync Cluster Engine ('1.2.1'): started and ready to provide service.

[...]

rec=[2607] Log Message=Delivering MCAST message with seq a to pending delivery queue

rec=[2608] Log Message=downlist received left_list: 2

rec=[2609] Log Message=chosen downlist from node r(0) ip(192.168.100.11)

Finishing replay: records found [2609]

## SEE ALSO
qb-blackbox(8), corosync-cmapctl(8)

## AUTHOR
Angus Salkeld


corosync-cfgtool

title: corosync-cfgtool(8)

summary: An administrative tool for corosync.

text:
# corosync-cfgtool(8)

## NAME
corosync-cfgtool - An administrative tool for corosync.

## SYNOPSIS
corosync-cfgtool [[-i IP_address] [-b] [-s] [-n] [-R] [-L] [-k nodeid] [-a nodeid] [-h] [-H] [--force]

## DESCRIPTION
corosync-cfgtool A tool for displaying and configuring active parameters within corosync.

## OPTIONS
-i

Finds only information about the specified interface IP address or link id with -s.

-s

Displays the status of the current links on this node for UDP/UDPU, with extended status for KNET. After each link, the nodes on that link are displayed in order with their status, for example there are 3 nodes with KNET transport: LINK ID 0

addr = 192.168.100.80

status:

nodeid 1: localhost

nodeid 2: connected

nodeid 3: connected

Please note that only one link is returned for a single node cluster configuration, no matter how many links are configured.

-b

Displays the brief status of the current links on this node when used with "-s". If any interfaces are faulty, 1 is returned by the binary. If all interfaces are active 0 is returned to the shell. After each link, the nodes on that link are displayed in order with their status encoded into a single digit, or characters 'n', 'd' and '?' with special meaning. 1=link enabled, 2=link connected, So a 3 in a node position indicates that the link is both enabled and connected. Status represented by character 'n' is used for localhost link. Character '?' means that Corosync was unable to get status of link from knet (log should contain more information). Character 'd' shouldn't appear and it means that Corosync was unable to configure a link and it is result of some error which should have been logged. The output will be:

LINK ID 0

addr = 192.168.100.80

status = n33

-n

Displays the status of the current nodes in the system with their link status(es).

```
Local node ID 1, transport knet
nodeid: 2 reachable   onwire (min/max/cur): 0, 1, 1

   LINK: 0 (192.168.1.101->192.168.1.102)  enabled connected mtu: 1397

   LINK: 1 (192.168.4.1->192.168.4.2)  enabled mtu: 469

   LINK: 2 (192.168.9.1->192.168.9.2)  enabled mtu: 469
```

Only reachable nodes are displayed so "reachable" should always be there.

‘onwire’ versions are the knet on-wire versions that are supported/in use (where appropriate).

IP addresses are the local and remote IP addresses (for UDP[U] only the local IP address is shown)

enabled - means the link has been brought up

connected - means that the link is connected to the remote node

dynconnected - is not currently implemented

mtu - shows the size of data packets. Should be the link packet size less a small amount for protocol overheads and encryption

-R

Tell all instances of corosync in this cluster to reload corosync.conf. Running corosync-cfgtool -R where nodes are running different versions of corosync (including minor versions) is unsupported and may result in undefined behaviour.

-L

Tell corosync to reopen all logging files. In contrast to other subcommands, nothing is displayed on terminal if call is successful.

-k

Kill a node identified by node id.

-a

Display the IP address(es) of a node.

-h

Print basic usage.

-H

Shutdown corosync cleanly on this node. corosync-cfgtool -H will request a shutdown from corosync, which means it will consult any interested daemons before shutting down and the shutdown maybe vetoed if a daemon regards the shutdown as inappropriate. If --force is added to the command line then corosync will shutdown regardless of the daemons' opinions on the matter.

## SEE ALSO
corosync_overview(7),

## AUTHOR
Angus Salkeld


corosync-cmapctl

title: corosync-cmapctl(8)

text:
# corosync-cmapctl(8)

## NAME
corosync-cmapctl: - A tool for accessing the object database.

## DESCRIPTION
usage: corosync-cmapctl [-b] [-DdghsTt] [-m map] [-p filename] [params...]

-b show binary values

-m select map to use

The default map is 'icmap' which contains configuration information and some runtime variables used by corosync. A 'stats' map is also available which displays network statistics - in great detail when knet is used as the transport. Tracking of individual keys (but not prefixes) works on the stats map but notifications are sent on a timer, and not every time a value changes.

### Set key:

corosync-cmapctl -s key_name type value

where type is one of ([i|u][8|16|32|64] | flt | dbl | str | bin) for bin, value is file name (or - for stdin)

### Load settings from a file:

corosync-cmapctl -p filename

the format of the file is: [^[^]]<key_name>[ <type> <value>]

Keys prefixed with single caret ('^') are deleted (see -d).

Keys (actually prefixes) prefixed with double caret ('^^') are deleted by prefix (see -D).

<type> and <value> are optional (not checked) in above cases.

Other keys are set (see -s) so both <type> and <value> are required.

### Delete key:

corosync-cmapctl -d key_name...

### Delete multiple keys with prefix:

corosync-cmapctl -D key_prefix...

### Get key:

corosync-cmapctl [-b] -g key_name...

### Quiet output:

corosync-cmapctl [-b] -q -g key_name...

### Display all keys:

corosync-cmapctl [-b]

### Display keys with prefix key_name:

corosync-cmapctl [-b] key_name...

### Track changes on keys with key_name:

corosync-cmapctl [-b] -t key_name

### Track changes on keys with key prefix:

corosync-cmapctl [-b] -T key_prefix

### Clear statistics (-mstats is implied)

corosync-cmapctl -C [ipc|totem|knet|all]

## SEE ALSO
cmap_overview(3), cmap_keys(7)


corosync-cpgtool

title: corosync-cpgtool(8)

text:
# corosync-cpgtool(8)

## NAME
corosync-cpgtool - A tool for displaying cpg groups and members.

## SYNOPSIS
corosync-cpgtool [-d delimiter] [-e] [-n] [-h]

## DESCRIPTION
corosync-cpgtool A tool for displaying cpg groups and members.

## OPTIONS
-d

Delimiter between fields.

-e

Don't escape unprintable characters in group name.

-n

Display only all existing group names.

-h

Display this help.

## EXAMPLES
Display the groups and process that belong to those cpg groups.

$ corosync-cpgtool

Group Name PID Node ID

example-group

2515 191146176 (192.168.100.11)

2471 207923392 (192.168.100.12)

Get a comma-delimited list.

$ corosync-cpgtool -d ","

GRP_NAME,PID,NODEID

example-group,2515,191146176

example-group,2471,207923392

Just get the group names

$ corosync-cpgtool -n

example-group

## SEE ALSO
corosync_overview(7),

## AUTHOR
Angus Salkeld


corosync-keygen

title: corosync-keygen(8)

text:
# corosync-keygen(8)

## NAME
corosync-keygen - Generate an authentication key for Corosync.

## SYNOPSIS
corosync-keygen [-k <filename>] [-m <randomfile>] [-s size] [-l] [-h]

## DESCRIPTION
If you want to configure corosync to use cryptographic techniques to ensure authenticity and privacy of the messages, you will need to generate a private key.

corosync-keygen creates this key and writes it to /etc/corosync/authkey or to file specified by -k option.

This private key must be copied to every processor in the cluster. If the private key isn't the same for every node, those nodes with nonmatching private keys will not be able to join the same configuration.

Copy the key to some security transportable storage or use ssh to transmit the key from node to node. Then install the key with the command:

unix#: install -D --group=0 --owner=0 --mode=0400 /path_to_authkey/authkey /etc/corosync/authkey

If a message "Invalid digest" appears from the corosync executive, the keys are not consistent between processors.

## OPTIONS
-k <filename>

This specifies the fully qualified path to the shared key to create.

The default is /etc/corosync/authkey.

-r

Random number source file. Default is /dev/urandom. As an example /dev/random may be used when really superb randomness is needed.

-s size

Size of the generated key in bytes. Default is 256 bytes. Allowed range is <128, 4096>.

-l

Option is not used and it's kept only for compatibility.

-h

Print basic usage.

## EXAMPLES
Generate the key.

```
# corosync-keygen
Corosync Cluster Engine Authentication key generator.
Gathering 2048 bits for key from /dev/urandom.
Writing corosync key to /etc/corosync/authkey
```

Generate longer key and store it in the /tmp/authkey file.

```
$ corosync-keygen -s 2048 -k /tmp/authkey
Corosync Cluster Engine Authentication key generator.
Gathering 16384 bits for key from /dev/urandom.
Writing corosync key to /tmp/authkey.
```

Generate superb key using /dev/random

```
# corosync-keygen -r /dev/random
Gathering 2048 bits for key from /dev/random.
Press keys on your keyboard to generate entropy.
Press keys on your keyboard to generate entropy (1128 bits still needed).
Press keys on your keyboard to generate entropy (504 bits still needed).
Press keys on your keyboard to generate entropy (128 bits still needed).
Press keys on your keyboard to generate entropy (32 bits still needed).
Writing corosync key to /etc/corosync/authkey.
```

## SEE ALSO
corosync_overview(7), corosync.conf(5),

## AUTHOR
Angus Salkeld


corosync-notifyd

title: corosync-notifyd(8)

text:
# corosync-notifyd(8)

## NAME
corosync-notifyd - Listen for important corosync events and send dbus and/or snmp traps.

## SYNOPSIS
corosync-notifyd [-f] [-l] [-o] [-s] [-m manager] [-d] [-h]

## DESCRIPTION
corosync-notifyd uses corosync API to listen for important cluster events and can log them, generate dbus signals or generate snmp traps.

## OPTIONS
-f

Start application in foreground.

-l

Log all events.

-o

Print events to stdout (turns on -l).

-s

Send SNMP traps on all events.

-m

Set the SNMP Manager IP address (defaults to localhost).

-n

No reverse DNS lookup on cmap member change events.

-d

Send DBUS signals on all events.

-h

Print this help.

## EXAMPLES
$ corosync-notifyd -o

corosync-notifyd[18505]: troll[23374016] corosync-notify:18505:12 is now connected to corosync

corosync-notifyd[18505]: troll[23374016] corosync-notify:18505:13 is now disconnected from corosync

corosync-notifyd[18505]: troll[23374016] is now quorate

corosync-notifyd[18505]: r2[1550100672] ip:192.168.100.92 joined

corosync-notifyd[18505]: r2[1550100672] ip:192.168.100.92 left

$ corosync-notifyd -d

Note this output below is from "dbus-monitor --system"

signal sender=:1.216 -> dest=(null destination) serial=2 path=/com/redhat/cluster/corosync;

interface=com.redhat.cluster.corosync; member=ConnectionStateChange

string "troll"

uint32 23374016

string "corosync-notify:18900:12"

string "connected"

signal sender=:1.216 -> dest=(null destination) serial=3 path=/com/redhat/cluster/corosync;

interface=com.redhat.cluster.corosync; member=ConnectionStateChange

string "troll"

uint32 23374016

string "corosync-notify:18900:13"

string "disconnected"

signal sender=:1.216 -> dest=(null destination) serial=4 path=/com/redhat/cluster/corosync;

interface=com.redhat.cluster.corosync; member=QorumStateChange

string "troll"

uint32 23374016

string "quorate"

signal sender=:1.216 -> dest=(null destination) serial=5 path=/com/redhat/cluster/corosync;

interface=com.redhat.cluster.corosync; member=NodeStateChange

string "r2"

uint32 1550100672

string "192.168.100.92"

string "joined"

signal sender=:1.216 -> dest=(null destination) serial=6 path=/com/redhat/cluster/corosync;

interface=com.redhat.cluster.corosync; member=NodeStateChange

string "r2"

uint32 1550100672

string "192.168.100.92"

string "left"

## SEE ALSO
corosync(8), corosync-cmapctl(8), dbus-monitor(1),

## AUTHOR
Angus Salkeld


corosync-quorumtool

title: corosync-quorumtool(8)

summary: Set and display quorum settings.

text:
# corosync-quorumtool(8)

## NAME
corosync-quorumtool - Set and display quorum settings.

## SYNOPSIS
corosync-quorumtool [-s] [-m] [-l] [-p] [-v votes] [-n nodeid] [-e expected] [-H] [-i] [-o <a|n|i>] [-a] [-f] [-h] [-V]

## DESCRIPTION
Display the current state of quorum in the cluster and set vote quorum options.

## OPTIONS
-s

show quorum status

-m

constantly monitor quorum status

-l

list nodes

-p

when used with -s or -l, generates machine parsable output

-v <votes>

change the number of votes for a node *

-n <nodeid>

optional nodeid of node for -v

-e <expected>

change expected votes for the cluster *

-H

show nodeids in hexadecimal rather than decimal

-i

show node IP addresses instead of the resolved name

-p

when used with -s or -l, generates machine parsable output

-o <a|n|i>

Orders the output of the nodes list. By default or with -oa nodes are listed in IP address order: as they come from corosync. -on will order the nodes based on their name, and -oi will order them based on their node ID.

-a

Show the name or IP address (see -i above) of all interfaces in use on the nodes, rather than just the first one.

-f

forcefully unregister a quorum device *DANGEROUS* *

-h (if no other argument)

show this help text

-V

show version and exit

* Starred items only work if votequorum is the quorum provider for corosync

## EXIT STATUS
corosync-quorumtool may return one of several error codes if it encounters problems.

0

No problems occurred (quorate for -s operation).

1

Generic error code.

2

Not quorate (returned only for -s operation).

## SEE ALSO
corosync_overview(7), votequorum_overview(3),

## AUTHOR
Angus Salkeld


corosync-xmlproc

title: corosync-xmlproc(8)

text:
# corosync-xmlproc(8)

## NAME
corosync-xmlproc - Converts corosync.xml to the Corosync configuration file.

## SYNOPSIS
corosync-xmlproc input_xml [output_file]

## DESCRIPTION
corosync-xmlproc Converts valid corosync.xml file to the Corosync configuration file format. Command internally uses xsltproc for XML conversion.

## OPTIONS
input_xml

Valid XML file to convert.

output_file

Destination file name. If parameter is - or omitted, output is written to standard output.

## SEE ALSO
corosync.xml(5)

## AUTHOR
Jan Friesse


corosync-qdevice

package: corosync-qdevice

title: corosync-qdevice(8)

summary: QDevice daemon

text:
# corosync-qdevice(8)

## NAME
corosync-qdevice - QDevice daemon

## SYNOPSIS
corosync-qdevice [-dfh] [-S option=value[,option2=value2,...]]

## DESCRIPTION
corosync-qdevice is a daemon running on each node of a cluster. It provides a configured number of votes to the quorum subsystem based on a third-party arbitrator's decision. Its primary use is to allow a cluster to sustain more node failures than standard quorum rules allow. It is recommended for clusters with an even number of nodes and highly recommended for 2 node clusters.

## OPTIONS
-d

Forcefully turn on debug information without the need to change corosync.conf. For bumping syslog messages priority to info, use this parameter twice.

-f

Do not daemonize, run in the foreground.

-h

Show short help text

-S

Set advanced settings described in its own section below. This option shouldn't be generally used because most of the options are not safe to change.

## CONFIGURATION
corosync-qdevice reads its configuration from corosync.conf file.

The main configuration is within quorum.device sub-key. Each model also has its own configuration within a similarly named sub-key.

model

Specifies the model to be used. This parameter is required. corosync-qdevice is modular and is able to support multiple different models. The model basically defines what type of arbitrator is used. Currently only net is supported.

timeout

Specifies how often corosync-qdevice should call the votequorum_qdevice_poll function. It is also used by the net model to adjust its hearbeat timeout. It is recommended that you don't change this value. Default is 10000.

sync_timeout

Specifies how often corosync-qdevice should call the votequorum_qdevice_poll function during a sync phase. It is recommended that you don't change this value. Default is 30000.

votes

The number of votes provided to the cluster by qdevice. Default is (number_of_nodes - 1) or generally sum(votes_per_node) - 1.

quorum.device.heuristics subkey holds the configuration of the heuristics. Heuristics are set of commands executed locally on startup, cluster membership change, successful connect to corosync-qnetd and optionally also at regular times. Commands are executed in parallel. When all commands finish successfully (their return error code is zero) on time, heuristics have passed, otherwise they have failed. The heuristics result is sent to corosync-qnetd and there it's used in calculations to determine which partition should be quorate.

timeout

Specifies maximum time in milliseconds how long corosync-qdevice waits till the heuristics commands finish. If some command doesn't finish before the timeout, it's killed and heuristics fail. This timeout is used for heuristics executed at regular times. Default value is half of the quorum.device.timeout, so 5000.

sync_timeout

Similar to quorum.device.heuristics.timeout but used during membership changes. Default value is half of the quorum.device.sync_timeout, so 15000.

interval

Specifies interval between two regular heuristics execution. Default value is 3 * quorum.device.timeout, so 30000.

mode

Can be one of on, sync or off and specifies mode of operation of heuristics. Default is off, which means heuristics are disabled. When sync is set, heuristics are executed only during startup, membership change and when connection to corosync-qnetd is established. When heuristics should be running also on regular basis, this option should be set to on value.

exec_NAME

defines executables. NAME can be arbitrary valid cmap key name string and it has no special meaning. The value of this variable must contain a command to execute. The value is parsed (split) into arguments similarly as Bourne shell would do. Quoting is possible by using backslash and double quotes.

quorum.device.net subkey holds the configuration for model net.

tls

Can be one of on, off or required and specifies if tls should be used. on means a connection with TLS is attempted first, but if the server doesn't advertise TLS support then non-TLS will be used. off is used then TLS is not required and it's then not even tried. This mode is the only one which doesn't need a properly initialized NSS database. required means TLS is required and if the server doesn't support TLS, qdevice will exit with error message. Default is on.

host

Specifies the IP address or host name of the qnetd server to be used. This parameter is required.

port

Specifies TCP port of qnetd server. Default is 5403.

algorithm

Decision algorithm. Can be one of the ffsplit or lms. (actually there are also test and 2nodelms, both of which are mainly for developers and shouldn't be used for production clusters). For a description of what each algorithm means and how the algorithms differ see their individual sections. Default value is ffsplit.

tie_breaker

can be one of lowest, highest or valid_node_id (number) values. It's used as a fallback if qdevice has to decide between two or more equal partitions. lowest means the partition with the lowest node id is chosen. highest means the partition with highest node id is chosen. And valid_node_id means that the partition containing the node with the given node id is chosen. Default is lowest.

connect_timeout

Timeout when corosync-qdevice is trying to connect to corosync-qnetd host. Default is 0.8 * quorum.device.timeout.

force_ip_version

can be one of 0|4|6 and forces the software to use the given IP version. 0 (default value) means IPv6 is preferred and IPv4 should be used as a fallback.

keep_active_partition_tie_breaker

Can be one of on or off and specifies if keep active partition tie breaker should be used. When this option is enabled and tie happens QNetd will prefer partition with members of previously active (quorate) partition. This is hard-coded behavior of LMS algorithm so this setting affects only FFSplit algorithm. Default is on.

Logging configuration is within the logging directive. corosync-qdevice parses and supports only debug option. The logger_subsys sub-directive can be also used if subsys is set to QDEVICE.

For corosync-qdevice to work correctly, the nodelist directive has to be used and properly configured. Also the net model requires that totem.cluster_name option is set.

## MODEL NET TLS CONFIGURATION
For model net to work using TLS, it's necessary to create the NSS database, import Qnetd CA certificate, and get/distribute a valid client certificate.

If pcs is used (recommended) the following steps are not needed because pcs does them automatically.

corosync-qdevice-net-certutil is the tool to perform required actions semi-automatically. Please consult the help output of it and its man page. For a first time configuration it may make sense to start with the -Q option.

If TLS is not required just edit corosync.conf file and set quorum.device.net.tls to off.

Depending on configuration of NSS (stored in nss.config file usually in /etc/crypto-policies/back-ends/ directory) disabled ciphers or too short keys may be rejected. Proper solution is to regenerate NSS databases for both corosync-qnetd and corosync-qdevice daemons. As a quick workaround it's also possible to set environment variable NSS_IGNORE_SYSTEM_POLICY=1 before running corosync-qdevice daemon.

When NSS is updated it may also be needed to upgrade database into new format. There is no consensus on recommended way, but following command seems to work just fine (if qdevice sysconfdir is set to /etc)

```
# certutil -N -d /etc/corosync/qdevice/net/nssdb -f /etc/corosync/qdevice/net/nssdb/pwdfile.txt
```

## MODEL NET ALGORITHMS
Algorithms are used to change behavior of how corosync-qnetd provides votes to a given node/partition. Currently there are two algorithms supported.

ffsplit

This one makes sense only for clusters with an even number of nodes. It provides exactly one vote to the partition with the highest number of active nodes. If there are two exactly similar partitions, it provides its vote to the partition with higher score. The score is computed as (number_of_connected_nodes + number_of_connected_nodes_with_passed_heuristics - number_of_connected_nodes_with_failed_heuristics) If the scores are equal, the vote is provided to partition with the most clients connected to the qnetd server. If this number is also equal, then the tie_breaker is used. It is able to transition its vote if the currently active partition becomes partitioned and a non-active partition still has at least 50% of the active nodes. Because of this, a vote is not provided if the qnetd connection is not active. To use this algorithm it's required to set the number of votes per node to 1 (default) and the qdevice number of votes has to be also 1. This is achieved by setting quorum.device.votes key in corosync.conf file to 1.

lms

Last-man-standing. If the node is the only one left in the cluster that can see the qnetd server then we return a vote. If more than one node can see the qnetd server but some nodes can't see each other then the cluster is divided up into 'partitions' based on their ring_id and this algorithm returns a vote to the partition with highest heuristics score (computed the same way as for the ffsplit algorithm), or if there is more than 1 partition with equal scores, the largest active partition or, if there is more than 1 equal partition, the partition that contains the tie_breaker node (lowest, highest, etc). For LMS to work, the number of qdevice votes has to be set to default (so just delete quorum.device.votes key from corosync.conf).

## ADVANCED SETTINGS
Set by using -S option. The default value is shown in parentheses) Options beginning with net_ prefix are specific to model net.

lock_file

Lock file location. (/var/run/corosync-qdevice/corosync-qdevice.pid)

local_socket_file

Internal IPC socket file location. (/var/run/corosync-qdevice/corosync-qdevice.sock)

local_socket_backlog

Parameter passed to listen syscall. (10)

max_cs_try_again

How many times to retry the call to a corosync function which has returned CS_ERR_TRY_AGAIN. (10)

votequorum_device_name

Name used for qdevice registration. (Qdevice)

ipc_max_clients

Maximum allowed simultaneous IPC clients. (10)

ipc_max_receive_size

Maximum size of a message received by IPC client. (4096)

ipc_max_send_size

Maximum size of a message allowed to be sent to an IPC client. (65536)

master_wins

Force enable/disable master wins. (default is model)

heuristics_ipc_max_send_buffers

Maximum number of heuristics worker send buffers. (128)

heuristics_ipc_max_send_receive_size

Maximum size of a message allowed to be send to, or received from heuristics worker. (4096)

heuristics_min_timeout

Minimum heuristics timeout accepted by client in ms. (1000)

heuristics_max_timeout

Maximum heuristics timeout accepted by client in ms. (120000)

heuristics_min_interval

Minimum heuristics interval accepted by client in ms. (1000)

heuristics_max_interval

Maximum heuristics interval accepted by client in ms. (3600000)

heuristics_max_execs

Maximum number of exec_ commands. (32)

heuristics_use_execvp

Use execvp instead of execv for executing commands. (off)

heuristics_max_processes

Maximum number of processes running at one time. (160)

heuristics_kill_list_interval

Interval between status is gathered and eventually signal is sent to processes which didn't finished on time in ms. (5000)

net_nss_db_dir

NSS database directory. (/etc/corosync/qdevice/net/nssdb)

net_initial_msg_receive_size

Initial (used during connection parameters negotiation) maximum size of the receive buffer for message (maximum allowed message size received from qnetd). (32768)

net_initial_msg_send_size

Initial (used during connection parameter negotiation) maximum size of one send buffer (message) to be sent to server. (32768)

net_min_msg_send_size

Minimum required size of one send buffer (message) to be sent to server. (32768)

net_max_msg_receive_size

Maximum allowed size of receive buffer for a message sent by server. (16777216)

net_max_send_buffers

Maximum number of send buffers. (10)

net_nss_qnetd_cn

Canonical name of qnetd server certificate. (Qnetd Server)

net_nss_client_cert_nickname

NSS nickname of qdevice client certificate. (Cluster Cert)

net_heartbeat_interval_min

Minimum heartbeat timeout accepted by client in ms. (1000)

net_heartbeat_interval_max

Maximum heartbeat timeout accepted by client in ms. (120000)

net_min_connect_timeout

Minimum connection timeout accepted by client in ms. (1000)

net_max_connect_timeout

Maximum connection timeout accepted by client in ms. (120000)

net_test_algorithm_enabled

Enable test algorithm. (if built with --enable-debug on, otherwise off)

## EXAMPLE
Define qdevice with net model connecting to qnetd running on qnetd.example.org host, using ffsplit algorithm. Heuristics is set to sync mode and executes two commands.

```
quorum {

  provider: corosync_votequorum

  device {

    votes: 1

    model: net

    net {

      tls: on

      host: qnetd.example.org

      algorithm: ffsplit

    }

    heuristics {

      mode: sync

      exec_ping: /bin/ping -q -c 1 "www.example.org"

      exec_test_txt_exists: /usr/bin/test -f /tmp/test.txt

    }
}
```

## SEE ALSO
corosync-qdevice-tool(8) corosync-qdevice-net-certutil(8) corosync-qnetd(8) corosync.conf(5) votequorum_qdevice_poll(3)

## AUTHOR
Jan Friesse


corosync-qdevice-net-certutil

title: corosync-qdevice-net-certutil(8)

text:
# corosync-qdevice-net-certutil(8)

## NAME
corosync-qdevice-net-certutil - tool to generate qdevice model net TLS certificates

## SYNOPSIS
corosync-qdevice-net-certutil [-i|-m|-M|-r|-s|-Q] [-c certificate] [-n cluster_name]

## DESCRIPTION
corosync-qdevice-net-certutil is a frontend for NSS certutil used for generating client certificate for the net model of qdevice.

## OPTIONS
-i

Initialize the QDevice Net NSS certificate database. The default directory for the database is /etc/corosync/qdevice/net/. This directory has to be writable by the current user. It needs the QNetd CA certificate passed as the -c parameter. This certificate can be found on the server running QNetd in the file /etc/corosync/qnetd/nssdb/qnetd-cacert.crt.

-m

Import the cluster certificate and key from a pk12 file.

-r

Generate a certificate request. The certificate request is exported into /etc/corosync/qdevice/net/qdevice-net-node.crq. It is necessary to pass the cluster name using the -n parameter. The cluster name has to match the one defined in /etc/corosync/corosync.conf.

-M

Import a signed certificate and export a certificate with private key into pk12 file.

-Q

Use ssh/scp to properly set both corosync-qnetd and corosync-qdevice certificates on all nodes. It's highly recommended that you use an ssh agent, or ssh/scp will keep asking for a password - roughly 8 times the number of nodes.

-c

File with certificate to load.

-n

Name of the cluster.

## SEE ALSO
corosync-qnetd(8) corosync-qdevice(8)

## AUTHOR
Jan Friesse


corosync-qdevice-tool

title: corosync-qdevice-tool(8)

summary: corosync-qdevice control interface.

text:
# corosync-qdevice-tool(8)

## NAME
corosync-qdevice-tool - corosync-qdevice control interface.

## SYNOPSIS
corosync-qdevice-tool [-Hhsv] [-p qdevice_ipc_socket_path]

## DESCRIPTION
corosync-qdevice-tool is a frontend to the internal corosync-qdevice IPC. Its main purpose is to show important information about the current internal state of corosync-qdevice.

## OPTIONS
-H

Properly shutdown the corosync-qdevice process

-h

Display a short usage text

-s

Display the status of the corosync-qdevice process. The output is described in its own section below.

-v

Display more verbose output for the -s option.

-p

Path to the corosync-qdevice communication socket.

## STATUS COMMAND OUTPUT

```
Qdevice information
-------------------
Model:                  Net
Node ID:                1
HB interval:            10000ms
Sync HB interval:       30000ms
Configured node list:

    0   Node ID = 1
Heuristics:             Enabled
Ring ID:                1.a00000000021b48
Membership node list:   1
Quorate:                Yes
Quorum node list:

    0   Node ID = 1, State = member
Expected votes:         2
Last poll call:         2016-06-24T17:05:20 (cast vote)
Qdevice-net information
----------------------
Cluster name:           Cluster
QNetd host:             localhost:5403
Connect timeout:        8000ms
HB interval:            8000ms
VQ vote timer interval: 5000ms
TLS:                    Supported
Algorithm:              Fifty-Fifty split
Tie-breaker:            Node with lowest node ID
KAP Tie-breaker:        Enabled
Poll timer running:     Yes (cast vote)
State:                  Connected
Heuristics result:      Pass (regular: Pass, membership: Fail, connect: Fail)
TLS active:             Yes (client certificate sent)
Connected since:        2016-06-24T17:02:35
Echo reply received:    2016-06-24T17:05:15
```

The output is split into a generic qdevice section and a model specific section. Most of the items are just taken from corosync.conf file. It's helpful to note that the Membership node list is the membership list of the current node and should match the quorum node list. Last poll call is the timestamp (in iso format) of the last call to the votequorum_qdevice_poll function.

For model net, it's good to check the Poll timer running state. Internally, model net supports 3 states. Not voting (when Poll timer running is No, which means corosync-qdevice is waiting for corosync-qnetd to reply), voting (without cast vote, it means that the corosync-qnetd algorithm decides that the current node shouldn't get a vote) and voting (with cast vote).

## SEE ALSO
corosync-qnetd(8) corosync-qdevice(8)

## AUTHOR
Jan Friesse


corosync-qnetd

package: corosync-qnetd

title: corosync-qnetd(8)

summary: QNet daemon

text:
# corosync-qnetd(8)

## NAME
corosync-qnetd - QNet daemon

## SYNOPSIS
corosync-qnetd [-46dfhv] [-l listen_addr] [-p listen_port] [-s tls] [-c client_cert_required] [-m max_clients] [-S option=value[,option2=value2,...]]"

## DESCRIPTION
corosync-qnetd is a daemon running outside of the cluster with the purpose of providing a vote to the corosync-qdevice model net. It's designed to support multiple clusters and be almost configuration and state free. New clusters are handled dynamically and no configuration file exists. It's also able to run as non-root user - which is recommended. Connection between the corosync-qdevice model net client can be optionally configured with TLS client certificate checking. The communication protocol between server and client is designed to be very simple and allow backwards compatibility.

## OPTIONS
-4

and its counterpart -6 are used to force IPv4 or IPv6 communication. The default is to listen on both address families.

-d

Turn on debug logging. By default the messages sent to syslog are purely operational, this option sends additional debug messages. For bumping syslog messages priority to info, use the -d parameter twice.

-f

Do not daemonize, run in the foreground.

-h

Show short help text

-v

Show version and supported communication protocol messages/options.

-l

IP address to listen on. By default the daemon listens on all addresses (wildcard).

-p

TCP port to listen on. Default port is 5403.

-s

Determines if TLS should be used and can be one of on/off/required (the default is on ). on means TLS is enabled but the client is not required to start TLS, off means TLS is completely disabled, and required means TLS is required. on and required require the NSS database to be properly initialized by running the corosync-qnetd-certutil command.

-c

can be set to on/off. This option only makes sense if TLS is enabled. When -c is on a client is required to send its client certificate (default).

-m

Maximum simultaneous clients. The default is 0 which means no limit.

-S

Set advanced settings described in its own section below. This option shouldn't be generally used because most of the options are not safe to change.

## UNPRIVILEGED USER CONFIGURATION
It's generally recommended to run corosync-qnetd as a non root user. If you get a package from a distribution its highly possible that the packager has done all the hard work for you. If the installation is performed from source code, a few steps have to be taken.

First it's necessary to create an unprivileged user/group. The following commands can be used (executed as root):

```
# groupadd -r coroqnetd
# useradd -r -g coroqnetd -d / -s /sbin/nologin -c "User for corosync-qnetd" coroqnetd
```

The next step is to set the correct owner and group on /etc/corosync/qnetd and /var/run/corosync-qnetd directories.

```
# chown -R coroqnetd:coroqnetd /etc/corosync/qnetd /var/run/corosync-qnetd
```

Some systems have the /var/run directory on a tmpfs file system which gets discarded after a reboot. The solution is to use an initscript or systemd unit, because both of them takes care of the /var/run/corosync-qnetd creation and sets the correct owner and permissions.

The last step is to make sure corosync-qnetd is really executed as an unprivileged user. For initscript systems it's enough to set the line COROSYNC_QNETD_RUNAS in /etc/(sysconfig|default)/corosync-qnetd file. If the file is not already installed then use the one provided in the corosync source code (init/corosync-qnetd.sysconfig.example). For systemd, overwrite/copy the corosync-qnetd.service unit file and uncomment/change the "User=" directive.

## TLS CONFIGURATION
For TLS to work its necessary to create the NSS database. If pcs is used then the following steps are not needed because pcs does them automatically.

corosync-qnetd-certutil is the tool to perform required actions. Just run:

```
# corosync-qnetd-certutil -i
```

If TLS is not required then simply edit /etc/(sysconfig|default)/corosync-qnetd or systemd unit file and add the parameter -s off in the proper place.

Depending on configuration of NSS (stored in nss.config file usually in /etc/crypto-policies/back-ends/ directory) disabled ciphers or too short keys may be rejected. Proper solution is to regenerate NSS databases for both corosync-qnetd and corosync-qdevice daemons. As a quick workaround it's also possible to set environment variable NSS_IGNORE_SYSTEM_POLICY=1 before running corosync-qnetd daemon.

When NSS is updated it may also be needed to upgrade database into new format. There is no consensus on recommended way, but following command seems to work just fine (if qnetd sysconfdir is set to /etc)

```
# certutil -N -d /etc/corosync/qnetd/nssdb -f /etc/corosync/qnetd/nssdb/pwdfile.txt
```

## ADVANCED SETTINGS
Set by the -S option. The default value is shown in parentheses.

listen_backlog

Parameter passed to the listen syscall on the network socket. (10)

max_client_send_buffers

Maximum number of send buffers for one client. (32)

max_client_send_size

Maximum size of one send buffer (message) to be sent to a client. (32768)

max_client_receive_size

Maximum size of the receive buffer for a client message (maximum allowed message size received by client). (32768)

nss_db_dir

NSS database directory. (/etc/corosync/qnetd/nssdb)

cert_nickname

NSS nickname of qnetd server certificate. (QNetd Cert)

heartbeat_interval_min

Minimum heartbeat timeout accepted by server in ms. (1000)

heartbeat_interval_max

Maximum heartbeat timeout accepted by server in ms. (120000)

dpd_enabled

Dead peer detection enabled. (on)

dpd_interval_coefficient

Value is multiplied with heartbeat interval sent by qdevice client and used as a timeout for dead peer detection. (1.5)

lock_file

Lock file location. (/var/run/corosync-qnetd/corosync-qnetd.pid)

local_socket_file

Internal IPC socket file location. (/var/run/corosync-qnetd/corosync-qnetd.sock)

local_socket_backlog

Parameter passed to listen syscall on the local socket. (10)

ipc_max_clients

Maximum allowed simultaneous IPC clients. (10)

ipc_max_receive_size

Maximum size of a message received by IPC client. (4096)

ipc_max_send_size

Maximum size of a message sent to an IPC client. (10485760)

keep_active_partition_tie_breaker

When tie happens prefer partition with members of previously active (quorate) partition. This is hard-coded behavior of LMS algorithm so this setting affects only FFSplit algorithm. (off)

## SEE ALSO
corosync-qnetd-tool(8) corosync-qnetd-certutil(8) corosync-qdevice(8)

## AUTHOR
Jan Friesse


corosync-qnetd-certutil

title: corosync-qnetd-certutil(8)

text:
# corosync-qnetd-certutil(8)

## NAME
corosync-qnetd-certutil - tool to generate qnetd TLS certificates

## SYNOPSIS
corosync-qnetd-certutil [-i|-s] [-c certificate] [-n cluster_name]

## DESCRIPTION
corosync-qnetd-certutil is a frontend for the NSS certutil, it is used for generating the QNetd CA (Certificate Authority), server certificate and signing cluster certificate used by corosync-qdevice when using the model 'net'.

## OPTIONS
-i

Initialize the QNetd NSS certificate database and generate the QNetd CA and server certificates. The default directory for the database is /etc/corosync/qnetd. This directory must be writeable by the current user. The QNetd CA certificate is also exported into the file /etc/corosync/qnetd/nssdb/qnetd-cacert.crt.

-s

Sign the cluster certificate. It is necessary to pass the cluster name (as configured in corosync.conf) and the certificate request file - see options below. The signed certificate will be written to the file /etc/corosync/qnetd/nssdb/cluster-$ClusterName.crt

-c

Certificate request file to sign.

-G

Do not set group write bit for new files. This option has effect only when used together with -i option. It is useful when extended security is needed and it's viable to prohibit daemon to change its configuration. Expected usage is to first set owner of the /etc/corosync/qnetd directory to root:$COROQNETD with permissions 0750 and then create database (as a root):

```
# corosync-qnetd-certutil -i -G
```

-n

Name of the cluster.

## NOTES
If qnetd is executed by a non root user, /etc/corosync/qnetd and its subdirectories must be owned by (or have group access for) the given user. If corosync-qnetd-certutil is executed as root it tries to copy the owner and group of /etc/corosync/qnetd to all of the created files.

## SEE ALSO
corosync-qnetd(8) corosync-qdevice(8)

## AUTHOR
Jan Friesse


corosync-qnetd-tool

title: corosync-qnetd-tool(8)

summary: corosync-qnetd control interface.

text:
# corosync-qnetd-tool(8)

## NAME
corosync-qnetd-tool - corosync-qnetd control interface.

## SYNOPSIS
corosync-qnetd-tool [-Hhlsv] [-c cluster_name] [-p qnetd_ipc_socket_path]

## DESCRIPTION
corosync-qnetd-tool is a frontend to the internal corosync-qnetd IPC. Its main purpose is to show important information about the current internal state of corosync-qnetd.

## OPTIONS
-H

Properly shutdown the corosync-qnetd process

-h

Display a short usage text

-l

List all clients connected to the corosync-qnetd process. The output is described in its own section below.

-s

Display status of the corosync-qnetd process.

-v

Display more verbose output for options -l and -s

-c

Used only with the -l option. By default, information about all clients from all clusters is displayed, with this option it's possible to filter information from a single cluster given the cluster_name.

-p

Path to the corosync-qnetd communication socket.

## LIST COMMAND OUTPUT

```
Cluster "Cluster":

    Algorithm:          Fifty-Fifty split (KAP Tie-breaker)

    Tie-breaker:        Node with lowest node ID

    Node ID 1:

        Client address:         ::ffff:127.0.0.1:52000

        HB interval:            8000ms

        Configured node list:   1, 2

        Ring ID:                1.a00000000021b40

        Membership node list:   1, 2

        TLS active:             Yes (client certificate verified)

        Vote:                   No change (ACK)

 ...
```

The output contains a list of clusters. Each cluster has the cluster common options Algorithm (optionally with Keep Active Partition Tie Breaker information) and Tie-breaker as configured in the corosync.conf file. Information about nodes follows. Client address is the IP address and port of the client. HB interval is the heartbeat interval between corosync-qnetd and corosync-qdevice client. This option can be configured in corosync.conf. Configured node list is the list of nodes configured in corosync.conf. Ring ID and Membership node list are self-explanatory. TLS active describes if an encrypted transport is used between server and client. Vote is last vote sent to corosync-qdevice client. The last ACK/NACK vote (if it exists) is in parentheses.

## SEE ALSO
corosync-qnetd(8) corosync-qdevice(8)

## AUTHOR
Jan Friesse


corosync-vqsim

package: corosync-vqsim

title: corosync-vqsim(8)

summary: The votequorum simulator

text:
# corosync-vqsim(8)

## NAME
corosync-vqsim - The votequorum simulator

## SYNOPSIS
corosync-vqsim [-c config_file] [-o output file] [-n] [-h]

## DESCRIPTION
corosync-vqsim simulates the quorum functions of corosync in a single program. it can simulate multiple nodes, network splits and a basic quorum device.

By default vqsim will build a virtual cluster of all the nodes in the corosync.conf file, each 'node' running in a forked subprocess (and thus asynchronously). It then provides a command-line interface to add (up) or remove (down) nodes, and cause network splits and rejoins. After each event it shows the new quorum status for all nodes.

Nodes in vqsim are always referred to by their nodeid (the IP address is meaningless) and optionally by a 'partition' which precedes the nodeid with a colon. By default all nodes are in partition 0. Nodes can be moved between partitions using the split and join commands. Multiple nodes can be split and joined at the same time.

To script vqsim you must send input to it via a pipe rather than just redirecting STDIN. This is because it runs asynchronously to enable the virtual 'nodes' to report status when needed. (eg if you kill a subprocess using the 'kill(1)' command it gets removed from the cluster).

By default vqsim will wait for all nodes in all partitions to reach the same ring sequence number before returning a prompt, there is a timeout associated with this in case of a 'node' failure and exceeding this timeout can (optionally) quit the program signalling an error.

You can disable waiting using the 'sync off' command or the -n command-line option. This can easily cause unexpected behaviour so use it with care.

The number of votes per node is read from corosync.conf. New nodes added using the 'up' command will copy their number of votes from the first node in corosync.conf. This may not be what you expect and I might fix it in future. As most clusters have only 1 vote per node (and this is strongly recommended) then this should rarely be a problem.

Once you have the 'vqsim> ' prompt you can type 'help' and get a list of sub-commands.

## OPTIONS
-c

This specifies the fully qualified path to the corosync configuration file. The default is /etc/corosync/corosync.conf.

-o

Specifies the output destination. STDOUT by default.

-n

Don't pause after each command, come straight back to a prompt. Use with care!

-h

Display a brief help message

## SEE ALSO
corosync(9), corosync.conf(5),

## AUTHOR
Christine Caulfield


makeuserdb

package: courier-authlib-userdb

title: makeuserdb(8)

summary: create /etc/courier-authlib/userdb

text:
# makeuserdb(8)

## NAME
makeuserdb - create /etc/courier-authlib/userdb

## SYNOPSIS
makeuserdb [-f filename]

pw2userdb

vchkpw2userdb [--vpopmailhome=dir] [--todir=dir]

## DESCRIPTION
makeuserdb creates /etc/courier-authlib/userdb.db from the contents of /etc/courier-authlib/userdb. /etc/courier-authlib/userdb's contents are described later in this document. Maildrop, Courier, and other applications use /etc/courier-authlib/userdb.db as a substitute/complement for your system password file. The usual purpose for /etc/courier-authlib/userdb.db is to specify "virtual" accounts - accounts that do not have an associated system login. Usually (but not necessarily) all virtual accounts share the same system userid. /etc/courier-authlib/userdb.db may also replace your system password file. Because the system password file is a text file, when there's a large number of accounts it will be significantly faster to search @userdb.db@, which is a binary database, instead of a flat text file that the system password file usually is.

The makeuserdb command can be safely executed during normal system activity.

The -f option creates filename.db from filename, instead of the default /etc/courier-authlib/userdb.db from /etc/courier-authlib/userdb.

### Format of /etc/courier-authlib/userdb
/etc/courier-authlib/userdb is a plain text file that can be created using any text editor. Blank lines are ignored. Lines that start with the # character are comments, and are also ignored. Other lines define properties of a single "account", one line per account. /etc/courier-authlib/userdb may be a directory instead of a plain file. In that case all files in /etc/courier-authlib/userdb are essentially concatenated, and are treated as a single file. Each line takes the following format:

```
name<TAB>field=value|field=value...
```

name is the account name. name MUST contain only lowercase characters If Courier is configured to treat lowercase and uppercase account names as identical, name is followed by exactly one tab character, then a list of field/value pairs separated by vertical slashes. field is the name of the field, value is the field value. Fields and values themself cannot contain slashes or control characters. Fields may be specified in any order. Here are all the currently defined fields. Note that not every field is used by every application that reads /etc/courier-authlib/userdb.db.

uid - value is a (possibly) unique numerical user ID for this account.

gid - value is a (possibly) unique numerical group ID for this account.

home - value is the account's home directory.

shell - value is the account's default login shell.

systempw - value is the account's password. See userdbpw(8)[1] for details on how to set up this field.

pop3pw, esmtppw, imappw... - value specifies a separate password used only for authenticating access using a specific service, such as POP3, IMAP, or anything else. If not defined, systempw is always used. This allows access to an account to be restricted only to certain services, such as POP3, even if other services are also enabled on the server.

mail - value specifies the location of the account's Maildir mailbox. This is an optional field that is normally used when userdb is used to provide aliases for other mail accounts. For example, one particular multi-domain E-mail service configuration that's used by both Qmail and Courier servers is to deliver mail for a mailbox in a virtual domain, such as "user@example.com", to a local mailbox called "example-user". Instead of requiring the E-mail account holder to log in as "example-user" to download mail from this account, a userdb entry for "user@example.com" is set up with mail set to the location of example-user's Maildir mailbox, thus hiding the internal mail configuration from the E-mail account holder's view.

quota - value specifies the maildir quota for the account's Maildir. This has nothing to do with actual filesystem quotas. Courier has a software-based Maildir quota enforcement mechanism which requires additional setup and configuration. See maildirquota(7)[2] for additional information.

### /etc/courier-authlib/userdbshadow.db
All fields whose name ends with 'pw' will NOT copied to /etc/courier-authlib/userdb.db. These fields will be copied to /etc/courier-authlib/userdbshadow.db. makeuserdb creates /etc/courier-authlib/userdbshadow.db without any group and world permissions. Note that makeuserdb reports an error if /etc/courier-authlib/userdb has any group or world permissions.

### CONVERTING /etc/passwd and vpopmail to /etc/courier-authlib/userdb format
pw2userdb reads the /etc/passwd and /etc/shadow files and converts all entries to the /etc/courier-authlib/userdb format, printing the result on standard output. The output of pw2userdb can be saved as /etc/courier-authlib/userdb (or as some file in this subdirectory). Linear searches of /etc/passwd can be very slow when you have tens of thousands of accounts. Programs like maildrop always look in /etc/courier-authlib/userdb first. By saving the system password file in /etc/courier-authlib/userdb it is possible to significantly reduce the amount of time it takes to look up this information.

After saving the output of pw2userdb, you must still run makeuserdb to create /etc/courier-authlib/userdb.db.

vchkpw2userdb converts a vpopmail-style directory hierarchy to the /etc/courier-authlib/userdb format. This is an external virtual domain management package that's often used with Qmail servers.

Generally, an account named 'vpopmail' is reserved for this purpose. In that account the file users/vpasswd has the same layout as /etc/passwd, and performs a similar function, except that all userid in users/vpasswd have the same userid. Additionally, the domains subdirectory stores virtual accounts for multiple domains. For example, domains/example.com/vpasswd has the passwd file for the domain example.com. Some systems also have a soft link, domains/default, that points to a domain that's considered a "default" domain.

The vchkpw2userdb reads all this information, and tries to convert it into the /etc/courier-authlib/userdb format. The --vpopmailhost option specifies the top level directory, if it is not the home directory of the vpopmail account.

The vchkpw2userdb script prints the results on standard output. If specified, the --todir option tries to convert all vpasswd files one at a time, saving each one individually in dir. For example:

```
mkdir /etc/courier-authlib/userdb
vchkpw2userdb --todir=/etc/courier-authlib/userdb/vpopmail
makeuserdb
```

It is still necessary to run makeuserdb, of course, to create the binary database file /etc/courier-authlib/userdb.db

NOTE: You are still required to create the /etc/courier-authlib/userdb entry which maps system userids back to accounts, "uid=<TAB>name", if that's applicable. vchkpw2userdb will not do it for you.

NOTE: makeuserdb may complain about duplicate entries, if your "default" entries in users/vpasswd or domains/default/vpasswd are the same as anything in any other /etc/courier-authlib/userdb file. It is also likely that you'll end up with duplicate, but distinct, entries for every account in the default domain. For example, if your default domain is example.com, you'll end up with duplicate entries - you'll have entries for both user and user@example.com.

If you intend to maintain the master set of accounts using vchkpw/vpopmail, in order to avoid cleaning this up every time, you might want to consider doing the following: run vchkpw2userdb once, using the --todir option. Then, go into the resulting directory, and replace one of the redundant files with a soft link to /dev/null. This allows you to run vchkpw2userdb without having to go in and cleaning up again, afterwards.

## FILES

```
/etc/courier-authlib/userdb
/etc/courier-authlib/userdb.db
/etc/courier-authlib/userdbshadow.db
/etc/courier-authlib/userdb.tmp - temporary file
/etc/courier-authlib/userdbshadow.tmp - temporary file
```

## BUGS
makeuserdb is a Perl script, and uses Perl's portable locking. Perl's documentation notes that certain combinations of locking options may not work with some networks.

## SEE ALSO
userdb(8)[3], maildrop(8)[4], courier(8)[5], maildirquota(7)[2].

## NOTES
1.

userdbpw(8)

[set $man.base.url.for.relative.links]/userdbpw.html

2.

maildirquota(7)

[set $man.base.url.for.relative.links]/maildirquota.html

3.

userdb(8)

[set $man.base.url.for.relative.links]/userdb.html

4.

maildrop(8)

[set $man.base.url.for.relative.links]/maildrop.html

5.

courier(8)

[set $man.base.url.for.relative.links]/courier.html


userdb

title: userdb(8)

summary: manipulate /etc/courier-authlib/userdb

text:
# userdb(8)

## NAME
userdb - manipulate /etc/courier-authlib/userdb

## SYNOPSIS
userdb {addr} set {field=value...}

userdb {addr} unset {field...}

userdb {addr} del

userdb {path/addr} [set | unset | del] ...

userdb -f {file} {adr} [set | unset | del] ...

userdb -show {path}

userdb -show {path} {addr}

userdb -show -f {file}

userdb -show -f {file} {addr}

## DESCRIPTION
userdb is a convenient script to individually manipulate entries in /etc/courier-authlib/userdb. See makeuserdb(8)[1] for a description of its contents. /etc/courier-authlib/userdb can always be edited using any text editor, but userdb is a convenient way to modify this file from another script.

/etc/courier-authlib/userdb can also be a subdirectory, instead of a file. Specify foo/bar/addr to manipulate addr in the file /etc/courier-authlib/userdb/foo/bar. You can also use the -f flag: -f /etc/courier-authlib/userdb/foo/bar is equivalent. Use whatever form makes the most sense to you.

/etc/courier-authlib/userdb must not have any group or world permissions. That's because its contents may include system passwords (depending upon the application which uses this virtual user account database).

Each line in /etc/courier-authlib/userdb takes following form:

addr<TAB>field=value|field=value...

addr specifies a unique virtual address. It is followed by a single tab character, then a list of field=value pairs, separated by vertical slash characters. See makeuserdb(8)[1] for field definitions.

A text editor can be used to add blank lines or comments in /etc/courier-authlib/userdb. Any blank lines or comments are ignored by the userdb script.

The names of the actual fields, and their contents, are defined entirely by applications that use the /etc/courier-authlib/userdb database, the userdb command just adds or removes arbitrary fields.

For example:

```
userdb default/info set mail=/home/mail/info
```

This command accesses the address "info" in /etc/courier-authlib/userdb/default.

If the second argument to userdb is "set", the remaining arguments are taken as field=value pairs, which are added to the record for addr. If there is no record for addr, a new record will be appended to the file. If addr exists, any existing values of any specified fields are removed. If =value is missing, userdb stops and prompts for it. This is useful if you're setting a password field, where you do not want to specify the password on the command line, which can be seen by the ps(1) command. If userdb is being executed by a script, the value can be provided on standard input.

Use "unset" to delete fields from an existing record. Use "del" to delete all fields in the existing record, plus the record itself.

### DISPLAYING /etc/courier-authlib/userdb
If the first argument to userdb is -show, userdb displays the contents of /etc/courier-authlib/userdb. If /etc/courier-authlib/userdb is a subdirectory, path must refer to a specific file in /etc/courier-authlib/userdb. The -f option can be used instead of path in order to specify an arbitrary file.

If addr is not specified, userdb produces a list, on standard output, containing all addresses found in the file, on per line. If addr is specified, userdb produces a list, on standard output, of all the fields in /etc/courier-authlib/userdb for this addr.

### International domains
addrs with international domains should use UTF-8 to specify an international domain name:

```
userdb postmaster@test.испытание set \

        home=/home/postmaster.test.com uid=999 gid=999
```

### REBUILDING /etc/courier-authlib/userdb.db
The actual virtual account/address database is /etc/courier-authlib/userdb.db. This is a binary database file. /etc/courier-authlib/userdb is the plain text version. After running userdb, execute the makeuserdb(8)[1] command to rebuild /etc/courier-authlib/userdb.db for the changes to take effect.

## BUGS
addr must be unique. If /etc/courier-authlib/userdb is a subdirectory, it's possible to create the same addr in different files in the subdirectory. This is an error that is not currently detected by userdb, however the subsequent makeuserdb(8)[1] command will fail with an error message.

## FILES
/etc/courier-authlib/userdb - plain text file, or directory of plain text files

.lock.filename - lock file for filename

.tmp.filename - temporary file used to create new contents of filename

## SEE ALSO
makeuserdb(8)[1], userdbpw(8)[2]

## NOTES
1.

makeuserdb(8)

[set $man.base.url.for.relative.links]/makeuserdb.html

2.

userdbpw(8)

[set $man.base.url.for.relative.links]/userdbpw.html


userdbpw

title: userdbpw(8)

summary: create an encrypted password

text:
# userdbpw(8)

## NAME
userdbpw - create an encrypted password

## SYNOPSIS
userdbpw [[-md5] | [-hmac-md5] | [-hmac-sha1]] |userdb {name} set {field}

## DESCRIPTION
userdbpw enables secure entry of encrypted passwords into /etc/courier-authlib/userdb.

userdbpw reads a single line of text on standard input, encrypts it, and prints the encrypted result to standard output.

If standard input is attached to a terminal device, userdbpw explicitly issues a "Password: " prompt on standard error, and turns off echo while the password is entered.

The -md5 option is available on systems that use MD5-hashed passwords (such as systems that use the current version of the PAM library for authenticating, with MD5 passwords enabled). This option creates an MD5 password hash, instead of using the traditional crypt() function.

-hmac-md5 and -hmac-sha1 options are available only if the userdb library is installed by an application that uses a challenge/response authentication mechanism. -hmac-md5 creates an intermediate HMAC context using the MD5 hash function. -hmac-sha1 uses the SHA1 hash function instead. Whether either HMAC function is actually available depends on the actual application that installs the userdb library.

Note that even though the result of HMAC hashing looks like an encrypted password, it's really not. HMAC-based challenge/response authentication mechanisms require the cleartext password to be available as cleartext. Computing an intermediate HMAC context does scramble the cleartext password, however if its compromised, it WILL be possible for an attacker to succesfully authenticate. Therefore, applications that use challenge/response authentication will store intermediate HMAC contexts in the "pw" fields in the userdb database, which will be compiled into the userdbshadow.db database, which has group and world permissions turned off. The userdb library also requires that the cleartext userdb source for the userdb.db and userdbshadow.db databases is also stored with the group and world permissions turned off.

userdbpw is usually used together in a pipe with userdb, which reads from standard input. For example:

```
userdbpw -md5 | userdb users/john set systempw
```

or:

```
userdbpw -hmac-md5 | userdb users/john set hmac-md5pw
```

These commands set the systempw field in the record for the user john in /etc/courier-authlib/userdb/users file, and the hmac-md5pw field. Don't forget to run makeuserdb for the change to take effect.

The following command does the same thing:

```
userdb users/john set systempw=SECRETPASSWORD
```

However, this command passes the secret password as an argument to the userdb command, which can be viewed by anyone who happens to run ps(1) at the same time. Using userdbpw allows the secret password to be specified in a way that cannot be easily viewed by ps(1).

## SEE ALSO
userdb(8)[1], makeuserdb(8)[2]

## NOTES
1.

userdb(8)

[set $man.base.url.for.relative.links]/userdb.html

2.

makeuserdb(8)

[set $man.base.url.for.relative.links]/makeuserdb.html