libnftables-json

package: libnftables-devel

title: libnftables-json(5)

summary: Supported JSON schema by libnftables

text:
# libnftables-json(5)

## NAME
libnftables-json - Supported JSON schema by libnftables

## SYNOPSIS
{ "nftables": [ OBJECTS ] }

OBJECTS := LIST_OBJECTS | CMD_OBJECTS

LIST_OBJECTS := LIST_OBJECT [ , LIST_OBJECTS ]

CMD_OBJECTS := CMD_OBJECT [ , CMD_OBJECTS ]

CMD_OBJECT := { CMD: LIST_OBJECT } | METAINFO_OBJECT

CMD := "add" | "replace" | "create" | "insert" | "delete" | "list" | "reset" | "flush" | "rename"

LIST_OBJECT := TABLE | CHAIN | RULE | SET | MAP | ELEMENT | FLOWTABLE | COUNTER | QUOTA | CT_HELPER | LIMIT | METAINFO_OBJECT | CT_TIMEOUT | CT_EXPECTATION

## DESCRIPTION
libnftables supports JSON formatted input and output. This is implemented as an alternative frontend to the standard CLI syntax parser, therefore basic behaviour is identical and, for (almost) any operation available in standard syntax, there should be an equivalent one in JSON.

JSON input may be provided in a single string as parameter to nft_run_cmd_from_buffer() or in a file identified by the filename parameter of the nft_run_cmd_from_filename() function.

JSON output has to be enabled via the nft_ctx_output_set_json() function, turning library standard output into JSON format. Error output remains unaffected.

## GLOBAL STRUCTURE
In general, any JSON input or output is enclosed in an object with a single property named nftables. Its value is an array containing commands (for input) or ruleset elements (for output).

A command is an object with a single property whose name identifies the command. Its value is a ruleset element - basically identical to output elements, apart from certain properties which may be interpreted differently or are required when output generally omits them.

## METAINFO OBJECT
In output, the first object in an nftables array is a special one containing library information. Its content is as follows:

```
{ "metainfo": {

        "version": STRING,

        "release_name": STRING,

        "json_schema_version": NUMBER
}}
```

The values of version and release_name properties are equal to the package version and release name as printed by nft -v. The value of the json_schema_version property is an integer indicating the schema version.

If supplied in library input, the parser will verify the json_schema_version value to not exceed the internally hardcoded one (to make sure the given schema is fully understood). In future, a lower number than the internal one may activate compatibility mode to parse outdated and incompatible JSON input.

## COMMAND OBJECTS
The structure accepts an arbitrary amount of commands which are interpreted in order of appearance. For instance, the following standard syntax input:

```
flush ruleset
add table inet mytable
add chain inet mytable mychain
add rule inet mytable mychain tcp dport 22 accept
```

translates into JSON as such:

```
{ "nftables": [

        { "flush": { "ruleset": null }},

        { "add": { "table": {

                        "family": "inet",

                        "name": "mytable"

        }}},

        { "add": { "chain": {

                        "family": "inet",

                        "table": "mytable",

                        "name": "mychain"

        }}},

        { "add": { "rule": {

                        "family": "inet",

                        "table": "mytable",

                        "chain": "mychain",

                        "expr": [

                                { "match": {

                                        "op": "==",

                                        "left": { "payload": {

                                                        "protocol": "tcp",

                                                        "field": "dport"

                                        }},

                                        "right": 22

                                }},

                                { "accept": null }

                        ]

        }}}
]}
```

### ADD

```
{ "add": ADD_OBJECT }
ADD_OBJECT := TABLE | CHAIN | RULE | SET | MAP | ELEMENT |

                FLOWTABLE | COUNTER | QUOTA | CT_HELPER | LIMIT |

                CT_TIMEOUT | CT_EXPECTATION
```

Add a new ruleset element to the kernel.

### REPLACE

```
{ "replace": RULE }
```

Replace a rule. In RULE, the handle property is mandatory and identifies the rule to be replaced.

### CREATE

```
{ "create": ADD_OBJECT }
```

Identical to add command, but returns an error if the object already exists.

### INSERT

```
{ "insert": RULE }
```

This command is identical to add for rules, but instead of appending the rule to the chain by default, it inserts at first position. If a handle or index property is given, the rule is inserted before the rule identified by those properties.

### DELETE

```
{ "delete": ADD_OBJECT }
```

Delete an object from the ruleset. Only the minimal number of properties required to uniquely identify an object is generally needed in ADD_OBJECT. For most ruleset elements, this is family and table plus either handle or name (except rules since they don’t have a name).

### LIST

```
{ "list": LIST_OBJECT }
LIST_OBJECT := TABLE | TABLES | CHAIN | CHAINS | SET | SETS |

                 MAP | MAPS | COUNTER | COUNTERS | QUOTA | QUOTAS |

                 CT_HELPER | CT_HELPERS | LIMIT | LIMITS | RULESET |

                 METER | METERS | FLOWTABLE | FLOWTABLES |

                 CT_TIMEOUT | CT_EXPECTATION
```

List ruleset elements. The plural forms are used to list all objects of that kind, optionally filtered by family and for some, also table.

### RESET

```
{ "reset": RESET_OBJECT }
RESET_OBJECT := COUNTER | COUNTERS | QUOTA | QUOTAS | RULE | RULES | SET | MAP | ELEMENT
```

Reset state in suitable objects, i.e. zero their internal counter.

### FLUSH

```
{ "flush": FLUSH_OBJECT }
FLUSH_OBJECT := TABLE | CHAIN | SET | MAP | METER | RULESET
```

Empty contents in given object, e.g. remove all chains from given table or remove all elements from given set.

### RENAME

```
{ "rename": CHAIN }
```

Rename a chain. The new name is expected in a dedicated property named newname.

## RULESET ELEMENTS

### TABLE

```
{ "table": {

        "family": STRING,

        "name": STRING,

        "handle": NUMBER
}}
```

This object describes a table.

family

The table’s family, e.g. "ip" or "ip6".

name

The table’s name.

handle

The table’s handle. In input, it is used only in delete command as alternative to name.

### CHAIN

```
{ "chain": {

        "family": STRING,

        "table": STRING,

        "name": STRING,

        "newname": STRING,

        "handle": NUMBER,

        "type": STRING,

        "hook": STRING,

        "prio": NUMBER,

        "dev": STRING,

        "policy": STRING
}}
```

This object describes a chain.

family

The table’s family.

table

The table’s name.

name

The chain’s name.

handle

The chain’s handle. In input, it is used only in delete command as alternative to name.

newname

A new name for the chain, only relevant in the rename command.

The following properties are required for base chains:

type

The chain’s type.

hook

The chain’s hook.

prio

The chain’s priority.

dev

The chain’s bound interface (if in the netdev family).

policy

The chain’s policy.

### RULE

```
{ "rule": {

        "family": STRING,

        "table": STRING,

        "chain": STRING,

        "expr": [ STATEMENTS ],

        "handle": NUMBER,

        "index": NUMBER,

        "comment": STRING
}}
STATEMENTS := STATEMENT [, STATEMENTS ]
```

This object describes a rule. Basic building blocks of rules are statements. Each rule consists of at least one.

family

The table’s family.

table

The table’s name.

chain

The chain’s name.

expr

An array of statements this rule consists of. In input, it is used in add/insert/replace commands only.

handle

The rule’s handle. In delete/replace commands, it serves as an identifier of the rule to delete/replace. In add/insert commands, it serves as an identifier of an existing rule to append/prepend the rule to.

index

The rule’s position for add/insert commands. It is used as an alternative to handle then.

comment

Optional rule comment.

### SET / MAP

```
{ "set": {

        "family": STRING,

        "table": STRING,

        "name": STRING,

        "handle": NUMBER,

        "type": SET_TYPE,

        "policy": SET_POLICY,

        "flags": [ SET_FLAG_LIST ],

        "elem": SET_ELEMENTS,

        "timeout": NUMBER,

        "gc-interval": NUMBER,

        "size": NUMBER
}}
{ "map": {

        "family": STRING,

        "table": STRING,

        "name": STRING,

        "handle": NUMBER,

        "type": SET_TYPE,

        "map": STRING,

        "policy": SET_POLICY,

        "flags": [ SET_FLAG_LIST ],

        "elem": SET_ELEMENTS,

        "timeout": NUMBER,

        "gc-interval": NUMBER,

        "size": NUMBER
}}
SET_TYPE := STRING | [ SET_TYPE_LIST ]
SET_TYPE_LIST := STRING [, SET_TYPE_LIST ]
SET_POLICY := "performance" | "memory"
SET_FLAG_LIST := SET_FLAG [, SET_FLAG_LIST ]
SET_FLAG := "constant" | "interval" | "timeout"
SET_ELEMENTS := EXPRESSION | [ EXPRESSION_LIST ]
EXPRESSION_LIST := EXPRESSION [, EXPRESSION_LIST ]
```

These objects describe a named set or map. Maps are a special form of sets in that they translate a unique key to a value.

family

The table’s family.

table

The table’s name.

name

The set’s name.

handle

The set’s handle. For input, it is used in the delete command only.

type

The set’s datatype, see below.

map

Type of values this set maps to (i.e. this set is a map).

policy

The set’s policy.

flags

The set’s flags.

elem

Initial set element(s), see below.

timeout

Element timeout in seconds.

gc-interval

Garbage collector interval in seconds.

size

Maximum number of elements supported.

TYPE

The set type might be a string, such as "ipv4_addr" or an array consisting of strings (for concatenated types).

ELEM

A single set element might be given as string, integer or boolean value for simple cases. If additional properties are required, a formal elem object may be used.

Multiple elements may be given in an array.

### ELEMENT

```
{ "element": {

        "family": STRING,

        "table": STRING,

        "name": STRING,

        "elem": SET_ELEM
}}
SET_ELEM := EXPRESSION | [ EXPRESSION_LIST ]
EXPRESSION_LIST := EXPRESSION [, EXPRESSION ]
```

Manipulate element(s) in a named set.

family

The table’s family.

table

The table’s name.

name

The set’s name.

elem

See elem property of set object.

### FLOWTABLE

```
{ "flowtable": {

        "family": STRING,

        "table": STRING,

        "name": STRING,

        "handle": NUMBER,

        "hook": STRING,

        "prio": NUMBER,

        "dev": FT_INTERFACE
}}
FT_INTERFACE := STRING | [ FT_INTERFACE_LIST ]
FT_INTERFACE_LIST := STRING [, STRING ]
```

This object represents a named flowtable.

family

The table’s family.

table

The table’s name.

name

The flow table’s name.

handle

The flow table’s handle. In input, it is used by the delete command only.

hook

The flow table’s hook.

prio

The flow table’s priority.

dev

The flow table’s interface(s).

### COUNTER

```
{ "counter": {

        "family": STRING,

        "table": STRING,

        "name": STRING,

        "handle": NUMBER,

        "packets": NUMBER,

        "bytes": NUMBER
}}
```

This object represents a named counter.

family

The table’s family.

table

The table’s name.

name

The counter’s name.

handle

The counter’s handle. In input, it is used by the delete command only.

packets

Packet counter value.

bytes

Byte counter value.

### QUOTA

```
{ "quota": {

        "family": STRING,

        "table": STRING,

        "name": STRING,

        "handle": NUMBER,

        "bytes": NUMBER,

        "used": NUMBER,

        "inv": BOOLEAN
}}
```

This object represents a named quota.

family

The table’s family.

table

The table’s name.

name

The quota’s name.

handle

The quota’s handle. In input, it is used by the delete command only.

bytes

Quota threshold.

used

Quota used so far.

inv

If true, match if the quota has been exceeded.

### CT HELPER

```
{ "ct helper": {

        "family": STRING,

        "table": STRING,

        "name": STRING,

        "handle": ... ',

        "type": 'STRING,

        "protocol": CTH_PROTO,

        "l3proto": STRING
}}
CTH_PROTO := "tcp" | "udp"
```

This object represents a named conntrack helper.

family

The table’s family.

table

The table’s name.

name

The ct helper’s name.

handle

The ct helper’s handle. In input, it is used by the delete command only.

type

The ct helper type name, e.g. "ftp" or "tftp".

protocol

The ct helper’s layer 4 protocol.

l3proto

The ct helper’s layer 3 protocol, e.g. "ip" or "ip6".

### LIMIT

```
{ "limit": {

        "family": STRING,

        "table": STRING,

        "name": STRING,

        "handle": NUMBER,

        "rate": NUMBER,

        "per": STRING,

        "burst": NUMBER,

        "unit": LIMIT_UNIT,

        "inv": BOOLEAN
}}
LIMIT_UNIT := "packets" | "bytes"
```

This object represents a named limit.

family

The table’s family.

table

The table’s name.

name

The limit’s name.

handle

The limit’s handle. In input, it is used by the delete command only.

rate

The limit’s rate value.

per

Time unit to apply the limit to, e.g. "week", "day", "hour", etc. If omitted, defaults to "second".

burst

The limit’s burst value. If omitted, defaults to 0.

unit

Unit of rate and burst values. If omitted, defaults to "packets".

inv

If true, match if limit was exceeded. If omitted, defaults to false.

### CT TIMEOUT

```
{ "ct timeout": {

        "family": STRING,

        "table": STRING,

        "name": STRING,

        "handle": NUMBER,

        "protocol": CTH_PROTO,

        "state": STRING,

        "value: NUMBER,

        "l3proto": STRING
}}
CTH_PROTO := "tcp" | "udp" | "dccp" | "sctp" | "gre" | "icmpv6" | "icmp" | "generic"
```

This object represents a named conntrack timeout policy.

family

The table’s family.

table

The table’s name.

name

The ct timeout object’s name.

handle

The ct timeout object’s handle. In input, it is used by delete command only.

protocol

The ct timeout object’s layer 4 protocol.

state

The connection state name, e.g. "established", "syn_sent", "close" or "close_wait", for which the timeout value has to be updated.

value

The updated timeout value for the specified connection state.

l3proto

The ct timeout object’s layer 3 protocol, e.g. "ip" or "ip6".

### CT EXPECTATION

```
{ "ct expectation": {

        "family": STRING,

        "table": STRING,

        "name": STRING,

        "handle": NUMBER,

        "l3proto": STRING

        "protocol":* CTH_PROTO,

        "dport": NUMBER,

        "timeout: NUMBER,

        "size: NUMBER,
*}}
CTH_PROTO := "tcp" | "udp" | "dccp" | "sctp" | "gre" | "icmpv6" | "icmp" | "generic"
```

This object represents a named conntrack expectation.

family

The table’s family.

table

The table’s name.

name

The ct expectation object’s name.

handle

The ct expectation object’s handle. In input, it is used by delete command only.

l3proto

The ct expectation object’s layer 3 protocol, e.g. "ip" or "ip6".

protocol

The ct expectation object’s layer 4 protocol.

dport

The destination port of the expected connection.

timeout

The time in millisecond that this expectation will live.

size

The maximum count of expectations to be living in the same time.

## STATEMENTS
Statements are the building blocks for rules. Each rule consists of at least one.

### VERDICT

```
{ "accept": null }
{ "drop": null }
{ "continue": null }
{ "return": null }
{ "jump": { "target": * STRING *}}
{ "goto": { "target": * STRING *}}
```

A verdict either terminates packet traversal through the current chain or delegates to a different one.

jump and goto statements expect a target chain name.

### MATCH

```
{ "match": {

        "left": EXPRESSION,

        "right": EXPRESSION,

        "op": STRING
}}
```

This matches the expression on left hand side (typically a packet header or packet meta info) with the expression on right hand side (typically a constant value). If the statement evaluates to true, the next statement in this rule is considered. If not, processing continues with the next rule in the same chain.

left

Left hand side of this match.

right

Right hand side of this match.

op

Operator indicating the type of comparison.

OPERATORS

&

Binary AND

|

Binary OR

^

Binary XOR

<<

Left shift

>>

Right shift

==

Equal

!=

Not equal

<

Less than

>

Greater than

⇐

Less than or equal to

>=

Greater than or equal to

in

Perform a lookup, i.e. test if bits on RHS are contained in LHS value

Unlike with the standard API, the operator is mandatory here. In the standard API, a missing operator may be resolved in two ways, depending on the type of expression on the RHS:

•If the RHS is a bitmask or a list of bitmasks, the expression resolves into a binary operation with the inequality operator, like this: LHS & RHS != 0.

•In any other case, the equality operator is simply inserted.

For the non-trivial first case, the JSON API supports the in operator.

### COUNTER

```
{ "counter": {

        "packets": NUMBER,

        "bytes": NUMBER
}}
{ "counter": STRING }
```

This object represents a byte/packet counter. In input, no properties are required. If given, they act as initial values for the counter.

The first form creates an anonymous counter which lives in the rule it appears in. The second form specifies a reference to a named counter object.

packets

Packets counted.

bytes

Bytes counted.

### MANGLE

```
{ "mangle": {

        "key": EXPRESSION,

        "value": EXPRESSION
}}
```

This changes the packet data or meta info.

key

The packet data to be changed, given as an exthdr, payload, meta, ct or ct helper expression.

value

Value to change data to.

### QUOTA

```
{ "quota": {

        "val": NUMBER,

        "val_unit": STRING,

        "used": NUMBER,

        "used_unit": STRING,

        "inv": BOOLEAN
}}
{ "quota": STRING }
```

The first form creates an anonymous quota which lives in the rule it appears in. The second form specifies a reference to a named quota object.

val

Quota value.

val_unit

Unit of val, e.g. "kbytes" or "mbytes". If omitted, defaults to "bytes".

used

Quota used so far. Optional on input. If given, serves as initial value.

used_unit

Unit of used. Defaults to "bytes".

inv

If true, will match if quota was exceeded. Defaults to false.

### LIMIT

```
{ "limit": {

        "rate": NUMBER,

        "rate_unit": STRING,

        "per": STRING,

        "burst": NUMBER,

        "burst_unit": STRING,

        "inv": BOOLEAN
}}
{ "limit": STRING }
```

The first form creates an anonymous limit which lives in the rule it appears in. The second form specifies a reference to a named limit object.

rate

Rate value to limit to.

rate_unit

Unit of rate, e.g. "packets" or "mbytes". Defaults to "packets".

per

Denominator of rate, e.g. "week" or "minutes".

burst

Burst value. Defaults to 0.

burst_unit

Unit of burst, ignored if rate_unit is "packets". Defaults to "bytes".

inv

If true, matches if the limit was exceeded. Defaults to false.

### FWD

```
{ "fwd": {

        "dev": EXPRESSION,

        "family": FWD_FAMILY,

        "addr": EXPRESSION
}}
FWD_FAMILY := "ip" | "ip6"
```

Forward a packet to a different destination.

dev

Interface to forward the packet on.

family

Family of addr.

addr

IP(v6) address to forward the packet to.

Both family and addr are optional, but if at least one is given, both must be present.

### NOTRACK

```
{ "notrack": null }
```

Disable connection tracking for the packet.

### DUP

```
{ "dup": {

        "addr": EXPRESSION,

        "dev": EXPRESSION
}}
```

Duplicate a packet to a different destination.

addr

Address to duplicate packet to.

dev

Interface to duplicate packet on. May be omitted to not specify an interface explicitly.

### NETWORK ADDRESS TRANSLATION

```
{ "snat": {

        "addr": EXPRESSION,

        "family": STRING,

        "port": EXPRESSION,

        "flags": FLAGS
}}
{ "dnat": {

        "addr": EXPRESSION,

        "family": STRING,

        "port": EXPRESSION,

        "flags": FLAGS
}}
{ "masquerade": {

        "port": EXPRESSION,

        "flags": FLAGS
}}
{ "redirect": {

        "port": EXPRESSION,

        "flags": FLAGS
}}
FLAGS := FLAG | [ FLAG_LIST ]
FLAG_LIST := FLAG [, FLAG_LIST ]
FLAG := "random" | "fully-random" | "persistent"
```

Perform Network Address Translation.

addr

Address to translate to.

family

Family of addr, either ip or ip6. Required in inet table family.

port

Port to translate to.

flags

Flag(s).

All properties are optional and default to none.

### REJECT

```
{ "reject": {

        "type": STRING,

        "expr": EXPRESSION
}}
```

Reject the packet and send the given error reply.

type

Type of reject, either "tcp reset", "icmpx", "icmp" or "icmpv6".

expr

ICMP code to reject with.

All properties are optional.

### SET

```
{ "set": {

        "op": STRING,

        "elem": EXPRESSION,

        "set": STRING
}}
```

Dynamically add/update elements to a set.

op

Operator on set, either "add" or "update".

elem

Set element to add or update.

set

Set reference.

### LOG

```
{ "log": {

        "prefix": STRING,

        "group": NUMBER,

        "snaplen": NUMBER,

        "queue-threshold": NUMBER,

        "level": LEVEL,

        "flags": FLAGS
}}
LEVEL := "emerg" | "alert" | "crit" | "err" | "warn" | "notice" |

           "info" | "debug" | "audit"
FLAGS := FLAG | [ FLAG_LIST ]
FLAG_LIST := FLAG [, FLAG_LIST ]
FLAG := "tcp sequence" | "tcp options" | "ip options" | "skuid" |

          "ether" | "all"
```

Log the packet.

prefix

Prefix for log entries.

group

Log group.

snaplen

Snaplen for logging.

queue-threshold

Queue threshold.

level

Log level. Defaults to "warn".

flags

Log flags.

All properties are optional.

### CT HELPER

```
{ "ct helper": EXPRESSION }
```

Enable the specified conntrack helper for this packet.

ct helper

CT helper reference.

### METER

```
{ "meter": {

        "name": STRING,

        "key": EXPRESSION,

        "stmt": STATEMENT
}}
```

Apply a given statement using a meter.

name

Meter name.

key

Meter key.

stmt

Meter statement.

### QUEUE

```
{ "queue": {

        "num": EXPRESSION,

        "flags": FLAGS
}}
FLAGS := FLAG | [ FLAG_LIST ]
FLAG_LIST := FLAG [, FLAG_LIST ]
FLAG := "bypass" | "fanout"
```

Queue the packet to userspace.

num

Queue number.

flags

Queue flags.

### VERDICT MAP

```
{ "vmap": {

        "key": EXPRESSION,

        "data": EXPRESSION
}}
```

Apply a verdict conditionally.

key

Map key.

data

Mapping expression consisting of value/verdict pairs.

### CT COUNT

```
{ "ct count": {

        "val": NUMBER,

        "inv": BOOLEAN
}}
```

Limit the number of connections using conntrack.

val

Connection count threshold.

inv

If true, match if val was exceeded. If omitted, defaults to false.

### CT TIMEOUT

```
{ "ct timeout": EXPRESSION }
```

Assign connection tracking timeout policy.

ct timeout

CT timeout reference.

### CT EXPECTATION

```
{ "ct expectation": EXPRESSION }
```

Assign connection tracking expectation.

ct expectation

CT expectation reference.

### XT

```
{ "xt": {

        "type": TYPENAME,

        "name": STRING
}}
TYPENAME := match | target | watcher
```

This represents an xt statement from xtables compat interface. It is a fallback if translation is not available or not complete.

Seeing this means the ruleset (or parts of it) were created by iptables-nft and one should use that to manage it.

BEWARE: nftables won’t restore these statements.

## EXPRESSIONS
Expressions are the building blocks of (most) statements. In their most basic form, they are just immediate values represented as a JSON string, integer or boolean type.

### IMMEDIATES

```
STRING
NUMBER
BOOLEAN
```

Immediate expressions are typically used for constant values. For strings, there are two special cases:

@STRING

The remaining part is taken as set name to create a set reference.

\*

Construct a wildcard expression.

### LISTS

```
ARRAY
```

List expressions are constructed by plain arrays containing of an arbitrary number of expressions.

### CONCAT

```
{ "concat": CONCAT }
CONCAT := [ EXPRESSION_LIST ]
EXPRESSION_LIST := EXPRESSION [, EXPRESSION_LIST ]
```

Concatenate several expressions.

### SET

```
{ "set": SET }
SET := EXPRESSION | [ EXPRESSION_LIST ]
```

This object constructs an anonymous set. For mappings, an array of arrays with exactly two elements is expected.

### MAP

```
{ "map": {

        "key": EXPRESSION,

        "data": EXPRESSION
}}
```

Map a key to a value.

key

Map key.

data

Mapping expression consisting of value/target pairs.

### PREFIX

```
{ "prefix": {

        "addr": EXPRESSION,

        "len": NUMBER
}}
```

Construct an IPv4 or IPv6 prefix consisting of address part in addr and prefix length in len.

### RANGE

```
{ "range": [ EXPRESSION , EXPRESSION ] }
```

Construct a range of values. The first array item denotes the lower boundary, the second one the upper boundary.

### PAYLOAD

```
{ "payload": {

        "base": BASE,

        "offset": NUMBER,

        "len": NUMBER
}}
{ "payload": {

        "protocol": STRING,

        "field": STRING
}}
BASE := "ll" | "nh" | "th"
```

Construct a payload expression, i.e. a reference to a certain part of packet data. The first form creates a raw payload expression to point at a random number (len) of bytes at a certain offset (offset) from a given reference point (base). The following base values are accepted:

"ll"

The offset is relative to Link Layer header start offset.

"nh"

The offset is relative to Network Layer header start offset.

"th"

The offset is relative to Transport Layer header start offset.

The second form allows one to reference a field by name (field) in a named packet header (protocol).

### EXTHDR

```
{ "exthdr": {

        "name": STRING,

        "field": STRING,

        "offset": NUMBER
}}
```

Create a reference to a field (field) in an IPv6 extension header (name). offset is used only for rt0 protocol.

If the field property is not given, the expression is to be used as a header existence check in a match statement with a boolean on the right hand side.

### TCP OPTION

```
{ "tcp option": {

        "name": STRING,

        "field": STRING
}}
```

Create a reference to a field (field) of a TCP option header (name).

If the field property is not given, the expression is to be used as a TCP option existence check in a match statement with a boolean on the right hand side.

### SCTP CHUNK

```
{ "sctp chunk": {

        "name": STRING,

        "field": STRING
}}
```

Create a reference to a field (field) of an SCTP chunk (name).

If the field property is not given, the expression is to be used as an SCTP chunk existence check in a match statement with a boolean on the right hand side.

### DCCP OPTION

```
{ "dccp option": {

        "type": NUMBER*
}}
```

Create a reference to a DCCP option (type).

The expression is to be used as a DCCP option existence check in a match statement with a boolean on the right hand side.

### META

```
{ "meta": {

        "key": META_KEY
}}
META_KEY := "length" | "protocol" | "priority" | "random" | "mark" |

              "iif" | "iifname" | "iiftype" | "oif" | "oifname" |

              "oiftype" | "skuid" | "skgid" | "nftrace" |

              "rtclassid" | "ibriport" | "obriport" | "ibridgename" |

              "obridgename" | "pkttype" | "cpu" | "iifgroup" |

              "oifgroup" | "cgroup" | "nfproto" | "l4proto" |

              "secpath"
```

Create a reference to packet meta data.

### RT

```
{ "rt": {

        "key": RT_KEY,

        "family": RT_FAMILY
}}
RT_KEY := "classid" | "nexthop" | "mtu"
RT_FAMILY := "ip" | "ip6"
```

Create a reference to packet routing data.

The family property is optional and defaults to unspecified.

### CT

```
{ "ct": {

        "key": STRING,

        "family": CT_FAMILY,

        "dir": CT_DIRECTION
}}
CT_FAMILY := "ip" | "ip6"
CT_DIRECTION := "original" | "reply"
```

Create a reference to packet conntrack data.

Some CT keys do not support a direction. In this case, dir must not be given.

### NUMGEN

```
{ "numgen": {

        "mode": NG_MODE,

        "mod": NUMBER,

        "offset": NUMBER
}}
NG_MODE := "inc" | "random"
```

Create a number generator.

The offset property is optional and defaults to 0.

### HASH

```
{ "jhash": {

        "mod": NUMBER,

        "offset": NUMBER,

        "expr": EXPRESSION,

        "seed": NUMBER
}}
{ "symhash": {

        "mod": NUMBER,

        "offset": NUMBER
}}
```

Hash packet data.

The offset and seed properties are optional and default to 0.

### FIB

```
{ "fib": {

        "result": FIB_RESULT,

        "flags": FIB_FLAGS
}}
FIB_RESULT := "oif" | "oifname" | "type"
FIB_FLAGS := FIB_FLAG | [ FIB_FLAG_LIST ]
FIB_FLAG_LIST := FIB_FLAG [, FIB_FLAG_LIST ]
FIB_FLAG := "saddr" | "daddr" | "mark" | "iif" | "oif"
```

Perform kernel Forwarding Information Base lookups.

### BINARY OPERATION

```
{ "|": [ EXPRESSION, EXPRESSION ] }
{ "^": [ EXPRESSION, EXPRESSION ] }
{ "&": [ EXPRESSION, EXPRESSION ] }
{ "<<": [ EXPRESSION, EXPRESSION ] }
{ ">>": [ EXPRESSION, EXPRESSION ] }
```

All binary operations expect an array of exactly two expressions, of which the first element denotes the left hand side and the second one the right hand side.

### VERDICT

```
{ "accept": null }
{ "drop": null }
{ "continue": null }
{ "return": null }
{ "jump": { "target": STRING }}
{ "goto": { "target": STRING }}
```

Same as the verdict statement, but for use in verdict maps.

jump and goto verdicts expect a target chain name.

### ELEM

```
{ "elem": {

        "val": EXPRESSION,

        "timeout": NUMBER,

        "expires": NUMBER,

        "comment": STRING
}}
```

Explicitly set element object, in case timeout, expires or comment are desired. Otherwise, it may be replaced by the value of val.

### SOCKET

```
{ "socket": {

        "key": SOCKET_KEY
}}
SOCKET_KEY := "transparent"
```

Construct a reference to packet’s socket.

### OSF

```
{ "osf": {

        "key": OSF_KEY,

        "ttl": OSF_TTL
}}
OSF_KEY := "name"
OSF_TTL := "loose" | "skip"
```

Perform OS fingerprinting. This expression is typically used in the LHS of a match statement.

key

Which part of the fingerprint info to match against. At this point, only the OS name is supported.

ttl

Define how the packet’s TTL value is to be matched. This property is optional. If omitted, the TTL value has to match exactly. A value of loose accepts TTL values less than the fingerprint one. A value of skip omits TTL value comparison entirely.

## AUTHOR
Phil Sutter <phil@nwl.cc>

Author.


title: r2test.conf(5)

text:
# r2test.conf(5)

## NAME
r2test.conf - OpenR2 r2test program configuration file

## SYNOPSIS
/etc/openr2/r2test.conf

## DESCRIPTION
This file defines the behavior of the r2test program

This file works pretty much like Asterisk zapata.conf file, the channel parameter will create a R2 context with the specified range of channels and will take all the preceding parameters as configuration.

## SYNTAX
No spaces are allowed in parameter definition, lines starting with # or spaces will be ignored

This definition will not be read properly

param = value

This definition will be read fine

param=value

## OPTIONS
category=<NATIONAL_SUBSCRIBER, NATIONAL_PRIORITY_SUBSCRIBER, INTERNATIONAL_SUBSCRIBER, INTERNATIONAL_PRIORITY_SUBSCRIBER>

Defines the call category of subscriber. Defaults to NATIONAL_SUBSCRIBER

loglevel=<all,error,warning,debug,notice,cas,mf,stack,nothing>

Defines the log level for debugging purposes. Defaults to all error, warning, debug, notice These options are self-descriptive

cas is for logging ABCD CAS tx and rx

mf is for logging of the Multi Frequency tones

stack is for very verbose output of the channel and context call stack, only useful if you are debugging a crash or want to learn how the library works. The stack logging will be only enabled if the OpenR2 library was compiled with -DOR2_TRACE_STACKS

all is a special value to log all the activity

nothing is a clean-up value, in case you want to not log any activity for a channel or group of channels

You can mix up values, like: loglevel=error,debug,mf to log just error, debug and multi frequency messages

callfile=<yes|no>

Call files useful to debug signaling issues are dumped in the current directory if this parameter is enabled. Defaults to no

variant=<br,mx,ar,itu>

R2 country variant. Defaults to mx

maxani

How much ANI to expect. Defaults to 10

maxdnis

How much DNIS to expect. Defaults to 4

getanifirst=<yes|no>

Whether or not we want to request ANI first. Defaults to no

usedahdimf=<yes|no>

Whether to use the built-in OpenR2 MF tone generation or DAHDI MF tone generation. DAHDI is faster since it does not require to copy user space buffers to the kernel, however this option will only be available when the configure script detects DAHDI support for MF R2 tone generation. Defaults to no

mfthreshold

MF threshold in milliseconds. This is the amount of time a R2 MF signal is required to be ON or OFF after has been detected to be handled. 0 means as soon as we detect a signal we handle it. This aids when a buggy generator or detector causes small false positives. Defaults to 0

mfbacktimeout

MF backward timeout in milliseconds to use OpenR2 default just specify any negative number or comment this line. Defaults to -1

meteringpulsetimeout

Value in milliseconds for the metering pulse timeout, any negative value means default. Defaults to -1

collectcalls=<yes|no>

Whether to accept collect calls (see also doubleanswer). Defaults to no

doubleanswer=<yes|no>

This option are related but independent of collectcalls. If you have problems to block collect calls using Group B signals (collectcalls), enable this option. Defaults to no

immediateaccept=<yes|no>

Whether to skip Group B/II signals and go directly to the accepted state for an incoming call. Defaults to no

advancedprotocolfile

This option is for advanced users only! Define a file that contains hacks to R2 protocol. This allow advanced users to fine tune the library or make test with specific scenarios to include in the library in the future.

playaudio=<yes|no>

This feature allows you to play an alaw audio file for incoming/outgoing calls. Defaults to no

audiofile

If you set playaudio=yes you should provide the path to the audio file

channel

Define range of channels to configure using previous options. The channel range must be specified, unless you will use only one channel. If this option is specified after dnid, cid and caller that options will be used. Defaults to channel=1-15

channel=17-31

dnid

Defines the destination number. Only used if .B caller = yes

cid

Defines the caller id number. Only used if .B caller = yes

caller=<yes|no>

Whether or not the group of channels will start a call to the specified dnid. Defaults to yes

## FILES
/etc/openr2/r2test.conf

/etc/openr2/r2proto.conf

## SEE ALSO
r2test(8)

## AUTHOR
This manual page was written by Alexandre Cavalcante Alencar

<alexandre.alencar@gmail.com>

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.


title: pkcs11.conf(5)

summary: Configuration files for PKCS#11 modules

text:
# pkcs11.conf(5)

## NAME
pkcs11.conf - Configuration files for PKCS#11 modules

## DESCRIPTION
The pkcs11.conf configuration files are a standard way to configure PKCS#11 modules.

## FILE FORMAT
A complete configuration consists of several files. These files are text files. Since p11-kit is built to be used in all sorts of environments and at very low levels of the software stack, we cannot make use of high level configuration APIs that you may find on a modern desktop.

Each setting in the config file is specified consists of a name and a value. The name is a simple string consisting of characters and dashes. The name consists of alpha numeric characters, dot, hyphen and underscore.

The value is specified after the name on the same line, separated from it by a : (colon). White space between the name and value is ignored.

Blank lines are ignored. White space at the beginning or end of lines is stripped. Lines that begin with a # character are ignored as comments. Comments are not recognized when they come after a value on a line.

A fictitious module configuration file might look like:

```
module: module.so
# Here is a comment
managed: true
setting.2: A long value with text.
x-custom : text
```

## MODULE CONFIGURATION
Each configured PKCS#11 module has its own config file. These files can be placed in various locations.

The filename of the configuration file may consist of upper and lowercase letters underscore, comma, dash and dots. The first characters needs to be an alphanumeric, the filename should end with a .module extension.

Most importantly each config file specifies the path of the PKCS#11 module to load. A module config file has the following fields:

module:

The filename of the PKCS#11 module to load. This should include an extension like .so If this value is blank, then the module will be ignored. This can be used in the user configs to override loading of a module specified in the system configuration.

If this is a relative path, then the module will be loaded from the default module directory.

critical:

Set to yes if the module is critical and required to load. If a critical module fails to load or initialize, then the loading process for all registered modules will abort and return an error code. This argument is optional and defaults to no.

enable-in:

A comma and/or space separated list of names of programs that this module should only be loaded in. The module will not be loaded for other programs using p11-kit. The base name of the process executable should be used here, for example seahorse, ssh. This option can also be used to control whether the module will be loaded by the proxy module. To enable loading only from the proxy module, specify p11-kit-proxy as the value.

This is not a security feature. The argument is optional. If not present, then any process will load the module.

disable-in:

A comma and/or space separated list of names of programs that this module should not be loaded in. The module will be loaded for any other programs using p11-kit. The base name of the process executable should be used here, for example firefox, thunderbird-bin. This option can also be used to control whether the module will be loaded by the proxy module. To disable loading from the proxy module, specify p11-kit-proxy as the value.

This is not a security feature. The argument is optional. If not present, then any process will load the module.

managed:

Set to no if the module is not to be managed by p11-kit. Making a module unmanaged is not recommended, and will cause problems if multiple callers in a single process share a PKCS#11 module. This argument is optional and defaults to yes.

priority:

The value should be an integer. When lists of modules are returned to a caller of p11-kit, modules with a higher number are sorted first. When applications search modules for certificates, keys and trust policy information, this setting will affect what find first. This argument is optional, and defaults to zero. Modules with the same priority option will be sorted alphabetically.

remote:

Instead of loading the PKCS#11 module locally, run the module remotely. Specify a command to run, prefixed with | a pipe. The command must speak the p11-kit remoting protocol on its standard in and standard out. For example:

```
remote: |ssh user@remote p11-kit remote /path/to/module.so
```

Other forms of remoting will appear in later p11-kit releases.

trust-policy:

Set to yes to use use this module as a source of trust policy information such as certificate anchors and blocklists.

log-calls:

Set to yes to write a log to stderr of all the calls into the module. This is only supported for managed modules. This argument is optional and defaults to no.

Do not specify both enable-in and disable-in for the same module.

Other fields may be present, but it is recommended that field names that are not specified in this document start with a x- prefix.

## GLOBAL CONFIGURATION
A global configuration may also be present. This file contains settings that are not related to a single PKCS#11 module. The location(s) of the global configuration are described below. The global configuration file can contain the following fields:

user-config:

This will be equal to one of the following values: none, merge, only.

managed:

Set to yes or no to force all modules to be managed or unmanaged by p11-kit. Setting this setting in a global configuration file will override the managed setting in the individual module configuration files. Making modules unmanaged is not recommended, and will cause problems if multiple callers in a single process share a PKCS#11 module. This argument is optional.

log-calls:

Set to yes to write a log to stderr of all the calls into all configured modules. This is only supported for managed modules. This argument is optional.

Other fields may be present, but it is recommended that field names that are not specified in this document start with a x- prefix.

## CONFIGURATION FILES
Each configured PKCS#11 module has its own config file. These files are placed in a directory. In addition a global config file exists. There is a system configuration consisting of the various module config files and a file for global configuration. Optionally each user can provide additional configuration or override the system configuration.

The system global configuration file is usually in /etc/pkcs11/pkcs11.conf and the user global configuration file is in ~/.config/pkcs11/pkcs11.conf in the user's home directory.

The module config files are usually located in the /etc/pkcs11/modules directory, with one configuration file per module. In addition the ~/.config/pkcs11/modules directory can be used for modules installed by the user.

Note that user configuration files are not loaded from the home directory if running inside a setuid or setgid program.

The default system config file and module directory can be changed when building p11-kit. Always lookup these paths using pkg-config.

## SEE ALSO
p11-kit(8)

Further details available in the p11-kit online documentation at https://p11-glue.github.io/p11-glue/p11-kit/manual/.


papersize

package: libpaper

title: papersize(5)

summary: specify preferred paper size

text:
# papersize(5)

## NAME
papersize - specify preferred paper size

## SYNOPSYS
/etc/papersize

## DESCRIPTION
The papersize file is used to specify the preferred paper size to use by available commands and programs generating documents.

The format of this file is extremely simple: whitespace and anything starting with `#' is ignored, and the name of the paper is the first string found; the case in the name of the paper does not import (see CAVEATS section however).

## PAPER NAMES
The following names are commonly understood by programs: a3, a4, a5, b5, letter, legal, executive, note and 11x17.

Additional paper names that one may encounter are: a0, a1, a2, a6, a7, a8, a9, a10, b0, b1, b2, b3, b4, tabloid, statement, note, halfletter, halfexecutive, folio, quarto, ledger, archA, archB, archC, archD, archE, flsa, flse, csheet, dsheet, esheet and 10x14.

The value of the papersize file can be overrideen by looking in order at the PAPERSIZE environment variable, then at the contents of the file specified by the PAPERCONF environment variable. If the papersize file does not exist, programs using the paper library default to using letter as a fall-back value

## CAVEATS
This manual page documents the format of the papersize file that is read by the libpaper library. Some programs that read this file do not yet use the library and may have trouble ignoring whitespace and comments in the file; they may also require that the paper names use a specific capitalization.

## DOCUMENTATION
Yves Arrouye <arrouye@debian.org>

## SEE ALSO
paperconf(1)

paperconfig(8)


passwdqc.conf

package: libpasswdqc

title: passwdqc.conf(5)

summary: libpasswdqc configuration file

text:
# passwdqc.conf(5)

## NAME
passwdqc.conf — libpasswdqc configuration file

## DESCRIPTION
libpasswdqc is a simple password strength checking library. In addition to checking regular passwords, it offers support for passphrases and can provide randomly generated ones. A passwdqc.conf configuration file may be used to override default libpasswdqc settings.

## FORMAT
A passwdqc.conf file consists of 0 or more lines of the following format:

option=value

Empty lines and lines beginning with “#” are ignored. Whitespace characters between the option, “=”, and value are not allowed.

## DIRECTIVE OPTIONS
config=FILE

Load the specified configuration FILE in the passwdqc.conf format. This file may define any options described in this manual, including load of yet another configuration file, but loops are not allowed.

## PASSWORD QUALITY CONTROL OPTIONS
min=N0,N1,N2,N3,N4

(default: min=disabled,24,11,8,7) The minimum allowed password lengths for different kinds of passwords/passphrases. The keyword disabled can be used to disallow passwords of a given kind regardless of their length. Each subsequent number is required to be no larger than the preceding one. N0 is used for passwords consisting of characters from one character class only. The character classes are: digits, lower-case letters, upper-case letters, and other characters. There is also a special class for non-ASCII characters, which could not be classified, but are assumed to be non-digits.

N1 is used for passwords consisting of characters from two character classes that do not meet the requirements for a passphrase.

N2 is used for passphrases. Note that besides meeting this length requirement, a passphrase must also consist of a sufficient number of words (see the passphrase option below).

N3 and N4 are used for passwords consisting of characters from three and four character classes, respectively.

When calculating the number of character classes, upper-case letters used as the first character and digits used as the last character of a password are not counted.

In addition to being sufficiently long, passwords are required to contain enough different characters for the character classes and the minimum length they have been checked against.

max=N

(default: max=72) The maximum allowed password length. This can be used to prevent users from setting passwords that may be too long for some system services. The value 8 is treated specially: if max is set to 8, passwords longer than 8 characters will not be rejected, but will be truncated to 8 characters for the strength checks and the user will be warned. This is to be used with the traditional DES-based password hashes, which truncate the password at 8 characters. It is important that you do set max=8 if you are using the traditional hashes, or some weak passwords will pass the checks.

passphrase=N

(default: passphrase=3) The number of words required for a passphrase, or 0 to disable the support for user-chosen passphrases.

match=N

(default: match=4) The length of common substring required to conclude that a password is at least partially based on information found in a character string, or 0 to disable the substring search. Note that the password will not be rejected once a weak substring is found; it will instead be subjected to the usual strength requirements with the weak substring partially discounted. The substring search is case-insensitive and is able to detect and remove a common substring spelled backwards.

similar=permit|deny

(default: similar=deny) Whether a new password is allowed to be similar to the old one. The passwords are considered to be similar when there is a sufficiently long common substring and the new password with the substring partially discounted would be weak.

wordlist=FILE

Deny passwords that are based on lines of the tiny external text FILE, which can reasonably be e.g. a list of a few thousand common passwords. Common dictionary words may also reasonably be included, especially in a local language other than English, or longer yet common English words. (passwdqc includes a list of a few thousand common English words of lengths from 3 to 6 built in. Any word list possibly specified with this option is used in addition to the built-in word list.) Substring matching and discounting will be used if the match setting above is non-zero. Please note that this is very inefficient, and isn't to be used with large wordlists.

denylist=FILE

Deny passwords or passphrases directly appearing in the tiny external text FILE. That file can reasonably be e.g. a list of common passwords if only a relaxed policy is desired and stricter checks are thus disabled (using their separate options). Such policy would only be somewhat effective against online/remote attacks, but not against offline attacks on hashed passwords.

filter=FILE

Deny passwords or passphrases directly appearing in a maybe huge binary filter FILE created with pwqfilter. This is very efficient, needing at most two random disk reads per query. A filter created from millions of leaked passwords can reasonably be used on top of passwdqc's other checks to further reduce the number of passing yet weak passwords without causing unreasonable inconvenience (as e.g. higher minimum lengths and character set requirements could).

random=N[,only]

(default: random=47) The size of randomly-generated passphrases in bits (24 to 136), or 0 to disable this feature. Any passphrase that contains the offered randomly-generated string will be allowed regardless of other possible restrictions. The only modifier can be used to disallow user-chosen passwords.

## PAM MODULE OPTIONS
enforce=none|users|everyone

(default: enforce=everyone) The PAM module can be configured to warn of weak passwords only, but not actually enforce strong passwords. The users setting will enforce strong passwords for invocations by non-root users only.

non-unix

Normally, the PAM module uses getpwnam(3) to obtain the user's personal login information and use that during the password strength checks. This behavior can be disabled with the non-unix option.

retry=N

(default: retry=3) The number of times the PAM module will ask for a new password if the user fails to provide a sufficiently strong password and enter it twice the first time.

ask_oldauthtok[=update]

Ask for the old password as well. Normally, the PAM module leaves this task for subsequent modules. With no argument, the ask_oldauthtok option will cause the PAM module to ask for the old password during the preliminary check phase. If the ask_oldauthtok option is specified with the update argument, the PAM module will do that during the update phase.

check_oldauthtok

This tells the PAM module to validate the old password before giving a new password prompt. Normally, this task is left for subsequent modules. The primary use for this option is when ask_oldauthtok=update is also specified, in which case no other module gets a chance to ask for and validate the password. Of course, this will only work with UNIX passwords.

use_first_pass, use_authtok

Use the new password obtained by other modules stacked before the PAM module. This disables user interaction within the PAM module. The only difference between use_first_pass and use_authtok is that the former is incompatible with ask_oldauthtok.

noaudit

If audit is enabled at build time, the PAM module logs audit events once user tries to change their credentials. This option disables that audit logging.

## FILES
/etc/passwdqc.conf (not read unless this suggested file location is specified with the config=/etc/passwdqc.conf option).

## SEE ALSO
getpwnam(3), libpasswdqc(3), pam_passwdqc(8).

https://www.openwall.com/passwdqc/

## AUTHORS
The pam_passwdqc module was written for Openwall GNU/*/Linux by Solar Designer ⟨solar at openwall.com⟩. This manual page was derived from pam_passwdqc(8). The latter, derived from the author's documentation, was written for the FreeBSD Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 (“CBOSS”), as part of the DARPA CHATS research program.


pcap-savefile

package: libpcap-devel

title: pcap-savefile(5)

summary: libpcap savefile format

text:
# pcap-savefile(5)

## NAME
pcap-savefile - libpcap savefile format

## DESCRIPTION
NOTE: applications and libraries should, if possible, use libpcap to read savefiles, rather than having their own code to read savefiles. If, in the future, a new file format is supported by libpcap, applications and libraries using libpcap to read savefiles will be able to read the new format of savefiles, but applications and libraries using their own code to read savefiles will have to be changed to support the new file format.

``Savefiles'' read and written by libpcap and applications using libpcap start with a per-file header. The format of the per-file header is:

Magic number

Major version

Minor version

Time zone offset

Time stamp accuracy

Snapshot length

Link-layer header type

The per-file header length is 24 octets.

All fields in the per-file header are in the byte order of the host writing the file. Normally, the first field in the per-file header is a 4-byte magic number, with the value 0xa1b2c3d4. The magic number, when read by a host with the same byte order as the host that wrote the file, will have the value 0xa1b2c3d4, and, when read by a host with the opposite byte order as the host that wrote the file, will have the value 0xd4c3b2a1. That allows software reading the file to determine whether the byte order of the host that wrote the file is the same as the byte order of the host on which the file is being read, and thus whether the values in the per-file and per-packet headers need to be byte-swapped.

If the magic number has the value 0xa1b23c4d (with the two nibbles of the two lower-order bytes of the magic number swapped), which would be read as 0xa1b23c4d by a host with the same byte order as the host that wrote the file and as 0x4d3cb2a1 by a host with the opposite byte order as the host that wrote the file, the file format is the same as for regular files, except that the time stamps for packets are given in seconds and nanoseconds rather than seconds and microseconds.

Following this are:

A 2-byte file format major version number; the current version number is 2.

A 2-byte file format minor version number; the current version number is 4.

A 4-byte time zone offset; this is always 0.

A 4-byte number giving the accuracy of time stamps in the file; this is always 0.

A 4-byte number giving the "snapshot length" of the capture; packets longer than the snapshot length are truncated to the snapshot length, so that, if the snapshot length is N, only the first N bytes of a packet longer than N bytes will be saved in the capture.

a 4-byte number giving the link-layer header type for packets in the capture; see pcap-linktype(7) for the LINKTYPE_ values that can appear in this field.

Following the per-file header are zero or more packets; each packet begins with a per-packet header, which is immediately followed by the raw packet data. The format of the per-packet header is:

Time stamp, seconds value

Time stamp, microseconds or nanoseconds value

Length of captured packet data

Un-truncated length of the packet data

The per-packet header length is 16 octets.

All fields in the per-packet header are in the byte order of the host writing the file. The per-packet header begins with a time stamp giving the approximate time the packet was captured; the time stamp consists of a 4-byte value, giving the time in seconds since January 1, 1970, 00:00:00 UTC, followed by a 4-byte value, giving the time in microseconds or nanoseconds since that second, depending on the magic number in the file header. Following that are a 4-byte value giving the number of bytes of captured data that follow the per-packet header and a 4-byte value giving the number of bytes that would have been present had the packet not been truncated by the snapshot length. The two lengths will be equal if the number of bytes of packet data are less than or equal to the snapshot length.

## SEE ALSO
pcap(3PCAP)


package: libpmem-devel

title: pmem_ctl(5)

text:
# pmem_ctl(5)

## NAME
ctl - interface for examination and modification of the library’s internal state.

## DESCRIPTION
The CTL namespace is organized in a tree structure. Starting from the root, each node can be either internal, containing other elements, or a leaf. Internal nodes themselves can only contain other nodes and cannot be entry points. There are two types of those nodes: named and indexed. Named nodes have string identifiers. Indexed nodes represent an abstract array index and have an associated string identifier. The index itself is provided by the user. A collection of indexes present on the path of an entry point is provided to the handler functions as name and index pairs.

Entry points are the leaves of the CTL namespace structure. Each entry point can read from the internal state, write to the internal state, exec a function or a combination of these operations.

The entry points are listed in the following format:

name | r(ead)w(rite)x(ecute) | global/- | read argument type | write argument type | exec argument type | config argument type

A description of pmem_ctl functions can be found on the following manual pages: libpmemblk_ctl_get(3), libpmemlog_ctl_get(3), libpmemobj_ctl_get(3)

## CTL EXTERNAL CONFIGURATION
In addition to direct function call, each write entry point can also be set using two alternative methods.

The first method is to load a configuration directly from the PMEMBLK_CONF/ PMEMLOG_CONF/ PMEMOBJ_CONF environment variable. A properly formatted ctl config string is a single-line sequence of queries separated by `;':

```
query0;query1;...;queryN

```

A single query is constructed from the name of the ctl write entry point and the argument, separated by `=':

```
entry_point=entry_point_argument

```

The entry point argument type is defined by the entry point itself, but there are three predefined primitives:

```
*) integer: represented by a sequence of [0-9] characters that form

    a single number.
*) boolean: represented by a single character: y/n/Y/N/0/1, each

    corresponds to true or false. If the argument contains any

    trailing characters, they are ignored.
*) string: a simple sequence of characters.

```

There are also complex argument types that are formed from the primitives separated by a `,':

```
first_arg,second_arg

```

In summary, a full configuration sequence looks like this:

```
(first_entry_point)=(arguments, ...);...;(last_entry_point)=(arguments, ...);

```

As an example, to set both prefault at_open and at_create variables:

```
PMEMBLK_CONF="prefault.at_open=1;prefault.at_create=1"

```

The second method of loading an external configuration is to set the PMEMBLK_CONF_FILE/ PMEMLOG_CONF_FILE/ PMEMOBJ_CONF_FILE environment variable to point to a file that contains a sequence of ctl queries. The parsing rules are all the same, but the file can also contain white-spaces and comments.

To create a comment, simply use `#' anywhere in a line and everything afterwards, until a new line, will be ignored.

An example configuration file:

```
#########################
# My pmemblk configuration
#########################
#
# Global settings:
prefault. # modify the behavior of pre-faulting

    at_open = 1; # prefault when the pool is opened
prefault.

    at_create = 0; # but don't prefault when it's created
# Per-pool settings:
# ...

```

## SEE ALSO
libpmemblk_ctl_get(3), libpmemlog_ctl_get(3), libpmemobj_ctl_get(3) and <https://pmem.io>


poolset

package: libpmempool-devel

title: poolset(5)

text:
# poolset(5)

## NAME
poolset - persistent memory pool configuration file format

## SYNOPSIS

```
mypool.set

```

## DESCRIPTION
Depending on the configuration of the system, the available non-volatile memory space may be divided into multiple memory devices. In such case, the maximum size of the transactional object store could be limited by the capacity of a single memory device. Therefore, libpmemobj(7), libpmemblk(7) and libpmemlog(7) allow building object stores spanning multiple memory devices by creation of persistent memory pools consisting of multiple files, where each part of such a pool set may be stored on a different pmem-aware filesystem.

To improve reliability and eliminate single point of failure, libpmemobj(7) also allows all the data written to a persistent memory pool to be copied to local or remote pool replicas, thereby providing backup for the persistent memory pool by producing a mirrored pool set. In practice, the pool replicas may be considered as binary copies of the “master” pool set. Data replication is not supported in libpmemblk(7) and libpmemlog(7).

The set file for each type of pool is a plain text file. Lines in the file are formatted as follows:

•

The first line of the file must be the literal string “PMEMPOOLSET”

•

The pool parts are specified, one per line, in the format:

size pathname

•

Replica sections, if any, start with the literal string “REPLICA”. See REPLICAS, below, for further details.

•

Pool set options, if any, start with literal string OPTION. See POOL SET OPTIONS below for details.

•

Lines starting with “#” are considered comments and are ignored.

The size must be compliant with the format specified in IEC 80000-13, IEEE 1541 or the Metric Interchange Format. These standards accept SI units with obligatory B - kB, MB, GB, ... (multiplier by 1000) suffixes, and IEC units with optional “iB” - KiB, MiB, GiB, ..., K, M, G, ... - (multiplier by 1024) suffixes.

pathname must be an absolute pathname.

The pathname of a part can point to a Device DAX. Device DAX is the device-centric analogue of Filesystem DAX. It allows memory ranges to be allocated and mapped without need of an intervening file system.

Pools created on Device DAX have additional options and restrictions:

•

The size may be set to “AUTO”, in which case the size of the device will be automatically resolved at pool creation time.

•

To concatenate more than one Device DAX device into a single pool set, the configured internal alignment of the devices must be 4KiB, unless the SINGLEHDR or NOHDRS option is used in the pool set file. See POOL SET OPTIONS below for details.

Please see ndctl-create-namespace(1) for more information on Device DAX, including how to configure desired alignment.

The minimum file size of each part of the pool set is defined as follows:

•

For block pools, as PMEMBLK_MIN_PART in <libpmemblk.h>

•

For object pools, as PMEMOBJ_MIN_PART in <libpmemobj.h>

•

For log pools, as PMEMLOG_MIN_PART in <libpmemlog.h>

The net pool size of the pool set is equal to:

```
net_pool_size = sum_over_all_parts(page_aligned_part_size - 4KiB) + 4KiB

```

where

```
page_aligned_part_size = part_size & ~(page_size - 1)

```

Note that page size is OS specific. For more information please see sysconf(3).

The minimum net pool size of a pool set is defined as follows:

•

For block pools, as PMEMBLK_MIN_POOL in <libpmemblk.h>

•

For object pools, as PMEMOBJ_MIN_POOL in <libpmemobj.h>

•

For log pools, as PMEMLOG_MIN_POOL in <libpmemlog.h>

Here is an example “mypool.set” file:

```
PMEMPOOLSET
OPTION NOHDRS
100G /mountpoint0/myfile.part0
200G /mountpoint1/myfile.part1
400G /mountpoint2/myfile.part2

```

The files in the set may be created by running one of the following commands. To create a block pool:

```
$ pmempool create blk <bsize> mypool.set

```

To create a log pool:

```
$ pmempool create log mypool.set

```

## REPLICAS
Sections defining replica sets are optional. There may be multiple replica sections.

Local replica sections begin with a line containing only the literal string “REPLICA”, followed by one or more pool part lines as described above.

Remote replica sections consist of the REPLICA keyword, followed on the same line by the address of a remote host and a relative path to a remote pool set file:

```
REPLICA [<user>@]<hostname> [<relative-path>/]<remote-pool-set-file>

```

•

hostname must be in the format recognized by the ssh(1) remote login client

•

pathname is relative to the root config directory on the target node - see librpmem(7)

There are no other lines in the remote replica section - the REPLICA line defines a remote replica entirely.

Here is an example “myobjpool.set” file with replicas:

```
PMEMPOOLSET
100G /mountpoint0/myfile.part0
200G /mountpoint1/myfile.part1
400G /mountpoint2/myfile.part2
# local replica
REPLICA
500G /mountpoint3/mymirror.part0
200G /mountpoint4/mymirror.part1
# remote replica
REPLICA user@example.com remote-objpool.set

```

The files in the object pool set may be created by running the following command:

```
$ pmempool create --layout="mylayout" obj myobjpool.set

```

Remote replica cannot have replicas, i.e. a remote pool set file cannot define any replicas.

## POOL SET OPTIONS
Pool set options can appear anywhere after the line with PMEMPOOLSET string. Pool set file can contain several pool set options. The following options are supported:

•

SINGLEHDR

•

NOHDRS

If the SINGLEHDR option is used, only the first part in each replica contains the pool part internal metadata. In that case the effective size of a replica is the sum of sizes of all its part files decreased once by 4096 bytes.

The NOHDRS option can appear only in the remote pool set file, when librpmem does not serve as a means of replication for libpmemobj pool. In that case none of the pool parts contains internal metadata. The effective size of such a replica is the sum of sizes of all its part files.

Options SINGLEHDR and NOHDRS are mutually exclusive. If both are specified in a pool set file, creating or opening the pool will fail with an error.

When using the SINGLEHDR or NOHDRS option, one can concatenate more than one Device DAX devices with any internal alignments in one replica.

The SINGLEHDR option concerns only replicas that are local to the pool set file. That is if one wants to create a pool set with the SINGLEHDR option and with remote replicas, one has to add this option to the local pool set file as well as to every single remote pool set file.

Using the SINGLEHDR and NOHDRS options has important implications for data integrity checking and recoverability in case of a pool set damage. See pmempool_sync() API for more information about pool set recovery.

## DIRECTORIES
Providing a directory as a part’s pathname allows the pool to dynamically create files and consequently removes the user-imposed limit on the size of the pool.

The size argument of a part in a directory poolset becomes the size of the address space reservation required for the pool. In other words, the size argument is the maximum theoretical size of the mapping. This value can be freely increased between instances of the application, but decreasing it below the real required space will result in an error when attempting to open the pool.

The directory must NOT contain user created files with extension .pmem, otherwise the behavior is undefined. If a file created by the library within the directory is in any way altered (resized, renamed) the behavior is undefined.

A directory poolset must exclusively use directories to specify paths - combining files and directories will result in an error. A single replica can consist of one or more directories. If there are multiple directories, the address space reservation is equal to the sum of the sizes.

The order in which the files are created is unspecified, but the library will try to maintain equal usage of the directories.

By default pools grow in 128 megabyte increments.

Only poolsets with the SINGLEHDR option can safely use directories.

## NOTES
Creation of all the parts of the pool set and the associated replica sets can be done with the pmemobj_create(3), pmemblk_create(3) or pmemlog_create(3) function, or by using the pmempool(1) utility.

Restoring data from a local or remote replica can be done by using the pmempool-sync(1) command or the pmempool_sync() API from the libpmempool(7) library.

Modifications of a pool set file configuration can be done by using the pmempool-transform(1) command or the pmempool_transform() API from the libpmempool(7) library.

When creating a pool set consisting of multiple files, or when creating a replicated pool set, the path argument passed to pmemobj_create(3), pmemblk_create(3) or pmemlog_create(3) must point to the special set file that defines the pool layout and the location of all the parts of the pool set.

When opening a pool set consisting of multiple files, or when opening a replicated pool set, the path argument passed to pmemobj_open(3), pmemblk_open(3) or pmemlog_open(3) must point to the same set file that was used for pool set creation.

## SEE ALSO
ndctl-create-namespace(1), pmemblk_create(3), pmemlog_create(3), pmemobj_create(3), sysconf(3), libpmemblk(7), libpmemlog(7), libpmemobj(7) and <https://pmem.io>


png

title: png(5)

summary: Portable Network Graphics (PNG) format

text:
# png(5)

## NAME
png - Portable Network Graphics (PNG) format

## DESCRIPTION
PNG (Portable Network Graphics) is an extensible file format for the lossless, portable, well-compressed storage of raster images. PNG provides a patent-free replacement for GIF, and can also replace many common uses of TIFF. Indexed-color, grayscale, and truecolor images are supported, plus an optional alpha channel. Sample depths range from 1 to 16 bits.

PNG is designed to work well in online viewing applications, such as the World Wide Web, so it is fully streamable with a progressive display option. PNG is robust, providing both full file integrity checking and fast, simple detection of common transmission errors. Also, PNG can store color space data for improved color matching on heterogeneous platforms.

## SEE ALSO
libpng(3), zlib(3), deflate(5), and zlib(5)

Portable Network Graphics (PNG) Specification (Third Edition):

W3C Recommendation 24 June 2025

https://www.w3.org/TR/2025/REC-png-3-20250624/

Portable Network Graphics (PNG) Specification (Second Edition):

ISO/IEC 15948:2004(E)

https://www.iso.org/standard/29581.html

W3C Recommendation 10 November 2003

https://www.w3.org/TR/2003/REC-PNG-20031110/

Portable Network Graphics (PNG) Specification Version 1.2:

Published by the PNG Development Group on 14 July 1999

https://www.libpng.org/pub/png/spec/1.2/

Portable Network Graphics (PNG) Specification Version 1.1:

Published by the PNG Development Group on 15 February 1999

https://www.libpng.org/pub/png/spec/1.1/

Portable Network Graphics (PNG) Specification Version 1.0:

IETF RFC 2083, March 1997

https://www.ietf.org/rfc/rfc2083.txt

W3C Recommendation 1 October 1996

https://www.w3.org/TR/REC-png-961001

## AUTHORS
This man page: Glenn Randers-Pehrson, Cosmin Truta, Chris Lilley.

PNG Specification (Third Edition): Chris Blume et al.

PNG Specification (Second Edition): David Duce et al.

PNG Specification Version 1.2: Glenn Randers-Pehrson et al.

PNG Specification Version 1.1: Glenn Randers-Pehrson et al.

PNG Specification Version 1.0: Thomas Boutell et al.