readers.conf

title: readers.conf(5)

text:
# readers.conf(5)

## NAME
readers.conf - Access control and configuration for nnrpd

## DESCRIPTION
readers.conf in pathetc specifies access control for nnrpd(8). It controls who is allowed to connect as a news reader and what they're allowed to do after they connect. nnrpd reads this file when it starts up. This generally means that any changes take effect immediately on all subsequent connections, but nnrpd may have to be restarted if you use the -D option. (The location pathetc/readers.conf is only the default; the same format applies to any file specified with "nnrpd -c".)

There are two types of entries in readers.conf: parameter/value pairs and configuration groups. Blank lines and anything after a number sign ("#") are ignored, unless the character "#" is escaped with "\". The maximum number of characters on each line is 8,191.

Parameter/value pairs consist of a keyword immediately followed by a colon, at least one whitespace character, and a value. The case of the parameter is significant (parameter should generally be in all lowercase), and a parameter may contain any characters except colon, "#", and whitespace. An example:

```
    hosts: *.example.com
```

Values that contain whitespace should be quoted with double quotes, as in:

```
    hosts: "*.example.com, *.example.net"
```

If the parameter does not contain whitespace, such as:

```
    hosts: *.example.com,*.example.net
```

it's not necessary to quote it, although you may wish to anyway for clarity.

There is no way to continue a line on the next line, and therefore no way to have a single parameter with a value longer than about 8,180 characters.

Many parameters take a boolean value. For all such parameters, the value may be specified as "true", "yes", or "on" to turn it on and may be any of "false", "no", or "off" to turn it off. The case of these values is not significant.

There are two basic types of configuration groups, auth and access. The auth group provides mechanisms to establish the identity of the user, who they are. The access group determines, given the user's identity, what that user is permitted to do. Writing a readers.conf file for your setup is a two-step process: first assigning an identity to each incoming connection using auth groups, and then giving each identity appropriate privileges with access group. We recommend not intermingling auth groups and access groups in the config file; it is often more sensible (in the absence of the key parameter) to put all of the auth groups first, and all of the access groups below.

A user identity, as established by an auth group, looks like an e-mail address; in other words, it's in the form "<username>@<domain>" (or sometimes just "<username>" if no domain is specified.

If nnrpdauthsender is set in inn.conf, the user identity is also put into the Sender: header of posts made by that user. See the documentation of that option in inn.conf(5) for more details.

An auth group definition looks like:

```
    auth <name> {
        hosts: <host-wildmat>
        auth: <auth-program>
        res: <res-program>
        default: <defuser>
        default-domain: <defdomain>
        # ...possibly other settings
    }
```

The <name> is used as a label for the group and is only for documentation purposes. (If your syslog configuration records the "news.debug" facility, the <name> will appear in the debugging output of nnrpd. Examining that output can be very helpful in understanding why your configuration doesn't do what you expect it to.)

A given auth group applies only to hosts whose name or IP address matches the wildmat expression given with the hosts: parameter (comma-separated wildmat expressions allowed, but "@" is not supported). Rather than wildmat expressions, you may also use CIDR notation to match any IP address in a netblock; for example, "10.10.10.0/24" will match any IP address between 10.10.10.0 and 10.10.10.255 inclusive.

If compiled against the TLS/SSL or SASL libraries, an auth group with the require_ssl parameter set to true only applies if the incoming connection is using an encryption layer, either from the beginning if the -S flag was passed to nnrpd, or after a successful use of STARTTLS, or after a successful authentication using a SASL mechanism which negotiates an encryption layer.

For any connection from a host that matches that wildmat expression or netblock, each <res-program> (multiple res: lines may be present in a block; they are run in sequence until one succeeds), if any, is run to determine the identity of the user just from the connection information. If all the resolvers fail, or if the res: parameter isn't present, the user is assigned an identity of "<defuser>@<defdomain>"; in other words, the values of the default: and default-domain: parameters are used. If <res-program> only returns a username, <defdomain> is used as the domain.

If the user later authenticates via the AUTHINFO USER/PASS commands, the provided username and password are passed to each <auth-program> (multiple auth, perl_auth, or python_auth lines may be present in a block; they are run in sequence until one succeeds), if any. If one succeeds and returns a different identity than the one assigned at the time of the connection, it is matched against the available access groups again and the actions the user is authorized to do may change. The most common <auth-program> to use is ckpasswd, which supports several ways of checking passwords including using PAM. See the ckpasswd(8) man page for more details.

When matching auth groups, the last auth group in the file that matches a given connection and username/password combination is used.

An access group definition usually looks like:

```
    access <name> {
        users: <identity-wildmat>
        newsgroups: <group-wildmat>
        # ...possibly other settings
    }
```

Again, <name> is just for documentation purposes. This says that all users whose identity matches <identity-wildmat> can read and post to all newsgroups matching <group-wildmat> (as before, comma-separated wildmat expressions are allowed, but "@" is not supported). Alternately, you can use the form:

```
    access <name> {
        users: <identity-wildmat>
        read: <read-wildmat>
        post: <post-wildmat>
    }
```

and matching users will be able to read any group that matches <read-wildmat> and post to any group that matches <post-wildmat>. You can also set several other things in the access group as well as override various inn.conf(5) parameters for just a particular group of users.

Just like with auth groups, when matching access groups the last matching one in the file is used to determine the user's permissions. There is an exception to this rule: if the auth group which matched the client contains a perl_access: or python_access: parameter, then the script given as argument is used to dynamically generate an access group. This new access group is then used to determine the access rights of the client; the access groups in the file are ignored.

There is one additional special case to be aware of. When forming particularly complex authentication and authorization rules, it is sometimes useful for the identities provided by a given auth group to only apply to particular access groups; in other words, rather than checking the identity against the users: parameter of every access group, it's checked against the users: parameter of only some specific access groups. This is done with the key: parameter. For example:

```
    auth example {
        key: special
        hosts: *.example.com
        default: <SPECIAL>
    }
    access example {
        key: special
        users: <SPECIAL>
        newsgroups: *
    }
```

In this case, the two key: parameters bind this auth group with this access group. For any incoming connection matching "*.example.com" (assuming there isn't any later auth group that also matches such hosts), no access group that doesn't have "key: special" will even be considered. Similarly, the above access group will only be checked if the user was authenticated with an auth group containing "key: special". This mechanism normally isn't useful; there is almost always a better way to achieve the same result.

Also note in the example that there's no default-domain: parameter, which means that no domain is appended to the default username and the identity for such connections is just "<SPECIAL>". Note that some additional add-ons to INN may prefer that authenticated identities always return a full e-mail address (including a domain), so you may want to set up your system that way.

Configuration files can be included in other configuration files via the syntax:

```
    include <filename>
```

The file named <filename> is then included. This syntax is allowed only at top-level.

Below is the full list of allowable parameters for auth groups and access groups, and after that are some examples that may make this somewhat clearer.

## AUTH GROUP PARAMETERS
An auth group without at least one of the res:, auth:, perl_auth:, python_auth:, or default: parameters makes no sense (and in practice will just be ignored).

hosts:

A comma-separated list of remote hosts, wildmat patterns matching either hostnames or IP addresses, or IP netblocks specified in CIDR notation. If a user connects from a host that doesn't match this parameter, this auth group will not match the connection and is ignored. Note that if you have a large number of patterns that can't be merged into broader patterns (such as a large number of individual systems scattered around the net that should have access), the hosts: parameter may exceed the maximum line length of 8,192 characters. In that case, you'll need to break that auth group into multiple auth groups, each with a portion of the hosts listed in its hosts: parameter, and each assigning the same user identity.

All hosts match if this parameter is not given.

localaddress:

A comma-separated list of local host or address patterns with the same syntax as the same as with the hosts: parameter. If this parameter is specified, its auth group will only match connections made to a matching local interface. (Obviously, this is only useful for servers with multiple interfaces.) All local addresses match if this parameter is not given.

res:

A simple command line for a user resolver (shell metacharacters are not supported). If a full path is not given, the program executed must be in the pathbin/auth/resolv directory. A resolver is an authentication program which attempts to figure out the identity of the connecting user using nothing but the connection information (in other words, the user has not provided a username and password). An examples of a resolver would be a program that assigns an identity from an ident callback or from the user's hostname. One auth group can have multiple res: parameters, and they will be tried in the order they're listed. The results of the first successful one will be used.

Alternatively, a res block can be used instead of a res: parameter. The recognized parameters in such res blocks are:

log:

A string to log in pathlog/news.notice (with "res also-log:" prepended) before the resolver is tried. One res group can have multiple log: parameters, and they will be logged in the order they're listed.

program:

This parameter is mandatory in a res block. Its meaning is the same as the res: parameter used directly in an auth block.

```
    auth <auth-name> {
        res: <res-program>
    }

```

is therefore equivalent to:

```
    auth <auth-name> {
        res <res-name> {
            program: <res-program>
        }
    }

```

auth:

A simple command line for a user authenticator (shell metacharacters are not supported). If a full path is not given, the program executed must be located in the pathbin/auth/passwd directory. An authenticator is a program used to handle a user-supplied username and password, via a mechanism such as AUTHINFO USER/PASS. Like with res:, one auth group can have multiple auth: parameters; they will be tried in order and the results of the first successful one will be used. See also perl_auth: below. The most common authenticator to use is ckpasswd(8); see its man page for more information.

perl_auth:

A path to a perl script for authentication. The perl_auth: parameter works exactly like auth:, except that it calls the named script using the perl hook rather than an external program. Multiple/mixed use of the auth, perl_auth, and python_auth parameters is permitted within any auth group; each line is tried in the order it appears. perl_auth: has more power than auth: in that it provides the authentication program with additional information about the client and the ability to return an error string and a username. This parameter is only valid if INN is compiled with Perl support (--with-perl passed to configure). More information may be found in doc/hook-perl.

python_auth:

A Python script for authentication. The python_auth parameter works exactly like auth, except that it calls the named script (without its ".py" extension) using the Python hook rather than an external program. Multiple/mixed use of the auth, perl_auth, and python_auth parameters is permitted within any auth group; each line is tried in the order it appears. python_auth has more power than auth in that it provides the authentication program with additional information about the client and the ability to return an error string and a username. This parameter is only valid if INN is compiled with Python support (--with-python passed to configure). More information may be found in doc/hook-python.

default:

The default username for connections matching this auth group. This is the username assigned to the user at connection time if all resolvers fail or if there are no res: parameters. Note that it can be either a bare username, in which case default-domain: (if present) is appended after an "@", or a full identity string containing an "@", in which case it will be used verbatim.

default-domain:

The default domain string for this auth group. If a user resolver or authenticator doesn't provide a domain, or if the default username is used and it doesn't contain a "@", this domain is used to form the user identity. (Note that for a lot of setups, it's not really necessary for user identities to be qualified with a domain name, in which case there's no need to use this parameter.)

key:

If this parameter is present, any connection matching this auth group will have its privileges determined only by the subset of access groups containing a matching key parameter.

require_ssl:

If set to true, an incoming connection only matches this auth group if it is encrypted, either from the beginning if the -S flag was passed to nnrpd, or after a successful use of STARTTLS, or after a successful authentication using a SASL mechanism which negotiates an encrypted layer. This parameter is only valid if INN is compiled with TLS/SSL or SASL support (by default if the OpenSSL SSL and crypto libraries or the Cyrus SASL library are found at configure time, otherwise see the --with-openssl and --with-sasl flags passed to configure).

perl_access:

A path to a perl script for dynamically generating an access group. If an auth group matches successfully and contains a perl_access parameter, then the argument perl script will be used to create an access group. This group will then determine the access rights of the client, overriding any access groups in readers.conf. If and only if a sucessful auth group contains the perl_access parameter, readers.conf access groups are ignored and the client's rights are instead determined dynamically. This parameter is only valid if INN is compiled with Perl support (--with-perl passed to configure). More information may be found in the file doc/hook-perl.

python_access:

A Python script for dynamically generating an access group. If an auth group matches successfully and contains a python_access parameter, then the argument script (without its ".py" extension) will be used to create an access group. This group will then determine the access rights of the client, overriding any access groups in readers.conf. If and only if a successful auth group contains the python_access parameter, readers.conf access groups are ignored and the client's rights are instead determined dynamically. This parameter is only valid if INN is compiled with Python support (--with-python passed to configure). More information may be found in the file doc/hook-python.

python_dynamic:

A Python script for applying access control dynamically on a per newsgroup basis. If an auth group matches successfully and contains a python_dynamic parameter, then the argument script (without its ".py" extension) will be used to determine the clients rights each time the user attempts to view a newsgroup, or read or post an article. Access rights as determined by python_dynamic override the values of access group parameters such as newsgroups, read and post. This parameter is only valid if INN is compiled with Python support (--with-python passed to configure). More information may be found in the file doc/hook-python.

## ACCESS GROUP PARAMETERS
users:

The privileges given by this access group apply to any user identity which matches this comma-separated list of wildmat patterns. If this parameter isn't given, the access group applies to all users (and is essentially equivalent to "users: *").

newsgroups:

Users that match this access group are allowed to read and post to all newsgroups matching this comma-separated list of wildmat patterns. The empty string is equivalent to "newsgroups: *"; if this parameter is missing, the connection will be rejected (unless read: and/or post: are used instead, see below).

read:

Like the newsgroups: parameter, but the client is only given permission to read the matching newsgroups. This parameter is often used with post: (below) to specify some read-only groups; it cannot be used in the same access group with a newsgroups: parameter. (If read: is used and post: is missing, the client will have only read-only access.)

post:

Like the newsgroups: parameter, but the client is only given permission to post to the matching newsgroups. This parameter is often used with read: (above) to define the patterns for reading and posting separately (usually to give the user permission to read more newsgroups than they're permitted to post to). It cannot be used in the same access group with a newsgroups: parameter.

access:

A set of letters specifying the permissions granted to the client. The letters are chosen from the following set:

R

The client may read articles.

P

The client may post articles.

I

The client may inject articles with IHAVE. Note that in order to inject articles with the IHAVE command, the user must also have POST permission (the "P" option). Articles injected with IHAVE are treated as though they were injected with POST, that is to say such articles must not have been previously injected (they must not contain headers like Injection-Info:).

A

The client may post articles with Approved: headers (in other words, may approve articles for moderated newsgroups). By default, this is not allowed.

N

The client may use the NEWNEWS command, overriding the global setting.

L

The client may post to newsgroups that are set to disallow local posting (status fields "j", "n" and "x" in the active(5) file).

Note that if this parameter is given, allownewnews in inn.conf is ignored for connections matching this access group and the ability of the client to use NEWNEWS is entirely determined by the presence of "N" in the access string. If you want to support NEWNEWS, make sure to include "N" in the access string when you use this parameter.

Note that if this parameter is given and "R" isn't present in the access string, the client cannot read regardless of newsgroups: or read: parameters. Similarly, if this parameter is given and "P" isn't present, the client cannot post. This use of access: is deprecated and confusing; it's strongly recommended that if the access: parameter is used, "R" and "P" always be included in the access string and newsgroups:, read:, and post: be used to control access. (To grant read access but no posting access, one can have just a read: parameter and no post: parameter.)

key:

If this parameter is present, this access group is only considered when finding privileges for users matching auth groups with this same key: parameter.

reject_with:

If this parameter is present, a client matching this block will be disconnected with a "Permission denied" message containing the contents (a "reason" string) of this parameter. Some newsreaders will then display the reason to the user.

max_rate:

If this parameter is present (and nonzero), it is used for nnrpd's rate-limiting code. The client will only be able to download at this speed (in bytes/second). Note that if an encryption layer is being used, limiting is applied to the pre-encryption datastream.

localtime:

If a Date: or an Injection-Date: header field is not included in a posted article, nnrpd(8) normally adds these header fields in UTC. If this is set to true, the Date: header field will be formatted in local time instead. (The Injection-Date: header field is added according to the behaviour of the addinjectiondate parameter in inn.conf, and will remain in UTC, though.) This is a boolean value and the default is false. This parameter permits handling a relatively unusual corner case. It is mostly a tool for people who want to disclose their local time zone (it can be useful information in certain types of discussions), but whose clients don't for some reason, and who can arrange for the server to be in the same time zone as the client.

newsmaster:

Used as the contact address in the help message returned by nnrpd(8), if the virtualhost: parameter is set to true.

strippath:

If set to true, any Path: header provided by a user in a post is stripped rather than used as the beginning of the Path: header of the article. This is a boolean value and the default is false.

perlfilter:

If set to false, posts made by these users do not pass through the Perl filter even if it is otherwise enabled. This is a boolean value and the default is true.

pythonfilter:

If set to false, posts made by these users do not pass through the Python filter even if it is otherwise enabled. This is a boolean value and the default is true.

virtualhost:

Set this parameter to true in order to make nnrpd behave as if it is running on a server with a different name than it actually is. If you set this parameter to true, you must also set either pathhost: or domain: in the relevant access group in readers.conf to something different than is set in inn.conf. All articles displayed to clients will then have their Path: and Xref: headers altered to appear to be from the server named in pathhost: or domain: (whichever is set), and posted articles will use that server name in the Path:, Message-ID:, and Injection-Info: headers. Note that setting this parameter requires the server modify all posts before presenting them to the client and therefore may decrease performance slightly.

In addition, all of the following parameters are valid in access groups and override the global setting in inn.conf. See inn.conf(5) for the descriptions of these parameters:

```
    addinjectiondate, addinjectionpostingaccount, addinjectionpostinghost,
    backoff_auth, backoff_db, backoff_k, backoff_postfast, backoff_postslow,
    backoff_trigger, checkincludedtext, clienttimeout, complaints, domain,
    fromhost, localmaxartsize, moderatormailer, nnrpdauthsender, nnrpdcheckart,
    nnrpdoverstats, nnrpdposthost, nnrpdpostport, organization, pathhost,
    readertrack, spoolfirst, strippostcc.
```

## SUMMARY
Here's a basic summary of what happens when a client connects:

- All auth groups are scanned and the ones that don't match the client (due to hosts, localaddress, require_ssl, etc.) are eliminated.

- The remaining auth groups are scanned from the last to the first, and an attempt is made to apply it to the current connection. This means running res: programs, if any, and otherwise applying default:. The first auth group (starting from the bottom) to return a valid user is kept as the active auth group.

- If no auth groups yield a valid user (none have default: parameters or successful res: programs) but some of the auth groups have auth: lines (indicating a possibility that the user can authenticate and then obtain permissions), the connection is considered to have no valid auth group (which means that the access groups are ignored completely) but the connection isn't closed. Instead, 480 is returned for everything until the user authenticates.

- When the user authenticates, the auth groups are rescanned, and only the matching ones which contain at least one auth, perl_auth, or python_auth line are considered. These auth groups are scanned from the last to the first, running auth: programs and perl_auth: or python_auth: scripts. The first auth group (starting from the bottom) to return a valid user is kept as the active auth group.

- Regardless of how an auth group is established, as soon as one is, that auth group is used to assign a user identity by taking the result of the successful res, auth, perl_auth, or python_auth line (or the default: if necessary), and appending the default-domain if necessary. (If the perl_access: or python_access: parameter is present, see below.)

- Finally, an access group is selected by scanning the access groups from bottom up and finding the first match. (If the established auth group contained a perl_access: or python_access line, the dynamically generated access group returned by the script is used instead.) User permissions are granted based on the established access group.

## EXAMPLES
Probably the simplest useful example of a complete readers.conf, this gives permissions to read and post to all groups to any connections from the "example.com" domain, and no privileges for anyone connecting elsewhere:

```
    auth example.com {
        hosts: "*.example.com, example.com"
        default: "<EXAMPLE>"
    }
    access full {
        users: "<EXAMPLE>"
        newsgroups: *
    }
```

Note that the above access realm could also be written without the users: key, in which case it applies to any user identity (though in this example, the user identity that will be assigned to all matching connections is "<EXAMPLE>"). It is however recommended to keep an explicit users: key so as to better view to whom the access block applies.

As the only available auth realm only matches hosts in the "example.com" domain, any connections from other hosts will be rejected immediately.

If you have some systems that should only have read-only access to the server, you can modify the example above slightly by adding an additional auth and access group:

```
    auth lab {
        hosts: "*.lab.example.com"
        default: <LAB>
    }
    access lab {
        users: <LAB>
        read: *
    }
```

If those are put in the file after the above example, they'll take precedence (because they're later in the file) for any user coming from a machine in the lab.example.com domain, everyone will only have read access, not posting access.

Here's a similar example for a news server that accepts connections from anywhere but requires the user to specify a username and password. The username and password are first checked against an external database of usernames and passwords, and then against the system shadow password file:

```
    auth all {
        auth: "ckpasswd -d <pathdb in inn.conf>/newsusers"
        auth: "ckpasswd -s"
    }
    access full {
        users: *
        newsgroups: *
    }
```

When the user first connects, there are no res: keys and no default, so they don't receive any valid identity and the connection won't match any access groups (even ones with "users: *"). Such users receive nothing but authentication-required responses from nnrpd until they authenticate.

If they then later authenticate, the username and password are checked first by running ckpasswd with the -d option for an external dbm file of encrypted passwords, and then with the -s option to check the shadow password database (note that this option may require ckpasswd to be setgid to a shadow group, and there are security considerations; see ckpasswd(8) for details). If both of those fail, the user will continue to have no identity; otherwise, an identity will be assigned (usually the supplied username, perhaps with a domain appended, although an authenticator technically can provide a completely different username for the identity), and the access group will match, giving full access.

It may be educational to consider how to combine the above examples; general groups always go first. The order of the auth groups actually doesn't matter, since the "hosts: example.com" one only matches connections before username/password is sent, and the "auth: ckpasswd" one only matches after; order would matter if either group applied to both cases. The order of the access groups in this case does matter, provided the newsgroups: lines differ; the access group with no users: line needs to be first, with the "users: <LOCAL>" group after.

Here's an example of another common case: a server that only allows connections from a local domain and has an additional hierarchy that's password-restricted.

```
    auth "example.com" {
        hosts: "*.example.com"
        auth: "ckpasswd -d <pathdb in inn.conf>/newsusers"
        default: "anonymous"
    }
    access regular {
        newsgroups: "*,!example.restricted.*"
    }
    access full {
        users: "*,!anonymous"
        newsgroups: *
    }
```

In this example, unauthenticated users get the identity "anonymous", which matches only the first access group and hence doesn't get access to the example.restricted.* hierarchy. Anyone who authenticates using a password in the newsusers file gets full access to all groups. However, note that the only authentication block is limited to hostnames in the example.com domain; connections outside of that domain will never be allowed access or an opportunity to authenticate.

Here's a very complicated example. This is for an organization that has an internal hierarchy "example.*" only available to local shell users, who are on machines where identd can be trusted. Dialup users must provide a username and password, which is then checked against RADIUS. Remote users have to use a username and password that's checked against a database on the news server. Finally, the admin staff (users "joe" and "jane") can post anywhere (including the "example.admin.*" groups that are read-only for everyone else), and are exempted from the Perl filter. For an additional twist, posts from dialup users have their Sender: header replaced by their authenticated identity.

Since this organization has some internal moderated newsgroups, the admin staff can also post messages with Approved: headers, but other users cannot.

```
    auth default {
        auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
        default: <FAIL>
        default-domain: example.com
    }
    auth shell {
        hosts: *.shell.example.com
        res: ident
        auth: "ckpasswd -s"
        default: <FAIL>
        default-domain: shell.example.com
    }
    auth dialup {
        hosts: *.dialup.example.com
        auth: radius
        default: <FAIL>
        default-domain: dialup.example.com
    }
    access shell {
        users: *@shell.example.com
        read: *
        post: "*, !example.admin.*"
    }
    access dialup {
        users: *@dialup.example.com
        newsgroups: *,!example.*
        nnrpdauthsender: true
    }
    access other {
        users: "*@example.com, !<FAIL>@example.com"
        newsgroups: *,!example.*
    }
    access fail {
        users: "<FAIL>@*"
        newsgroups: !*
    }
    access admin {
        users: "joe@*,jane@*"
        newsgroups: *
        access: "RPA"
        perlfilter: false
    }
```

Note the use of different domains to separate dialup from shell users easily. Another way to do that would be with key: parameters, but this way provides slightly more intuitive identity strings. Note also that the fail access group catches not only failing connections from external users but also failed authentication of shell and dialup users and dialup users before they've authenticated. The identity string given for, say, dialup users before RADIUS authentication has been attempted matches both the dialup access group and the fail access group, since it's "<FAIL>@dialup.example.com", but the fail group is last so it takes precedence.

The shell auth group has an auth: parameter so that users joe and jane can, if they choose, use username and password authentication to gain their special privileges even if they're logged on as a different user on the shell machines (or if ident isn't working). When they first connect, they'd have the default access for that user, but they could then send AUTHINFO USER and AUTHINFO PASS in order to get their extended access.

Also note that if the users joe and jane are using their own accounts, they get their special privileges regardless of how they connect, whether the dialups, the shell machines, or even externally with a username and password.

Finally, here's a very simple example of a configuration for a public server for a particular hierarchy.

```
    auth default {
        hosts: *
        default: <PUBLIC>
    }
    access default {
        users: <PUBLIC>
        newsgroups: example.*
    }
```

Notice that clients aren't allowed to read any other groups; this keeps them from getting access to administrative groups or reading control messages, just as a precaution. When running a public server like this, be aware that many public hierarchies will later be pulled down and reinjected into the main Usenet, so it's highly recommended that you also run a Perl or Python filter to reject any messages crossposted out of your local hierarchy and any messages containing a Supersedes: header. This will keep messages posted to your public hierarchy from hurting any of the rest of Usenet if they leak out.

## SECURITY CONSIDERATIONS
In general, separate passwords should be used for NNTP wherever possible; the NNTP protocol itself does not protect passwords from casual interception, and many implementations (including this one) do not "lock out" accounts or otherwise discourage password-guessing attacks. So it is best to ensure that a compromised password has minimal effects.

Authentication using the AUTHINFO USER/PASS commands passes unencrypted over the network. Extreme caution should therefore be used especially with system passwords (e.g. "auth: ckpasswd -s"). Passwords can be protected by using NNTP over TLS/SSL or through ssh tunnels, and this usage can be enforced by a well-considered server configuration that only permits certain auth groups to be applied in certain cases. One can also authenticate using a strong SASL mechanism. Here are some ideas:

- To restrict connections on the standard NNTP port (119) to use an encryption layer for some (or all) of the auth groups to match, use the require_ssl parameter. Note that a client can use STARTTLS to negotiate an encrypted TLS connection. A secure layer can also be negotiated during authentication via AUTHINFO SASL.

- If you consider your local network (but not the internet) secure, have some auth groups with a restrictive hosts: parameter; they would go above, with ones having global applicability below.

- Consider running nnrpd with the -S flag (either also with -D, or out of "super-server" like inetd) on the NNTPS port (563) for clients that support TLS/SSL. See nnrpd(8) for more details about how to configure that. You can use the require_ssl parameter or the -c flag to specify an alternate readers.conf file if you want a substantially different configuration for this case.

- If you want to restrict an auth group to only match loopback connections (for users running newsreaders on localhost or connecting via an ssh tunnel), use the localaddress: parameter.

## HISTORY
Written by Aidan Cully <aidan@panix.com> for InterNetNews. Substantially expanded by Russ Allbery <eagle@eyrie.org>.

$Id: readers.conf.pod 10283 2018-05-14 12:43:05Z iulius $

## SEE ALSO
auth_krb5(8), ckpasswd(8), inn.conf(5), innd(8), newsfeeds(5), nnrpd(8), uwildmat(3).


storage.conf

package: inn

title: storage.conf(5)

summary: Configuration file for storage manager

text:
# storage.conf(5)

## NAME
storage.conf - Configuration file for storage manager

## DESCRIPTION
The file pathetc/storage.conf contains the rules to be used in assigning articles to different storage methods. These rules determine where incoming articles will be stored.

The storage manager is a unified interface between INN and a variety of different storage methods, allowing the news administrator to choose between different storage methods with different trade-offs (or even use several at the same time for different newsgroups, or articles of different sizes). The rest of INN need not care what type of storage method was used for a given article; the storage manager will figure this out automatically when that article is retrieved via the storage API. Note that you may also want to see the options provided in inn.conf(5) regarding article storage.

The storage.conf file consists of a series of storage method entries. Blank lines and lines beginning with a number sign ("#") are ignored. The maximum number of characters in each line is 255. The order of entries in this file is important, see below.

Each entry specifies a storage method and a set of rules. Articles which match all of the rules of a storage method entry will be stored using that storage method; if an article matches multiple storage method entries, the first one will be used. Each entry is formatted as follows:

```
    method <methodname> {
        class: <storage_class>
        newsgroups: <wildmat>
        size: <minsize>[,<maxsize>]
        expires: <mintime>[,<maxtime>]
        options: <options>
        exactmatch: <bool>
    }
```

If spaces or tabs are included in a value, that value must be enclosed in double quotes (""). If either a number sign ("#") or a double quote are meant to be included verbatim in a value, they should be escaped with "\".

<methodname> is the name of a storage method to use for articles which match the rules of this entry. The currently available storage methods are:

```
    cnfs
    timecaf
    timehash
    tradspool
    trash
```

See the "STORAGE METHODS" section below for more details.

The meanings of the keys in each storage method entry are as follows:

class: <storage_class>

An identifier for this storage method entry. <storage_class> should be a number between 0 and 255. It should be unique across all of the entries in this file. It is mainly used for specifying expiration times by storage class as described in expire.ctl(5); "timehash" and "timecaf" will also set the top-level directory in which articles accepted by this storage class are stored. The assignment of a particular number to a storage class is arbitrary but permanent (since it is used in storage tokens). Storage classes can be for instance numbered sequentially in storage.conf.

newsgroups: <wildmat>

What newsgroups are stored using this storage method. <wildmat> is a uwildmat(3) pattern which is matched against the newsgroups an article is posted to. If storeonxref in inn.conf is true, this pattern will be matched against the newsgroup names in the Xref: header; otherwise, it will be matched against the newsgroup names in the Newsgroups: header (see inn.conf(5) for discussion of the differences between these possibilities). Poison wildmat expressions (expressions starting with "@") are allowed and can be used to exclude certain group patterns: articles crossposted to poisoned newsgroups will not be stored using this storage method. The <wildmat> pattern is matched in order. There is no default newsgroups pattern; if an entry should match all newsgroups, use an explicit "newsgroups: *".

size: <minsize>[,<maxsize>]

A range of article sizes (in bytes) which should be stored using this storage method. If <maxsize> is 0 or not given, the upper size of articles is limited only by maxartsize in inn.conf. The size: field is optional and may be omitted entirely if you want articles of any size to be stored in this storage method (if, of course, these articles fulfill all the other requirements of this storage method entry). By default, <minsize> is set to 0.

expires: <mintime>[,<maxtime>]

A range of article expiration times which should be stored using this storage method. Be careful; this is less useful than it may appear at first. This is based only on the Expires: header of the article, not on any local expiration policies or anything in expire.ctl! If <mintime> is non-zero, then this entry will not match any article without an Expires: header. This key is therefore only really useful for assigning articles with requested longer expire times to a separate storage method. Articles only match if the time until expiration (that is to say, the amount of time into the future that the Expires: header of the article requests that it remain around) falls in the interval specified by <mintime> and <maxtime>. The format of these parameters is "0d0h0m0s" (days, hours, minutes, and seconds into the future). If <maxtime> is "0s" or is not specified, there is no upper bound on expire times falling into this entry (note that this key has no effect on when the article will actually be expired, but only on whether or not the article will be stored using this storage method). This field is also optional and may be omitted entirely if you do not want to store articles according to their Expires: header, if any.

A <mintime> value greater than "0s" implies that this storage method won't match any article without an Expires: header.

options: <options>

This key is for passing special options to storage methods that require them (currently only "cnfs"). See the "STORAGE METHODS" section below for a description of its use.

exactmatch: <bool>

If this key is set to true, all the newsgroups in the Newsgroups: header of incoming articles will be examined to see if they match newsgroups patterns. (Normally, any non-zero number of matching newsgroups is sufficient, provided no newsgroup matches a poison wildmat as described above.) This is a boolean value; "true", "yes" and "on" are usable to enable this key. The case of these values is not significant. The default is false.

If an article matches all of the constraints of an entry, it is stored via that storage method and is associated with that <storage_class>. This file is scanned in order and the first matching entry is used to store the article.

If an article does not match any entry, either by being posted to a newsgroup which does not match any of the <wildmat> patterns or by being outside the size and expires ranges of all entries whose newsgroups pattern it does match, the article is not stored and is rejected by innd. When this happens, the error message:

```
    cant store article: no matching entry in storage.conf
```

is logged to syslog. If you want to silently drop articles matching certain newsgroup patterns or size or expires ranges, assign them to the "trash" storage method rather than having them not match any storage method entry.

## STORAGE METHODS
Currently, there are five storage methods available. Each method has its pros and cons; you can choose any mixture of them as is suitable for your environment. Note that each method has an attribute EXPENSIVESTAT which indicates whether checking the existence of an article is expensive or not. This is used to run expireover(8).

cnfs

The "cnfs" storage method stores articles in large cyclic buffers (CNFS stands for Cyclic News File System). Articles are stored in CNFS buffers in arrival order, and when the buffer fills, it wraps around to the beginning and stores new articles over the top of the oldest articles in the buffer. The expire time of articles stored in CNFS buffers is therefore entirely determined by how long it takes the buffer to wrap around, which depends on how quickly data is being stored in it. (This method is therefore said to have self-expire functionality. It also means that when an article is cancelled, the cycbuff doesn't go back and use space until it rolls over and the whole cycbuff starts being reused.) EXPENSIVESTAT is false for this method. CNFS has its own configuration file, cycbuff.conf, which describes some subtleties to the basic description given above. Storage method entries for the "cnfs" storage method must have an options: field specifying the metacycbuff into which articles matching that entry should be stored; see cycbuff.conf(5) for details on metacycbuffs.

Advantages: By far the fastest of all storage methods (except for "trash"), since it eliminates the overhead of dealing with a file system and creating new files. Unlike all other storage methods, it does not require manual article expiration. With CNFS, the server will never throttle itself due to a full spool disk, and groups are restricted to just the buffer files given so that they can never use more than the amount of disk space allocated to them.

Disadvantages: Article retention times are more difficult to control because old articles are overwritten automatically. Attacks on Usenet, such as flooding or massive amounts of spam, can result in wanted articles expiring much faster than intended (with no warning).

timecaf

This method stores multiple articles in one file, whose name is based on the article's arrival time and the storage class. The file name will be:

```
    <patharticles>/timecaf-nn/bb/aacc.CF

```

where "nn" is the hexadecimal value of <storage_class>, "bb" and "aacc" are the hexadecimal components of the arrival time, and "CF" is a hardcoded extension. (The arrival time, in seconds since the epoch, is converted to hexadecimal and interpreted as 0xaabbccdd, with "aa", "bb", and "cc" used to build the path.) This method does not have self-expire functionality (meaning expire has to run periodically to delete old articles, as well as cancelled articles if immediatecancel is not set to true in inn.conf). EXPENSIVESTAT is false for this method.

Advantages: It is roughly four times faster than "timehash" for article writes, since much of the file system overhead is bypassed, while still retaining the same fine control over article retention time.

Disadvantages: Using this method means giving up all but the most careful manually fiddling with the article spool; in this aspect, it looks like "cnfs". As one of the newer and least widely used storage types, "timecaf" has not been as thoroughly tested as the other methods.

timehash

This method is very similar to "timecaf" except that each article is stored in a separate file. The name of the file for a given article will be:

```
    <patharticles>/time-nn/bb/cc/yyyy-aadd

```

where "nn" is the hexadecimal value of <storage_class>, "yyyy" is a hexadecimal sequence number, and "bb", "cc", and "aadd" are components of the arrival time in hexadecimal (the arrival time is interpreted as documented above under "timecaf"). This method does not have self-expire functionality. Cancelled articles are removed immediately. EXPENSIVESTAT is true for this method.

Advantages: Heavy traffic groups do not cause bottlenecks, and a fine control of article retention time is still possible.

Disadvantages: The ability to easily find all articles in a given newsgroup and manually fiddle with the article spool is lost, and INN still suffers from speed degradation due to file system overhead (creating and deleting individual files is a slow operation).

tradspool

Traditional spool, or "tradspool", is the traditional news article storage format. Each article is stored in an individual text file named:

```
    <patharticles>/news/group/name/nnnnn

```

where "news/group/name" is the name of the newsgroup to which the article was posted with each period changed to a slash, and "nnnnn" is the sequence number of the article in that newsgroup. For crossposted articles, the article is linked into each newsgroup to which it is crossposted (using either hard or symbolic links). This is the way versions of INN prior to 2.0 stored all articles, as well as being the article storage format used by C News and earlier news systems. This method does not have self-expire functionality. Cancelled articles are removed immediately. EXPENSIVESTAT is true for this method.

Advantages: It is widely used and well-understood; it can read article spools written by older versions of INN and it is compatible with all third-party INN add-ons. This storage mechanism provides easy and direct access to the articles stored on the server and makes writing programs that fiddle with the news spool very easy, and gives fine control over article retention times.

Disadvantages: It takes a very fast file system and I/O system to keep up with current Usenet traffic volumes due to file system overhead. Groups with heavy traffic tend to create a bottleneck because of inefficiencies in storing large numbers of article files in a single directory. It requires a nightly expire program to delete old articles out of the news spool, a process that can slow down the server for several hours or more.

trash

This method silently discards all articles stored in it. Its only real uses are for testing and for silently discarding articles matching a particular storage method entry (for whatever reason). Articles stored in this method take up no disk space and can never be retrieved, so this method has self-expire functionality of a sort. EXPENSIVESTAT is false for this method.

## EXAMPLES
The following sample storage.conf file would store all articles posted to alt.binaries.* in the "BINARIES" CNFS metacycbuff, all articles over roughly 50 KB in any other hierarchy in the "LARGE" CNFS metacycbuff, all other articles in alt.* in one timehash class, and all other articles in any newsgroups in a second timehash class, except for the internal.* hierarchy which is stored in traditional spool format.

```
    method tradspool {
        class: 1
        newsgroups: internal.*
    }
    method cnfs {
        class: 2
        newsgroups: alt.binaries.*
        options: BINARIES
    }
    method cnfs {
        class: 3
        newsgroups: *
        size: 50000
        options: LARGE
    }
    method timehash {
        class: 4
        newsgroups: alt.*
    }
    method timehash {
        class: 5
        newsgroups: *
    }
```

Notice that the last storage method entry will catch everything. This is a good habit to get into; make sure that you have at least one catch-all entry just in case something you did not expect falls through the cracks. Notice also that the special rule for the internal.* hierarchy is first, so it will catch even articles crossposted to alt.binaries.* or over 50 KB in size.

As for poison wildmat expressions, if you have for instance an article crossposted between misc.foo and misc.bar, the pattern:

```
    misc.*,!misc.bar
```

will match that article whereas the pattern:

```
    misc.*,@misc.bar
```

will not match that article. An article posted only to misc.bar will fail to match either pattern.

Usually, high-volume groups and groups whose articles do not need to be kept around very long (binaries groups, *.jobs*, news.lists.filters, etc.) are stored in CNFS buffers. Use the other methods (or CNFS buffers again) for everything else. However, it is as often as not most convenient to keep in "tradspool" special hierarchies like local hierarchies and hierarchies that should never expire or through the spool of which you need to go manually.

## HISTORY
Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews. Rewritten into POD by Julien Elie.

$Id: storage.conf.pod 10230 2018-01-28 21:22:21Z iulius $

## SEE ALSO
cycbuff.conf(5), expire.ctl(5), expireover(8), inn.conf(5), innd(8), uwildmat(3).


subscriptions

title: subscriptions(5)

summary: Default recommended subscriptions

text:
# subscriptions(5)

## NAME
subscriptions - Default recommended subscriptions

## DESCRIPTION
The pathetc/subscriptions file contains a list of newsgroups that is returned by the NNTP command LIST SUBSCRIPTIONS.

Clients that support this command usually send it the first time they connect to a new news server. They use the returned list to initialize the list of subscribed newsgroups. The subscriptions file therefore should contain groups intended for new users, for testing, or that contain FAQs and other useful information for first-time Usenet users.

The syntax of the subscriptions file is trivial; it is a simple list of newsgroup names, one per line. The order of newsgroups may be significant; the news reading client may present the groups in that order to the user.

Be aware that use of the LIST SUBSCRIPTIONS command is not widespread (though documented in RFC 6048) and most news clients will never ask for this file.

## EXAMPLE
A typical subscriptions file may look like:

```
    news.announce.newusers
    news.newusers.questions
    local.test
    local.general
    local.talk
    misc.test
    misc.test.moderated
    news.answers
    news.announce.newgroups
```

This gives the client the FAQs and question newsgroup for new users first, then a local newsgroup for testing and various commonly-read local discussion groups, followed by the world-wide test groups, all the FAQs, and announcements of new world-wide newsgroups. If there is a local new users group, one might want to list it first.

## HISTORY
Written by Bettina Fink <laura@hydrophil.de> for InterNetNews.

$Id: subscriptions.pod 9137 2010-10-29 18:09:12Z iulius $

## SEE ALSO
nnrpd(8).


ipcad.conf

package: ipcad

title: ipcad.conf(5)

summary: ipcad configuration file

text:
# ipcad.conf(5)

## NAME
ipcad.conf — ipcad configuration file

## SYNOPSIS
/usr/local/etc/ipcad.conf

## DESCRIPTION
The file /usr/local/etc/ipcad.conf contains configuration information for the ipcad(8) daemon. The ipcad.conf file consists of a series of configuration options describing the interfaces on which ipcad should be listening and other configuration data.

### Global configuration
capture-ports { enable | disable };

Make ipcad account for UDP/TCP ports, IP protocol and ICMP types on a per-interface basis. This setting is relevant for RSH and interactive export methods only. Capturing UDP and TCP is disabled by default to maintain historic RSH output format compatibility. To selectively enable capturing ports on certain interfaces, specify the capture-ports between the appropriate interface configuration statements.

buffers = <number> [{ k | m }] ;

Defines a buffer size to use for transferring the data from the kernel. Using larger buffers may increase the performance by lowering the number of expensive context switches, whereas using smaller values improves responsiveness. NOTE: This option has no effect on NetFlow operation.

### Interface configuration
interface <face> [promisc] [input-only] [netflow-sampled] [netflow-disable] [filter "<pcap_filter>"] ;

Listen on specified interface using BPF or PCAP packet source. (Please refer to the Interface options section below).

interface ulog group <group> [, group <group> ...] [netflow-sampled] [netflow-disable] ;

Use Linux iptables' ULOG interface for packet capturing. You should configure the iptables to forward the packets into the appropriate group:

```
iptables -A OUTPUT -j ULOG --ulog-nlgroup <group>
```

### Interface options:
promisc: Put interface into promiscuous mode. This enables listening for the packets which are not destined for this host and thus ipcad will count and display all the traffic within the local network. Note that the interface might be in promiscuous mode for some other reason.

input-only: Use kernel feature of counting only incoming packets.

NOTE: "input-only" directive must be supported by kernel. Probably, you were noticed about it during the compilation process if it was not supported. FreeBSD 3.x and elder kernels do not support this feature.

netflow-sampled: If the NetFlow export mechanism is used, this option instructs the interface to supply only one out of N packets to the NetFlow accounting code, thus lowering the CPU and memory requirements. The value of N is configured explicitly in a NetFlow configuration section.

NOTE: This option is NOT used to enable NetFlow on the interface, it just modifies the NetFlow behavior on this interface.

netflow-disable: By default, all interfaces are included into NetFlow accounting. This option is used to disable NetFlow accounting on a particular interface.

filter: Install a custom filter on packets instead of basic IP protocol filter. Requires libpcap (even if BPF is being used). May be employed to eliminate CPU overhead on passing unnecessary data between the kernel and user space (by installing the filter directly into the kernel).

### IP aggregation
aggregate <ip>/<masklen> strip <maskbits>;

Aggregate addresses from the specified network (<ip>/<masklen>), by AND'ing with specified mask (<maskbits>). Use of aggregation helps to save memory space and recomendeed for efficiency.

aggregate <port_from>-<port_to> into <port>;

aggregate <port> into <port>;

Aggregate specified UDP/TCP ports range into a given port number. Use of aggregation helps to save memory space and recomendeed for efficiency.

### RSH server configuration
rsh { enable | disable } [at <listen_ip>];

Enable/disable RSH server (disabled by default). Optionally, a server's IP address may be specified.

rsh [[<user>@]<host_addr>] [access] ;

Specifies an rsh access list entry. access values are: admin Can shutdown ipcad

backup Can dump/restore/import accounting tables

default Can view and modify accounting tables

view-only Can view accounting tables

deny Deny all activity

rsh ttl = <ttl>;

Keep the IP time to live (TTL) value reasonably low to lower the possibility of remote attacks. Default is 3. This means that if you are trying to gather IP accounting from a distant (a few network "hops", see traceroute(1)) ipcad server using RSH, such attempts may fail.

rsh timeout = <seconds>;

Set rsh timeout for the same purpose.

dumpfile = <filename>;

Dump memory table to this file on exit and read on startup (refer to ipcad(8) and read about -s and -r options). NOTE: This setting has no effect on NetFlow operation. The contents of the flow cache are flushed to the collector upon ipcad termination.

### NetFlow export configuration
netflow export destination <collector-ip> <collector-port>;

Enable NetFlow information export to the specified destination. By default, ipcad does not export NetFlow information.

netflow export version { 1 | 5 };

Specify the NetFlow export format version. By default, version 5 is used.

netflow export timeout active <time-minutes>;

Configure the timer to expire active flows after the given value in minutes.

netflow export timeout inactive <time-seconds>;

Configure the timer to expire inactive flows after the given value in seconds.

### Other options:
memory_limit = <number> [{ k | m | e }] ;

Defines a memory limit for storing the per-stream associations. Shortcuts are for kilobytes, megabytes or entries respectively.

chroot = </path>;

Chroot to this directory before processing.

uid = <number>;

Set this uid to be safe in the long run. Please change it if you're aware of the consequences. RSH service will NOT work if process is not privileged. Default is to not to change privileges.

gid = <number>;

Set this gid to be safe in the long run. Default is not to change privileges.

pidfile = <filename>;

File to keep the process PID in it. ipcad will also hold a lock. Creation of the PID file is done after chroot()'ing.

## SEE ALSO
ipcad(8).

## AUTHORS
Lev Walkin <vlm@lionet.info>


package: ir-keytable

title: rc_keymap(5)

text:
# rc_keymap(5)

## NAME
rc_keymap - toml file describing remote control keymap

## DESCRIPTION
An rc_keymap describes a remote control. It list the protocols used, and the mapping from decoded IR to linux input keycodes. This file is used by ir-keytable(1) for IR decoding, and by ir-ctl(1) for sending IR.

The file format is toml. Since a remote control can use multiple protocols, the top level is an array of protocols. The vast majority of remotes only use one protocol.

## KEYMAP PROTOCOL ENTRY
For each protocol the remote uses, there should be one entry in the top level protocols array.

### Name Field
Each protocols entry has a name field. The name is not used by ir-keytable or ir-ctl, but can be used to give the remote control a more descriptive name than the file name, e.g. the model number.

### Protocol Field
The protocol field specifies the protocol. This can either be one of the linux kernel decoders, in which case it is nec, rc-5, rc-6, jvc, sony, sanyo, rc-5-sz, sharp, mce-kbd, xmp, imon, rc-mm, other or unknown. If it does not match any of these entries, then it is assumed to be a BPF based decoder. The unknown and other are protocols decoded by specific RC devices where the protocol is either unknown or proprietary, respectively.

There are some pre-defined BPF protocol decoders, which are listed below. See https://lwn.net/Articles/759188/ for how to write your own.

### Variant Field
The variant field specifies which variant a particular protocol uses. The sony, rc-5, rc-6 protocols have different bit length variants, for example. This field is used by ir-ctl when sending IR.

The following variants are currently defined:

Protocol rc-5 has variants rc-5, rc-5x-20, rc-5-sz.

Protocol nec has variants nec, nec-x, nec-32.

Protocol sony has variants sony-12, sony-15, sony-20.

Protocol rc-6 has variants rc-6-0, rc-6-6a-20, rc-6-6a-24, rc-6-6a-32, rc-6-mce.

Protocol rc-mm has variants rc-mm-12, rc-mm-24, and rc-mm-32.

### Scancodes field
The scancodes table list the scancodes and the mapping to linux input keycode. Multiple scancodes can map to the same keycode. The scancodes field is not present for raw protocols.

If the scancode start with 0x, it is interpreted as a hexadecimal number. If it starts with a 0, it is interpreted as an octal number.

Valid keycodes are listed in the input-event-codes.h header file. Examples are KEY_ENTER, KEY_ESC or BTN_LEFT for the left mouse button. Note that if the keymap is only used for sending IR, then the key does not have to be a valid linux keycode. It can be any string without whitespace.

### Raw field
If the protocol is raw, the raw field is an array of keycode to raw mapping. For each entry, there is a keycode field and raw field. The keycode is a linux input keycode, as explained in the scancodes field above.

The raw field is an string, which lists pulse and space values, separated by whitespace. The first is a pulse value microseconds, and the second a space, third pulse, etc. The space values can be preceded by a - sign and the pulse value can be preceded by a +sign. There should be an odd number of value so that the last entry is a pulse.

### Remaining fields (BPF parameters)
If the protocol is a BPF based decoder, it may have any number of numeric parameters. These parameters are used to support protocols with non-standard signaling lengths for standard IR protocols. Any other field specified here which is required by the selected BPF decoder will be used. All other fields are ignored.

Kernel based non-BPF protocol decoders do not have any parameters.

## BPF PROTOCOLS
Some of the BPF protocol decoders are generic and will need parameters to work. Other are for specific remotes and should work without any parameters. The timing parameters are all in microseconds (µs).

### raw
This decoder must be used when the keymap is raw; for each key, there is an entry in raw array with the pulse and space values for that key. No decoding is done, the incoming IR is simply matched against the different pulse and space values.

### imon_rsc
This decoder is specifically for the iMON RSC remote, which was packaged with the iMON Station (amongst others). The decoder is for the directional stick in the middle; it will decode them into mouse movements. The buttons are all encoded using nec-x so the keymap needs two protocols to work correctly.

This is unrelated to the imon protocol.

margin

Define how much tolerance there is for message length. Default 200.

### grundig
This decoder is specifically for old grundig remotes.

header_pulse

Length of first pulse, default 900.

header_space

Length of following space, default 2900.

leader_pulse

Length of second pulse, default 1300.

### xbox
This decoder is specifically for the XBox Remote DVD, which is for the first generation XBox.

margin

Define how much tolerance there is for message length. Default 200.

### manchester
Most manchester encoded remote controls are either rc-5, rc-6, or rc-mm. Some remote use a different variant (e.g. they might have a header pulse) and that is what the decoder is for. Some parameters must be specified, by default it is set up for rc-5.

margin

Define how much tolerance there is for message length. Default 200.

header_pulse

Define how long a leading pulse is. This is not always present. Default 0.

header_space

Define how long the space is after the leading pulse. Must be set if header_pulse is set.

zero_pulse, zero_space, one_pulse, one_space

Signally lengths for bits. See https://clearwater.com.au/code/rc5 for these are defined.

bits

Number of bits. Default 14.

scancode_mask

Bits to mask out of resulting scancode.

toggle_bit

Bit that specifies the toggle. If this value is greater than the number of bits, no toggle is defined.

### pulse_distance
This is a generic decoder for protocols that define bits by distance between pulses, and the pulses are always of the same length. The most well known protocol like this is nec. This decoder is cases where nec is not used. The parameters must be set.

margin

Define how much tolerance there is for message length. Default 200.

header_pulse

Length of the first leading pulse. Default 2125.

header_space

Length of the space after the leading pulse. Default 1875.

repeat_pulse

Length of the leading pulse for key repeat. Default 0.

repeat_space

Length of the space after the leading pulse for key repeat. Default 0.

bit_pulse

Length of the pulse for each bit. Default 625.

bit_0_space

Length of the space for a zero bit. Default 375.

bit_1_space

Length of the space for a one bit. Default 1625.

trailer_pulse

Length of the pulse after the last bit. Needed to bookend the last bit. Default 625.

bits

Number of bits. Default 4.

reverse

Should the bits be read in least significant bit first. Set to non-zero to enable. Default 0.

header_optional

Some remotes do not send the header pulse and space for key repeats, so set this to non-zero to make the header optional. Default 0. An alternative implementation might only allow missing headers for repeat messages, but this would fail to decode key presses if the first message with the header did not decode correctly to due interference.

### pulse_length
This is a generic decoder for protocols that define bits by length of pulses, and the spaces are always the same. The sony protocol is the most well-known protocol, but this decoder is for protocols which are not sony.

margin

Define how much tolerance there is for message length. Default 200.

header_pulse

Length of the first leading pulse. Default 2125.

header_space

Length of the space after the leading pulse. Default 1875.

repeat_pulse

Length of the leading pulse for key repeat. Default 0.

repeat_space

Length of the space after the leading pulse for key repeat. Default 0.

bit_space

Length of the space for each bit. Default 625.

bit_0_pulse

Length of the pulse for a zero bit. Default 375.

bit_1_pulse

Length of the pulse for a one bit. Default 1625.

trailer_pulse

Length of the pulse after the last bit. Optional. Default 0.

bits

Number of bits. Default 4.

reverse

Should the bits be read in least significant bit first. Set to non-zero to enable. Default 0.

header_optional

Some remotes do not send the header pulse and space for key repeats, so set this to non-zero to make the header optional. Default 0. An alternative implementation might only allow missing headers for repeat messages, but this would fail to decode key presses if only the first message did not decode correctly to due interference.

## EXAMPLE

```
[[protocols]]
name = "iMON Station RSC"
protocol = "nec"
variant = "necx"
[protocols.scancodes]
0x801010 = "KEY_EXIT"
0x80102f = "KEY_POWER"
0x80104a = "KEY_SCREENSAVER"
0x801049 = "KEY_TIME"
0x801054 = "KEY_NUMERIC_1"
0x801055 = "KEY_NUMERIC_2"
0x801056 = "KEY_NUMERIC_3"
0x801057 = "KEY_NUMERIC_4"
0x801058 = "KEY_NUMERIC_5"
0x801059 = "KEY_NUMERIC_6"
0x80105a = "KEY_NUMERIC_7"
0x80105b = "KEY_NUMERIC_8"
0x80105c = "KEY_NUMERIC_9"
0x801081 = "KEY_SCREEN"
0x80105d = "KEY_NUMERIC_0"
0x801082 = "KEY_MAX"
0x801048 = "KEY_ESC"
0x80104b = "KEY_MEDIA"
0x801083 = "KEY_MENU"
0x801045 = "KEY_APPSELECT"
0x801084 = "KEY_STOP"
0x801046 = "KEY_CYCLEWINDOWS"
0x801085 = "KEY_BACKSPACE"
0x801086 = "KEY_KEYBOARD"
0x801087 = "KEY_SPACE"
0x80101e = "KEY_RESERVED"
0x801098 = "BTN_0"
0x80101f = "KEY_TAB"
0x80101b = "BTN_LEFT"
0x80101d = "BTN_RIGHT"
0x801016 = "BTN_MIDDLE"
0x801088 = "KEY_MUTE"
0x80105e = "KEY_VOLUMEDOWN"
0x80105f = "KEY_VOLUMEUP"
0x80104c = "KEY_PLAY"
0x80104d = "KEY_PAUSE"
0x80104f = "KEY_EJECTCD"
0x801050 = "KEY_PREVIOUS"
0x801051 = "KEY_NEXT"
0x80104e = "KEY_STOP"
0x801052 = "KEY_REWIND"
0x801053 = "KEY_FASTFORWARD"
0x801089 = "KEY_ZOOM"
[[protocols]]
protocol = "imon_rsc"
```

## BUGS
Report bugs to Linux Media Mailing List <linux-media@vger.kernel.org>

## COPYRIGHT
Copyright (C) 2019 by Sean Young <sean@mess.org>

License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

## SEE ALSO
ir-keytable(1) and ir-ctl(1)

https://lwn.net/Articles/759188/

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/input-event-codes.h#n64


sane-epkowa

package: iscan-free

title: sane-epkowa(5)

text:
# sane-epkowa(5)

## NAME
sane-epkowa - SANE backend for EPSON scanners

## DESCRIPTION
The sane-epkowa library implements a SANE (Scanner Access Now Easy) backend that provides access to a large number of EPSON devices. A list with supported device information may be found in the iscan-data package's documentation directory, typically /usr/share/doc/iscan-data/.

## OPTIONS
The options the backend supports can either be selected through command line options to programs like scanimage or through GUI elements in xscanimage or xsane.

Valid command line options and their syntax can be listed by using

scanimage --help -d epkowa

Not all devices support all options and not all options may be docmented below. Scan Mode

The --mode switch selects the basic mode of operation of the scanner valid choices are Binary, Gray and Color. The Binary mode is black and white only, Gray will produce up to 256 levels of gray and Color means 24 bit color mode. Some scanners will internally use 36 bit color, the external interface however does only support 24 bits. The --halftoning switch selects the mode that is used in Binary mode. Valid options are None, Halftone A (Hard Tone), Halftone B (Soft Tone), Halftone C (Net Screen), Dither A (4x4 Bayer), Dither B (4x4 Spiral), Dither C (4x4 Net Screen), Dither D (8x4 Net Screen), Text Enhanced Technology, Download pattern A, and Download pattern B.

The --dropout switch selects the so called dropout color. Valid options are None, Red, Green and Blue. The default is None. The dropout color is used for monochrome scanning and selects the color that is not scanned. This can be used to e.g. scan an original with a colored background.

The --brightness switch controls the brightness of the scan. Valid options are the numbers from -3 to 3. The default is 0. The larger the brightness value, the brighter the image gets. If a user defined table for the gamma correction is selected, the brightness parameter is not available.

The --sharpness switch sets the sharpness of the image data. Valid options are the numbers from -2 to 2, with -2 meaning "Defocus", -1 "Defocus slightly", 0 "Normal", 1 "Sharpen slighly" and 2 "Sharpen".

The --gamma-correction switch controls the scanner's internal gamma correction. Valid options are "Default", "User defined", "High density printing" "Low density printing" and "High contrast printing".

The --color-correction switch controls the scanner's internal color correction function. Valid options are "No Correction", "Impact-dot printers", "Thermal printers", "Ink-jet printers" and "CRT monitors". The default is "CRT monitors".

The --resolution switch selects the resolution for a scan. Many EPSON scanners will scan in any resolution between the lowest and highest possible value. The list reported by the scanner can be displayed using the "--help -d epkowa" parameters to scanimage.

The --mirror option controls the way the image is scanned. By reading the image data from right to left the image is mirored. Valid options are "yes" and "no". The default is "no".

The --speed option can improve the scan speed in monochrome mode. Valid options are "yes" or "no", the "yes" option will speed up the scan if this option is supported.

The --auto-area-segmentation switch turns on the automatic area segmentation for monochrome scans. The scanner will try to determine which areas are text and which contain images. The image areas will be halftoned, and the text will be impoved. Valid options are "yes" and "no". The default is "yes".

The --gamma-table parameter can be used to download a user defined gamma table. The options takes 256 values from the range 0..255. In color mode this option equally affects the red, green, and blue channel.

The --red-gamma-table parameter can be used to download a user defined gamma table for the red channel. The valid options are the same as for --gamma-table.

The --green-gamma-table parameter can be used to download a user defined gamma table for the green channel. The valid options are the same as for --gamma-table.

The --blue-gamma-table parameter can be used to download a user defined gamma table for the blue channel. The valid options are the same as for --gamma-table.

The color correction coefficients --cct-1 --cct-2 --cct-3 ... --cct-9 will install color correction coefficients for the user defined color correction. Possible values are in the range -127..127.

The --preview option requests a preview scan. The frontend software automatically selects a low resolution. Valid options are "yes" and "no". The default is "no".

The --preview-speed options will increase the scan speed if this is supported by the scanner. Valid options are "yes" and "no", the default is "no".

The geometry options -l -t -x -y control the scan area: -l sets the top left x coordinate, -t the top left y coordinate, -x selects the width and -y the height of the scan aea. All parameters are specified in milimeters.

The --quick-format option lets the user select a scan area with predefined sizes. Valid parameters are "CD", "A5 portrait", "A5 landscape", "Letter", "A4" and "max". The default is "max", which selects the largest possible area.

The --source option selects the scan source. Valid options depend on the installed options. The default is "Flatbed".

The --auto-eject option will eject a page after scanning from the document feeder.

## CONFIGURATION FILE
The configuration file /etc/sane.d/epkowa.conf specifies the device(s) that the backend will use. Possible connection types are:

USB

All supported USB devices should be recognised automatically when the "usb" keyword is specified. You may have to add yourself to a specific system group though to get the privileges required to access the device. See the configuration file for information on how to get unsupported devices recognised.

SCSI

The "scsi" keyword activates detection of supported SCSI devices. If your device is not recognised despite this see the configuration file for more information.

More extensive documentation is available in the comments of the

default configuration file.

## FILES
/usr/lib64/sane/libsane-epkowa.a

The static library implementing this backend.

/usr/lib64/sane/libsane-epkowa.so

The shared library implementing this backend (present on systems that support dynamic loading).

## ENVIRONMENT
SANE_DEBUG_EPKOWA

If the library was compiled with debug support enabled, this environment variable controls the debug level for this backend. The following, case insensitive string literals are supported (in increasing level of feedback): FATAL, MAJOR, MINOR, INFO, CALL, DATA, CMD, HEX, IMG. Note that the last level includes the raw image data as obtained from the scanner and produces vast amounts of output. For most trouble shooting situations, the HEX level is sufficient.

SANE_EPSON_CMD_LVL

This allows to override the function or command level that the backend uses to communicate with the scanner. The function level a scanner supports is determined during the initialization of the device. If the backend does not recognize the function level reported by the scanner it will default to function level B5. Valid function levels include A1, A2, B1, B2, B3, B4, B5, B6, B7, B8, D1, D2, D7, D8 and F5. Use this feature only if you know what you are doing!

## SEE ALSO
sane-scsi(5), scanimage(1), xscanimage(1), xsane(1)

## BUGS
Sometimes the scanner is not initialized correctly. The problem can be resolved by killing the program and restarting it again.

## UNSUPPORTED DEVICES
Note that a number of EPSON scanners require a non-free plugin before they can be used by the backend.

The backend may be used with EPSON scanners that are not yet listed under the list of supported devices. A scanner that is not recognized may default to the function level B3, which means that not all functions that the scanner may be capable of are accessible.

If the scanner is not even recognized as an EPSON scanner it is probably because the device info reported by the scanner is not in the correct format. Please send this information to the sane-devel mailing list.

## AUTHOR
AVASYS CORPORATION


iwpmd.conf

package: iwpmd

title: iwpmd.conf(5)

summary: iWARP port mapper config file.

text:
# iwpmd.conf(5)

## NAME
iwpmd.conf - iWARP port mapper config file.

## SYNOPSIS

```
iwpmd.conf
```

## DESCRIPTION
The iwpmd.conf file provides configuration parameters for iwpmd. Parameters are in the form: param=value, and one per line. Parameters include:

nl_sock_rbuf_size - The socket buffer size of the netlink socket used to communicate with the kernel port map client. The default is 400MB.

## EXAMPLES
nl_sock_rbuf_size=419430400

## FILES
/etc/iwpmd.conf

## SEE ALSO
iwpmd(8)


keymaps

package: kbd

title: keymaps(5)

text:
# keymaps(5)

## NAME
keymaps - keyboard table descriptions for loadkeys and dumpkeys

## DESCRIPTION
These files are used by loadkeys(1) to modify the translation tables used by the kernel keyboard driver and generated by dumpkeys(1) from those translation tables.

The format of these files is vaguely similar to the one accepted by xmodmap(1). The file consists of charset or key or string definition lines interspersed with comments.

Comments are introduced with ! or # characters and continue to the end of the line. Anything following one of these characters on that line is ignored. Note that comments need not begin from column one as with xmodmap(1).

The syntax of keymap files is line oriented; a complete definition must fit on a single logical line. Logical lines can, however, be split into multiple physical lines by ending each subline with the backslash character (\).

## INCLUDE FILES
A keymap can include other keymaps using the syntax

include "pathname"

## CHARSET DEFINITIONS
A character set definition line is of the form:

```
charset "iso-8859-x"
```

It defines how following keysyms are to be interpreted. For example, in iso-8859-1 the symbol mu (or micro) has code 0265, while in iso-8859-7 the letter mu has code 0354.

## COMPLETE KEYCODE DEFINITIONS
Each complete key definition line is of the form:

```
keycode keynumber = keysym keysym keysym...
```

keynumber is the internal identification number of the key, roughly equivalent to the scan code of it. keynumber can be given in decimal, octal or hexadecimal notation. Octal is denoted by a leading zero and hexadecimal by the prefix 0x.

Each of the keysyms represent keyboard actions, of which up to 256 can be bound to a single key. The actions available include outputting character codes or character sequences, switching consoles or keymaps, booting the machine etc. (The complete list can be obtained from dumpkeys(1) by saying dumpkeys -l .)

Each keysym may be prefixed by a '+' (plus sign), in wich case this keysym is treated as a "letter" and therefore affected by the "CapsLock" the same way as by "Shift" (to be correct, the CapsLock inverts the Shift state). The ASCII letters ('a'-'z' and 'A'-'Z') are made CapsLock'able by default. If Shift+CapsLock should not produce a lower case symbol, put lines like

```
keycode 30 = +a  A
```

in the map file.

Which of the actions bound to a given key is taken when it is pressed depends on what modifiers are in effect at that moment. The keyboard driver supports 9 modifiers. These modifiers are labeled (completely arbitrarily) Shift, AltGr, Control, Alt, ShiftL, ShiftR, CtrlL, CtrlR and CapsShift. Each of these modifiers has an associated weight of power of two according to the following table:

modifier

weight

Shift 1

AltGr 2

Control 4

Alt 8

ShiftL 16

ShiftR 32

CtrlL 64

CtrlR 128

CapsShift 256

The effective action of a key is found out by adding up the weights of all the modifiers in effect. By default, no modifiers are in effect, so action number zero, i.e. the one in the first column in a key definition line, is taken when the key is pressed or released. When e.g. Shift and Alt modifiers are in effect, action number nine (from the 10th column) is the effective one.

Changing the state of what modifiers are in effect can be achieved by binding appropriate key actions to desired keys. For example, binding the symbol Shift to a key sets the Shift modifier in effect when that key is pressed and cancels the effect of that modifier when the key is released. Binding AltGr_Lock to a key sets AltGr in effect when the key is pressed and cancels the effect when the key is pressed again. (By default Shift, AltGr, Control and Alt are bound to the keys that bear a similar label; AltGr may denote the right Alt key.)

Note that you should be very careful when binding the modifier keys, otherwise you can end up with an unusable keyboard mapping. If you for example define a key to have Control in its first column and leave the rest of the columns to be VoidSymbols, you're in trouble. This is because pressing the key puts Control modifier in effect and the following actions are looked up from the fifth column (see the table above). So, when you release the key, the action from the fifth column is taken. It has VoidSymbol in it, so nothing happens. This means that the Control modifier is still in effect, although you have released the key. Re-pressing and releasing the key has no effect. To avoid this, you should always define all the columns to have the same modifier symbol. There is a handy short-hand notation for this, see below.

keysyms can be given in decimal, octal, hexadecimal, unicode or symbolic notation. The numeric notations use the same format as with keynumber. Unicode notation is "U+" followed by four hexadecimal digits. The symbolic notation resembles that used by xmodmap(1). Notable differences are the number symbols. The numeric symbols '0', ..., '9' of xmodmap(1) are replaced with the corresponding words 'zero', 'one', ... 'nine' to avoid confusion with the numeric notation.

It should be noted that using numeric notation for the keysyms is highly unportable as the key action numbers may vary from one kernel version to another and the use of numeric notations is thus strongly discouraged. They are intended to be used only when you know there is a supported keyboard action in your kernel for which your current version of loadkeys(1) has no symbolic name.

There is a number of short-hand notations to add readability and reduce typing work and the probability of typing-errors.

First of all, you can give a map specification line, of the form

```
keymaps 0-2,4-5,8,12
```

to indicate that the lines of the keymap will not specify all 256 columns, but only the indicated ones. (In the example: only the plain, Shift, AltGr, Control, Control+Shift, Alt and Control+Alt maps, that is, 7 columns instead of 256.) When no such line is given, the keymaps 0-M will be defined, where M+1 is the maximum number of entries found in any definition line.

Next, you can leave off any trailing VoidSymbol entries from a key definition line. VoidSymbol denotes a keyboard action which produces no output and has no other effects either. For example, to define key number 30 to output 'a' unshifted, 'A' when pressed with Shift and do nothing when pressed with AltGr or other modifiers, you can write

```
keycode  30 = a	A
```

instead of the more verbose

```
keycode  30 = a	A	VoidSymbol	VoidSymbol \
		VoidSymbol VoidSymbol VoidSymbol ...
```

For added convenience, you can usually get off with still more terse definitions. If you enter a key definition line with only and exactly one action code after the equals sign, it has a special meaning. If the code (numeric or symbolic) is not an ASCII letter, it means the code is implicitly replicated through all columns being defined. If, on the other hand, the action code is an ASCII character in the range 'a', ..., 'z' or 'A', ..., 'Z' in the ASCII collating sequence, the following definitions are made for the different modifier combinations, provided these are actually being defined. (The table lists the two possible cases: either the single action code is a lower case letter, denoted by 'x' or an upper case letter, denoted by 'Y'.)

modifier

symbol

none

x Y

Shift

X y

AltGr

x Y

Shift+AltGr

X y

Control

Control_x Control_y

Shift+Control

Control_x Control_y

AltGr+Control

Control_x Control_y

Shift+AltGr+Control

Control_x Control_y

Alt

Meta_x Meta_Y

Shift+Alt

Meta_X Meta_y

AltGr+Alt

Meta_x Meta_Y

Shift+AltGr+Alt

Meta_X Meta_y

Control+Alt

Meta_Control_x Meta_Control_y

Shift+Control+Alt

Meta_Control_x Meta_Control_y

AltGr+Control+Alt

Meta_Control_x Meta_Control_y

Shift+AltGr+Control+Alt

Meta_Control_x Meta_Control_y

## SINGLE MODIFIER DEFINITIONS
All the previous forms of key definition lines always define all the M+1 possible modifier combinations being defined, whether the line actually contains that many action codes or not. There is, however, a variation of the definition syntax for defining only single actions to a particular modifier combination of a key. This is especially useful, if you load a keymap which doesn't match your needs in only some modifier combinations, like AltGr+function keys. You can then make a small local file redefining only those modifier combinations and loading it after the main file. The syntax of this form is:

{ plain | <modifier sequence> } keycode keynumber = keysym

, e.g.,

```
plain keycode 14 = BackSpace
control alt keycode 83 = Boot
alt keycode 105 = Decr_Console
alt keycode 106 = Incr_Console
```

Using "plain" will define only the base entry of a key (i.e. the one with no modifiers in effect) without affecting the bindings of other modifier combinations of that key.

## STRING DEFINITIONS
In addition to comments and key definition lines, a keymap can contain string definitions. These are used to define what each function key action code sends. The syntax of string definitions is:

string keysym = "text"

text can contain literal characters, octal character codes in the format of backslash followed by up to three octal digits, and the three escape sequences \n, \\, and \", for newline, backslash and quote, respectively.

## COMPOSE DEFINITIONS
Then there may also be compose definitions. They have syntax

compose 'char' 'char' to 'char'

and describe how two bytes are combined to form a third one (when a dead accent or compose key is used). This is used to get accented letters and the like on a standard keyboard.

## ABBREVIATIONS
Various abbreviations can be used with kbd-0.96 and later.

strings as usual

Defines the usual values of the strings (but not the keys they are bound to).

compose as usual for "iso-8859-1"

Defines the usual compose combinations.

To find out what keysyms there are available for use in keymaps, use the command

```
dumpkeys --long-info
```

Unfortunately, there is currently no description of what each symbol does. It has to be guessed from the name or figured out from the kernel sources.

## EXAMPLES
(Be careful to use a keymaps line, like the first line of `dumpkeys`, or "keymaps 0-15" or so.)

The following entry exchanges the left Control key and the Caps Lock key on the keyboard:

```
keycode  58 = Control
keycode  29 = Caps_Lock
```

Key number 58 is normally the Caps Lock key, and key number 29 is normally the Control key.

The following entry sets the Shift and Caps Lock keys to behave more nicely, like in older typewriters. That is, pressing Caps Lock key once or more sets the keyboard in CapsLock state and pressing either of the Shift keys releases it.

```
keycode  42 = Uncaps_Shift
keycode  54 = Uncaps_Shift
keycode  58 = Caps_On
```

The following entry sets the layout of the edit pad in the enhanced keyboard to be more like that in the VT200 series terminals:

```
keycode 102 = Insert
keycode 104 = Remove
keycode 107 = Prior
shift keycode 107 = Scroll_Backward
keycode 110 = Find
keycode 111 = Select
control alt   keycode 111 = Boot
control altgr keycode 111 = Boot
```

Here's an example to bind the string "du\ndf\n" to the key AltGr-D. We use the "spare" action code F100 not normally bound to any key.

```
altgr keycode 32 = F100
string F100 = "du\ndf\n"
```

## SEE ALSO
loadkeys(1), dumpkeys(1), showkey(1), xmodmap(1)


kdump-tools

package: kdump-tools

title: kdump-tools(5)

text:
# kdump-tools(5)

## NAME
kdump-tools.conf - configuration file for the kdump-tools init script

## SYNOPSIS
/etc/sysconfig/kdump-tools

## DESCRIPTION
kdump-tools manages the kdump feature of the Linux kernel. The /etc/sysconfig/kdump-tools file contains local configuration settings of kdump.

This file is sourced into a shell script, so it's format should be consistent with shell scripting.

## OPTIONS
USE_KDUMP

Controls whether or not kdump-tools will take any action. If not set or 0, the kdump-tools init script will not run.

KDUMP_KERNEL

A full pathname to a kdump kernel (the kernel that is kexec'd at crash time in a reserved memory area, exposing the old kernel's memory for dumping). If not set, kdump-config will use the boot kernel as the kdump kernel if it is relocatable; otherwise you must set KDUMP_KERNEL in order for kdump-tools to work.

KDUMP_INITRD

A full pathname to the kdump initrd (if used). If KDUMP_KERNEL is set and KDUMP_INITRD is not set, a warning message will be printed, and an initrd will not be used.

KDUMP_COREDIR

Full path to a directory where the vmcore will be saved. Date stamped subdirectories are created each time a vmcore file is processed. If not set, /var/crash will be used.

KDUMP_FAIL_CMD

This variable specifies a command to run if the vmcore save fails. If not set, no special action is taken.

KDUMP_DUMP_DMESG

This variable controls if the dmesg buffer is dumped. If not set or set to 1, the dmesg buffer is dumped. If set to 0, the dmesg buffer is not dumped.

KDUMP_NUM_DUMPS

This variable specifies how many dump files should be kept on the local machine. If not set or set to 0, no special action is taken. If set to >1 and there are too many dump files on the machine, older dumps are removed. The cleanup action is only taken after a successful dump. This variable is ignored if remote dumping is enabled.

MAKEDUMP_ARGS

Extra arguments passed to makedumpfile(8). If not set, “-c -d 31” will be used. This tells makedumpfile to use compression, and reduce the corefile to in-use kernel pages only. See makedumpfile(8) for details.

KDUMP_KEXEC_ARGS

Additional arguments to the kexec command used to load the kdump kernel.

KDUMP_CMDLINE

Normally, the current kernel commandline is obtained from /proc/cmdline. Set this variable to override /proc/cmdline.

KDUMP_CMDLINE_APPEND

Additional arguments to append to the command line for the kdump kernel. If not set, “systemd.unit=kdump-tools-dump.service sysrq=yes panic=9 nokaslr irqpoll reset_devices cgroup_disable=memory udev.children-max=4 transparent_hugepage=never cma=0 hugetlb_cma=0 novmcoredd nr_cpus=1 mce=off numa=off acpi_no_memhotplug nokaslr hest_disable” will be used.

SSH

username and hostname of the remote server that will receive the dump and dmesg files. username@hostname format must be used.

SSH_KEY

Full path of the ssh private key to be used to login to the remote server. Use “kdump-config propagate” to send the public key to the remote server. If not set, the default /root/.ssh/kdump_id_rsa will be used

HOSTTAG

Select if hostname of IP address will be used as a prefix to the timestamped directory when sending files to the remote server. If not set, “ip” will be used.

NFS

Hostname and mount point of the NFS server configured to receive the crash dump. The syntax must be HOSTNAME:MOUNTPOINT (e.g. remote:/var/crash )

## USAGE
kdump-tools is as automated as can be at this point but there are some prerequisites to using it. Additionally, some manual configuration is still required.

By default, kernel dumps are stored locally on the system. kdump-tools can be configured to store the kernel dumps on a remote server accessible through the network.

### Manual Configuration
1.

USE_KDUMP is set to 0 by default. To enable kdump-tools, edit the /etc/sysconfig/kdump-tools configuration file and set USE_KDUMP=1.

2.

Kernel Command line parameters - the kernel must be booted with a crashkernel= command line parameter. Some example crashkernel parameters:

```
    ia64:       crashkernel=384M

    x86:        crashkernel=128M

    x86_64:     crashkernel=256M
```

Some users may also want to add nmi_watchdog=1 on certain systems. The nmi watchdog will cause the kernel to panic (and kdump) if a system hang is detected.

The kernel command line parameter is generally set in one of these files: /etc/sysconfig/grub, /boot/grub/menu.lst, /etc/elilo.conf, or /etc/lilo.conf. If the command line parameter is changed, a reboot is required in order for it to take effect.

3.

Architectural considerations

A)

x86 && PAE && memory > 4 Gigabytes - use KDUMP_KEXEC_ARGS="--elf64-core-headers"

B)

x86 and x86_64 - Some systems can take advantage of the nmi watchdog. Add nmi_watchdog=1 to the boot commandline to turn on the watchdog. The nmi interrupt will call panic if activated.

C)

ia64 - Some systems may need KDUMP_KEXEC_ARGS="--noio". Use this if the system hangs after a panic, but before the kdump kernel begins to boot.

### Networked kernel dump Configuration
1.

Either use SSH or NFS to choose which protocol to use to remotely access the target server.

2

For SSH username@hostname needs to be provided along with an appropriate SSH_KEY definition or use “kdump-config propagate” to propagate a new default ssh key.

3

For NFS the remote server name must be provided along with the directory where files are to be copied.

### Prerequisites
1.

Boot Kernel Configuration - The boot kernel must be configured with CONFIG_KEXEC=y and, if it is also to be used as the kdump kernel, CONFIG_CRASHDUMP=y. For ia64, only makedumpfile level 1 will work if the memory model selected is CONFIG_DISCONTIG. CONFIG_SPARSEMEM is recommended instead.

2.

Kdump Kernel Configuration - The kdump kernel must be relocated or relocatable. ia64 is relocatable by default, but x86, x86_64, and powerpc must be built with CONFIG_RELOCATABLE=y. Other architectures may require a predermined start location via CONFIG_PHYSICAL_START. If the boot kernel is relocatable, kdump-tools will automatically use that kernel. Otherwise, a relocatable or relocated kernel will need to be provided. The kdump kernel can be specified in the /etc/sysconfig/kdump-tools file. Set the KDUMP_KERNEL variable and if necessary the KDUMP_INITRD variable to point to the provided kernel and its initrd. The kdump kernel must be configured with: CONFIG_CRASH_DUMP=y

## SYSCTLS
Currently kdump-tools automatically sets the kernel sysctl for panic on oops, in order to collect a dump in this case. If the users want more panic triggers, like panic on OOM, or when a NMI is detected, it's recommended that they edit the sysctl configuration files (/etc/sysctl.conf or files on /etc/sysctl.d) in order to do so, and/or apply the sysctl settings with sysctl tool.

### Sysctl handling *during a kdump*
kdump-tools allows users to configure sysctls overrides on kdump environment; this is specially useful to prevent sysctls from the regular boot to mess with the resource-impaired kdump environment.

The mechanism is restricted to kdump boot and will not affect regular boots. In order to add overrides, user should edit the file /etc/kdump/sysctl.conf.

By default, hugepages overrides are set and is highly recommended to keep them in the file, to prevent kdump out-of-memory conditions.

## EXAMPLES
Use this option on x86 systems with PAE and more than 4 gig of memory:

KDUMP_KEXEC_ARGS="--elf64-core-headers"

This option starts a shell if kdump-tools cannot save the vmcore file:

KDUMP_FAIL_CMD="/bin/bash; reboot -f"

## FILES
/etc/init.d/kdump-tools

an init script to automatically load a kdump kernel, or save a vmcore and reboot.

/etc/sysconfig/kdump-tools

the kdump-tools configuration file

/etc/kdump/sysctl.conf

kdump-tools sysctl override file

/var/crash/kernel_link

a link to the current debug kernel

/var/crash/kexec_cmd

the last kexec_cmd executed by kdump-config

## DIAGNOSTICS
See kdump-config(8) for explanations of various error messages.

## SEE ALSO
/usr/share/doc/kdump-tools/README

/usr/share/doc/kdump-tools/README.Debian

kdump-config(8), kexec(8), sysctl(8), makedumpfile(8), crash(8), gdb(1),

## AUTHOR
Terry Loftin <terry.loftin@hp.com>