corosync.conf

package: corosync

title: corosync.conf(5)

text:
# corosync.conf(5)

## NAME
corosync.conf - corosync executive configuration file

## SYNOPSIS
/etc/corosync/corosync.conf

## DESCRIPTION
The corosync.conf instructs the corosync executive about various parameters needed to control the corosync executive. Empty lines and lines starting with # character are ignored. The configuration file consists of bracketed top level directives. The possible directive choices are:

totem { }

This top level directive contains configuration options for the totem protocol.

logging { }

This top level directive contains configuration options for logging.

quorum { }

This top level directive contains configuration options for quorum.

nodelist { }

This top level directive contains configuration options for nodes in cluster.

system { }

This top level directive contains configuration options related to system.

resources { }

This top level directive contains configuration options for resources.

nozzle { }

This top level directive contains configuration options for a libnozzle device.

Corosync supports multiple types of network transports for communication between the nodes in the cluster. There are three types of transports:

1.

KNET. This is a default and recommended transport introduced in Corosync 3. It provides several advantages over the UDP and UDPU transports, including better performance, link-level redundancy, automatic link recovery, and native IP compression and encryption.

2.

UDPU. This is for unicast communication. This transport is deprecated.

3.

UDP. This is for multicast communication. This transport is deprecated and highly discouraged to use.

The interface sub-directive of totem is optional for UDP and KNET transports.

For KNET, multiple interface subsections define parameters for each KNET link on the system.

For UDPU an interface section is not needed and it is recommended that the nodelist is used to define cluster nodes.

linknumber

This specifies the link number for the interface. When using the KNET protocol, each interface should specify separate link numbers to uniquely identify to the membership protocol which interface to use for which link. The linknumber must start at 0. For UDP the only supported linknumber is 0.

knet_link_priority

This specifies the priority for the link when KNET is used in 'passive' mode. (see link_mode below)

knet_ping_interval

This specifies the interval between KNET link pings. knet_ping_interval and knet_ping_timeout are a pair, if one is specified the other should be too, otherwise one will be calculated from the token timeout and one will be taken from the config file. (default is token timeout / (knet_pong_count*2))

knet_ping_timeout

If no ping is received within this time, the KNET link is declared dead. knet_ping_interval and knet_ping_timeout are a pair, if one is specified the other should be too, otherwise one will be calculated from the token timeout and one will be taken from the config file. (default is token timeout / knet_pong_count)

knet_ping_precision

How many values of latency are used to calculate the average link latency. (default 2048 samples)

knet_pong_count

How many valid ping/pongs before a link is marked UP. (default 2)

knet_transport

Which IP transport KNET should use. valid values are "udp" (or "sctp" if supported by the installed version of kronosnet). (default: udp) NOTE: even if currently included, sctp is deprecated and will be removed in kronoset v2.0

bindnetaddr (UDP only)

This specifies the network address the corosync executive should bind to when using UDP transport. bindnetaddr (UDP only) should be an IP address configured on the system, or a network address.

For example, if the local interface is 192.168.5.92 with netmask 255.255.255.0, you should set bindnetaddr to 192.168.5.92 or 192.168.5.0. If the local interface is 192.168.5.92 with netmask 255.255.255.192, set bindnetaddr to 192.168.5.92 or 192.168.5.64, and so forth.

This may also be an IPV6 address, in which case IPV6 networking will be used. In this case, the exact address must be specified and there is no automatic selection of the network interface within a specific subnet as with IPv4.

If IPv6 networking is used, the nodeid field in nodelist must be specified.

broadcast (UDP only)

This is optional and can be set to yes. If it is set to yes, the broadcast address will be used for communication. If this option is set, mcastaddr should not be set.

mcastaddr (UDP only)

This is the multicast address used by corosync executive. The default should work for most networks, but the network administrator should be queried about a multicast address to use. Avoid 224.x.x.x because this is a "config" multicast address. This may also be an IPV6 multicast address, in which case IPV6 networking will be used. If IPv6 networking is used, the nodeid field in nodelist must be specified.

It's not necessary to use this option if cluster_name option is used. If both options are used, mcastaddr has higher priority.

mcastport

This specifies the UDP port number. Exact meaning depends on used transport. For the KNET transport, it is used as both the binding and sending port. For additional links, the default value is computed as (mcastport + linknumber).

For the UDPU transport, mcastport specifies the bind port. Corosync also allocates and binds a random sending port for each remote node.

For the UDP transport, it is used as a bind port for mcastaddr. It is possible to use the same multicast address on a network with the corosync services configured for different UDP ports. Please note corosync uses two UDP ports mcastport (for mcast receives) and mcastport - 1 (for mcast sends). If you have multiple clusters on the same network using the same mcastaddr please configure the mcastports with a gap.

The default is 5405.

ttl (UDP only)

This specifies the Time To Live (TTL). If you run your cluster on a routed network then the default of "1" will be too small. This option provides a way to increase this up to 255. The valid range is 0..255.

Within the totem directive, there are seven configuration options of which one is required, five are optional, and one is required when IPV6 is configured in the interface subdirective. The required directive controls the version of the totem configuration. The optional option unless using IPV6 directive controls identification of the processor. The optional options control secrecy and authentication, the network mode of operation and maximum network MTU field.

version

This specifies the version of the configuration file. Currently the only valid version for this directive is 2.

clear_node_high_bit

This configuration option is optional and is only relevant when no nodeid is specified. Some corosync clients require a signed 32 bit nodeid that is greater than zero however by default corosync uses all 32 bits of the IPv4 address space when generating a nodeid. Set this option to yes to force the high bit to be zero and therefore ensure the nodeid is a positive signed 32 bit integer. WARNING: Cluster behavior is undefined if this option is enabled on only a subset of the cluster (for example during a rolling upgrade).

crypto_model

This specifies which cryptographic library should be used by KNET. Supported values depend on the libknet build and on the installed cryptography libraries. Typically nss and openssl will be available but gcrypt and others could also be allowed. The default is nss.

crypto_hash

This specifies which HMAC authentication should be used to authenticate all messages. Valid values are none (no authentication), md5, sha1, sha256, sha384 and sha512. Encrypted transmission is only supported for the KNET transport. The default is none.

crypto_cipher

This specifies which cipher should be used to encrypt all messages. Valid values are none (no encryption), aes256, aes192 and aes128. Enabling crypto_cipher, requires also enabling of crypto_hash. Encrypted transmission is only supported for the KNET transport. The default is none.

secauth

This implies crypto_cipher=aes256 and crypto_hash=sha256, unless those options are explicitly set. Encrypted transmission is only supported for the KNET transport. The default is off.

keyfile

This specifies the fully qualified path to the shared key used to authenticate and encrypt data used within the Totem protocol. The default is /etc/corosync/authkey.

key

Shared key stored in configuration instead of authkey file. This option has lower precedence than keyfile option so it's used only when keyfile is not specified. Using this option is not recommended for security reasons.

link_mode

This specifies the Kronosnet mode, which may be passive, active, or rr (round-robin). passive: the active link with the highest priority (highest number) will be used. If one or more links share the same priority the one with the lowest link ID will be used. active: All active links will be used simultaneously to send traffic. link priority is ignored. rr: Round-Robin policy. Each packet will be sent to the next active link in order. If only one interface directive is specified, passive is automatically chosen.

The maximum number of interface directives that is allowed with Kronosnet is 8. For other transports it is 1.

netmtu

This specifies maximum packet length sent by corosync. It's mainly for the UDPU (and UDP) transport, where it specifies the network maximum transmit size, but can be used also with the KNET transport, where it defines the maximum length of packets passed to the KNET layer. To specify the network MTU manually for KNET, use the knet_mtu option. For UDPU (and UDP), setting this value beyond 1500, the regular frame MTU, requires ethernet devices that support large, or also called jumbo, frames. If any device in the network doesn't support large frames, the protocol will not operate properly. The hosts must also have their mtu size set from 1500 to whatever frame size is specified here.

Please note while some NICs or switches claim large frame support, they support 9000 MTU as the maximum frame size including the IP header. Setting the netmtu and host MTUs to 9000 will cause totem to use the full 9000 bytes of the frame. Then Linux will add a 18 byte header moving the full frame size to 9018. As a result some hardware will not operate properly with this size of data. A netmtu of 8982 seems to work for the few large frame devices that have been tested. Some manufacturers claim large frame support when in fact they support frame sizes of 4500 bytes.

When sending multicast traffic, if the network frequently reconfigures, chances are that some device in the network doesn't support large frames.

Choose hardware carefully if intending to use large frame support.

The default is 1500 for UDPU (and UDP) and 65536 for the KNET transport.

transport

This directive controls the transport mechanism used. The default is knet (for KNET). The transport type can also be set to udpu (for UDPU) or udp (for UDP). Only KNET allows crypto or multiple interfaces per node.

cluster_name

This specifies the name of cluster and it's used for automatic generating of multicast address.

config_version

This specifies version of config file. This is converted to unsigned 64-bit int. By default it's 0. Option is used to prevent joining old nodes with not up-to-date configuration. If value is not 0, and node is going for first time (only for first time, join after split doesn't follow this rules) from single-node membership to multiple nodes membership, other nodes config_versions are collected. If current node config_version is not equal to highest of collected versions, corosync is terminated.

ip_version

This specifies version of IP to ask DNS resolver for. The value can be one of ipv4 (look only for an IPv4 address) , ipv6 (check only IPv6 address) , ipv4-6 (look for all address families and use first IPv4 address found in the list if there is such address, otherwise use first IPv6 address) and ipv6-4 (look for all address families and use first IPv6 address found in the list if there is such address, otherwise use first IPv4 address). Default (if unspecified) is ipv6-4 for KNET and UDPU transports and ipv4 for UDP transport.

The KNET transport supports IPv4 and IPv6 addresses concurrently, provided they are consistent on each link.

ip_dscp

This specifies the dscp (differentiated services code point) value to be used in the IP header's type of service (TOS) field according to RFC 2474. Allowed values are 0-63 and symbolic dscp names cs0, cs1, cs2, cs3, cs4, cs5, cs6, cs7, af11, af12, af13, af21, af22, af23, af31, af32, af33, af41, af42, af43 and ef. Value 0 disables the dscp support. Use of TOS field then depends on the used transport. If ip_dscp is set to a value not equal to zero, and an appropriate socket option (IP_TOS) is available, the value is put into the upper six bits of the TOS header field.

Within the totem directive, there are several configuration options which are used to control the operation of the protocol. It is generally not recommended to change any of these values without proper guidance and sufficient testing. Some networks may require larger values if suffering from frequent reconfigurations. Some applications may require faster failure detection times which can be achieved by reducing the token timeout.

token

This timeout is used directly or as a base for real token timeout calculation (explained in token_coefficient section). Token timeout specifies in milliseconds until a token loss is declared after not receiving a token. This is the time spent detecting a failure of a processor in the current configuration. Reforming a new configuration takes about 50 milliseconds in addition to this timeout. For real token timeout used by totem it's possible to read cmap value of runtime.config.totem.token key.

Be careful to use the same timeout values on each of the nodes in the cluster or unpredictable results may occur.

The default is 3000 milliseconds.

token_warning

Specifies the interval between warnings that the token has not been received. The value is a percentage of the token timeout and can be set to 0 to disable warnings. The default is 75%.

token_coefficient

This value is used only when nodelist section is specified and contains at least 3 nodes. If so, real token timeout is then computed as token + (number_of_nodes - 2) * token_coefficient. This allows cluster to scale without manually changing token timeout every time new node is added. This value can be set to 0 resulting in effective removal of this feature. The default is 650 milliseconds.

token_retransmit

This timeout specifies in milliseconds after how long before receiving a token the token is retransmitted. This will be automatically calculated if token is modified. It is not recommended to alter this value without guidance from the corosync community. The minimum is 30 milliseconds. If not set and error occur, make sure token / (token_retransmits_before_loss_const + 0.2) is more than 30.

The default is 238 milliseconds for two nodes cluster. Three or more nodes reference token_coefficient.

knet_compression_model

Type of compression used by Kronosnet. Supported values depend on the libknet build and on the installed compression libraries. Typically zlib and lz4 will be available but bzip2 and others could also be allowed. The default is 'none'.

knet_compression_threshold

Tells KNET to NOT compress any packets that are smaller than the value indicated. Default 100 bytes. Set to 0 to reset to the default. Set to 1 to compress everything.

knet_compression_level

Many compression libraries allow tuning of compression parameters. For example 0 or 1 ... 9 are commonly used to determine the level of compression. This value is passed unmodified to the compression library so it is recommended to consult the library's documentation for more detailed information.

hold

This timeout specifies in milliseconds how long the token should be held by the representative when the protocol is under low utilization. It is not recommended to alter this value without guidance from the corosync community. The default is 180 milliseconds.

token_retransmits_before_loss_const

This value identifies how many token retransmits should be attempted before forming a new configuration. It is also used for token_retransmit and hold calculations. The default is 4 retransmissions.

join

This timeout specifies in milliseconds how long to wait for join messages in the membership protocol. The default is 50 milliseconds.

send_join

This timeout specifies in milliseconds an upper range between 0 and send_join to wait before sending a join message. For configurations with less than 32 nodes, this parameter is not necessary. For larger rings, this parameter is necessary to ensure the NIC is not overflowed with join messages on formation of a new ring. A reasonable value for large rings (128 nodes) would be 80msec. Other timer values must also change if this value is changed. Seek advice from the corosync mailing list if trying to run larger configurations. The default is 0 milliseconds.

consensus

This timeout specifies in milliseconds how long to wait for consensus to be achieved before starting a new round of membership configuration. The minimum value for consensus must be 1.2 * token. This value will be automatically calculated at 1.2 * token if the user doesn't specify a consensus value. For two node clusters, a consensus larger than the join timeout but less than token is safe. For three node or larger clusters, consensus should be larger than token. There is an increasing risk of odd membership changes, which still guarantee virtual synchrony, as node count grows if consensus is less than token.

The default is 3600 milliseconds.

merge

This timeout specifies in milliseconds how long to wait before checking for a partition when no multicast traffic is being sent. If multicast traffic is being sent, the merge detection happens automatically as a function of the protocol. The default is 200 milliseconds.

downcheck

This timeout specifies in milliseconds how long to wait before checking that a network interface is back up after it has been downed. The default is 1000 milliseconds.

fail_recv_const

This constant specifies how many rotations of the token without receiving any of the messages when messages should be received may occur before a new configuration is formed. The default is 2500 failures to receive a message.

seqno_unchanged_const

This constant specifies how many rotations of the token without any multicast traffic should occur before the hold timer is started. The default is 30 rotations.

heartbeat_failures_allowed

[HeartBeating mechanism] Configures the optional HeartBeating mechanism for faster failure detection. Keep in mind that engaging this mechanism in lossy networks could cause faulty loss declaration as the mechanism relies on the network for heartbeating. So as a rule of thumb use this mechanism if you require improved failure in low to medium utilized networks.

This constant specifies the number of heartbeat failures the system should tolerate before declaring heartbeat failure e.g 3. Also if this value is not set or is 0 then the heartbeat mechanism is not engaged in the system and token rotation is the method of failure detection

The default is 0 (disabled).

max_network_delay

[HeartBeating mechanism] This constant specifies in milliseconds the approximate delay that your network takes to transport one packet from one machine to another. This value is to be set by system engineers and please don't change if not sure as this effects the failure detection mechanism using heartbeat. The default is 50 milliseconds.

window_size

This constant specifies the maximum number of messages that may be sent on one token rotation. If all processors perform equally well, this value could be large (300), which would introduce higher latency from origination to delivery for very large rings. To reduce latency in large rings(16+), the defaults are a safe compromise. If 1 or more slow processor(s) are present among fast processors, window_size should be no larger than 256000 / netmtu to avoid overflow of the kernel receive buffers. The user is notified of this by the display of a retransmit list in the notification logs. There is no loss of data, but performance is reduced when these errors occur. The default is 50 messages.

max_messages

This constant specifies the maximum number of messages that may be sent by one processor on receipt of the token. The max_messages parameter is limited to 256000 / netmtu to prevent overflow of the kernel transmit buffers. The default is 17 messages.

miss_count_const

This constant defines the maximum number of times on receipt of a token a message is checked for retransmission before a retransmission occurs. This parameter is useful to modify for switches that delay multicast packets compared to unicast packets. The default setting works well for nearly all modern switches. The default is 5 messages.

knet_pmtud_interval

How often the KNET PMTUd runs to look for network MTU changes. Value in seconds, default: 30

knet_mtu

Switch between manual and automatic MTU discovery. A value of 0 means automatic, other values set a manual MTU. In a setup with multiple interfaces, please specify the lowest MTU of the selected interfaces. The default value is 0.

block_unlisted_ips

Allow UDPU and KNET to drop packets from IP addresses that are not known (nodes which don't exist in the nodelist) to corosync. Value is yes or no. This feature is mainly to protect against the joining of nodes with outdated configurations after a cluster split. Another use case is to allow the atomic merge of two independent clusters.

Changing the default value is not recommended, the overhead is tiny and an existing cluster may fail if corosync is started on an unlisted node with an old configuration.

The default value is yes.

cancel_token_hold_on_retransmit

Allows Corosync to hold token by representative when there is too much retransmit messages. This allows network to process increased load without overloading it. Used mechanism is same as described for hold directive. Some deployments may prefer to never hold token when there is retransmit messages. If so, option should be set to yes.

The default value is no.

Within the logging directive, there are several configuration options which are all optional.

The following 3 options are valid only for the top level logging directive:

timestamp

This specifies that a timestamp is placed on all log messages. It can be one of off (no timestamp), on (second precision timestamp) or hires (millisecond precision timestamp - only when supported by LibQB). The default is hires (or on if hires is not supported).

fileline

This specifies that file and line should be printed. The default is off.

function_name

This specifies that the code function name should be printed. The default is off.

blackbox

This specifies that blackbox functionality should be enabled. The default is on.

The following options are valid both for top level logging directive and they can be overridden in logger_subsys entries.

to_stderr

to_logfile

to_syslog

These specify the destination of logging output. Any combination of these options may be specified. Valid options are yes and no. The default is syslog and stderr.

Please note, if you are using to_logfile and want to rotate the file, use logrotate(8) with the option copytruncate. eg.

```
/var/log/corosync.log {
	missingok
	compress
	notifempty
	daily
	rotate 7
	copytruncate
}
```

logfile

If the to_logfile directive is set to yes , this option specifies the pathname of the log file. No default.

logfile_priority

This specifies the logfile priority for this particular subsystem. Ignored if debug is on. Possible values are: alert, crit, debug (same as debug = on), emerg, err, info, notice, warning. The default is: info.

syslog_facility

This specifies the syslog facility type that will be used for any messages sent to syslog. options are daemon, local0, local1, local2, local3, local4, local5, local6 & local7. The default is daemon.

syslog_priority

This specifies the syslog level for this particular subsystem. Ignored if debug is on. Possible values are: alert, crit, debug (same as debug = on), emerg, err, info, notice, warning. The default is: info.

debug

This specifies whether debug output is logged for this particular logger. Also can contain value trace, what is highest level of debug information. The default is off.

Within the logging directive, logger_subsys directives are optional.

Within the logger_subsys sub-directive, all of the above logging configuration options are valid and can be used to override the default settings. The subsys entry, described below, is mandatory to identify the subsystem.

subsys

This specifies the subsystem identity (name) for which logging is specified. This is the name used by a service in the log_init() call. E.g. 'CPG'. This directive is required.

Within the quorum directive it is possible to specify the quorum configuration options. The following option is required to activate quorum service:

provider

This specifies algorithm to use. At the time of writing only corosync_votequorum is supported. See votequorum(5) for configuration options.

Within the nodelist directive it is possible to specify specific information about nodes in cluster. Directive can contain only node sub-directive, which specifies every node that should be a member of the membership, and where non-default options are needed. Every node must have at least ring0_addr field filled.

Every node that should be a member of the membership must be specified.

Possible options are:

ringX_addr

This specifies IP or network hostname address of the particular node. X is a link number.

nodeid

This configuration option is required for each node for Kronosnet mode. It is a 32 bit value specifying the node identifier delivered to the cluster membership service. The node identifier value of zero is reserved and should not be used. If KNET is set, this field must be set.

name

This option is used mainly with KNET transport to identify local node. It's also used by client software (pacemaker). Algorithm for identifying local node is following:

1.

Looks up $HOSTNAME in the nodelist

2.

If this fails strip the domain name from $HOSTNAME and looks up that in the nodelist

3.

If this fails look in the nodelist for a fully-qualified name whose short version matches the short version of $HOSTNAME

4.

If all this fails then search the interfaces list for an address that matches a name in the nodelist

Within the system directive it is possible to specify system options.

Possible options are:

qb_ipc_type

This specifies type of IPC to use. Can be one of native (default), shm and socket. Native means one of shm or socket, depending on what is supported by OS. On systems with support for both, SHM is selected. SHM is generally faster, but need to allocate ring buffer file in /dev/shm.

sched_rr

Should be set to yes (default) if corosync should try to set round robin realtime scheduling with maximal priority to itself. When setting of scheduler fails, fallback to set maximal priority.

priority

Set priority of corosync process. Valid only when sched_rr is set to no. Can be ether numeric value with similar meaning as nice(1) or max / min meaning maximal / minimal priority (so minimal / maximal nice value).

move_to_root_cgroup

Can be one of yes (Corosync always moves itself to root cgroup), no (Corosync never tries to move itself to root cgroup) or auto (Corosync first checks if sched_rr is enabled, and if so, it tries to set round robin realtime scheduling with maximal priority to itself. If setting of priority fails, corosync tries to move itself to root cgroup and retries setting of priority). This feature is available only for systems with cgroups v1 with RT sched enabled (Linux with CONFIG_RT_GROUP_SCHED kernel option) and cgroups v2.

It's worth noting that currently (May 3 2021) cgroup2 doesn’t yet support control of realtime processes and the cpu controller can only be enabled when all RT processes are in the root cgroup (applies only for kernel with CONFIG_RT_GROUP_SCHED enabled). So when move_to_root_cgroup is disabled, kernel is compiled with CONFIG_RT_GROUP_SCHED and systemd is used, it may be impossible to make systemd options like CPUQuota working correctly until corosync is stopped.

Also when moving to root cgroup is enforced and used together with cgroup2 and systemd it makes impossible (most of the time) for journald to add systemd specific metadata (most importantly _SYSTEMD_UNIT) properly, because corosync is moved out of cgroup created by systemd. This means it is not possible to filter corosync logged messages based on these metadata (for example using -u or _SYSTEMD_UNIT=UNIT pattern) and also running systemctl status doesn't display (all) corosync log messages. The problem is even worse because journald caches pid for some time (approx. 5 sec) so initial corosync messages have correct metadata.

allow_knet_handle_fallback

If KNET handle creation fails using privileged operations, allow fallback to creating KNET handle using unprivileged operations. Defaults to no, meaning if privileged KNET handle creation fails, corosync will refuse to start. The KNET handle will always be created using privileged operations if possible, setting this to yes only allows fallback to unprivileged operations. This fallback may result in performance issues, but if running in an unprivileged environment, e.g. as a normal user or in unprivileged container, this may be required.

state_dir

Existing directory where corosync should chdir into. Corosync stores important state files and blackboxes there. The default is the value of the environment variable STATE_DIRECTORY or /var/lib/corosync.

Within the resources directive it is possible to specify options for resources.

Possible option is:

watchdog_device

(Valid only if Corosync was compiled with watchdog support.)

Watchdog device to use, for example /dev/watchdog. If unset, empty or "off", no watchdog is used.

In a cluster with properly configured power fencing a watchdog provides no additional value. On the other hand, slow watchdog communication may incur multi-second delays in the Corosync main loop, potentially breaking down membership. IPMI watchdogs are particularly notorious in this regard: read about kipmid_max_busy_us in IPMI.txt in the Linux kernel documentation.

Within the nozzle directive it is possible to specify options for a libnozzle device. This is a pseudo ethernet device that routes network traffic through a channel on the corosync KNET network (NOT cpg or any corosync internal service) to other nodes in the cluster. This allows applications to take advantage of KNET features such as multipathing, automatic failover, link switching etc. Note that libnozzle is not a reliable transport, but you can tunnel TCP through it for reliable communications.

libnozzle also supports optional interface up/down scripts that are kept under a /etc/corosync/updown.d/ directory. See the KNET documentation for more information.

Only one nozzle device is allowed.

The nozzle stanza takes several options:

name

The name of the network device to be created. On Linux this may be any name at all, other platforms have restrictions on the name.

ipaddr

The IP address (IPv6 or IPv4) of the interface. The bottom part of this address will be replaced by the local node's nodeid in conjunction with ipprefix. so, eg ipaddr: 192.168.1.0 ipprefix: 24 will make nodeids 1,2,5 use IP addresses 192.168.1.1, 192.168.1.2 & 192.168.1.5. If a prefix length of 16 is used then the bottom two bytes will be filled in with nodeid numbers. IPv6 addresses must end in '::', the nodeid will be added after the two colons to make the local IP address. Only one IP address is currently supported in the corosync.conf file. Additional IP addresses can be added in the ifup script if necessary.

ipprefix

specifies the IP address prefix for the nozzle device (see above)

macaddr

Specifies the MAC address prefix for the nozzle device. As for the IP address, the bottom part of the MAC address will be filled in with the node id. In this case no prefix applies, the bottom two bytes of the MAC address will always be overwritten with the node id. So specifying macaddr: 54:54:12:24:12:12 on nodeid 1 will result in it having a MAC address of 54:54:12:24:00:01

## TO ADD A NEW NODE TO THE CLUSTER
For example to add a node with address 10.24.38.108 with nodeid 3. The node has the name NEW (in DNS or /etc/hosts) and is not currently running corosync. The current corosync.conf nodelist looks like this:

```
nodelist {

    node {

        nodeid: 1

        ring0_addr: 10.24.38.101

        name: node1

    }

    node {

        nodeid: 2

        ring0_addr: 10.24.38.102

        name: node2

    }
}
```

```

```

Add a new entry for the node below the existing nodes. Node entries don't have to be in nodeid order, but it will help keep you sane. So the nodelist now looks like this:

```
nodelist {

    node {

        nodeid: 1

        ring0_addr: 10.24.38.101

        name: node1

    }

    node {

        nodeid: 2

        ring0_addr: 10.24.38.102

        name: node2

    }

    node {

        nodeid: 3

        ring0_addr: 10.24.38.108

        name: NEW

    }
}
```

```

```

This file must then be copied onto all three nodes - the existing two nodes, and the new one. On one of the existing corosync nodes, tell corosync to re-read the updated config file into memory:

```
corosync-cfgtool -R
```

```

```

This command only needs to be run on one node in the cluster. You may then start corosync on the NEW node and it should join the cluster. If this doesn't work as expected then check the communications between all three nodes is working, and check the syslog files on all nodes for more information. It's important to note that the key bit of information about a node failing to join might be on a different node than you expect.

## TO REMOVE A NODE FROM THE CLUSTER
This is the reverse procedure to 'Adding a node' above. First you need to shut down the node you will be removing from the cluster.

```
corosync-cfgtool -H
```

```

```

Then delete the nodelist stanza from corosync.conf and finally update corosync on the remaining nodes by running

```
corosync-cfgtool -R
```

```

```

on one of them.

## ADDRESS RESOLUTION
corosync resolves ringX_addr names/IP addresses using the getaddrinfo(3) call with respect of totem.ip_version setting.

getaddrinfo() function uses a sophisticated algorithm to sort node addresses into a preferred order and corosync always chooses the first address in that list of the required family. As such it is essential that your DNS or /etc/hosts files are correctly configured so that all addresses for ringX appear on the same network (or are reachable with minimal hops) and over the same IP protocol. If this is not the case then some nodes might not be able to join the cluster. It is possible to override the search order used by getaddrinfo() using the configuration file /etc/gai.conf(5) if necessary, but this is not recommended.

If there is any doubt about the order of addresses returned from getaddrinfo() then it might be simpler to use IP addresses (v4 or v6) in the ringX_addr field.

## FILES
/etc/corosync/corosync.conf

The corosync executive configuration file.

## SEE ALSO
corosync_overview(7), votequorum(5), corosync-qdevice(8), logrotate(8) getaddrinfo(3) gai.conf(5)


corosync.xml

title: corosync.xml(5)

text:
# corosync.xml(5)

## NAME
corosync.xml - XML version of corosync executive configuration file

## SYNOPSIS
/etc/corosync/corosync.xml

## DESCRIPTION
The corosync.xml is XML version of corosync.conf file. It is processed by corosync-xmlproc (8) to generate valid conf file.

File must be valid XML. File starts with root element corosync which can contain same arguments as described in corosync.conf (5).

Within corosync tag are other tags which are processed as follows:

- Every tag is start of new directive

- Every tag attribute is one of options in directive

- Directive is automatically closed

- Sub-tags are processed same and stays within directive

For example, see /etc/corosync/corosync.xml.example

## FILES
/etc/corosync/corosync.xml

XML version of the corosync executive configuration file.

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

branch: sisyphus


votequorum

title: votequorum(5)

summary: Votequorum Configuration Overview

text:
# votequorum(5)

## NAME
votequorum - Votequorum Configuration Overview

## OVERVIEW
The votequorum service is part of the corosync project. This service can be optionally loaded into the nodes of a corosync cluster to avoid split-brain situations. It does this by having a number of votes assigned to each system in the cluster and ensuring that only when a majority of the votes are present, cluster operations are allowed to proceed. The service must be loaded into all nodes or none. If it is loaded into a subset of cluster nodes the results will be unpredictable.

The following corosync.conf extract will enable votequorum service within corosync:

```
quorum {

    provider: corosync_votequorum
}
```

votequorum reads its configuration from corosync.conf. Some values can be changed at runtime, others are only read at corosync startup. It is very important that those values are consistent across all the nodes participating in the cluster or votequorum behavior will be unpredictable.

votequorum requires an expected_votes value to function, this can be provided in two ways. The number of expected votes will be automatically calculated when the nodelist { } section is present in corosync.conf or expected_votes can be specified in the quorum { } section. Lack of both will disable votequorum. If both are present at the same time, the quorum.expected_votes value will override the one calculated from the nodelist.

Example (no nodelist) of an 8 node cluster (each node has 1 vote):

```
quorum {

    provider: corosync_votequorum

    expected_votes: 8
}
```

Example (with nodelist) of a 3 node cluster (each node has 1 vote):

```
quorum {

    provider: corosync_votequorum
}
nodelist {

    node {

        ring0_addr: 192.168.1.1

    }

    node {

        ring0_addr: 192.168.1.2

    }

    node {

        ring0_addr: 192.168.1.3

    }
}
```

## SPECIAL FEATURES
two_node: 1

Enables two node cluster operations (default: 0).

The "two node cluster" is a use case that requires special consideration. With a standard two node cluster, each node with a single vote, there are 2 votes in the cluster. Using the simple majority calculation (50% of the votes + 1) to calculate quorum, the quorum would be 2. This means that the both nodes would always have to be alive for the cluster to be quorate and operate.

Enabling two_node: 1, quorum is set artificially to 1.

Example configuration 1:

```
quorum {

    provider: corosync_votequorum

    expected_votes: 2

    two_node: 1
}
```

Example configuration 2:

```
quorum {

    provider: corosync_votequorum

    two_node: 1
}
nodelist {

    node {

        ring0_addr: 192.168.1.1

    }

    node {

        ring0_addr: 192.168.1.2

    }
}
```

NOTES: enabling two_node: 1 automatically enables wait_for_all. It is still possible to override wait_for_all by explicitly setting it to 0. If more than 2 nodes join the cluster, the two_node option is automatically disabled.

wait_for_all: 1

Enables Wait For All (WFA) feature (default: 0).

The general behaviour of votequorum is to switch a cluster from inquorate to quorate as soon as possible. For example, in an 8 node cluster, where every node has 1 vote, expected_votes is set to 8 and quorum is (50% + 1) 5. As soon as 5 (or more) nodes are visible to each other, the partition of 5 (or more) becomes quorate and can start operating.

When WFA is enabled, the cluster will be quorate for the first time only after all nodes have been visible at least once at the same time.

This feature has the advantage of avoiding some startup race conditions, with the cost that all nodes need to be up at the same time at least once before the cluster can operate.

A common startup race condition based on the above example is that as soon as 5 nodes become quorate, with the other 3 still offline, the remaining 3 nodes will be fenced.

It is very useful when combined with last_man_standing (see below).

Example configuration:

```
quorum {

    provider: corosync_votequorum

    expected_votes: 8

    wait_for_all: 1
}
```

last_man_standing: 1 / last_man_standing_window: 10000

Enables Last Man Standing (LMS) feature (default: 0). Tunable last_man_standing_window (default: 10 seconds, expressed in ms).

The general behaviour of votequorum is to set expected_votes and quorum at startup (unless modified by the user at runtime, see below) and use those values during the whole lifetime of the cluster.

Using for example an 8 node cluster where each node has 1 vote, expected_votes is set to 8 and quorum to 5. This condition allows a total failure of 3 nodes. If a 4th node fails, the cluster becomes inquorate and it will stop providing services.

Enabling LMS allows the cluster to dynamically recalculate expected_votes and quorum under specific circumstances. It is essential to enable WFA when using LMS in High Availability clusters.

Using the above 8 node cluster example, with LMS enabled the cluster can retain quorum and continue operating by losing, in a cascade fashion, up to 6 nodes with only 2 remaining active.

Example chain of events:

```
1) cluster is fully operational with 8 nodes.

   (expected_votes: 8 quorum: 5)
2) 3 nodes die, cluster is quorate with 5 nodes.
3) after last_man_standing_window timer expires,

   expected_votes and quorum are recalculated.

   (expected_votes: 5 quorum: 3)
4) at this point, 2 more nodes can die and

   cluster will still be quorate with 3.
5) once again, after last_man_standing_window

   timer expires expected_votes and quorum are

   recalculated.

   (expected_votes: 3 quorum: 2)
6) at this point, 1 more node can die and

   cluster will still be quorate with 2.
7) one more last_man_standing_window timer

   (expected_votes: 2 quorum: 2)
```

NOTES: In order for the cluster to downgrade automatically from 2 nodes to a 1 node cluster, the auto_tie_breaker feature must also be enabled (see below). If auto_tie_breaker is not enabled, and one more failure occurs, the remaining node will not be quorate. LMS does not work with asymmetric voting schemes, each node must vote 1. LMS is also incompatible with quorum devices, if last_man_standing is specified in corosync.conf then the quorum device will be disabled.

Example configuration 1:

```
quorum {

    provider: corosync_votequorum

    expected_votes: 8

    last_man_standing: 1
}
```

Example configuration 2 (increase timeout to 20 seconds):

```
quorum {

    provider: corosync_votequorum

    expected_votes: 8

    last_man_standing: 1

    last_man_standing_window: 20000
}
```

auto_tie_breaker: 1

Enables Auto Tie Breaker (ATB) feature (default: 0).

The general behaviour of votequorum allows a simultaneous node failure up to 50% - 1 node, assuming each node has 1 vote.

When ATB is enabled, the cluster can suffer up to 50% of the nodes failing at the same time, in a deterministic fashion. By default the cluster partition, or the set of nodes that are still in contact with the node that has the lowest nodeid will remain quorate. The other nodes will be inquorate. This behaviour can be changed by also specifying

auto_tie_breaker_node: lowest|highest|<list of node IDs>

‘lowest’ is the default, ‘highest’ is similar in that if the current set of nodes contains the highest nodeid then it will remain quorate. Alternatively it is possible to specify a particular node ID or list of node IDs that will be required to maintain quorum. If a (space-separated) list is given, the nodes are evaluated in order, so if the first node is present then it will be used to determine the quorate partition, if that node is not in either half (ie was not in the cluster before the split) then the second node ID will be checked for and so on. ATB is incompatible with quorum devices - if auto_tie_breaker is specified in corosync.conf then the quorum device will be disabled.

Example configuration 1:

```
quorum {

    provider: corosync_votequorum

    expected_votes: 8

    auto_tie_breaker: 1

    auto_tie_breaker_node: lowest
}
```

Example configuration 2:

```
quorum {

    provider: corosync_votequorum

    expected_votes: 8

    auto_tie_breaker: 1

    auto_tie_breaker_node: 1 3 5
}
```

```

```

allow_downscale: 1

Enables allow downscale (AD) feature (default: 0).

THIS FEATURE IS INCOMPLETE AND CURRENTLY UNSUPPORTED.

The general behaviour of votequorum is to never decrease expected votes or quorum.

When AD is enabled, both expected votes and quorum are recalculated when a node leaves the cluster in a clean state (normal corosync shutdown process) down to configured expected_votes.

Example use case:

```
1) N node cluster (where N is any value higher than 3)
2) expected_votes set to 3 in corosync.conf
3) only 3 nodes are running
4) admin requires to increase processing power and adds 10 nodes
5) internal expected_votes is automatically set to 13
6) minimum expected_votes is 3 (from configuration)
- up to this point this is standard votequorum behavior -
7) once the work is done, admin wants to remove nodes from the cluster
8) using an ordered shutdown the admin can reduce the cluster size

   automatically back to 3, but not below 3, where normal quorum

   operation will work as usual.
```

Example configuration:

```
quorum {

    provider: corosync_votequorum

    expected_votes: 3

    allow_downscale: 1
}
```

allow_downscale implicitly enabled EVT (see below). expected_votes_tracking: 1

Enables Expected Votes Tracking (EVT) feature (default: 0).

Expected Votes Tracking stores the highest-seen value of expected votes on disk and uses that as the minimum value for expected votes in the absence of any higher authority (eg a current quorate cluster). This is useful for when a group of nodes becomes detached from the main cluster and after a restart could have enough votes to provide quorum, which can happen after using allow_downscale.

Note that even if the in-memory version of expected_votes is reduced, eg by removing nodes or using corosync-quorumtool, the stored value will still be the highest value seen - it never gets reduced.

The value is held in the file ev_tracking (stored in the directory configured in system.state_dir or /var/lib/corosync/ when unset) which can be deleted if you really do need to reduce the expected votes for any reason, like the node has been moved to a different cluster.

## VARIOUS NOTES
* WFA / LMS / ATB / AD can be used combined together.

* In order to change the default votes for a node there are two options:

```
1) nodelist:
nodelist {

    node {

        ring0_addr: 192.168.1.1

        quorum_votes: 3

    }

    ....
}
2) quorum section (deprecated):
quorum {

    provider: corosync_votequorum

    expected_votes: 2

    votes: 2
}
```

In the event that both nodelist and quorum { votes: } are defined, the value from the nodelist will be used. * Only votes, quorum_votes, expected_votes and two_node can be changed at runtime. Everything else requires a cluster restart.

## BUGS
No known bugs at the time of writing. The authors are from outerspace. Deal with it.

## SEE ALSO
corosync(8), corosync.conf(5), corosync-quorumtool(8), corosync-qdevice(8), votequorum_overview(3)


maildir

package: courier-maildrop

title: maildir(5)

summary: E\-mail directory

text:
# maildir(5)

## NAME
maildir - E-mail directory

## SYNOPSIS
$HOME/Maildir

## DESCRIPTION
A “Maildir” is a structured directory that holds E-mail messages. Maildirs were first implemented by the Qmail mail server. Qmail's maildirs were a simple data structure, nothing more than a single collection of E-mail messages. The Courier mail server builds upon Qmail's maildirs to provide extended functionality, such as folders and quotas. This document describes the Courier mail server's extended maildirs, without explicitly identifying The Courier mail server-specific extensions. See maildir(5) in Qmail's documentation for the original definition of maildirs.

Traditionally, E-mail folders were saved as plain text files, called “mboxes”. Mboxes have known limitations. Only one application can use an mbox at the same time. Locking is required in order to allow simultaneous concurrent access by different applications. Locking is often problematic, and not very reliable in network-based filesystem requirements. Some network-based filesystems don't offer any reliable locking mechanism at all. Furthermore, even bulletproof locking won't prevent occasional mbox corruption. A process can be killed or terminated in the middle of updating an mbox. This will likely result in corruption, and a loss of most messages in the mbox.

Maildirs allow multiple concurrent access by different applications. Maildirs do not require locking. Multiple applications can update a maildir at the same time, without stepping on each other's feet.

### Maildir contents
A “maildir” is a directory that's created by maildirmake(1)[1]. Naturally, maildirs should not have any group or world permissions, unless you want other people to read your mail. A maildir contains three subdirectories: tmp, new, and cur. These three subdirectories comprise the primary folder, where new mail is delivered by the system.

Folders are additional subdirectories in the maildir whose names begin with a period: such as .Drafts or .Sent. Each folder itself contains the same three subdirectories, tmp, new, and cur, and an additional zero-length file named maildirfolder, whose purpose is to inform any mail delivery agent that it's really delivering to a folder, and that the mail delivery agent should look in the parent directory for any maildir-related information.

Folders are not physically nested. A folder subdirectory, such as .Sent does not itself contain any subfolders. The main maildir contains a single, flat list of subfolders. These folders are logically nested, and periods serve to separate folder hierarchies. For example, .Sent.2002 is considered to be a subfolder called “2002” which is a subfolder of “Sent”.

Folder name encoding

Folder names can contain any Unicode character, except for control characters. US-ASCII characters, U+0x0020 - U+0x007F, except for the period, and forward-slash. Non-Latin characters are encoded in UTF-8.

Other maildir contents

Software that uses maildirs may also create additional files besides the tmp, new, and cur subdirectories -- in the main maildir or a subfolder -- for its own purposes.

### Messages
E-mail messages are stored in separate, individual files, one E-mail message per file. The tmp subdirectory temporarily stores E-mail messages that are in the process of being delivered to this maildir. tmp may also store other kinds of temporary files, as long as they are created in the same way that message files are created in tmp. The new subdirectory stores messages that have been delivered to this maildir, but have not yet been seen by any mail application. The cur subdirectory stores messages that have already been seen by mail applications.

### Adding new mail to maildirs
The following process delivers a new message to the maildir:

A new unique filename is created using one of two possible forms: “time.MusecPpid.host”, or “time.MusecPpid_unique.host”. “time” and “usec” is the current system time, obtained from gettimeofday(2). “pid” is the process number of the process that is delivering this message to the maildir. “host” is the name of the machine where the mail is being delivered. In the event that the same process creates multiple messages, a suffix unique to each message is appended to the process id; preferrably an underscore, followed by an increasing counter. This applies whether messages created by a process are all added to the same, or different, maildirs. This protocol allows multiple processes running on multiple machines on the same network to simultaneously create new messages without stomping on each other.

The filename created in the previous step is checked for existence by executing the stat(2) system call. If stat(2) results in ANYTHING OTHER than the system error ENOENT, the process must sleep for two seconds, then go back and create another unique filename. This is an extra step to insure that each new message has a completely unique filename.

Other applications that wish to use tmp for temporary storage should observe the same protocol (but see READING MAIL FROM MAILDIRS below, because old files in tmp will be eventually deleted).

If the stat(2) system call returned ENOENT, the process may proceed to create the file in the tmp subdirectory, and save the entire message in the new file. The message saved MUST NOT have the “From_” header that is used to mboxes. The message also MUST NOT have any “From_” lines in the contents of the message prefixed by the “>” character.

When saving the message, the number of bytes returned by the write(2) system call must be checked, in order to make sure that the complete message has been written out.

After the message is saved, the file descriptor is fstat(2)-ed. The file's device number, inode number, and the its byte size, are saved. The file is closed and is then immediately moved/renamed into the new subdirectory. The name of the file in new should be “time.MusecPpidVdevIino.host,S=cnt”, or “time.MusecPpidVdevIino_unique.host,S=cnt”. “dev” is the message's device number, “ino” is the message's inode number (from the previous fstat(2) call); and “cnt” is the message's size, in bytes.

The “,S=cnt” part optimizes the Courier[2] mail server's maildir quota enhancement; it allows the size of all the mail stored in the maildir to be added up without issuing the stat(2) system call for each individual message (this can be quite a performance drain with certain network filesystems).

### READING MAIL FROM MAILDIRS
Applications that read mail from maildirs should do it in the following order:

When opening a maildir or a maildir folder, read the tmp subdirectory and delete any files in there that are at least 36 hours old.

Look for new messages in the new subdirectory. Rename new/filename, as cur/filename:2,info. Here, info represents the state of the message, and it consists of zero or more boolean flags chosen from the following: “D” - this is a 'draft' message, “R” - this message has been replied to, “S” - this message has been viewed (seen), “T” - this message has been marked to be deleted (trashed), but is not yet removed (messages are removed from maildirs simply by deleting their file), “F” - this message has been marked by the user, for some purpose. These flags must be stored in alphabetical order. New messages contain only the :2, suffix, with no flags, indicating that the messages were not seen, replied, marked, or deleted.

Maildirs may have maximum size quotas defined, but these quotas are purely voluntary. If you need to implement mandatory quotas, you should use any quota facilities provided by the underlying filesystem that is used to store the maildirs. The maildir quota enhancement is designed to be used in certain situations where filesystem-based quotas cannot be used for some reason. The implementation is designed to avoid the use of any locking. As such, at certain times the calculated quota may be imprecise, and certain anomalous situations may result in the maildir actually going over the stated quota. One such situation would be when applications create messages without updating the quota estimate for the maildir. Eventually it will be precisely recalculated, but wherever possible new messages should be created in compliance with the voluntary quota protocol.

The voluntary quota protocol involves some additional procedures that must be followed when creating or deleting messages within a given maildir or its subfolders. The deliverquota(8)[3] command is a tiny application that delivers a single message to a maildir using the voluntary quota protocol, and hopefully it can be used as a measure of last resort. Alternatively, applications can use the libmaildir.a library to handle all the low-level dirty details for them. The voluntary quota enhancement is described in the maildirquota(7)[4] man page.

### Maildir Quotas
This is a voluntary mechanism for enforcing "loose" quotas on the maximum sizes of maildirs. This mechanism is enforced in software, and not by the operating system. Therefore it is only effective as long as the maildirs themselves are not directly accessible by their users, since this mechanism is trivially disabled.

If possible, operating system-enforced quotas are preferrable. Where operating system quota enforcement is not available, or not possible, this voluntary quota enforcement mechanism might be an acceptable compromise. Since it's enforced in software, all software that modifies or accesses the maildirs is required to voluntary obey and enforce a quota. The voluntary quota implementation is flexible enough to allow non quota-aware applications to also access the maildirs, without any drastic consequences. There will be some non-drastic consequences, though. Of course, non quota-aware applications will not enforce any defined quotas. Furthermore, this voluntary maildir quota mechanism works by estimating the current size of the maildir, with periodic exact recalculation. Obviously non quota-aware maildir applications will not update the maildir size estimation, so the estimate will be thrown off for some period of time, until the next recalculation.

This voluntary quota mechanism is designed to be a reasonable compromise between effectiveness, and performance. The entire purpose of using maildir-based mail storage is to avoid any kind of locking, and to permit parallel access to mail by multiple applications. In order to compute the exact size of a maildir, the maildir must be locked somehow to prevent any modifications while its contents are added up. Obviously something like that defeats the original purpose of using maildirs, therefore the voluntary quota mechanism does not use locking, and that's why the current recorded maildir size is always considered to be an estimate. Regular size recalculations will compensate for any occasional race conditions that result in the estimate to be thrown off.

A quota for an existing maildir is installed by running maildirmake with the -q option, and naming an existing maildir. The -q option takes a parameter, quota, which is a comma-separated list of quota specifications. A quota specification consists of a number followed by either 'S', indicating the maximum message size in bytes, or 'C', maximum number of messages. For example:

```
maildirmake -q 5000000S,1000C ./Maildir
```

This sets the quota to 5,000,000 bytes or 1000 messages, whichever comes first.

```
maildirmake -q 1000000S ./Maildir
```

This sets the quota to 1,000,000 bytes, without limiting the number of messages.

A quota of an existing maildir can be changed by rerunning the maildirmake command with a new -q option. To delete a quota entirely, delete the Maildir/maildirsize file.

## SEE ALSO
maildirmake(1)[1].

## AUTHOR
Sam Varshavchik

Author

## NOTES
1.

maildirmake(1)

http://www.courier-mta.org/maildirmake.html

2.

Courier

https://www.courier-mta.org

3.

deliverquota(8)

http://www.courier-mta.org/deliverquota.html

4.

maildirquota(7)

http://www.courier-mta.org/maildirquota.html


cpufreqd.conf

package: cpufreqd

title: cpufreqd.conf(5)

summary: configuration file for cpufreqd(1)

text:
# cpufreqd.conf(5)

## NAME
cpufreqd.conf - configuration file for cpufreqd(1)

## DESCRIPTION
cpufreqd.conf is a simple text file containing rules to be used by cpufreqd(1).

cpufreqd.conf is divided into sections enclosed in tags (eg.: [General][/General]). You need at least one [General] section and one or more [Profile] and [Rule] sections. Each [Rule] depends on previously defined [Profile] subsections. Some plugins also require a proper configuration section.

Some notes to better understand how to write appropriate rules:

- the score of a rule is made up of the percentage of entries that match the current system state as reported by plugins + the number of matching entries. In this way even a single-entry rule can reach 100% but more accurate rules are preferred. - in case of 2 or more rules having the same score the first one (as found in the configuration file) or the one already applied if applicable is kept and set.

- each directive is handled by a single plugin that will determine if the state described matches the current system state.

- if no rule matches the current system status, no action is performed.

What to keep in mind when writing rules:

- the -V switch is (hopefully) your friend, test your configuration slightly increasing cpufreqd verbosity and look what happens (-V6 will report rules' scores, -V7 will report which entry matched and which not). - if you want a rule to be preferred over another just describe the system state more accurately.

A good approach to write cpufreqd rules is to first describe the basic parameters you want for a general usage (e.g.: define at least an "AC-on" rule and an "AC-off" rule), then proceed and describe all the special cases by describing the system state more accurately (e.g.: "AC-off but running mplayer" or "AC-on but temperature too hot").

Note that no white space is allowed between name and value pairs. Characters after a '#' are considered comments and ignored.

## SECTIONS
Acceptable configuration tokens and values include:

### [General]
poll_interval

A float larger than 0.15, measures the interval between system status reading in seconds. Note: the lower bound has been set in order to try to avoid trashing your system if using a too low value. (default: 1.0)

enable_plugins

A list of plugins separated by comma. As of cpufreqd 2.1.0 this option is useless, cpufreqd will load all available plugins and remove those remaining unused after the configuration file is read.

pidfile

Specifies the file to write as its process identification file. (default: /var/run/cpufreqd.pid)

enable_remote

Make cpufreqd open a local UNIX socket and listen for command to be executed. See cpufreqd-set(1) and cpufreqd-set(1) for two very simple clients.

remote_group

Make the socket readable and writeable to the specified group. Useful to allow simple users to tweak cpufreqd with cpufreqd-set and cpufreqd-get.

double_check

Make cpufreqd check if the requested policy has been correctly applied by re-reading the corresponding kernel attributes.

verbosity

Verbosity level from 0 (less verbose) to 7 (most verbose), the default value only prints warning/error/critical messages. (default: 4)

### [Profile]
name

An arbitrary and unique name for your profile. [REQUIRED]

minfreq

An integer value representing the minimum frequency to set in /proc/cpufreq. This value can be both a percentage of the CPU full capacity or frequency in kHz. [REQUIRED]

maxfreq

An integer value representing the maximum frequency to set. This value can be both a percentage of the CPU full capacity or frequency in kHz. [REQUIRED]

policy

Can be any of the available governor's name as shown in /sys/devices/.../cpufreq/scaling_available_governors, this means that if you compiled governors as modules in your kernel, you need to load them before running cpufreqd. [REQUIRED]

other plugin entries

Other Profile directives are available according to the enabled plugins.

### [Rule]
name

An arbitrary and unique name for your rule. [REQUIRED]

profile

A character string that must match a [Profile] section name property. A Rule can also associate profiles to single cpus providing a list of the format CPU%d:%s separated by semicolons (";"), e.g.: profile=CPU0:profile0;CPU1:profile1. The keyword "ALL" can be used to indicate that all cpus must have the profile applied. The "ALL" keyword has a lower priority so you can mix up CPU%d and ALL meaning that if no specific profile is supplied, the "ALL" one will be used. [REQUIRED]

other plugin entries

Other Rule directives are available according to the enabled plugins.

## PLUGINS
Plugins extend cpufreqd in order to be able to cope with the most exotic system paramters. Currently available plugins are listed below along with the configration directives they provide and their configuration section description if available.

### acpi plugin
This plugin includes all the acpi monitoring functionalities previously available as separate plugins. It allows monitoring battery, temperature, ac and interacting with acpid to immediately react on ACPI events.

Section [acpi]

acpid_socket The path to Acpid open socket (default: /var/run/acpid.socket). When available cpufreqd will wake up immediately upon event arrival and battery and ac status updates are forced. battery_update_interval

The number of seconds that have to elapse before polling the battery again. In such period the battery value will be estimated based on reported power consumption (default: 30).

battery_interval

The rule will have a higher score if battery percentage is between the values provided. Can be of the form %d-%d or simply %d for a fixed value (e.g.: battery_interval=10-100) or %s:%d-%d or %s:%d where the string represents the battery name that must match (look at 'ls /proc/acpi/battery' for available names).

ac

Can be on or off. The rule will have a higher score if the A/C adapter is on or off as defined in this setting.

acpi_temperature

The rule will have a higher score if the temperature percentage corresponds to the provided values. Can be of the form %d-%d or simply %d for a fixed value (e.g.: acpi_temperature=10-100) or %s:%d-%d or %s:%d where the string represents the thermal zone name that must match (look at 'ls /proc/acpi/thermal_zone' for available names).

### apm plugin
Monitors values reported by the APM subsystem. Available Rule entries:

ac

Can be on or off. The rule will have a higher score if the A/C adapter is on or off as defined in this setting.

battery_interval

The rule will have a higher score if battery percentage is between the values provided. Must be of the form %d-%d (e.g.: battery_interval=10-100).

### pmu plugin
Monitors values reported by the PMU subsystem. Available Rule entries:

ac

Can be on or off. The rule will have a higher score if the A/C adapter is on or off as defined in this setting.

battery_interval

The rule will have a higher score if battery percentage is between the values provided. Must be of the form %d-%d (e.g.: battery_interval=10-100).

### tau plugin
Support for the Thermal Assist Unit to read the CPU temperature from /proc/cpuinfo.

tau_temperature

The rule will have a higher score if the temperature is between the values provided. Must be of the form %d-%d (e.g.: tau_temperature=30-60).

### cpu plugin
Monitors the cpu usage. Available Rule entries:

cpu_interval

The rule will have a higher score if cpu usage is between the values provided. Must be of the form %d-%d (e.g.: cpu_interval=10-100) or %d:%d-%d to monitor a specific cpu in SMP/SMT systems (e.g.: cpu_interval=1:50-100). Moreover you can combine multiple cpus giving multiple intervals on the same line separated by semicolon (';'), if any of them matches the full directive will match (e.g.: cpu_interval=0:50-100;1:0-60). Additionally you can use the strings "ALL" and "ANY" to request that all cpus or any cpu matches respectively (e.g.: cpu_interval=ANY:50-100). It is possible to specify the scale to calculate niced processes cpu usage with the form %d-%d,%f or %d:%d-%d,%f (e.g.: cpu_interval=1:70-100,1.5), default is 3, in this way niced processes will be considered 1/3 of their real value. Rules with overlapping cpu_intervals are allowed.

### exec plugin
Executes command on Rule/Profile selection. Available Rule and Profile entries:

exec_pre

exec_post

You can give commands that you want to be executed when a Rule or Profile is applied. As the names suggest, exec_pre will be run before a Rule or Profile is applied, exec_post will be run after.

### programs plugin
Monitors active processes. Available entries:

programs

The rule will have a higher score if one of the listed processes is running. This is a comma separated list. No white space is allowed between values. cpufreqd will try to match each process name with the configured process list. If you need to match against program from a spe- cific location you have to supply the full path as search pattern.

### nforce2_atxp1 plugin
Allows you to change Vcore of the CPU on the fly if you own a NForce2 board with atxp1 voltage regulator (and its module loaded). The use of this plugin will allow a new Profile directive and requires a configuration section.

Section [nforce2_atxp1]

vcore_path Defines the interface file created by atxp1 module which will be used to change Vcore. vcore_default As NForce2 boards only initialize the atxp1 on power-on, you need to put back default Vcore before reboot. This value will be used to set Vcore on exit.

vcore

Will set Vcore to this value (given in mV) when the corresponding Profile is applied. Due to safety reasons range is limited from 1200 to 1850.

### nvclock plugin
Allows you to tweak the core an memory clock for NVidia cards. The use of this plugin will allow new Profile directives. NOTE: you MUST use this plugin ONLY with supported cards. See also the nvclock homepage (http://www.linuxhardware.org/nvclock).

nv_core

Sets the core clock in MHz. Must be of the form %d:%d where the first integer represents the card number, the second the desired frequency in MHz.

nv_mem

Sets the memory clock in MHz. Must be of the form %d:%d where the first integer represents the card number, the second the desired frequency in MHz.

### sensors plugin
Allows you to specify lm-sensors features to watch, see `sensors -u' to find out which sensors are available on your system. A configuration section is also available to tell cpufreqd which sensors.conf file to use. If not specified it will take the first on the default locations.

Section [sensors_plugin]

sensors_conf Define this directive to the sensors.conf file you want cpufreqd to use to load the sensors library.

sensor

The rule will have a higher score if the given sensor feature reports a value between the two defined. Must be of the form %s:%f-%f where the string represents the feature name or label and the two decimal numbers the interval into which the directive is valid (e.g.: sensor=temp1:0-50).

### governor_parameters plugin
Allows you to specify parameters for governors in [Profile] sections. Currently only the `ondemand' and `conservative' governors support parameters. The description of the parameters below is basically a summary of the information found in the file `governors.txt' in the documentation of kernel versions 2.6.16 or later.

sampling_rate

How often the governor checks the CPU usage. Specify in micro-seconds or percentage of mimimum and maximum available values. Supported suffixes: `%' for a percentage, `s' for a value in seconds, `m' for a value in milli-seconds, or `u' for a value in micro-seconds (the default),

up_threshold

What the average CPU usage needs be at least to make the governor decide to switch to a higher frequency. Though the value is interpreted as percentage by the governor, you should not append a `%' in cpufreqd.conf for this parameter.

down_threshold (`conservative' governor only)

What the average CPU usage needs be at most to make the governor decide to switch to a lower frequency. This is the opposite of up_threshold (see above).

sampling_down_factor

How quickly the frequency will be decreased in respect to how quickly it will be increased. E.g. when set to 5, the frequency will go down 5 times `less easy' than it will go up.

ignore_nice, ignore_nice_load

Whether `nice' processes should be considered as CPU usage by the governor. This is a boolean value (e.g. value is either 0 or 1). When set to 1 `nice' processes will not be counted as CPU usage by the governor. Note: `ignore_nice' was renamed to `ignore_nice_load' in kernel version 2.6.16. Both names are accepted in cpufreqd.conf, regardless the version of the running kernel.

freq_step (`conservative' governor only)

How much the frequency should be changed (up or down) each time the governor decides the frequency should go up or down. The value is the percentage of the maximum available frequency you want the frequency to increase or decrease each time. The actual frequency your CPU runs at will only change when the desired frequency reaches the next available frequency. Though the value is interpreted as percentage by the governor, you should not append a `%' in cpufreqd.conf for this parameter.

## EXAMPLE

```
# cpufreqd.conf sample
# this is a comment
[General]
pidfile=/var/run/cpufreqd.pid
poll_interval=2
verbosity=5 #(if you want a minimal logging)
[/General]
[Profile]
name=hi
minfreq=100%
maxfreq=100%
policy=performance
[/Profile]
[Profile]
name=medium
minfreq=66%
maxfreq=66%
policy=performance
[/Profile]
[Profile]
name=lo
minfreq=33%
maxfreq=33%
policy=performance
[/Profile]
[Profile]
name=ondemand_hi
minfreq=0%
maxfreq=100%
policy=ondemand
[/Profile]
[Profile]
name=ondemand_lo
minfreq=0%
maxfreq=66%
policy=ondemand
ignore_nice=1
sampling_rate=80%
[/Profile]
# full power when AC
# max score 101%
[Rule]
name=AC_on
ac=on
profile=hi
[/Rule]
# conservative mode when not AC
# max score 101%
[Rule]
name=AC_off
ac=off
profile=ondemand_hi
[/Rule]
# low battery
# max score 102%
[Rule]
name=lo_battery
ac=off
battery_interval=0-40
profile=ondemand_lo
[/Rule]
# need big power (not if battery very low)
# max score 103%
[Rule]
name=hi_cpu
ac=off
battery_interval=40-100
cpu_interval=ANY:70-100
profile=hi
[/Rule]
# slow down a little if overheated
# max score 103%
[Rule]
name=overheat
acpi_temperature=55-100
cpu_interval=ANY:0-100
battery_interval=40-100
profile=medium
[/Rule]
# full power when watching DVDs and not AC
# can reach a 105% score
[Rule]
name=dvd_watching
ac=off
battery_interval=0-100
acpi_temperature=0-100
cpu_interval=ANY:0-100
programs=xine,mplayer
profile=hi
[/Rule]
```

## SEE ALSO
cpufreqd(8),cpufreqd-set(1),cpufreqd-get(1)

## AUTHOR
Mattia Dongili <malattia@linux.it>

George Staikos <staikos@0wned.org>


regulatory.bin

package: crda

title: regulatory.bin(5)

summary: The Linux wireless regulatory database

text:
# regulatory.bin(5)

## NAME
regulatory.bin, regulatory.db - The Linux wireless regulatory database

## Description
regulatory.bin and regulatory.db are the files used by the Linux wireless subsystem to keep its regulatory database information.

regulatory.bin is read by crda upon the Linux kernel's request for regulatory information for a specific ISO / IEC 3166 alpha2 country code.

regulatory.db is a newer, extensible database format which (since Linux 4.15) is read by the kernel directly as a firmware file.

The regulatory database is kept in a small binary format for size and code efficiency. The regulatory.bin file can be parsed and read in human format by using the regdbdump command. The regulatory database files should be updated upon regulatory changes or corrections.

## Upkeeping
The regulatory database is maintained by the community as such you are encouraged to send any corrections or updates to the linux-wireless and wireless-regdb mailing lists: linux-wireless@vger.kernel.org and wireless-regdb@lists.infradead.org

## SEE ALSO
regdbdump(8) crda(8) iw(8)

https://wireless.docs.kernel.org/en/latest/en/developers/regulatory.html


crio.conf

title: crio.conf(5)

summary: configuration file of the CRI\-O OCI Kubernetes Container Runtime daemon

text:
# crio.conf(5)

## NAME
crio.conf - configuration file of the CRI-O OCI Kubernetes Container Runtime daemon

## DESCRIPTION
The CRI-O configuration file specifies all of the available configuration options and command-line flags for the crio(8) OCI Kubernetes Container Runtime daemon ⟨./crio.8.md⟩, but in a TOML format that can be more easily modified and versioned.

CRI-O supports partial configuration reload during runtime, which can be done by sending SIGHUP to the running process. Currently supported options in crio.conf are explicitly marked with 'This option supports live configuration reload'.

The containers-registries.conf(5) file can be reloaded as well by sending SIGHUP to the crio process.

The default crio.conf is located at /etc/crio/crio.conf.

## FORMAT
The TOML format ⟨https://github.com/toml-lang/toml⟩ is used as the encoding of the configuration file. Every option and subtable listed here is nested under a global "crio" table. No bare options are used. The format of TOML can be simplified to:

```
[table]
option = value
[table.subtable1]
option = value
[table.subtable2]
option = value
```

## CRIO TABLE
CRI-O reads its storage defaults from the containers-storage.conf(5) file located at /etc/containers/storage.conf. Modify this storage configuration if you want to change the system's defaults. If you want to modify storage just for CRI-O, you can change the storage configuration options here.

root="/var/lib/containers/storage"

Path to the "root directory". CRI-O stores all of its data, including containers images, in this directory.

runroot="/var/run/containers/storage"

Path to the "run directory". CRI-O stores all of its state in this directory.

storage_driver="overlay"

Storage driver used to manage the storage of images and containers. Please refer to containers-storage.conf(5) to see all available storage drivers.

storage_option=[]

List to pass options to the storage driver. Please refer to containers-storage.conf(5) to see all available storage options.

log_dir="/var/log/crio/pods"

The default log directory where all logs will go unless directly specified by the kubelet. The log directory specified must be an absolute directory.

version_file="/var/run/crio/version"

Location for CRI-O to lay down the temporary version file.

It is used to check if crio wipe should wipe containers, which should

always happen on a node reboot

version_file_persist="/var/lib/crio/version"

Location for CRI-O to lay down the persistent version file.

It is used to check if crio wipe should wipe images, which should

only happen when CRI-O has been upgraded

internal_wipe=true

This option is currently DEPRECATED, and will be removed in the future.

Whether CRI-O should wipe containers after a reboot and images after an upgrade when the server starts.

If set to false, one must run crio wipe to wipe the containers and images in these situations.

clean_shutdown_file="/var/lib/crio/clean.shutdown"

Location for CRI-O to lay down the clean shutdown file.

It is used to check whether crio had time to sync before shutting down.

If not found, crio wipe will clear the storage directory.

## CRIO.API TABLE
The crio.api table contains settings for the kubelet/gRPC interface.

listen="/var/run/crio/crio.sock"

Path to AF_LOCAL socket on which CRI-O will listen.

stream_address="127.0.0.1"

IP address on which the stream server will listen.

stream_port="0"

The port on which the stream server will listen. If the port is set to "0", then CRI-O will allocate a random free port number.

stream_enable_tls=false

Enable encrypted TLS transport of the stream server.

stream_idle_timeout=""

Length of time until open streams terminate due to lack of activity.

stream_tls_cert=""

Path to the x509 certificate file used to serve the encrypted stream. This file can change and CRI-O will automatically pick up the changes within 5 minutes.

stream_tls_key=""

Path to the key file used to serve the encrypted stream. This file can change and CRI-O will automatically pick up the changes within 5 minutes.

stream_tls_ca=""

Path to the x509 CA(s) file used to verify and authenticate client communication with the encrypted stream. This file can change and CRI-O will automatically pick up the changes within 5 minutes.

grpc_max_send_msg_size=83886080

Maximum grpc send message size in bytes. If not set or <=0, then CRI-O will default to 80 * 1024 * 1024.

grpc_max_recv_msg_size=83886080

Maximum grpc receive message size. If not set or <= 0, then CRI-O will default to 80 * 1024 * 1024.

## CRIO.RUNTIME TABLE
The crio.runtime table contains settings pertaining to the OCI runtime used and options for how to set up and manage the OCI runtime.

default_runtime="runc"

The name of the OCI runtime to be used as the default.

default_ulimits=[]

A list of ulimits to be set in containers by default, specified as "<ulimit name>=<soft limit>:<hard limit>", for example:"nofile=1024:2048". If nothing is set here, settings will be inherited from the CRI-O daemon.

no_pivot=false

If true, the runtime will not use pivot_root, but instead use MS_MOVE.

decryption_keys_path="/etc/crio/keys/"

Path where the keys required for image decryption are located

conmon=""

Path to the conmon binary, used for monitoring the OCI runtime. Will be searched for using $PATH if empty.

conmon_cgroup="system.slice"

Cgroup setting for conmon

conmon_env=["PATH=/usr/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"]

Environment variable list for the conmon process, used for passing necessary environment variables to conmon or the runtime.

default_env=[]

Additional environment variables to set for all the containers. These are overridden if set in the container image spec or in the container runtime configuration.

selinux=false

If true, SELinux will be used for pod separation on the host.

seccomp_profile=""

Path to the seccomp.json profile which is used as the default seccomp profile for the runtime. If not specified, then the internal default seccomp profile will be used.

seccomp_use_default_when_empty=false

Changes the meaning of an empty seccomp profile. By default (and according to CRI spec), an empty profile means unconfined.

This option tells CRI-O to treat an empty profile as the default profile, which might increase security.

apparmor_profile=""

Used to change the name of the default AppArmor profile of CRI-O. The default profile name is "crio-default".

blockio_config_file=""

Path to the blockio class configuration file for configuring the cgroup blockio controller.

irqbalance_config_file="/etc/sysconfig/irqbalance"

Used to change irqbalance service config file which is used by CRI-O.

For CentOS/SUSE, this file is located at /etc/sysconfig/irqbalance. For Ubuntu, this file is located at /etc/default/irqbalance.

rdt_config_file=""

Path to the RDT configuration file for configuring the resctrl pseudo-filesystem.

cgroup_manager="systemd"

Cgroup management implementation used for the runtime.

default_capabilities=[]

List of default capabilities for containers. If it is empty or commented out, only the capabilities defined in the container json file by the user/kube will be added.

The default list is:

```
  default_capabilities = [
	  "CHOWN",
	  "DAC_OVERRIDE",
	  "FSETID",
	  "FOWNER",
	  "SETGID",
	  "SETUID",
	  "SETPCAP",
	  "NET_BIND_SERVICE",
	  "KILL",

  ]
```

default_sysctls=[]

List of default sysctls. If it is empty or commented out, only the sysctls defined in the container json file by the user/kube will be added.

One example would be allowing ping inside of containers. On systems that support /proc/sys/net/ipv4/ping_group_range, the default list could be:

```
  default_sysctls = [

       "net.ipv4.ping_group_range = 0   2147483647",

  ]
```

allowed_devices=[]

List of devices on the host that a user can specify with the "io.kubernetes.cri-o.Devices" allowed annotation.

additional_devices=[]

List of additional devices. Specified as "<device-on-host>:<device-on-container>:<permissions>", for example: "--additional-devices=/dev/sdc:/dev/xvdc:rwm". If it is empty or commented out, only the devices defined in the container json file by the user/kube will be added.

hooks_dir=["path", ...]

Each *.json file in the path configures a hook for CRI-O containers. For more details on the syntax of the JSON files and the semantics of hook injection, see oci-hooks(5). CRI-O currently support both the 1.0.0 and 0.1.0 hook schemas, although the 0.1.0 schema is deprecated.

Paths listed later in the array have higher precedence (oci-hooks(5) discusses directory precedence).

For the annotation conditions, CRI-O uses the Kubernetes annotations, which are a subset of the annotations passed to the OCI runtime. For example, io.kubernetes.cri-o.Volumes is part of the OCI runtime configuration annotations, but it is not part of the Kubernetes annotations being matched for hooks.

For the bind-mount conditions, only mounts explicitly requested by Kubernetes configuration are considered. Bind mounts that CRI-O inserts by default (e.g. /dev/shm) are not considered.

default_mounts=[]

List of default mounts for each container. Deprecated: this option will be removed in future versions in favor of default_mounts_file.

default_mounts_file=""

Path to the file specifying the defaults mounts for each container. The format of the config is /SRC:/DST, one mount per line. Notice that CRI-O reads its default mounts from the following two files:

```
1) `/etc/containers/mounts.conf` (i.e., default_mounts_file): This is the override file, where users can either add in their own default mounts, or override the default mounts shipped with the package.
2) `/usr/share/containers/mounts.conf`: This is the default file read for mounts. If you want CRI-O to read from a different, specific mounts file, you can change the default_mounts_file. Note, if this is done, CRI-O will only add mounts it finds in this file.
```

pids_limit=1024

Maximum number of processes allowed in a container.

log_filter=""

Filter the log messages by the provided regular expression. This option supports live configuration reload. For example 'request:.*' filters all gRPC requests.

log_level="info"

Changes the verbosity of the logs based on the level it is set to. Options are fatal, panic, error, warn, info, debug, and trace. This option supports live configuration reload.

log_size_max=-1

Maximum size allowed for the container log file. Negative numbers indicate that no size limit is imposed. If it is positive, it must be >= 8192 to match/exceed conmon's read buffer. The file is truncated and re-opened so the limit is never exceeded.

log_to_journald=false

Whether container output should be logged to journald in addition to the kuberentes log file.

container_exits_dir="/var/run/crio/exits"

Path to directory in which container exit files are written to by conmon.

container_attach_socket_dir="/var/run/crio"

Path to directory for container attach sockets.

bind_mount_prefix=""

A prefix to use for the source of the bind mounts. This option would be useful when running CRI-O in a container and the / directory on the host is mounted as /host in the container. Then if CRI-O runs with the --bind-mount-prefix=/host option, CRI-O would add the /host directory to any bind mounts it hands over to CRI. If Kubernetes asked to have /var/lib/foobar bind mounted into the container, then CRI-O would bind mount /host/var/lib/foobar. Since CRI-O itself is running in a container with / or the host mounted on /host, the container would end up with /var/lib/foobar from the host mounted in the container rather than /var/lib/foobar from the CRI-O container.

read_only=false

If set to true, all containers will run in read-only mode.

uid_mappings=""

The UID mappings for the user namespace of each container. A range is specified in the form containerUID:HostUID:Size. Multiple ranges must be separated by comma.

minimum_mappable_uid=-1

The lowest host UID which can be specified in mappings supplied, either as part of a uid_mappings or as part of a request received over CRI, for a pod that will be run as a UID other than 0.

gid_mappings=""

The GID mappings for the user namespace of each container. A range is specified in the form containerGID:HostGID:Size. Multiple ranges must be separated by comma.

minimum_mappable_gid=-1

The lowest host GID which can be specified in mappings supplied, either as part of a gid_mappings or as part of a request received over CRI, for a pod that will be run as a UID other than 0.

ctr_stop_timeout=30

The minimal amount of time in seconds to wait before issuing a timeout regarding the proper termination of the container.

drop_infra_ctr=true

Determines whether we drop the infra container when a pod does not have a private PID namespace, and does not use a kernel separating runtime (like kata).

Requies manage_ns_lifecycle to be true.

infra_ctr_cpuset=""

Determines the CPU set to run infra containers. If not specified, the CRI-O will use all online CPUs to run infra containers.

You can specify CPUs in the Linux CPU list format.

To get better isolation for guaranteed pods, set this parameter to be equal to kubelet reserved-cpus.

namespaces_dir="/var/run"

The directory where the state of the managed namespaces gets tracked. Only used when manage_ns_lifecycle is true

pinns_path=""

The path to find the pinns binary, which is needed to manage namespace lifecycle

absent_mount_sources_to_reject=[]

A list of paths that, when absent from the host, will cause a container creation to fail (as opposed to the current behavior of creating a directory).

device_ownership_from_security_context=false

Changes the default behavior of setting container devices uid/gid from CRI's SecurityContext (RunAsUser/RunAsGroup) instead of taking host's uid/gid.

### CRIO.RUNTIME.RUNTIMES TABLE
The "crio.runtime.runtimes" table defines a list of OCI compatible runtimes. The runtime to use is picked based on the runtime handler provided by the CRI. If no runtime handler is provided, the runtime will be picked based on the level of trust of the workload.

runtime_path=""

Path to the OCI compatible runtime used for this runtime handler.

runtime_root=""

Root directory used to store runtime data

runtime_type="oci"

Type of the runtime used for this runtime handler. "oci", "vm"

runtime_config_path=""

Path to the runtime configuration file, should only be used with VM runtime types

privileged_without_host_devices=false

Whether this runtime handler prevents host devices from being passed to privileged containers.

allowed_annotations=[]

This field is currently DEPRECATED. If you'd like to use allowed_annotations, please use a workload.

A list of experimental annotations this runtime handler is allowed to process.

The currently recognized values are:

"io.kubernetes.cri-o.userns-mode" for configuring a user namespace for the pod.

"io.kubernetes.cri-o.Devices" for configuring devices for the pod.

"io.kubernetes.cri-o.ShmSize" for configuring the size of /dev/shm.

"io.kubernetes.cri-o.UnifiedCgroup.$CTR_NAME" for configuring the cgroup v2 unified block for a container.

"io.containers.trace-syscall" for tracing syscalls via the OCI seccomp BPF hook.

### CRIO.RUNTIME.WORKLOADS TABLE
The "crio.runtime.workloads" table defines a list of workloads - a way to customize the behavior of a pod and container. A workload is chosen for a pod based on whether the workload's activation_annotation is an annotation on the pod.

activation_annotation=""

activation_annotation is the pod annotation that activates these workload settings.

annotation_prefix=""

annotation_prefix is the way a pod can override a specific resource for a container.

The full annotation must be of the form $annotation_prefix.$resource/$ctrname = $value.

allowed_annotations=[]

allowed_annotations is a slice of experimental annotations that this workload is allowed to process.

The currently recognized values are:

"io.kubernetes.cri-o.userns-mode" for configuring a user namespace for the pod.

"io.kubernetes.cri-o.Devices" for configuring devices for the pod.

"io.kubernetes.cri-o.ShmSize" for configuring the size of /dev/shm.

"io.kubernetes.cri-o.UnifiedCgroup.$CTR_NAME" for configuring the cgroup v2 unified block for a container.

"io.containers.trace-syscall" for tracing syscalls via the OCI seccomp BPF hook.

### CRIO.RUNTIME.WORKLOAD.RESOURCES TABLE
The resources table is a structure for overriding certain resources for pods using this workload. This structure provides a default value, and can be overridden by using the AnnotationPrefix.

cpushares="" Specifies the number of CPU shares this pod has access to.

cpuset="" Specifies the cpuset this pod has access to.

## CRIO.IMAGE TABLE
The crio.image table contains settings pertaining to the management of OCI images.

CRI-O reads its configured registries defaults from the system wide containers-registries.conf(5) located in /etc/containers/registries.conf. If you want to modify just CRI-O, you can change the registries configuration in this file. Otherwise, leave insecure_registries and registries commented out to use the system's defaults from /etc/containers/registries.conf.

default_transport="docker://"

Default transport for pulling images from a remote container storage.

global_auth_file=""

The path to a file like /var/lib/kubelet/config.json holding credentials necessary for pulling images from secure registries.

pause_image="k8s.gcr.io/pause:3.6"

The image used to instantiate infra containers. This option supports live configuration reload.

pause_image_auth_file=""

The path to a file like /var/lib/kubelet/config.json holding credentials specific to pulling the pause_image from above. This option supports live configuration reload.

pause_command="/pause"

The command to run to have a container stay in the paused state. This option supports live configuration reload.

signature_policy=""

Path to the file which decides what sort of policy we use when deciding whether or not to trust an image that we've pulled. It is not recommended that this option be used, as the default behavior of using the system-wide default policy (i.e., /etc/containers/policy.json) is most often preferred. Please refer to containers-policy.json(5) for more details.

image_volumes="mkdir"

Controls how image volumes are handled. The valid values are mkdir, bind and ignore; the latter will ignore volumes entirely.

insecure_registries=[]

List of registries to skip TLS verification for pulling images.

registries=["docker.io"]

List of registries to be used when pulling an unqualified image. Note support for this option has been dropped and it has no effect. Please refer to containers-registries.conf(5) for configuring unqualified-search registries.

big_files_temporary_dir=""

Path to the temporary directory to use for storing big files, used to store image blobs and data streams related to containers image management.

separate_pull_cgroup=""

[EXPERIMENTAL] If its value is set, then images are pulled into the specified cgroup. If its value is set to "pod", then the pod's cgroup is used. It is currently supported only with the systemd cgroup manager.

## CRIO.NETWORK TABLE
The crio.network table containers settings pertaining to the management of CNI plugins.

cni_default_network=""

The default CNI network name to be selected. If not set or "", then CRI-O will pick-up the first one found in network_dir.

network_dir="/etc/cni/net.d/"

Path to the directory where CNI configuration files are located.

plugin_dirs=["/opt/cni/bin/",]

List of paths to directories where CNI plugin binaries are located.

## CRIO.METRICS TABLE
The crio.metrics table containers settings pertaining to the Prometheus based metrics retrieval.

enable_metrics=false

Globally enable or disable metrics support.

enable_custom_shm_size=false If set to true, enable users to set a custom shm size instead of using the default value of 64M. The shm size can be set through K8S annotation with the key "io.kubernetes.cri-o.ShmSize", and the value representing the size in human readable format. For example: "io.kubernetes.cri-o.ShmSize: 128Mi"

metrics_collectors=["operations", "operations_latency_microseconds_total", "operations_latency_microseconds", "operations_errors", "image_pulls_by_digest", "image_pulls_by_name", "image_pulls_by_name_skipped", "image_pulls_failures", "image_pulls_successes", "image_pulls_layer_size", "image_layer_reuse", "containers_oom_total", "containers_oom", "processes_defunct"]

Enabled metrics collectors

metrics_port=9090

The port on which the metrics server will listen.

metrics_socket=""

The socket on which the metrics server will listen.

metrics_cert=""

The certificate for the secure metrics server.

metrics_key=""

The certificate key for the secure metrics server.

## CRIO.TRACING TABLE
[EXPERIMENTAL] The crio.tracing table containers settings pertaining to the export of OpenTelemetry trace data.

enable_tracing=false

Globally enable or disable OpenTelemetry trace data exporting.

tracing_endpoint="0.0.0.0:4317"

Address on which the gRPC trace collector will listen.

tracing_sampling_rate_per_million=""

Number of samples to collect per million OpenTelemetry spans.

## CRIO.STATS TABLE
The crio.stats table specifies all necessary configuration for reporting container and pod stats.

stats_collection_period=0

The number of seconds between collecting pod and container stats. If set to 0, the stats are collected on-demand instead.

## SEE ALSO
crio.conf.d(5), containers-storage.conf(5), containers-policy.json(5), containers-registries.conf(5), crio(8)

## HISTORY
Aug 2018, Update to the latest state by Valentin Rothberg ⟨vrothberg@suse.com⟩

Oct 2016, Originally compiled by Aleksa Sarai ⟨asarai@suse.de⟩


crio.conf.d

title: crio.conf.d(5)

summary: directory for drop\-in configuration files for CRI\-O

text:
# crio.conf.d(5)

## NAME
crio.conf.d - directory for drop-in configuration files for CRI-O

## DESCRIPTION
Additionally to configuration in crio.conf(5), CRI-O allows to drop configuration snippets into the crio.conf.d directory. The default directory is /etc/crio/crio.conf.d/. The path can be changed via CRIO's --config-dir command line option.

## CONFIGURATION PRECEDENCE
When it exists, the main configuration file (/etc/crio/crio.conf by default) is read before any file in the configuration directory (/etc/crio/crio.conf.d). Settings in that file have the lowest precedence.

Files in the configuration directory are sorted by name in lexical order and applied in that order. If multiple configuration files specify the same configuration option the setting specified in file sorted last takes precedence over any other value. That is if both 00-default.conf and 10-custom.conf exist in crio.conf.d and both specify different values for a certain configuration option the value from 10-custom.conf will be applied.

## SEE ALSO
crio.conf(5), crio(8)