pcp-dstat

title: pcp-dstat(5)

summary: pcp-dstat configuration file

text:
# pcp-dstat(5)

## NAME
pcp-dstat - pcp-dstat configuration file

## DESCRIPTION
pcp-dstat is a customizable performance metrics reporting tool. It has a ``plugin'' architecture, where a set of pre-defined plugins offer small sets of columnar metric reports, and pcp-dstat command line options select which of these plugins are used in the generated report.

Each plugin is defined in a section of a configuration file. A typical installation will provide many configuration files, and often multiple sections (plugins) within each file.

Configuration files are read from both a system directory and the users home directory ($PCP_SYSCONF_DIR/dstat and $HOME/.pcp/dstat).

## FILE FORMAT
The configuration files have an ini-style syntax consisting of sections (plugins) and options within sections. A section begins with the name of the plugin in square brackets and continues until the next section begins. An example section with two options follows:

```
[plugin]
option = value
metric.option = value2
```

A line comment starts with a hash sign (``#'') or a semicolon (``;''). Inline comments are not supported.

There are some options which apply to the plugin as a whole, and anything else is considered to be a column definition. Column definitions map directly to individual PCP metrics.

### The [plugin] options
label (string)

The overall title to be used for this plugin. In the special case of metrics with instances being reported as a group (see grouptype below) this string may contain the %I pattern, which will be substituted with the name of the instance - refer to the cpu, disk, net and int(errupts) plugins for examples of this special syntax. Undefined by default, set automatically to the section (plugin) name.

width (integer)

The column width used for metrics in this plugin. The default is 5.

precision (integer)

The maximum precision to be used when reporting columns in floating point for this plugin. Undefined by default, set automatically based on width.

printtype (character)

Indicates the reporting style for metric values in this plugin. Possible settings are d(ecimal), f(loat), p(ercent), s(tring), b(its), t(ime). By default a setting will be used based on the metric type and semantic - refer to PMAPI(3) for further details of PCP metric metadata.

colorstep (integer)

Indicates a ``step'' at which the next color will be transitioned to, when reporting metric values. As metric values change on each sample, the colorstep is used to determine the increments beyond which a new color is to be selected. Defaults to 1000.

grouptype (integer)

For plugins with metrics sharing the same instance domain, it is possible to request more complex grouping behaviour. The default behaviour is to not use instance grouping, and to report each instance of the metric in a separate column (the load plugin is an example of this, using the kernel.all.load metric). The grouping can be set at three distinct levels - 1, 2, 3 or 4. Level 1 displays instances of metrics only (no totals) - this is the equivalent of using the --cpu plugin on the pcp-dstat command line with specific processors' utilization displayed, e.g. displaying CPU numbers 4, 5 and 12 (-C 4,5,12). Level 2 displays the total column - the sum of all instances for the specified metric(s) in this plugin. Level 3 is a combination of both modes, for example using the pcp-dstat --cpu plugin with options -C 4,5,12,total. Level 4 is a top-like mode, where a special "top" expression is used to rank all instances - the top-most (largest) value will be displayed.

instances (comma-separated-value string)

Defines the instances to be reported for the metric. The default is to report all instances for set-values metrics.

cullinsts (regex pattern)

An optional regular expression that can be used to cull metric instances from the aggregation ('total') in generated reports. For example it is common to exclude loopback devices from the network interface reports, this is achieved using this option. Default is to report on all instances (no culling).

### The [plugin] metrics
Each plugin must have at least one metric associated with it. Any key that is not one of the above global plugin options is considered to be a metric specification or a metric option. These keys define the metrics and their report formatting.

First and foremost, each column is typically represented by an individual metric (if the metric is set-valued - i.e. it has instances - this will result in multiple columns). This is specified by a new key (column) being set to a metric specification. The column (key) name is an arbitrary word using alphabetic characters. The metric specification is any PCP metric name or derived metric specification, allowing basic arithmetic calculations to be used to form this individual column. The derived metric syntax is described on the pmRegisterDerived(3) manual page.

Some examples of both forms of metric specification are given below in the ``EXAMPLES'' section. Once a column has been associated with a metric, other options specific to that column can be set using a dot-separated syntax.

Metric options

metric.label

The subtitle to be used for the reported values of this metric. The default label is the column name from the configuration file. When set-valued PCP metrics (i.e. with instances) are being used, it is often convenient to specify either the instance number or instance name in the heading. This is achieved using format specifiers - ``%d'' or ``%i'' for instance numbers (e.g. replaced by ``6'' for the sixth processor), and ``%s'' or ``%I'' for instance names (e.g. replaced by ``eth0'' for the ethernet interface). Available instance names for any metric can be discovered via the pminfo(1) or pmprobe(1) commands.

metric.width

The column width to be used when reporting values for this metric.

metric.unit (string)

Defines the unit/scale conversion for the metric. Needs to be dimension-compatible and is used with non-string metrics. For allowed values, see pmrep(1).

metric.type (string)

If set to raw rate conversion for the metric will be disabled.

metric.precision (integer)

Defines precision for floating point values.

metric.limit (string)

Defines value limit filter for numeric metric values.

## EXAMPLES
The following example defines a virtual filesystem plugin, with two columns, defined using three PCP metrics - vfs.files.count, vfs.inodes.count and vfs.inodes.free. The inodes metrics are combined using the derived metric notation.

```
[vfs]
width = 6
label = filesystem
files = vfs.files.count
inode = vfs.inodes.count - vfs.inodes.free
inode.label = inodes
```

The system default pcp-dstat plugin files contain many more examples.

## FILES
$HOME/.pcp/dstat/

private per-user configuration files

$PCP_SYSCONF_DIR/dstat/

system-wide configuration files

## PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the file /etc/pcp.conf contains the local values for these variables. The $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

For environment variables affecting PCP tools, see pmGetOptions(3).

## SEE ALSO
PCPIntro(1), pcp-dstat(1), pminfo(1), pmprobe(1), pmrep(1), PMAPI(3), pmGetOptions(3), pmRegisterDerived(3) and pmrep.conf(5).


pcp.conf

package: pcp-doc

title: pcp.conf(5)

text:
# pcp.conf(5)

## NAME
pcp.conf - the Performance Co-Pilot configuration and environment file

## SYNOPSIS
/etc/pcp.conf

## DESCRIPTION
When using Performance Co-Pilot (PCP) tools and utilities and when calling PCP library functions, a standard set of environment variables are defined in /etc/pcp.conf. These variables are generally used to specify the location of various PCP pieces in the file system and may be loaded into shell scripts by sourcing the /etc/pcp.env(5) shell script and queried by C/C++ programs using the pmGetConfig(3) library function. If a variable is already defined in the environment, the values in pcp.conf do not override those values, i.e. the values in pcp.conf serve as installation defaults only.

Both the pcp.env and pcp.conf files are expected to be found in /etc by default. If required, the pcp.conf file may be relocated and PCP_CONF set in the environment to specify the full path to the new location. The pcp.env file can not be relocated (this is the only hard coded path required by PCP).

The syntax rules for pcp.conf are as follows :

1.

the general syntax is

PCP_VARIABLE_NAME=variable value to end of line

2.

lines that begin with # and all blank lines are ignored.

3.

all variables must be prefixed with PCP_. This is a security issue - variables that do not have this prefix will be silently ignored.

4.

there should be no space between the variable name and the literal = and no space between the = and the variable value (unless the value actually starts with a space). This is required because the pcp.conf file may be sourced directly by Makefiles as well as interpreted by the pcp.env script and the pmGetConfig function.

5.

variable values may contain spaces and should not be quoted. The pcp.env script automatically quotes all variable values from the character immediately following the = through to the end of the line.

For further details and an explanation of the use of each variable, see the comments in the /etc/pcp.conf file itself.

## ENVIRONMENT
The PCP_CONF environment variable specifies an alternative path to the pcp.conf file.

## SEE ALSO
PCPIntro(1), pmconfig(1), PCPIntro(3), PMAPI(3), pmGetConfig(3) and pcp.env(5).

branch: sisyphus


pcp.env

title: pcp.env(5)

text:
# pcp.env(5)

## NAME
pcp.env - script to set Performance Co-Pilot run-time environment variables

## SYNOPSIS
/etc/pcp.env

## DESCRIPTION
The pcp.env script is sourced by assorted Performance Co-Pilot (PCP) scripts and utilities to define the PCP operating environment variables. The conjugate for executable programs using the PCP libraries is the __pmGetConfig(3) function.

Typical usage of pcp.env in a script is as follows :

\#! /bin/sh

\# source the PCP environment variables

. /etc/pcp.env

rest of script ...

The full syntax and semantics of the pcp.conf file and the __pmGetConfig function are described in their respective reference pages.

If the file $HOME/.pcp/pcp.conf exists then this will be processed after the system-wide pcp.conf file. This provides a mechanism to selectively modify or augment the environment settings for PCP scripts, which maybe useful if the scripts are run with sudo(1) which cleans the environment of important settings that are required to ensure the correct execution of the PCP scripts, e.g. $PATH or $PERL5LIB.

## ENVIRONMENT
The PCP_CONF environment variable specifies an alternative path to the pcp.conf file.

## SEE ALSO
PCPIntro(1), sudo(1), PCPIntro(3), PMAPI(3), __pmGetConfig(3) and pcp.conf(5).


perfevent.conf

title: perfevent.conf(5)

text:
# perfevent.conf(5)

## NAME
perfevent.conf - the Performance Co-Pilot perfevent PMDA configuration file

## SYNOPSIS
$PCP_PMDAS_DIRS/perfevent/perfevent.conf

## DESCRIPTION
The perfevent.conf configuration file defines which hardware performance counters are enabled by the perfevent PMDA.

The configuration file contains a list of events that should be enabled for each PMU. The perfevent PMDA detects which PMUs present and programs the configured events. If multiple PMUs are available, the perfevent PMDA uses the order of the entries in the configuration file to determine which PMU settings to use. The entries at the top of the configuration file have higher precedence. Only one PMU configuration setting is used. The configuration file may also contain perf derived events. A derived event has a list of events which must be listed as base events. The values for the counters in the derived events are aggregated and displayed.

## FILE FORMAT
The file consists of one or more groups of PMUs and the events that go with them.

The PMU identification string is enclosed in brackets and one or more events are listed below, one per line.

["PMU identification string"]

EVENT_NAME [CPU OPTION]

...

For derived events, one or more groups of events can be specified where, counters in one group can be specific to one architecture and the counters in other group can be specific to some other architecture. Else, only one group can be specified. EVENT_NAME_1, EVENT_NAME_2 etc. belong to group 1 and EVENT_NAME_3, EVENT_NAME_4 belong to group 2 and so on. If any of the event in the first group is not available, entire group will be discarded. And, the next group will be checked. The first group with all the events available will be activated and monitored. The derived perf event is enclosed in brackets along with :derived as a suffix. Note that the EVENT_NAME listed under derived event must be present as a base event in the configuration file. And, all the events under a particular derived perf event group must have the same CPU_OPTION. || acts as a separator for different groups inside a single derived event. The syntax is :

[event:derived]

EVENT_NAME_1 [CPU_OPTION] [scale]

EVENT_NAME_2 [CPU_OPTION] [scale]

...

||

EVENT_NAME_3 [CPU_OPTION] [scale]

EVENT_NAME_4 [CPU_OPTION] [scale]

...

The available event cpu options are as follows:

cpu

to add the counter to all cpus in the system

cpu_rr

to add to one of the cpus in a round-robin allocation strategy

node

to add the counter to the first cpu in each numa node

node_rr

to add the counter to the cpus in each numa node in a round-robin allocation strategy

[N]

where N is the numerical digit of the CPU index

if the CPU option is absent then the event is programmed on all cpus.

scale is applicable for the counters in derived events. If scale is given, the counters will be scaled to their respective values. The options are as follows :

a float value

Can be a simple float value, or a value in scientific notation.

perf_scale

The scale will be taken from the kernel sysfs scale file entry for that event. Its generally specified in /sys/bus/event_source/device/events/<event_name>.scale

If no scale is given, the default scale will be taken as 1.0.

Blank lines are ignored. Lines that begin with the # sign are ignored.

Multiple, comma separated, PMUs may be specified in the PMU definition.

## SEE ALSO
pmdaperfevent(1).


pmieconf

title: pmieconf(5)

text:
# pmieconf(5)

## NAME
pmieconf - generalized pmie rules and customizations

## DESCRIPTION
The pmieconf file formats are used by the pmieconf(1) tool as a way to generalize pmie(1) rule sets such that they can be easily configured for different systems and different environments. There are two completely different (although closely related) file formats discussed here, namely ``pmieconf-rules'' and ``pmieconf-pmie''.

The directory $PCP_VAR_DIR/config/pmieconf contains information about all the default system pmie generalized rules and variables, including default values for all variables. These files are in the pmieconf-rules format. Although new pmieconf-rules files can be added, the files in this directory should never be changed. Instead, use the pmieconf utility to change variable values in the pmie configuration file.

The pmieconf-pmie format allows site specific customizations of the rules contained in pmieconf-rules files and their associated variables. The pmieconf-pmie format is generated by pmieconf and should not be edited by hand. This generated file is in the pmie format, with some additional information held at the head of the file - thus, the pmieconf-pmie format is a superset of the pmie file format (extended to hold customizations to the generalized rules, but also containing the actual performance rules for pmie to evaluate) which can also be parsed by pmie (all extensions are hidden within comments, and are thus meaningless to pmie itself).

The file $PCP_VAR_DIR/config/pmieconf/config.pmie contains local system settings for pmieconf configurable variables. The variable settings in this file replace the default values specified in $PCP_VAR_DIR/config/pmieconf/*/*.

## PMIECONF-PMIE SYNTAX
All rule customization lines in a valid pmieconf-pmie specification are prefixed by ``//'' and are located at the head of the file - this allows files containing a pmieconf-pmie specification to be successfully parsed by pmie. A pmieconf-pmie must always have the first line in the form:

```
    // pmieconf-pmie version pmieconf_path
```

The version specifies which version of the pmieconf-pmie syntax should be used to parse this file. Currently the only supported version is 1. The pmieconf_path specifies the path to the pmieconf-rules files which were used, by pmieconf, to generate this file. This is discussed in the pmieconf(1) man page (see the -r option).

The remainder of the specification consists of one line entries for each of the modified variables. The syntax for each line is:

```
    // rule_version rule_name rule_variable = value
```

The rule_version and rule_name are used to identify the rule with which to associate the customization. These are followed by the rule_variable name (i.e. the variable of rule rule_name which has been changed) for which the new value is to be used.

A pmieconf-pmie specification must be terminated with the ``end'' keyword. This is used by pmieconf to distinguish where the customizations ends, and the actual pmie rule component begins.

## PMIECONF-PMIE EXAMPLE
The following example is a valid pmieconf-pmie format file, as generated by pmieconf. In order to make changes by hand which are preserved by pmieconf, see the comments contained in the generated file (below) as to where such changes should be made.

```
    // pmieconf-pmie 1 $PCP_VAR_DIR/config/pmieconf

    // 1 memory.exhausted delta = "4 minutes"

    // 1 memory.exhausted enabled = yes

    // 1 memory.exhausted pcplog_action = yes

    // end

    //

    // --- START GENERATED SECTION (do not change this section) ---

    //     generated by pmieconf on:  [DATESTAMP]

    //

    // 1 memory.exhausted

    delta = 4 minutes;

    some_host (

        ( avg_sample (swap.pagesout @0..9 ) ) > 0 &&

        30 %_sample swap.pagesout >= 5

    ) -> shell 10 min "$PCP_BINADM_DIR/pmpost Severe demand for real memory" \

            " %vpgsout/s@%h";

    // --- END GENERATED SECTION (changes below will be preserved) ---
```

To see how this all works, you can generate this file as follows:

```
    # cat - | pmieconf -f /tmp/pmieconf.out \

        -r $PCP_VAR_DIR/config/pmieconf/memory:$PCP_VAR_DIR/config/pmieconf/global

    modify memory.exhausted delta "4 minutes"

    modify memory.exhausted enabled yes

    modify memory.exhausted pcplog_action yes

    ^D

    #
```

Then verify that the generated file is a valid pmie configuration file using:

```
    # pmie -C /tmp/pmieconf.out
```

This parses the file, and then exits after reporting any syntax errors. Now replace -C with -v (above), and watch pmie do its work!

## PMIECONF-RULES SYNTAX
A pmieconf-rules specification consists of a number of separate data objects which together form a complete rule specification (note that a specification may span multiple files and even multiple subdirectories). Each object must have an identifier string and a data type, followed by an (optional) list of attributes.

The generic specification of a pmieconf-rules object is thus:

```
    type identifier [ attribute = value ]* ;
```

The set of valid types is: "rule" (rule definition), "string" (arbitrary, double-quote enclosed string), "double", "integer", "unsigned", "percent" (real number between 0 and 100), "hostlist" (space separated list of host names), "instlist" (space separated list of metric instance names), and the four pmie action types, namely "print", "shell", "alarm", and "syslog".

Rule names use the ``.'' character to introduce the concept of a rule group, e.g. "memory.exhausted" associates this rule with the "memory" group. pmieconf can operate at either the level of rule groups or individual rules. The group name "global" is reserved and may not be used with any rule.

Usually when an object is created it is associated with the current rule. However, if an object's name is preceded by the reserved group name "global", then that object is visible to all rules.

The set of valid attributes is: "help" (descriptive text about this object), "modify" (value is yes/no, flags whether pmieconf should allow changes), "enabled" (value is yes/no, flags whether this is on or off - only meaningful for rules and actions), "display" (yes/no - flags whether pmieconf should show this object), "default" (value determined by type, and is the default value for this object), and specific to objects of rule type are the "version", "predicate", and "enumerate" attributes. "version" and "predicate" are fairly self explanatory ("predicate" must equate to a valid pmie rule when expanded), but "enumerate" requires further discussion.

The "enumerate" clause is useful when you wish to generate multiple, similar pmie rules from a single predicate. This is most useful for rule definitions wishing to use the "some_inst" clause in the pmie language across multiple hosts. For a rule to use these together, it must be certain that the instance list is the same on all of the monitored hosts. This is rarely true, so the "enumerate" attribute allows us to generate multiple rules, expanded over variables of either type "instlist" or "hostlist". These variables make up the value for the "enumerate" attribute - which is a space-separated list of "instlist" or "hostlist" variable names.

Objects can be incorporated into other object definitions using the $identifier$ syntax. See the example later for more insight into how this is useful.

When pmieconf is generating the pmie configuration file, it looks at each enabled rule with N enabled actions (where N > 0) and expands the string:

```
    // "version" identifier

    delta = $delta$;

    "predicate" -> $threshold$ $action1$ & ... & $actionN$ ;
```

The delta, threshold, and action variables are defined globally (using the "global" keyword) for all rules, but can, of course, be changed at the level of an individual rule or rule group.

## PMIECONF-RULES EXAMPLE
The following is an example of a single pmieconf-rules specification, showing a number of different aspects of the language discussed above. The example defines a rule ("memory.exhausted") and a string ("rule").

```
    rule    memory.exhausted

            default = "$rule$"

            predicate =

    "some_host (

        ( avg_sample (swap.pagesout $hosts$ @0..9 ) ) > 0 &&

        $pct$ %_sample swap.pagesout $hosts$ @0..9 >= $threshold$

    )"

            enabled = yes

            version = 1

            help    =

    "The system is swapping modified pages out of main memory to the

    swap partitions, and has been doing this on at least pct of the

    last 10 evaluations of this rule.

    There appears to be insufficient main memory to meet the resident

    demands of the current workload.";

    string  rule

            default = "Severe demand for real memory"

            modify  = no

            display = no;
```

Note that for the above rule to be complete, "threshold" and "pct" would also need to be defined - for the full expression of this rule, refer to $PCP_VAR_DIR/config/pmieconf/memory/exhausted.

## FILES
$PCP_VAR_DIR/config/pmieconf/*/*

generalized system resource monitoring rules

$PCP_VAR_DIR/config/pmieconf/config.pmie

default super-user settings for system resource monitoring rules

$HOME/.pcp/pmie/config.pmie

default user settings for system resource monitoring rules

## SEE ALSO
pmie(1) and pmieconf(1).


pmlogger.control

title: pmlogger.control(5)

text:
# pmlogger.control(5)

## NAME
pmlogger.control - control files for Performance Co-Pilot archiving

## DESCRIPTION
Historical archiving of performance data for Performance Co-Pilot (see PCPIntro(1)) uses pmlogger(1) and one or more instances of pmlogger may be managed by pmlogger_check(1) and pmlogger_daily(1).

pmlogger_check(1) may be run at any time of the day and is intended to check that the desired set of pmlogger processes are running. If not, it (re-)starts any missing logger processes. By default, pmlogger_check(1) also calls pmlogger_daily(1) with a -K option to execute any required archive compression tasks.

pmlogger_daily(1) is intended to be run once per day, preferably in the early morning, as soon after midnight as practicable. Its task is to aggregate, rotate and perform general housekeeping for one or more sets of PCP archives.

Both pmlogger_check(1) and pmlogger_daily(1) operate on a family of shared control files, namely the $PCP_PMLOGGERCONTROL_PATH file and files within the $PCP_PMLOGGERCONTROL_PATH.d directory. These files must not be writable by any user other than root.

The control file(s) should be customized according to the following rules that define for the current version (1.1) of the control file format.

1.

Lines beginning with a ``#'' are comments. A special case is lines beginning ``#!#''; these are control lines for a pmlogger that has been stopped using pmlogctl(1).

2.

Lines beginning with a ``$'' are assumed to be assignments to environment variables in the style of sh(1), and all text following the ``$'' will be eval'ed by the script reading the control file, and the corresponding variable exported into the environment. This is particularly useful to set and export variables into the environment of the administrative scripts, e.g.

```
$ PMCD_CONNECT_TIMEOUT=20
```

If the value to the right of the ``='' contains any white space, then the value should be enclosed in double (") or single (') quotes.

3.

There must be a version line in the control file of the form:

```
$version=1.1
```

4.

Fields within a line of the control file(s) are usually separated by one or more spaces or tabs (although refer to the description of the directory field below for some important exceptions).

5.

There should be one line in the control file(s) for each pmlogger instance with at least 4 fields of the form:

```
host primary socks directory args ...
```

6.

The host field is the name of the host that is the source of the performance metrics for this pmlogger instance. The reserved word LOCALHOSTNAME will be replaced by the name of the local host.

7.

The primary field indicates if this is a primary pmlogger instance (y) or not (n). Since the primary logger must run on the local host, and there may be at most one primary logger for a particular host, this field can be y for at most one pmlogger instance, in which case the host name must be the name of the local host (or LOCALHOSTNAME).

8.

The socks field indicates if this pmlogger instance needs to be started under the control of pmsocks(1) to connect to a pmcd(1) through a firewall (y or n).

9.

The directory field is a directory name. All archive files associated with this pmlogger instance will be created in this directory, and this will be the current directory for the execution of any programs required to maintain those archives. A useful convention is that primary logger archives for the local host with hostname myhost are maintained in the directory $PCP_ARCHIVE_DIR/myhost (this is where the default pmlogger start-up script in $PCP_RC_DIR/pcp will create the archives), while archives for the remote host mumble are maintained in $PCP_ARCHIVE_DIR/mumble.

10.

The directory field may contain embedded shell syntax that will be evaluated by sh(1) to produce the real directory name to be used. The allowed constructs are:

- Any text (including white space) enclosed with $( and ) will be interpreted as a shell command.

- Any text (including white space) enclosed with ` and ` (back quotes) will be interpreted as a shell command.

- Within a single line only one style of embedded shell command is allowed, so either $(...) or `...`, but not both.

- An initial double quote (") followed by arbitrary text (including white space, but excluding an embedded double quote) and a final double quote.

- An initial single quote (') followed by arbitrary text (including white space, but excluding an embedded single quote) and a final single quote.

- Any word containing a $ (assumed to introduce an environment variable name).

11.

In the directory field, the reserved word LOCALHOSTNAME will be replaced by the name of the local host.

12.

The optional args field and any remaining fields are interpreted as arguments to be passed to pmlogger(1). Most typically this would be at least the -c option to specify the metrics to be logged and the logging frequencies.

The following sample control lines specify a primary logger on the local host (bozo), and non-primary loggers to collect and log performance metrics from the hosts wobbly, boing and the local host (i.e. bozo).

```
$version=1.1
bozo          y  n  $PCP_ARCHIVE_DIR/bozo   -c config.default
wobbly        n  n  "/store/wobbly/$(date +%Y)"  -c ./wobbly.config
boing         n  n  $PCP_ARCHIVE_DIR/boing   -c ./pmlogger.config
LOCALHOSTNAME n  n /cluster/LOCALHOSTNAME   -c ./precious.config
```

## SCHEDULED EXECUTION
The periodic execution of pmlogger_check(1) and pmlogger_daily(1) is controlled by either systemd(1) or cron(8).

Typical crontab(5) entries are provided in $PCP_SYSCONF_DIR/pmlogger/crontab (unless installed by default in /etc/cron.d already) and shown below.

```
# daily processing of archives
14      0       *       *       *       $PCP_BINADM_DIR/pmlogger_daily
# every 30 minutes, check pmlogger instances are running
25,55   *       *       *       *       $PCP_BINADM_DIR/pmlogger_check
```

When using systemd(1) on Linux, no crontab entries are needed as the timer mechanism provided by systemd is used instead to achieve the same period execution as the crontab example above.

## FILES
$PCP_PMLOGGERCONTROL_PATH

the PCP logger control file. For a new installation this file contains no pmlogger(1) control lines (the real control files are all in the $PCP_PMLOGGERCONTROL_PATH.d directory), but this file is still processed to support any legacy configurations therein from earlier PCP releases.

Warning: this file must not be writable by any user other than root.

$PCP_PMLOGGERCONTROL_PATH.d

optional directory containing additional PCP logger control files, with one or more per pmlogger specification per file.

Warning: the files herein must not be writable by any user other than root.

$PCP_SYSCONF_DIR/pmlogger/crontab

sample crontab for automated script execution by $PCP_USER (or root). Exists only if the platform does not support the /etc/cron.d mechanism.

## PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the file /etc/pcp.conf contains the local values for these variables. The $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

## SEE ALSO
PCPIntro(1), pmcd(1), pmlogctl(1), pmlogger(1), pmlogger_check(1), pmlogger_daily(1), pmlogger_daily_report(1), pmsocks(1), systemd(1) and cron(8).


pmrep.conf

title: pmrep.conf(5)

summary: pmrep configuration file

text:
# pmrep.conf(5)

## NAME
pmrep.conf - pmrep configuration file

## DESCRIPTION
pmrep is a customizable performance metrics reporting tool. Any available performance metric, live or archived, system and/or application, can be selected for reporting using one of the available output alternatives together with applicable formatting options.

The metrics of interest are named in the metricspec argument(s) on the pmrep command line. These metricspecs define individual metrics or pre-defined performance metricsets to be read from configuration files described below. For command line argument details see pmrep(1).

The pmrep.conf configuration file allows for setting default runtime values and defining any number of custom metricsets for pmrep. A metricset is a user-defined arbitrary set of performance metrics. This allows users to create specifically crafted metricsets particularly relevant for their application or environment. Instead of being dependent on what existing tools provide or collecting the needed data with several disjoint utilities users can define custom metricsets by merely editing pmrep.conf. See below for the metricset specification.

In case pmrep configuration files are read from a directory then values for the [options] and [global] sections will be combined from each file where defined. The last definition of a directive wins, meaning the last definition will be used in case defined multiple times. However, custom metricset sections will not be combined, only the last definition found will be used for reporting.

Options via environment values (see pmGetOptions(3)) override the corresponding built-in default values (if any). Configuration file options override the corresponding environment variables (if any). Command line options override the corresponding configuration file options (if any).

## FILE FORMAT
The file has an ini-style syntax and consists of sections and settings. A section begins with the name of the section in square brackets and continues until the next section begins. An example section with two settings follows:

```
[section]
key = value
key2 = value2
```

The supported data types for values are string, integer, and boolean. Values should not to be quoted expect when the value consists solely of whitespace (i.e., a whitespace-only column separator).

A line comment starts with a hash sign (``#'') or a semicolon (``;''). Inline comments are not supported.

pmrep.conf must be readable by the user invoking pmrep.

Any option described below with a corresponding command line option contains additional functional description in pmrep(1).

## SPECIAL SECTIONS

### The [options] section
The [options] section is read every time pmrep is run and it defines the default runtime options. These options may be overridden by metricspec specific options or by command line options. Metrics are not allowed in this section.

Allowed settings

version (integer)

Indicates the configuration file version. Defaults to 1. The only currently supported value is 1.

source (string)

Indicates the source for metrics. Interpreted as a PCP archive if the value contains a slash (``/''). If set to the special character ``@'', local DSO PMDA context is used. Otherwise interpreted as a hostname. Corresponding command line paraters are -a, -h, and -L. Defaults to local: (see PCPIntro(1)).

output (string)

Indicates the output target. Corresponding command line option is -o. For supported output targets, see pmrep(1). Defaults to stdout.

speclocal (string)

Indicates the local DSO PMDAs to be made available when using the local DSO PMDA context. Corresponding command line option is -K. For syntax description, see pmSpecLocalPMDA(3). Use a semicolon (``;'') to separate more than one spec. Undefined by default.

derived (string)

Derived metric specifications. Corresponding command line option is -e. For syntax description, see pmrep(1). Undefined by default.

daemonize (boolean)

Indicates whether to daemonize on startup. Corresponding command line option is --daemonize. Defaults to no.

header (boolean)

Indicates whether to print headers. Corresponding command line option is -H. Defaults to yes.

instinfo (boolean)

Indicates whether to include instance information as part of headers. Corresponding command line option is --no-inst-info. Defaults to yes.

unitinfo (boolean)

Indicates whether to include unit information as part of headers. Corresponding command line option is -U. Defaults to yes.

globals (boolean)

Indicates whether to include metrics from the [global] section (see below) for reporting. Corresponding command line option is -G. Defaults to yes.

timestamp (boolean)

Indicates whether to print the timestamp. Corresponding command line option is -p. Defaults to no.

samples (integer)

Indicates the number of samples to print. Corresponding command line option is -s. Undefined by default (meaning unlimited number of samples if not limited by other options).

interval (string)

Indicates the interval between samples. Corresponding command line option is -o. Follows the time syntax described in PCPIntro(1). Defaults to 1s.

delay (boolean)

Indicates whether to pause between samples when replaying from an archive rather than replaying at full speed. Corresponding command line option is -d. Defaults to no.

type (string)

Indicates whether to output raw metric values by disabling all rate conversions or convert cumulative counters to rates (default). Corresponding command line option is -r. Allowed values are default or raw.

type_prefer (string)

As type but does not override possible per-metric type specifications. Corresponding command line option is -R. Allowed values are default or raw.

ignore_incompat (boolean)

Indicates that incompatible metrics are to be ignored. Corresponding command line option is -I. Defaults to no.

ignore_unknown (boolean)

Indicates that unknown metrics are to be ignored. Corresponding command line option is -5. Defaults to no.

names_change (string)

Indicates the action to take on PMNS changes during sampling. Corresponding command line option is -4. Defaults to ignore.

instances (string)

Indicates the instances to be reported. Corresponding command line option is -i. Undefined (all instances are reported) by default.

live_filter (boolean)

Indicates that live filtering should be enabled. Corresponding command line option is -j. Defaults to no.

rank (integer)

Indicates the value to be used for ranking instances. Corresponding command line option is -J. Undefined (all instances are reported) by default.

overall_rank (boolean)

Indicates that overall ranking should be performed. Corresponding command line option is -2. Defaults to no.

overall_rank_alt (boolean)

Indicates that overall ranking with alternative output format should be performed. Corresponding command line option is -3. Defaults to no.

limit_filter (integer)

Indicates the value to be used with limit filtering. Corresponding command line option is -8. Undefined (all instances are reported) by default.

limit_filter_force (integer)

As limit_filter but overrides possible possible per-metric specifications. Corresponding command line option is -9. Undefined (all instances are reported) by default.

invert_filter (boolean)

Indicates that invert filtering should be performed. Corresponding command line option is -n. Defaults to no.

predicate (string)

Indicates the metrics to be used as predicate metrics. Corresponding command line option is -N. Undefined by default.

sort_metric (string)

Indicates the metrics to be used as sort reference metrics. Corresponding command line option is -6. Undefined by default.

omit_flat (boolean)

Indicates that single-valued ``flat'' metrics are to be omitted from reporting. Corresponding command line option is -v. Defaults to no.

include_labels (boolean)

Indicates that PCP metric labels should included in the output. Corresponding command line option is -m. Defaults to no.

include_texts (boolean)

Indicates that when writing a PCP archive, PCP help texts shall be included in the created archive. Corresponding command line option is --include-texts. Defaults to no.

colxrow (string)

Indicates to swap columns and rows in stdout output using the value as metric text label. Corresponding command line option is -X. Undefined (no swapping) by default.

width (integer)

Indicates the width of stdout output columns. Corresponding command line option is -w. Forced minimum is 3. Defaults to the shortest width that can fit the metric text label.

width_force (integer)

As width but overrides possible possible per-metric specifications. Corresponding command line option is -W. Forced minimum is 3.

precision (integer)

Indicates how many decimals to use for numeric non-integer output values. Corresponding command line option is -P. Defaults to 3.

precision_force (integer)

As precision but overrides possible per-metric specifications. Corresponding command line option is -0. Undefined by default.

delimiter (string)

Indicates the column separator. Corresponding command line option is -l. Default depends on the output target, see pmrep(1).

extcsv (boolean)

Indicates whether to write extended CSV output similar to sadf(1). Corresponding command line option is -k. Defaults to no.

extheader (boolean)

Indicates whether to print extended header. Corresponding command line option is -x. Defaults to no.

fixed_header (boolean)

Indicates that a fixed header should be used. Corresponding command line option is -7. Defaults to no.

repeat_header (integer)

Indicates how often to repeat the header. Corresponding command line option is -E. auto uses terminal height. Defaults to 0 (header is not repeated).

dynamic_header (boolean)

Indicates that a dynamic header should be used. Corresponding command line option is -1. Defaults to no.

separate_header (boolean)

Indicates whether to print a separate header. Corresponding command line option is -g. Defaults to no.

timefmt (string)

Indicates the format string for formatting the timestamp. Corresponding command line option is -f. Defaults to %H:%M:%S.

interpol (boolean)

Indicates whether to interpolate reported archive values. Corresponding command line option is -u. See pmrep(1) for complete description. Defaults to yes.

count_scale (string)

Indicates the unit/scale for counter metrics. Corresponding command line option is -q. For supported syntax, see pmrep(1). Undefined (no scaling) by default.

count_scale_force (string)

Like count_scale but overrides possible per-metric specifications. Corresponding command line option is -Q. Undefined by default.

space_scale (string)

Indicates the unit/scale for space metrics. Corresponding command line option is -b. For supported syntax, see pmrep(1). Undefined (no scaling) by default.

space_scale_force (string)

Like space_scale but overrides possible per-metric specifications. Corresponding command line option is -B. Undefined by default.

time_scale (string)

Indicates the unit/scale for time metrics. Corresponding command line option is -y. For supported syntax, see pmrep(1). Undefined (no scaling) by default.

time_scale_force (string)

Like time_scale but overrides possible per-metric specifications. Corresponding command line option is -Y. Undefined by default.

### The [global] section
The [global] section is used to define metrics that will be reported in addition to any other separately defined metric or metricset. Configuration options are not allowed in this section. Global metrics are reported by default, the command line option -G or the configuration file option globals can be used to disable global metrics.

Allowed settings

Only metricspecs are allowed in this section. See below for the metricspec specification.

## CUSTOM SECTIONS
Any other section than [options] or [global] will be interpreted as a new metricset specification. The section name is arbitrary, typically a reference to its coverage or purpose. A custom section may contain options, metricspecs, or both.

All the metrics specified in a custom section (metricset) will be reported when pmrep reports that particular metricset. More than one metricset (custom section) can be defined on the command line in which case pmrep reports the combination of all the metrics specified in the selected metricsets.

Allowed settings

Any option valid in the [options] section is also valid in a custom section. Any option or metric defined in a custom section will override the same option or metric possibly defined earlier. See below for the metricspec specification.

## METRICSET SPECIFICATION
There are three forms of the metricspec. First, on the command line a metricspec can start with a colon (``:'') to indicate a reference to a metricset (custom section) to be read from a pmrep configuration file. Second, the compact form of a metricspec is a one-line metric specification which can be used both on the command line and in the [global] and custom sections of the configuration file. The only difference of its usage in the configuration file is that the metric name is used as the key and the optional specifiers as values. The compact form of the metricspec is specified in detail in pmrep(1). The third, verbose form of a metricspec, is valid only in the configuration file (see below).

In a custom section a key containing a dot (``.'') is interpreted as a metric name and a non-option key not containing a dot is interpreted as an identifier (handle) to bind related declarations together. The identifier is arbitrary and is not used otherwise except for binding the below specifiers and the metric together.

The verbose form of a metricspec starts with a declaration consisting of a mandatory identifier as the key and a performance metric name (a PMNS node) as its value. This equals to the compact form of the metricspec defining the same performance metric without any of the optional specifiers defined.

The following specifiers are optional in the verbose form and can be used as keys in any order with an earlier declared identifier followed by a dot and the specifier (as in identifier.specifier). See also the example later below.

label

Defines text label for the metric used by supporting output targets.

formula

Defines the needed arithmetic expression for the metric. For details, see pmRegisterDerived(3).

instances

Defines the instances to be reported for the metric. For details, see pmrep(1).

unit

Defines the unit/scale conversion for the metric. Needs to be dimension-compatible and is used with non-string metrics. For allowed values, see pmrep(1).

type

If set to raw rate conversion for the metric will be disabled.

width

Defines the width of the output column for the metric.

precision

Defines precision for numeric non-integer output values.

limit

Defines value limit filter for numeric metric values.

## EXAMPLE
The following example contains a short [options] section setting some locally wanted default values. It then goes on to define the global metrics kernel.all.sysfork using the compact form and mem.util.allcache using the verbose form of a metricspec. The latter is a derived metric using the specified formula. Both of these metrics will be included in reporting unless disabled with -G or globals = no.

Three different metricsets are also specified: db1, db2, and sar-w.

The DB sets define a host to be used as the source for the metrics. Both use the verbose form of a metricspec (as the non-option key set does not contain the dot) to include all postgresql related metrics.

The sar-w set is an example how to mimic an existing tool with pmrep.

The system default pmrep configuration files contain many more examples. The tab key on the command line after a colon completes available metricsets (with bash and zsh).

```
[options]
timestamp = yes
interval = 2s
extheader = yes
repeat_header = auto
space_scale = MB
[global]
kernel.all.sysfork = forks,,,,8
cacheall = mem.util.allcache
cacheall.formula = mem.util.bufmem + mem.util.cached + mem.util.slab
cacheall.width = 12
[db1]
source = db-host1.example.com
set = postgresql
[db2]
source = db-host2.example.com
set = postgresql
[sar-w]
header = yes
unitinfo = no
globals = no
timestamp = yes
precision = 2
delimiter = " "
kernel.all.sysfork = proc/s,,,,12
kernel.all.pswitch = cswch/s,,,,9
```

## FILES
$PCP_SYSCONF_DIR/pmrep/*.conf

system provided default pmrep configuration files

## PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the file /etc/pcp.conf contains the local values for these variables. The $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

For environment variables affecting PCP tools, see pmGetOptions(3).

## SEE ALSO
PCPIntro(1), pmrep(1), pmGetOptions(3), pmRegisterDerived(3) and pmSpecLocalPMDA(3).


reader.conf

package: pcsc-lite

title: reader.conf(5)

text:
# reader.conf(5)

## NAME
reader.conf - configuration file for pcscd readers' drivers

## DESCRIPTION
The /etc/reader.conf.d/* files contain configuration information for serial and (some) PCMCIA smart card readers.

USB readers SHALL NOT be configured using these files. pcscd uses another mechanism to automatically load USB drivers.

## SYNTAX
The /etc/reader.conf.d/* files are regular text file. Each reader must be defined by four fields:

FRIENDLYNAME TEXT_STRING

DEVICENAME FILENAME

LIBPATH FILENAME

CHANNELID NUMBER

The "FRIENDLYNAME" field is an arbitrary text used to identify the reader. This text is displayed by commands like pcsc_scan(1) that prints the names of all the connected and detected readers.

The "DEVICENAME" field was not used for old drivers (using the IFD handler version 2.0 or earlier). It is now (IFD handler version 3.0) used to identify the physical port on which the reader is connected. This is the device name of this port. It is dependent of the OS kernel. The first serial port device is called /dev/ttyS0 under Linux and /dev/cuaa0 under FreeBSD.

The "LIBPATH" field is the filename of the driver code. The driver is a dynamically loaded piece of code (generally a drivername.so.* file).

The "CHANNELID" is no more used for recent drivers (IFD handler 3.0) and has been superseded by "DEVICENAME". If you have an old driver this field is used to indicate the port to use. You should read your driver documentation to know what information is needed here. It should be the serial port number for a serial reader.

## EXAMPLE

\# Gemplus GemPCTwin reader with serial communication

\# connected to the first serial port

FRIENDLYNAME "GemPCTwin serial"

DEVICENAME /dev/ttyS0

LIBPATH /usr/lib64/pcsc/drivers/serial/libccidtwin.so.0.4.1

CHANNELID 1

## DEBUGGING
In order to set up your /etc/reader.conf.d/my_reader.conf file correctly you may want to have debug messages from pcscd. I recommend you to start pscsd in the foreground and debug mode using:

\# pcscd --foreground --debug

If everything seems OK you can use the pcsc_scan command to print the list of correctly detected readers and try to get the ATR of your smart cards.

## AUTHOR
Ludovic Rousseau <ludovic.rousseau@free.fr>

## SEE ALSO
pcscd(8), pcsc_scan(1)


pdfpcrc

package: pdfpc

title: pdfpcrc(5)

summary: pdfpc configuration file

text:
# pdfpcrc(5)

## NAME
pdfpcrc - pdfpc configuration file

## DESCRIPTION
pdfpc(1) first reads its system-wide configuration file, followed by the user-specific one if it exists.

### Keybindings
The following commands are accepted:

bind <key> <action> [<arg>]

Bind a key to an action, passing a specified argument for actions that require one

unbind <key>

Unbind the given key

unbind_all

Clear all the key bindings

mouse <button> <action>

Bind a mouse button to an action

unmouse <button>

Unbind a mouse button

unmouse_all

Clear all the mouse bindings

Key names can be obtained with the help of the xev(1) utility. Note that names are case sensitive. Key combinations with modifiers can be specified in the form <mod>+<key>, where <mod> is one of S (for shift), C (for control) and A/M (for Alt/Meta).

A shorthand for specifying key combinations constituting shift and an alphabetic character is to simply give the uppercase version of the alphabetic character. For example, S+r and R are equivalent.

A list of all possible actions can be obtained via the -L command line option of pdfpc(1). Use the -B command line option to list the action bindings defined.

### Options
Some permanent changes can be configured via the config file. The syntax is:

option <option_name> <option_value>

The following option_name's are recognized:

black-on-end

Add an additional black slide at the end of the presentation (bool, Default is false).

cache-clean-period

Period (in units of s) to check for expired cached content (int, Default is 60).

cache-expiration

Time (in units of s) to keep (pre)rendered slides in the cache (int, Default is 600). Set to a negative value to keep cached slides permanently.

cache-max-rtime

Maximal time (in units of ms) it takes to render a slide for its cache to be protected from expiration (int, Default is 1000).

cache-min-rtime

Minimal time (in units of ms) it takes to render a slide for it to be cached (int, Default is 10).

cache-max-usize

Maximal size (in units of kB) of a slide image to store it uncompressed in the cache (int, Default is 256).

current-height

Percentage of the height of the "main" presenter area to be used for the current slide (int, Default is 80).

current-size

Percentage of the width of the presenter screen to be used for the current slide (int, Default is 60).

cursor-timeout

Mouse inactivity timeout (in units of s) after which the cursor gets hidden (int, Default is 2).

disable-input-autodetection

Do not automatically detect type (pen or eraser) of tablet input devices (bool, Default is false).

disable-input-pressure

Ignore pressure sensitivity of tablet input devices (pen or eraser) even when it is supported by the hardware (bool, Default is false).

disable-scrolling

Disable scrolling events on the presenter window (bool, Default is false).

disable-tooltips

Disable tooltips for the toolbox (bool, Default is false).

enable-auto-srt-load

Try loading video subtitle files automatically. For each video media, pdfpc will append ".srt" to the media URI and attempt to load a subtitle file (in the SRT format) from that location (bool, Default is false).

final-slide

Show the final slide of an overlay group instead of the next slide. If the user reaches the last slide of the overlay group the next slide will be shown again.

move-on-mapped

Dual-monitor full-screen window placement is a tricky business. Some window managers (e.g., FVWM) ignore the placement if made before the window is shown. This option enables a workaround (bool, Default is false).

next-height

Percentage of the height of the "main" presenter area to be used for the next slide (int, Default is 70).

next-slide-first-overlay

If the next slide is an overlay group, show the first slide of that group in the next slide view instead of the last slide of that group (bool, Default is false).

overview-min-size

Minimum width for the overview miniatures, in pixels (int, Default is 150).

pointer-color

Set the pointer color. Can be a literal color name or a #rrggbb representation (default is red).

pointer-opacity

Set the pointer opacity in percent (int, default is 50).

pointer-size

Set the initial pointer size, in pixels (int, default is 10).

prerender-delay

Delay (in seconds) to launch the pre-rendering process after a slide change (int, default is 4).

prerender-slides

Number of slides ahead of the current one to pre-render (int, default is 2). Set to 0 to disable the pre-rendering; set to a negative number to pre-render all at once.

presentation-interactive

Let the presentation window react to user actions, similar to the presenter (bool, default is false). Note that if the presentation window is the only pdfpc GUI (i.e., if run with -sS), it will be interactive irrespective of this flag.

presentation-screen

Screen to be used for the presentation (output name, see e.g. "xrandr --listmonitors").

presenter-screen

Screen to be used for the presenter (output name).

rest-https

Run the REST server in the TLS mode (bool, Default is false).

rest-port

Port of the REST server (int, Default is 8088).

rest-passwd

Password to authenticate against the REST server (string, if not set, a randomly generated one is used).

rest-static-root

Root path to serve static HTML content. If begins with "/", it is interpreted as the absolute path; otherwise, relative to /usr/share/pdfpc (string, Default is "www").

spotlight-opacity

Set opacity of the area outside of the spotlight, in percent (int, default is 50).

spotlight-size

Set the initial spotlight size, in pixels (int, default is 100).

status-height

Percentage of the height of the presenter screen left for the status area (timer, progress, icons), leaving (100 - status_height)% for the "main" area (int, Default is 10).

switch-screens

Switch the presentation and the presenter screen (bool, Default is false).

time-of-day

Display the current time instead of the timer

timer-pace-color

Enable color hints of the timer, continuously indicating whether the presentation is progressing according to the expected pace (bool, Default is true). See the timer operation description in pdfpc(1).

toolbox

Show the toolbox on startup (bool, Default is false).

toolbox-direction

Set the toolbox direction. LtoR, RtoL, TtoB, or BtoT for the left-to-right, right-to-left, top-to-bottom, or botton-to-top, respectively (Default is LtoR).

toolbox-minimized

Set the initial toolbox state minimized (bool, Default is false).

transition-fps

Frames-per-second for slide transitions (int, Default is 25). Set to 0 to disable all transitions.

windowed-mode

Set the initial windowed mode: none, presenter, presentation, or both (Default is presenter).

## EXAMPLES
To change the drawing pen color using the numerical pad keys:

bind S+KP_1 setPenColor red

bind S+KP_2 setPenColor green

bind S+KP_3 setPenColor blue

To always activate the black-on-end option, one could add the following to the config file

option black-on-end true

## FILES
/etc/pdfpcrc

System-wide configuration file

$XDG_CONFIG_HOME/pdfpc/pdfpcrc

User configuration file (if $XDG_CONFIG_HOME is not set, $HOME/.config will be used).

## SEE ALSO
pdfpc(1)


ixfrdist.yml

package: pdns-ixfrdist

title: ixfrdist.yml(5)

summary: The ixfrdist configuration file

text:
# ixfrdist.yml(5)

## NAME
ixfrdist.yml - The ixfrdist configuration file

## SYNOPSIS
ixfrdist.yml

## DESCRIPTION
ixfrdist reads its configuration from a YAML file. By default, this file is called ixfrdist.yml and is read from the directory configured as SYSCONFDIR when building the software. This directory is usually one of /etc/pdns, /etc/powerdns. Run ixfrdist --help to see the default.

## EXAMPLE

```
listen:

  - 192.0.2.2

  - '[2001:DB8:ABCD::2]:5300'

  - 127.0.0.1
acl:

  - 127.0.0.1

  - '192.0.2.0/24'

  - '2001:DB8:ABCD:1234::/64'
work-dir: /var/lib/ixfrdist
uid: ixfrdist
gid: ixfrdist
domains:

  - domain: example.com

    master: 192.0.2.18:5301

    max-soa-refresh: 1800

    notify:

      - 192.0.3.1

      - 192.0.3.2:5301

  - domain: example.net

    master: 2001:DB8:ABCD::2
```

## OPTIONS
listen

The list of addresses to listen on. ixfrdist listens on both TCP and UDP. When no port is specified, 53 is used. When specifying ports for IPv6, use the "bracket" notation. By default, ixfrdist listens on 127.0.0.1:53 and [::1]:53.

acl

A list of netmasks that are allowed to query ixfrdist and request AXFRs and IXFRs Entries without a netmask will be interpreted as a single address. By default, the ACL is set is 127.0.0.0/8 and ::1/128.

axfr-max-records

Maximum number of records allowed in an AXFR transaction requested by ixfrdist. This may prevent untrusted sources from using all the process memory. By default, this setting is 0, which means "unlimited".

axfr-timeout

Timeout in seconds an AXFR transaction requested by ixfrdist may take. Increase this when the network to the authoritative servers is slow or the domains are very large and you experience timeouts. Defaults to 20.

failed-soa-retry

Time in seconds between retries of the SOA query for a zone we have never transferred. Defaults to 30.

compress

Whether record compression should be enabled, leading to smaller answers at the cost of an increased CPU and memory usage. Defaults to false.

work-dir

The directory where the domain data is stored. When not set, the current working directory is used. This working directory has the following structure: work-dir/ZONE/SERIAL, e.g. work-dir/rpz.example./2018011902. It is highly recommended to set this option, as the current working directory might change between invocations. This directory must be writable for the user or group ixfrdist runs as.

keep

Amount of older copies/IXFR diffs to keep for every domain. This is set to 20 by default.

tcp-in-threads

Number of threads to spawn for TCP connections (AXFRs) from downstream hosts. This limits the number of concurrent AXFRs to clients. Set to 10 by default.

gid

Group name or numeric ID to drop privileges to after binding the listen sockets. By default, ixfrdist runs as the user that started the process.

uid

User name or numeric ID to drop privileges to after binding the listen sockets. By default, ixfrdist runs as the user that started the process.

domains

A list of domains to redistribute. This option is mandatory.

domain

The domain name to transfer from the master. Mandatory.

master

IP address of the server to transfer this domain from. Mandatory.

max-soa-refresh

Cap the refresh time to the given maximum (in seconds). Optional.

notify

The list of destinations to send NOTIFY to. Optional.

webserver-address

IP address to listen on for the built-in webserver. When not set, no webserver is started.

webserver-acl

A list of networks that are allowed to access the ixfrdist webserver. Entries without a netmask will be interpreted as a single address. By default, this list is set to 127.0.0.0/8 and ::1/128.

webserver-loglevel

How much the webserver should log: 'none', 'normal' or 'detailed'. When logging, each log-line contains the UUID of the request, this allows finding errors caused by certain requests. With 'none', nothing is logged except for errors. With 'normal' (the default), one line per request is logged in the style of the common log format:

```
[NOTICE] [webserver] 46326eef-b3ba-4455-8e76-15ec73879aa3 127.0.0.1:57566 "GET /metrics HTTP/1.1" 200 1846
```

with 'detailed', the full requests and responses (including headers) are logged along with the regular log-line from 'normal'.

## SEE ALSO
ixfrdist(1)

## AUTHOR
PowerDNS.COM BV

## COPYRIGHT
PowerDNS.COM BV