trafgen

title: trafgen(8)

text:
# trafgen(8)

## NAME
trafgen - a fast, multithreaded network packet generator

## SYNOPSIS
trafgen [options] [packet]

## DESCRIPTION
trafgen is a fast, zero-copy network traffic generator for debugging, performance evaluation, and fuzz-testing. trafgen utilizes the packet(7) socket interface of Linux which postpones complete control over packet data and packet headers into the user space. It has a powerful packet configuration language, which is rather low-level and not limited to particular protocols. Thus, trafgen can be used for many purposes. Its only limitation is that it cannot mimic full streams resp. sessions. However, it is very useful for various kinds of load testing in order to analyze and subsequently improve systems behaviour under DoS attack scenarios, for instance.

trafgen is Linux specific, meaning there is no support for other operating systems, same as netsniff-ng(8), thus we can keep the code footprint quite minimal and to the point. trafgen makes use of packet(7) socket's TX_RING interface of the Linux kernel, which is a mmap(2)'ed ring buffer shared between user and kernel space.

By default, trafgen starts as many processes as available CPUs, pins each of them to their respective CPU and sets up the ring buffer each in their own process space after having compiled a list of packets to transmit. Thus, this is likely the fastest one can get out of the box in terms of transmission performance from user space, without having to load unsupported or non-mainline third-party kernel modules. On Gigabit Ethernet, trafgen has a comparable performance to pktgen, the built-in Linux kernel traffic generator, except that trafgen is more flexible in terms of packet configuration possibilities. On 10-Gigabit-per-second Ethernet, trafgen might be slower than pktgen due to the user/kernel space overhead but still has a fairly high performance for out of the box kernels.

trafgen has the potential to do fuzz testing, meaning a packet configuration can be built with random numbers on all or certain packet offsets that are freshly generated each time a packet is sent out. With a built-in IPv4 ping, trafgen can send out an ICMP probe after each packet injection to the remote host in order to test if it is still responsive/alive. Assuming there is no answer from the remote host after a certain threshold of probes, the machine is considered dead and the last sent packet is printed together with the random seed that was used by trafgen. You might not really get lucky fuzz-testing the Linux kernel, but presumably there are buggy closed-source embedded systems or network driver's firmware files that are prone to bugs, where trafgen could help in finding them.

trafgen's configuration language is quite powerful, also due to the fact, that it supports C preprocessor macros. A stddef.h is being shipped with trafgen for this purpose, so that well known defines from Linux kernel or network programming can be reused. After a configuration file has passed the C preprocessor stage, it is processed by the trafgen packet compiler. The language itself supports a couple of features that are useful when assembling packets, such as built-in runtime checksum support for IP, UDP and TCP. Also it has an expression evaluator where arithmetic (basic operations, bit operations, bit shifting, ...) on constant expressions is being reduced to a single constant on compile time. Other features are ''fill'' macros, where a packet can be filled with n bytes by a constant, a compile-time random number or run-time random number (as mentioned with fuzz testing). Also, netsniff-ng(8) is able to convert a pcap file into a trafgen configuration file, thus such a configuration can be further tweaked for a given scenario.

## OPTIONS
-i <cfg|pcap|->, -c <cfg|->, --in <cfg|pcap|->, --conf <cfg|->

Defines the input configuration file that can either be passed as a normal plain text file or via stdin (''-''). Note that currently, if a configuration is passed through stdin, only 1 CPU will be used. It is also possible to specify PCAP file with .pcap extension via -i/--in option, by default packets will be sent at rate considering timestamp from PCAP file which might be reset via the -b or -t option.

-o <dev|.pcap|.cfg>, -d <dev|.pcap|.cfg>, --out <dev|.pcap|.cfg>, --dev <dev|.pcap|.cfg>

Defines the outgoing networking device such as eth0, wlan0 and others or a *.pcap or *.cfg file. Pcap and configuration files are identified by extension.

-p, --cpp

Pass the packet configuration to the C preprocessor before reading it into trafgen. This allows #define and #include directives (e.g. to include definitions from system headers) to be used in the trafgen configuration file.

-D <name>=<definition>, --define <name>=<definition>

Add macro definition for the C preprocessor to use it within trafgen file. This option is used in combination with the -p/--cpp option.

-J, --jumbo-support

By default trafgen's ring buffer frames are of a fixed size of 2048 bytes. This means that if you're expecting jumbo frames or even super jumbo frames to pass your line, then you will need to enable support for that with the help of this option. However, this has the disadvantage of a performance regression and a bigger memory footprint for the ring buffer.

-R, --rfraw

In case the output networking device is a wireless device, it is possible with trafgen to turn this into monitor mode and create a mon<X> device that trafgen will be transmitting on instead of wlan<X>, for instance. This enables trafgen to inject raw 802.11 frames. In case if the output is a pcap file the link type is set to 127 (ieee80211 radio tap).

-s <ipv4>, --smoke-test <ipv4>

In case this option is enabled, trafgen will perform a smoke test. In other words, it will probe the remote end, specified by an <ipv4> address, that is being ''attacked'' with trafgen network traffic, if it is still alive and responsive. That means, after each transmitted packet that has been configured, trafgen sends out ICMP echo requests and waits for an answer before it continues. In case the remote end stays unresponsive, trafgen assumes that the machine has crashed and will print out the content of the last packet as a trafgen packet configuration and the random seed that has been used in order to reproduce a possible bug. This might be useful when testing proprietary embedded devices. It is recommended to have a direct link between the host running trafgen and the host being attacked by trafgen.

-n <0|uint>, --num <0|uint>

Process a number of packets and then exit. If the number of packets is 0, then this is equivalent to infinite packets resp. processing until interrupted. Otherwise, a number given as an unsigned integer will limit processing.

-r, --rand

Randomize the packet selection of the configuration file. By default, if more than one packet is defined in a packet configuration, packets are scheduled for transmission in a round robin fashion. With this option, they are selected randomly instread.

-P <uint>[-<uint>], --cpus <uint>[-<uint>]

Specify the number of processes trafgen shall fork(2) off or list exact CPUs to use. By default trafgen will start as many processes as CPUs that are online and pin them to each, respectively. A single integer within interval [1,CPUs] overrides number of processes, which will be spawned starting from the first CPU. A pair of integers within interval [0,CPUs-1], and separated using ''-'' represents an interval of CPUs, which will be used to spawn worker processes.

-t <time>, --gap <time>

Specify a static inter-packet timegap in seconds, milliseconds, microseconds, or nanoseconds: ''<num>s/ms/us/ns''. If no postfix is given default to microseconds. If this option is given, then instead of packet(7)'s TX_RING interface, trafgen will use sendto(2) I/O for network packets, even if the <time> argument is 0. This option is useful for a couple of reasons:

1) comparison between sendto(2) and TX_RING performance,

2) low-traffic packet probing for a given interval,

3) ping-like debugging with specific payload patterns.

Furthermore, the TX_RING interface does not cope with interpacket gaps.

-b <rate>, --rate <rate>

Specify the packet send rate <num>pps/kpps/Mpps/B/kB/MB/GB/kbit/Mbit/Gbit/KiB/MiB/GiB units. Like with the -t/--gap option, the packets are sent in slow mode.

-S <size>, --ring-size <size>

Manually define the TX_RING resp. TX_RING size in ''<num>KiB/MiB/GiB''. By default the size is being determined based on the network connectivity rate.

-E <uint>, --seed <uint>

Manually set the seed for pseudo random number generator (PRNG) in trafgen. By default, a random seed from /dev/urandom is used to feed glibc's PRNG. If that fails, it falls back to the unix timestamp. It can be useful to set the seed manually in order to be able to reproduce a trafgen session, e.g. after fuzz testing.

-u <uid>, --user <uid> resp. -g <gid>, --group <gid>

After ring setup, drop privileges to a non-root user/group combination.

-H, --prio-high

Set this process as a high priority process in order to achieve a higher scheduling rate resp. CPU time. This is however not the default setting, since it could lead to starvation of other processes, for example low priority kernel threads.

-A, --no-sock-mem

Do not change systems default socket memory setting during testrun. Default is to boost socket buffer memory during the test to:

/proc/sys/net/core/rmem_default:4194304

/proc/sys/net/core/wmem_default:4194304

/proc/sys/net/core/rmem_max:104857600

/proc/sys/net/core/wmem_max:104857600

-Q, --notouch-irq

Do not reassign the NIC's IRQ CPU affinity settings.

-q, --qdisc-path

Since Linux 3.14, the kernel supports a socket option PACKET_QDISC_BYPASS, which trafgen enables by default. This options disables the qdisc bypass, and uses the normal send path through the kernel's qdisc (traffic control) layer, which can be usefully for testing the qdisc path.

-V, --verbose

Let trafgen be more talkative and let it print the parsed configuration and some ring buffer statistics.

-e, --example

Show a built-in packet configuration example. This might be a good starting point for an initial packet configuration scenario.

-C, --no-cpu-stats

Do not print CPU time statistics on exit.

-v, --version

Show version information and exit.

-h, --help

Show user help and exit.

## SYNTAX
trafgen's packet configuration syntax is fairly simple. The very basic things one needs to know is that a configuration file is a simple plain text file where packets are defined. It can contain one or more packets. Packets are enclosed by opening '{' and closing '}' braces, for example:

{ /* packet 1 content goes here ... */ }

{ /* packet 2 content goes here ... */ }

Alternatively, packets can also be specified directly on the command line, using the same syntax as used in the configuration files.

When trafgen is started using multiple CPUs (default), then each of those packets will be scheduled for transmission on all CPUs by default. However, it is possible to tell trafgen to schedule a packet only on a particular CPU:

cpu(1): { /* packet 1 content goes here ... */ }

cpu(2-3): { /* packet 2 content goes here ... */ }

Thus, in case we have a 4 core machine with CPU0-CPU3, packet 1 will be scheduled only on CPU1, packet 2 on CPU2 and CPU3. When using trafgen with --num option, then these constraints will still be valid and the packet is fairly distributed among those CPUs.

Packet content is delimited either by a comma or whitespace, or both:

{ 0xca, 0xfe, 0xba 0xbe }

Packet content can be of the following:

hex bytes: 0xca, xff

decimal: 42

binary: 0b11110000, b11110000

octal: 011

character: 'a'

string: "hello world"

shellcode: "\x31\xdb\x8d\x43\x17\x99\xcd\x80\x31\xc9"

Thus, a quite useless packet configuration might look like this (one can verify this when running this with trafgen in combination with -V):

{ 0xca, 42, 0b11110000, 011, 'a', "hello world",

"\x31\xdb\x8d\x43\x17\x99\xcd\x80\x31\xc9" }

There are a couple of helper functions in trafgen's language to make life easier to write configurations:

i) Fill with garbage functions:

byte fill function: fill(<content>, <times>): fill(0xca, 128)

compile-time random: rnd(<times>): rnd(128), rnd()

runtime random numbers: drnd(<times>): drnd(128), drnd()

compile-time counter: seqinc(<start-val>, <times>, <increment>)

seqdec(<start-val>, <times>, <decrement>)

runtime counter (1byte): dinc(<min-val>, <max-val>, <increment>)

ddec(<min-val>, <max-val>, <decrement>)

ii) Checksum helper functions (packet offsets start with 0):

IP/ICMP checksum: csumip/csumicmp(<off-from>, <off-to>)

UDP checksum: csumudp(<off-iphdr>, <off-udpdr>)

TCP checksum: csumtcp(<off-iphdr>, <off-tcphdr>)

UDP checksum (IPv6): csumudp6(<off-ip6hdr>, <off-udpdr>)

TCP checksum (IPv6): csumtcp6(<off-ip6hdr>, <off-tcphdr>)

iii) Multibyte functions, compile-time expression evaluation:

const8(<content>), c8(<content>), const16(<content>), c16(<content>),

const32(<content>), c32(<content>), const64(<content>), c64(<content>)

These functions write their result in network byte order into the packet configuration, e.g. const16(0xaa) will result in ''00 aa''. Within c*() functions, it is possible to do some arithmetics: -,+,*,/,%,&,|,<<,>>,^ E.g. const16((((1<<8)+0x32)|0b110)*2) will be evaluated to ''02 6c''.

iv) Protocol header functions:

The protocol header functions allow to fill protocol header fields by using following generic syntax:

<proto>(<field>=<value>,<field2>=<value2>,...,<field3>,...)

If a field is not specified, then a default value will be used (usually 0). Protocol fields might be set in any order. However, the offset of the fields in the resulting packet is according to the respective protocol.

Each field might be set with a function which generates field value at runtime by increment or randomize it. For L3/L4 protocols the checksum is calculated automatically if the field was changed dynamically by specified function. The following field functions are supported:

dinc - increment field value at runtime. By default increment step is '1'. min and max parameters are used to increment field only in the specified range, by default original field value is used. If the field length is greater than 4 then last 4 bytes are incremented only (useful for MAC and IPv6 addresses):

<field> = dinc() | dinc(min, max) | dinc(min, max, step)

drnd - randomize field value at runtime. min and max parameters are used to randomize field only in the specified range:

<field> = drnd() | drnd(min, max)

Example of using dynamic functions:

{

eth(saddr=aa:bb:cc:dd:ee:ff, saddr=dinc()),

ipv4(saddr=dinc()),

udp(sport=dinc(1, 13, 2), dport=drnd(80, 100))

}

Fields might be further manipulated with a function at a specific offset:

<field>[<index>] | <field>[<index>:<length>]

<index> - relative field offset with range 0..<field.len> - 1

<length> - length/size of the value which will be set; either 1, 2 or 4 bytes (default: 1)

The <index> starts from the field's first byte in network order.

The syntax is similar to the one used in pcap filters (man pcap-filter) for matching header field at a specified offset.

Examples of using field offset (showing the effect in a shortenet output from netsniff-ng):

1) trafgen -o lo --cpus 1 -n 3 '{ eth(da=11:22:33:44:55:66, da[0]=dinc()), tcp() }'

[ Eth MAC (00:00:00:00:00:00 => 11:22:33:44:55:66)

[ Eth MAC (00:00:00:00:00:00 => 12:22:33:44:55:66)

[ Eth MAC (00:00:00:00:00:00 => 13:22:33:44:55:66)

2) trafgen -o lo --cpus 1 -n 3 '{ ipv4(da=1.2.3.4, da[0]=dinc()), tcp() }'

[ IPv4 Addr (127.0.0.1 => 1.2.3.4)

[ IPv4 Addr (127.0.0.1 => 2.2.3.4)

[ IPv4 Addr (127.0.0.1 => 3.2.3.4)

All required lower layer headers will be filled automatically if they were not specified by the user. The headers will be filled in the order they were specified. Each header will be filled with some mimimum required set of fields.

Supported protocol headers:

Ethernet : eth(da=<mac>, sa=<mac>, type=<number>)

da|daddr - Destination MAC address (default: 00:00:00:00:00:00)

sa|saddr - Source MAC address (default: device MAC address)

etype|type|prot|proto - Ethernet type (default: 0)

PAUSE (IEEE 802.3X) : pause(code=<number>, time=<number>)

code - MAC Control opcode (default: 0x0001)

time - Pause time (default: 0)

By default Ethernet header is added with a fields:

Ethernet type - 0x8808

Destination MAC address - 01:80:C2:00:00:01

PFC : pfc(pri|prio(<number>)=<number>, time(<number>)=<number>)

code - MAC Control opcode (default: 0x0101)

pri|prio - Priority enable vector (default: 0)

pri|prio(<number>) - Enable/disable (0 - disable, 1 - enable) pause for priority <number> (default: 0)

time(<number>) - Set pause time for priority <number> (default: 0)

By default Ethernet header is added with a fields:

Ethernet type - 0x8808

Destination MAC address - 01:80:C2:00:00:01

VLAN : vlan(tpid=<number>, id=<number>, dei=<number>, tci=<number>, pcp=<number>, 1q, 1ad)

tpid|prot|proto - Tag Protocol Identifier (TPID) (default: 0x8100)

tci - Tag Control Information (TCI) field (VLAN Id + PCP + DEI) (default: 0)

dei|cfi - Drop Eligible Indicator (DEI), formerly Canonical Format Indicator (CFI) (default: 0)

pcp - Priority code point (PCP) (default: 0)

id - VLAN Identifier (default: 0)

1q - Set 802.1q header (TPID: 0x8100)

1ad - Set 802.1ad header (TPID: 0x88a8)

By default, if the lower level header is Ethernet, its EtherType is set to 0x8100 (802.1q).

MPLS : mpls(label=<number>, tc|exp=<number>, last=<number>, ttl=<number>)

label|lbl - MPLS label value (default: 0)

tclass|tc|exp - Traffic Class for QoS field (default: 0)

last - Bottom of stack S-flag (default: 1 for most last label)

ttl - Time To Live (TTL) (default: 0)

By default, if the lower level header is Ethernet, its EtherType is set to 0x8847 (MPLS Unicast). S-flag is set automatically to 1 for the last label and resets to 0 if the lower MPLS label was added after.

ARP : arp(htype=<number>, ptype=<number>, op=<request|reply|number>, request, reply, smac=<mac>, sip=<ip4_addr>, tmac=<mac>, tip=<ip4_addr>)

htype - ARP hardware type (default: 1 [Ethernet])

ptype - ARP protocol type (default: 0x0800 [IPv4])

op - ARP operation type (request/reply) (default: request)

req|request - ARP Request operation type

reply - ARP Reply operation type

smac|sha - Sender hardware (MAC) address (default: device MAC address)

sip|spa - Sender protocol (IPv4) address (default: device IPv4 address)

tmac|tha - Target hardware (MAC) address (default: 00:00:00:00:00:00)

tip|tpa - Target protocol (IPv4) address (default: device IPv4 address)

By default, the ARP operation field is set to request and the Ethernet destination MAC address is set to the broadcast address (ff:ff:ff:ff:ff:ff).

IPv4 : ip4|ipv4(ihl=<number>, ver=<number>, len=<number>, csum=<number>, ttl=<number>, tos=<number>, dscp=<number>, ecn=<number>,

id=<number>, flags=<number>, frag=<number>, df, mf, da=<ip4_addr>, sa=<ip4_addr>, prot[o]=<number>)

ver|version - Version field (default: 4)

ihl - Header length in number of 32-bit words (default: 5)

tos - Type of Service (ToS) field (default: 0)

dscp - Differentiated Services Code Point (DSCP, DiffServ) field (default: 0)

ecn - Explicit Congestion Notification (ECN) field (default: 0)

len|length - Total length of header and payload (calculated by default)

id - IPv4 datagram identification (default: 0)

flags - IPv4 flags value (DF, MF) (default: 0)

df - Don't fragment (DF) flag (default: 0)

mf - More fragments (MF) flag (default: 0)

frag - Fragment offset field in number of 8 byte blocks (default: 0)

ttl - Time to live (TTL) field (default: 0)

csum - Header checksum (calculated by default)

sa|saddr - Source IPv4 address (default: device IPv4 address)

da|daddr - Destination IPv4 address (default: 0.0.0.0)

prot|proto - IPv4 protocol number (default: 0)

By default, if the lower level header is Ethernet, its EtherType field is set to 0x0800 (IPv4). If the lower level header is IPv4, its protocol field is set to 0x4 (IP-in-IP).

IPv6 : ip6|ipv6(ver=<number>, class=<number>, flow=<number> len=<number>, nexthdr=<number>, hoplimit=<number>,

da=<ip6_addr>, sa=<ip6_addr>)

ver|version - Version field (default: 6)

tc|tclass - Traffic class (default: 0)

fl|flow - Flow label (default: 0)

len|length - Payload length (calculated by default)

nh|nexthdr - Type of next header, i.e. transport layer protocol number (default: 0)

hl|hoplimit|ttl - Hop limit, i.e. time to live (default: 0)

sa|saddr - Source IPv6 address (default: device IPv6 address)

da|daddr - Destination IPv6 address (default: 0:0:0:0:0:0:0:0)

By default, if the lower level header is Ethernet, its EtherType field is set to 0x86DD (IPv6).

ICMPv4 : icmp4|icmpv4(type=<number>, code=<number>, echorequest, echoreply, csum=<number>, mtu=<number>, seq=<number>, id=<number>, addr=<ip4_addr>)

type - Message type (default: 0 - Echo reply)

code - Message code (default: 0)

echorequest - ICMPv4 echo (ping) request (type: 8, code: 0)

echoreply - ICMPv4 echo (ping) reply (type: 0, code: 0)

csum - Checksum of ICMPv4 header and payload (calculated by default)

mtu - Next-hop MTU field used in 'Datagram is too big' message type (default; 0)

seq - Sequence number used in Echo/Timestamp/Address mask messages (default: 0)

id - Identifier used in Echo/Timestamp/Address mask messages (default: 0)

addr - IPv4 address used in Redirect messages (default: 0.0.0.0)

Example ICMP echo request (ping):

{ icmpv4(echorequest, seq=1, id=1326) }

ICMPv6 : icmp6|icmpv6(type=<number>, echorequest, echoreply, code=<number>, csum=<number>)

type - Message type (default: 0)

code - Code (default: 0)

echorequest - ICMPv6 echo (ping) request

echoreply - ICMPv6 echo (ping) reply

csum - Message checksum (calculated by default)

By default, if the lower level header is IPv6, its Next Header field is set to 58 (ICMPv6).

UDP : udp(sp=<number>, dp=<number>, len=<number>, csum=<number>)

sp|sport - Source port (default: 0)

dp|dport - Destination port (default: 0)

len|length - Length of UDP header and data (calculated by default)

csum - Checksum field over IPv4 pseudo header (calculated by default)

By default, if the lower level header is IPv4, its protocol field is set to 0x11 (UDP).

TCP : tcp(sp=<number>, dp=<number>, seq=<number>, aseq|ackseq=<number>, doff|hlen=<number>, cwr, ece|ecn, urg, ack, psh, rst, syn, fin, win|window=<number>, csum=<number>, urgptr=<number>)

sp|sport - Source port (default: 0)

dp|dport - Destination port (default: 0)

seq - Sequence number (default: 0)

aseq|ackseq - Acknowledgement number (default: 0)

doff|hlen - Header size (data offset) in number of 32-bit words (default: 5)

cwr - Congestion Window Reduced (CWR) flag (default: 0)

ece|ecn - ECN-Echo (ECE) flag (default: 0)

urg - Urgent flag (default: 0)

ack - Acknowledgement flag (default: 0)

psh - Push flag (default: 0)

rst - Reset flag (default: 0)

syn - Synchronize flag (default: 0)

fin - Finish flag (default: 0)

win|window - Receive window size (default: 0)

csum - Checksum field over IPv4 pseudo header (calculated by default)

urgptr - Urgent pointer (default: 0)

By default, if the lower level header is IPv4, its protocol field is set to 0x6 (TCP).

Simple example of a UDP Echo packet:

{

eth(da=11:22:33:44:55:66),

ipv4(daddr=1.2.3.4)

udp(dp=7),

"Hello world"

}

Furthermore, there are two types of comments in trafgen configuration files:

1. Multi-line C-style comments: /* put comment here */

2. Single-line Shell-style comments: # put comment here

Next to all of this, a configuration can be passed through the C preprocessor before the trafgen compiler gets to see it with option --cpp. To give you a taste of a more advanced example, run ''trafgen -e'', fields are commented:

/* Note: dynamic elements make trafgen slower! */

\#include <stddef.h>

{

/* MAC Destination */

fill(0xff, ETH_ALEN),

/* MAC Source */

0x00, 0x02, 0xb3, drnd(3),

/* IPv4 Protocol */

c16(ETH_P_IP),

/* IPv4 Version, IHL, TOS */

0b01000101, 0,

/* IPv4 Total Len */

c16(59),

/* IPv4 Ident */

drnd(2),

/* IPv4 Flags, Frag Off */

0b01000000, 0,

/* IPv4 TTL */

64,

/* Proto TCP */

0x06,

/* IPv4 Checksum (IP header from, to) */

csumip(14, 33),

/* Source IP */

drnd(4),

/* Dest IP */

drnd(4),

/* TCP Source Port */

drnd(2),

/* TCP Dest Port */

c16(80),

/* TCP Sequence Number */

drnd(4),

/* TCP Ackn. Number */

c32(0),

/* TCP Header length + TCP SYN/ECN Flag */

c16((8 << 12) | TCP_FLAG_SYN | TCP_FLAG_ECE)

/* Window Size */

c16(16),

/* TCP Checksum (offset IP, offset TCP) */

csumtcp(14, 34),

/* TCP Options */

0x00, 0x00, 0x01, 0x01, 0x08, 0x0a, 0x06,

0x91, 0x68, 0x7d, 0x06, 0x91, 0x68, 0x6f,

/* Data blob */

"gotcha!",

}

Another real-world example by Jesper Dangaard Brouer [1]:

{

\# --- ethernet header ---

0x00, 0x1b, 0x21, 0x3c, 0x9d, 0xf8, # mac destination

0x90, 0xe2, 0xba, 0x0a, 0x56, 0xb4, # mac source

const16(0x0800), # protocol

\# --- ip header ---

\# ipv4 version (4-bit) + ihl (4-bit), tos

0b01000101, 0,

\# ipv4 total len

const16(40),

\# id (note: runtime dynamic random)

drnd(2),

\# ipv4 3-bit flags + 13-bit fragment offset

\# 001 = more fragments

0b00100000, 0,

64, # ttl

17, # proto udp

\# dynamic ip checksum (note: offsets are zero indexed)

csumip(14, 33),

192, 168, 51, 1, # source ip

192, 168, 51, 2, # dest ip

\# --- udp header ---

\# as this is a fragment the below stuff does not matter too much

const16(48054), # src port

const16(43514), # dst port

const16(20), # udp length

\# udp checksum can be dyn calc via csumudp(offset ip, offset tcp)

\# which is csumudp(14, 34), but for udp its allowed to be zero

const16(0),

\# payload

'A', fill(0x41, 11),

}

[1] https://marc.info/?l=linux-netdev&m=135903630614184

The above example rewritten using the header generation functions:

{

\# --- ethernet header ---

eth(da=00:1b:21:3c:9d:f8, sa=90:e2:ba:0a:56:b4)

\# --- ip header ---

ipv4(id=drnd(), mf, ttl=64, sa=192.168.51.1, da=192.168.51.2)

\# --- udp header ---

udp(sport=48054, dport=43514, csum=0)

\# payload

'A', fill(0x41, 11),

}

## USAGE EXAMPLE
trafgen --dev eth0 --conf trafgen.cfg

This is the most simple and, probably, the most common use of trafgen. It will generate traffic defined in the configuration file ''trafgen.cfg'' and transmit this via the ''eth0'' networking device. All online CPUs are used.

trafgen --dev eth0 --conf trafgen.cfg --cpus 2-4

Instead of using all online CPUs, transmit traffic from CPUs 2, 3, and 4.

trafgen -e | trafgen -i - -o lo --cpp -n 1

This is an example where we send one packet of the built-in example through the loopback device. The example configuration is passed via stdin and also through the C preprocessor before trafgen's packet compiler will see it.

trafgen --dev eth0 --conf fuzzing.cfg --smoke-test 10.0.0.1

Read the ''fuzzing.cfg'' packet configuration file (which contains drnd() calls) and send out the generated packets to the ''eth0'' device. After each sent packet, ping probe the attacked host with address 10.0.0.1 to check if it's still alive. This also means, that we utilize 1 CPU only, and do not use the TX_RING, but sendto(2) packet I/O due to ''slow mode''.

trafgen --dev wlan0 --rfraw --conf beacon-test.txf -V --cpus 2

As an output device ''wlan0'' is used and put into monitoring mode, thus we are going to transmit raw 802.11 frames through the air. Use the ''beacon-test.txf'' configuration file, set trafgen into verbose mode and use only 2 CPUs starting from CPU 0.

trafgen --dev em1 --conf frag_dos.cfg --rand --gap 1000us

Use trafgen in sendto(2) mode instead of TX_RING mode and sleep after each sent packet a static timegap for 1000us. Generate packets from ''frag_dos.cfg'' and select next packets to send randomly instead of a round-robin fashion. The output device for packets is ''em1''.

trafgen --dev eth0 --conf icmp.cfg --rand --num 1400000 -k1000

Send only 1400000 packets using the ''icmp.cfg'' configuration file and then exit trafgen. Select packets randomly from that file for transmission and send them out via ''eth0''. Also, trigger the kernel every 1000us for batching the ring frames from user space (default is 10us).

trafgen --dev eth0 --conf tcp_syn.cfg -u `id -u bob` -g `id -g bob`

Send out packets generated from the configuration file ''tcp_syn.cfg'' via the ''eth0'' networking device. After setting up the ring for transmission, drop credentials to the non-root user/group bob/bob.

trafgen --dev eth0 '{ fill(0xff, 6), 0x00, 0x02, 0xb3, rnd(3), c16(0x0800), fill(0xca, 64) }' -n 1

Send out 1 invaid IPv4 packet built from command line to all hosts.

## NOTE
trafgen can saturate a Gigabit Ethernet link without problems. As always, of course, this depends on your hardware as well. Not everywhere where it says Gigabit Ethernet on the box, will you reach almost physical line rate! Please also read the netsniff-ng(8) man page, section NOTE for further details about tuning your system e.g. with tuned(8).

If you intend to use trafgen on a 10-Gbit/s Ethernet NIC, make sure you are using a multiqueue tc(8) discipline, and make sure that the packets you generate with trafgen will have a good distribution among tx_hashes so that you'll actually make use of multiqueues.

For introducing bit errors, delays with random variation and more, there is no built-in option in trafgen. Rather, one should reuse existing methods for that which integrate nicely with trafgen, such as tc(8) with its different disciplines, i.e. netem.

For more complex packet configurations, it is recommended to use high-level scripting for generating trafgen packet configurations in a more automated way, i.e. also to create different traffic distributions that are common for industrial benchmarking:

Traffic model Distribution

IMIX 64:7, 570:4, 1518:1

Tolly 64:55, 78:5, 576:17, 1518:23

Cisco 64:7, 594:4, 1518:1

RPR Trimodal 64:60, 512:20, 1518:20

RPR Quadrimodal 64:50, 512:15, 1518:15, 9218:20

The low-level nature of trafgen makes trafgen rather protocol independent and therefore useful in many scenarios when stress testing is needed, for instance. However, if a traffic generator with higher level packet descriptions is desired, netsniff-ng's mausezahn(8) can be of good use as well.

For smoke/fuzz testing with trafgen, it is recommended to have a direct link between the host you want to analyze (''victim'' machine) and the host you run trafgen on (''attacker'' machine). If the ICMP reply from the victim fails, we assume that probably its kernel crashed, thus we print the last sent packet together with the seed and quit probing. It might be very unlikely to find such a ping-of-death on modern Linux systems. However, there might be a good chance to find it on some proprietary (e.g. embedded) systems or buggy driver firmwares that are in the wild. Also, fuzz testing can be done on raw 802.11 frames, of course. In case you find a ping-of-death, please mention that you were using trafgen in your commit message of the fix!

## BUGS
For old trafgen versions only, there could occur kernel crashes: we have fixed this bug in the mainline and stable kernels under commit 7f5c3e3a8 (''af_packet: remove BUG statement in tpacket_destruct_skb'') and also in trafgen.

Probably the best is if you upgrade trafgen to the latest version.

## LEGAL
trafgen is licensed under the GNU GPL version 2.0.

## HISTORY
trafgen was originally written for the netsniff-ng toolkit by Daniel Borkmann. It is currently maintained by Tobias Klauser <tklauser@distanz.ch> and Daniel Borkmann <dborkma@tik.ee.ethz.ch>.

## SEE ALSO
netsniff-ng(8), mausezahn(8), ifpps(8), bpfc(8), flowtop(8), astraceroute(8), curvetun(8)

## AUTHOR
Manpage was written by Daniel Borkmann.

## COLOPHON
This page is part of the Linux netsniff-ng toolkit project. A description of the project, and information about reporting bugs, can be found at http://netsniff-ng.org/.


nfacct

package: nfacct

title: nfacct(8)

text:
# nfacct(8)

## NAME
nfacct - command line tool to create/retrieve/delete accounting objects

## SYNOPSIS
nfacct command [name] [options]

## DESCRIPTION
nfacct is the command line tool that allows to manipulate the Netfilter's extended accounting infrastructure.

## COMMANDS
These commands specify the action that nfacct performs. Only one of them can be specified at any given time.

list

List the existing accounting object in table.

restore

Restore accounting object table by reading from stdin. Input format is the one used as output by the list command.

add

Add new accounting object.

delete

Delete accounting object.

get

Get existing accounting object.

flush

Delete all unused accounting objects.

version

Displays the version information.

help

Displays the help message.

## OPTIONS
This tool also allows a couple of options with the get and list commands that are:

reset

That atomically obtains and resets the counters.

xml

That displays the output in XML format. json That displays the output in JSON format.

## SEE ALSO
iptables(8)

## BUGS
Please, report them to netfilter-devel@vger.kernel.org or file a bug in Netfilter's bugzilla (https://bugzilla.netfilter.org).

## AUTHORS
Pablo Neira Ayuso wrote and maintains the nfacct tool.

Man page written by Pablo Neira Ayuso <pablo@netfilter.org>.

branch: sisyphus


gssd

package: nfs-clients

title: gssd(8)

summary: RPCSEC_GSS daemon

text:
# gssd(8)

## NAME
rpc.gssd - RPCSEC_GSS daemon

## SYNOPSIS
rpc.gssd [-DfMnlvrHC] [-k keytab] [-p pipefsdir] [-d ccachedir] [-t timeout] [-T timeout] [-U timeout] [-R realm]

## INTRODUCTION
The RPCSEC_GSS protocol, defined in RFC 5403, is used to provide strong security for RPC-based protocols such as NFS.

Before exchanging RPC requests using RPCSEC_GSS, an RPC client must establish a GSS security context. A security context is shared state on each end of a network transport that enables GSS-API security services.

Security contexts are established using security credentials. A credential grants temporary access to a secure network service, much as a railway ticket grants temporary access to use a rail service.

A user typically obtains a credential by providing a password to the kinit(1) command, or via a PAM library at login time. A credential acquired with a user principal is known as a user credential (see kerberos(1) for more on principals).

Certain operations require a credential that represents no particular user or represents the host itself. This kind of credential is called a machine credential.

A host establishes its machine credential using a service principal whose encrypted password is stored in a local file known as a keytab. A machine credential remains effective without user intervention as long as the host can renew it.

Once obtained, credentials are typically stored in local temporary files with well-known pathnames.

## DESCRIPTION
To establish GSS security contexts using these credential files, the Linux kernel RPC client depends on a userspace daemon called rpc.gssd. The rpc.gssd daemon uses the rpc_pipefs filesystem to communicate with the kernel.

### User Credentials
When a user authenticates using a command such as kinit(1), the resulting credential is stored in a file with a well-known name constructed using the user's UID.

To interact with an NFS server on behalf of a particular Kerberos-authenticated user, the Linux kernel RPC client requests that rpc.gssd initialize a security context with the credential in that user's credential file.

Typically, credential files are placed in /tmp. However, rpc.gssd can search for credential files in more than one directory. See the description of the -d option for details.

### Machine Credentials
rpc.gssd searches the default keytab, /etc/krb5.keytab, in the following order for a principal and password to use when establishing the machine credential. For the search, rpc.gssd replaces <hostname> and <REALM> with the local system's hostname and Kerberos realm.

<HOSTNAME>$@<REALM>

root/<hostname>@<REALM>

nfs/<hostname>@<REALM>

host/<hostname>@<REALM>

root/<anyname>@<REALM>

nfs/<anyname>@<REALM>

host/<anyname>@<REALM>

rpc.gssd selects one of the <anyname> entries if it does not find a service principal matching the local hostname, e.g. if DHCP assigns the local hostname dynamically. The <anyname> facility enables the use of the same keytab on multiple systems. However, using the same service principal to establish a machine credential on multiple hosts can create unwanted security exposures and is therefore not recommended.

Note that <HOSTNAME>$@<REALM> is a user principal that enables Kerberized NFS when the local system is joined to an Active Directory domain using Samba. The keytab provides the password for this principal.

You can specify a different keytab by using the -k option if /etc/krb5.keytab does not exist or does not provide one of these principals.

### Credentials for UID 0
UID 0 is a special case. By default rpc.gssd uses the system's machine credentials for UID 0 accesses that require GSS authentication. This limits the privileges of the root user when accessing network resources that require authentication.

Specify the -n option when starting rpc.gssd if you'd like to force the root user to obtain a user credential rather than use the local system's machine credential.

When -n is specified, the kernel continues to request a GSS context established with a machine credential for NFSv4 operations, such as SETCLIENTID or RENEW, that manage state. If rpc.gssd cannot obtain a machine credential (say, the local system has no keytab), NFSv4 operations that require machine credentials will fail.

### Encryption types
A realm administrator can choose to add keys encoded in a number of different encryption types to the local system's keytab. For instance, a host/ principal might have keys for the aes256-cts-hmac-sha384-192, aes128-cts-hmac-sha256-128, aes256-cts-hmac-sha1-96, and aes128-cts-hmac-sha1-96 encryption types. This permits rpc.gssd to choose an appropriate encryption type that the target NFS server supports.

## OPTIONS
-D

The server name passed to GSSAPI for authentication is normally the name exactly as requested. e.g. for NFS it is the server name in the "servername:/path" mount request. Only if this servername appears to be an IP address (IPv4 or IPv6) or an unqualified name (no dots) will a reverse DNS lookup will be performed to get the canonical server name. If -D is present, a reverse DNS lookup will always be used, even if the server name looks like a canonical name. So it is needed if partially qualified, or non canonical names are regularly used.

Using -D can introduce a security vulnerability, so it is recommended that -D not be used, and that canonical names always be used when requesting services.

-f

Runs rpc.gssd in the foreground and sends output to stderr (as opposed to syslogd)

-n

When specified, UID 0 is forced to obtain user credentials which are used instead of the local system's machine credentials.

-k keytab

Tells rpc.gssd to use the keys found in keytab to obtain machine credentials. The default value is /etc/krb5.keytab.

-p path

Tells rpc.gssd where to look for the rpc_pipefs filesystem. The default value is /var/lib/nfs/rpc_pipefs.

-d search-path

This option specifies a colon separated list of directories that rpc.gssd searches for credential files. The default value is /tmp:/run/user/%U. The literal sequence "%U" can be specified to substitute the UID of the user for whom credentials are being searched.

-M

By default, machine credentials are stored in files in the first directory in the credential directory search path (see the -d option). When -M is set, rpc.gssd stores machine credentials in memory instead.

-v

Increases the verbosity of the output (can be specified multiple times).

-r

If the RPCSEC_GSS library supports setting debug level, increases the verbosity of the output (can be specified multiple times).

-R realm

Kerberos tickets from this realm will be preferred when scanning available credentials cache files to be used to create a context. By default, the default realm, as configured in the Kerberos configuration file, is preferred.

-t timeout

Timeout, in seconds, for kernel GSS contexts. This option allows you to force new kernel contexts to be negotiated after timeout seconds, which allows changing Kerberos tickets and identities frequently. The default is no explicit timeout, which means the kernel context will live the lifetime of the Kerberos service ticket used in its creation.

-T timeout

Timeout, in seconds, to create an RPC connection with a server while establishing an authenticated gss context for a user. The default timeout is set to 5 seconds. If you get messages like "WARNING: can't create tcp rpc_clnt to server %servername% for user with uid %uid%: RPC: Remote system error - Connection timed out", you should consider an increase of this timeout.

-U timeout

Timeout, in seconds, for upcall threads. Threads executing longer than timeout seconds will cause an error message to be logged. The default timeout is 30 seconds. The minimum is 5 seconds. The maximum is 600 seconds.

-C

In addition to logging an error message for threads that have timed out, the thread will be canceled and an error of -ETIMEDOUT will be reported to the kernel.

-H

Avoids setting $HOME to "/". This allows rpc.gssd to read per user k5identity files versus trying to read /.k5identity for each user. If -H is not set, rpc.gssd will use the first match found in /var/kerberos/krb5/user/$EUID/client.keytab and will not use a principal based on host and/or service parameters listed in $HOME/.k5identity.

## CONFIGURATION FILE
Many of the options that can be set on the command line can also be controlled through values set in the [gssd] section of the /etc/nfs.conf configuration file. Values recognized include:

verbosity

Value which is equivalent to the number of -v.

rpc-verbosity

Value which is equivalent to the number of -r.

use-memcache

A Boolean flag equivalent to -M.

use-machine-creds

A Boolean flag. Setting to false is equivalent to giving the -n flag.

avoid-dns

Setting to false is equivalent to providing the -D flag.

allowed-enctypes

Allows you to restrict rpc.gssd to using a subset of the encryption types permitted by the kernel and the krb5 libraries. This is useful if you need to interoperate with an NFS server that does not have support for the newer SHA2 and Camellia encryption types, for example. This configuration file option does not have an equivalent command-line option.

context-timeout

Equivalent to -t.

rpc-timeout

Equivalent to -T.

keytab-file

Equivalent to -k.

cred-cache-directory

Equivalent to -d.

preferred-realm

Equivalent to -R.

upcall-timeout

Equivalent to -U.

cancel-timed-out-upcalls

Setting to true is equivalent to providing the -C flag.

set-home

Setting to false is equivalent to providing the -H flag.

use-gss-proxy

Setting this to 1 allows gssproxy(8) to intercept GSSAPI calls and service them on behalf of rpc.gssd, enabling certain features such as keytab-based client initiation. Note that this is unrelated to the functionality that gssproxy(8) provides on behalf of the NFS server. For more information, see https://github.com/gssapi/gssproxy/blob/main/docs/NFS.md#nfs-client.

In addition, the following value is recognized from the [general] section:

pipefs-directory

Equivalent to -p.

## SEE ALSO
rpc.svcgssd(8), kerberos(1), kinit(1), krb5.conf(5), gssproxy(8)

## AUTHORS
Dug Song <dugsong@umich.edu>

Andy Adamson <andros@umich.edu>

Marius Aamodt Eriksen <marius@umich.edu>

J. Bruce Fields <bfields@umich.edu>


nfsconf

title: nfsconf(8)

text:
# nfsconf(8)

## NAME
nfsconf - Query various NFS configuration settings

## SYNOPSIS
nfsconf --dump [-v|--verbose] [-f|--file infile.conf] [outfile]

nfsconf --entry [--arg subsection] section tag

nfsconf --get [-v|--verbose] [-f|--file infile.conf] [-a|--arg subsection] section tag

nfsconf --isset [-v|--verbose] [-f|--file infile.conf] [-a|--arg subsection] section tag

nfsconf --set [-v|--verbose] [-m|--modified Modified by text] [-f|--file infile.conf] [-a|--arg subsection] section tag value

nfsconf --unset [-v|--verbose] [-f|--file infile.conf] [-a|--arg subsection] section tag

## DESCRIPTION
The nfsconf command can be used to test for and retrieve configuration settings from a range of nfs-utils configuration files.

### Modes
The following modes are available:

-d, --dump

Output an alphabetically sorted dump of the current configuration in conf file format. Accepts an optional filename in which to write the output.

-e, --entry

retrieve the config entry rather than its current expanded value

-i, --isset

Test if a specific tag has a value set.

-g, --get

Output the current value of the specified tag.

-s, --set

Update or Add a tag and value to the config file in a specified section, creating the tag, section, and file if necessary. If the section is defined as '#' then a comment is appended to the file. If a comment is set with a tag name then any exiting tagged comment with a matching name is replaced.

-u, --unset

Remove the specified tag and its value from the config file.

## OPTIONS

### Options valid in all modes
-v, --verbose

Increase verbosity and print debugging information.

-f, --file infile

Select a different config file to operate upon, default is /etc/nfs.conf

### Options only valid in --entry and --get and --isset modes.
-a, --arg subsection

Select a specific sub-section

### Options only valid in --set mode.
-m, --modified "Modified by nfsconf" Set the text on the Modified date comment in the file. Set to empty to remove.

## EXIT STATUS

### --isset mode
In this mode the command will return success (0) if the selected tag has a value, any other exit code indicates the value is not set, or some other error has occurred.

### all other modes
Success is indicated by an exit status of zero, any other status indicates an error. Error messages are output on stderr, and increasing verbosity will give more detailed explanations if any are available.

## EXAMPLES
nfsconf -v --dump --file /tmp/testconf.conf sorted.conf

Check a new config file for syntax errors and output a sorted version for ease of comparison with existing settings.

if ! nfsconf --isset gssd preferred-realm ; then echo 'No preferred realm configured for gss'; fi

The tool allows for easy testing of configuration values from shell scripts, here we test if a specific value has been set.

nfsconf --file /etc/nfsmount.conf --get --arg /home MountPoint background

Show default value for background option for NFS mounts of the /home path.

nfsconf --file /etc/nfs.conf --set nfsd debug 1

Enable debugging in nfsd

## FILES
/etc/nfs.conf

## SEE ALSO
nfsd(8), exportfs(8), idmapd(8), statd(8)

## AUTHOR
Justin Mitchell <jumitche@redhat.com>


nfsidmap

title: nfsidmap(8)

summary: The NFS idmapper upcall program

text:
# nfsidmap(8)

## NAME
nfsidmap - The NFS idmapper upcall program

## SYNOPSIS
nfsidmap [-v] [-t timeout] key desc

nfsidmap [-v] [-c]

nfsidmap [-v] [-u|-g|-r user]

nfsidmap -d

nfsidmap -l

nfsidmap -h

## DESCRIPTION
The NFSv4 protocol represents the local system's UID and GID values on the wire as strings of the form user@domain. The process of translating from UID to string and string to UID is referred to as "ID mapping."

The system derives the user part of the string by performing a password or group lookup. The lookup mechanism is configured in /etc/idmapd.conf.

By default, the domain part of the string is the system's DNS domain name. It can also be specified in /etc/idmapd.conf if the system is multi-homed, or if the system's DNS domain name does not match the name of the system's Kerberos realm.

When the domain is not specified in /etc/idmapd.conf the local DNS server will be queried for the _nfsv4idmapdomain text record. If the record exists that will be used as the domain. When the record does not exist, the domain part of the DNS domain will used.

The /usr/sbin/nfsidmap program performs translations on behalf of the kernel. The kernel uses the request-key mechanism to perform an upcall. /usr/sbin/nfsidmap is invoked by /sbin/request-key, performs the translation, and initializes a key with the resulting information. The kernel then caches the translation results in the key.

nfsidmap can also clear cached ID map results in the kernel, or revoke one particular key. An incorrect cached key can result in file and directory ownership reverting to "nobody" on NFSv4 mount points.

In addition, the -d and -l options are available to help diagnose misconfigurations. They have no effect on the keyring containing ID mapping results.

## OPTIONS
-c

Clear the keyring of all the keys.

-d

Display the system's effective NFSv4 domain name on stdout.

-g user

Revoke the gid key of the given user.

-h

Display usage message.

-l

Display on stdout all keys currently in the keyring used to cache ID mapping results. These keys are visible only to the superuser.

-r user

Revoke both the uid and gid key of the given user.

-t timeout

Set the expiration timer, in seconds, on the key. The default is 600 seconds (10 mins).

-u user

Revoke the uid key of the given user.

-v

Increases the verbosity of the output to syslog (can be specified multiple times).

## CONFIGURING
The file /etc/request-key.conf will need to be modified so /sbin/request-key can properly direct the upcall. The following line should be added before a call to keyctl negate:

create id_resolver * * /usr/sbin/nfsidmap -t 600 %k %d

This will direct all id_resolver requests to the program /usr/sbin/nfsidmap. The -t 600 defines how many seconds into the future the key will expire. This is an optional parameter for /usr/sbin/nfsidmap and will default to 600 seconds when not specified.

The idmapper system uses four key descriptions:

uid: Find the UID for the given user

gid: Find the GID for the given group

user: Find the user name for the given UID

group: Find the group name for the given GID

You can choose to handle any of these individually, rather than using the generic upcall program. If you would like to use your own program for a uid lookup then you would edit your request-key.conf so it looks similar to this:

create id_resolver uid:* * /some/other/program %k %d

create id_resolver * * /usr/sbin/nfsidmap %k %d

Notice that the new line was added above the line for the generic program. request-key will find the first matching line and run the corresponding program. In this case, /some/other/program will handle all uid lookups, and /usr/sbin/nfsidmap will handle gid, user, and group lookups.

## FILES
/etc/idmapd.conf

ID mapping configuration file

/etc/request-key.conf

Request key configuration file

## SEE ALSO
idmapd.conf(5), request-key(8)

## AUTHOR
Bryan Schumaker, <bjschuma@netapp.com>


rpcctl

title: rpcctl(8)

summary: Displays SunRPC connection information

text:
# rpcctl(8)

## NAME
rpcctl - Displays SunRPC connection information

## SYNOPSIS

```
rpcctl [ -h | --help ] { client | switch | xprt }
```

```
rpcctl client [ -h | --help ] { show }
rpcctl client show [ -h  --help ] [ XPRT ]
```

```
rpcctl switch [ -h | --help ] { set | show }
rpcctl switch add-xprt [ -h | --help ] [ SWITCH ]
rpcctl switch set [ -h | --help ] SWITCH dstaddr NEWADDR
rpcctl switch show [ -h | --help ] [ SWITCH ]
```

```
rpcctl xprt [ -h | --help ] { remove | set | show }
rpcctl xprt remove [ -h | --help ] XPRT
rpcctl xprt set [ -h | --help ] XPRT { dstaddr NEWADDR | offline | online }
rpcctl xprt show [ -h | --help ] [ XPRT ]
```

## DESCRIPTION
The rpcctl command displays information collected in the SunRPC sysfs files about the system's SunRPC objects.

### rpcctl client - Commands operating on RPC clients
show [ CLIENT ] (default)

Show detailed information about the RPC clients on this system. If CLIENT was provided, then only show information about a single RPC client.

### rpcctl switch - Commands operating on groups of transports
add-xprt SWITCH

Add an additional transport to the SWITCH. Note that the new transport will take its values from the "main" transport.

set SWITCH dstaddr NEWADDR

Change the destination address of all transports in the SWITCH to NEWADDR. NEWADDR can be an IP address, DNS name, or anything else resolvable by gethostbyname(3).

show [ SWITCH ] (default)

Show detailed information about groups of transports on this system. If SWITCH was provided, then only show information about a single transport group.

### rpcctl xprt - Commands operating on individual transports
remove XPRT

Removes the specified XPRT from the system. Note that "main" transports cannot be removed.

set XPRT dstaddr NEWADDR

Change the destination address of the specified XPRT to NEWADDR. NEWADDR can be an IP address, DNS name, or anything else resolvable by gethostbyname(3).

set XPRT offline

Sets the specified XPRT's state to offline.

set XPRT online

Sets the specified XPRT's state to online.

show [ XPRT ] (default)

Show detailed information about this system's transports. If XPRT was provided, then only show information about a single transport.

## EXAMPLES
rpcctl switch show switch-2

Show details about the RPC switch named "switch-2".

rpcctl xprt remove xprt-4

Remove the xprt named "xprt-4" from the system.

rpcctl xprt set xprt-3 dstaddr https://linux-nfs.org

Change the dstaddr of the xprt named "xprt-3" to point to linux-nfs.org

## DIRECTORY
/sys/kernel/sunrpc/

## AUTHOR
Anna Schumaker <Anna.Schumaker@Netapp.com>


sm-notify

title: sm-notify(8)

summary: send reboot notifications to NFS peers

text:
# sm-notify(8)

## NAME
sm-notify - send reboot notifications to NFS peers

## SYNOPSIS
/usr/sbin/sm-notify [-dfn] [-m minutes] [-v name] [-p notify-port] [-P path]

## DESCRIPTION
File locks are not part of persistent file system state. Lock state is thus lost when a host reboots.

Network file systems must also detect when lock state is lost because a remote host has rebooted. After an NFS client reboots, an NFS server must release all file locks held by applications that were running on that client. After a server reboots, a client must remind the server of file locks held by applications running on that client.

For NFS version 2 and version 3, the Network Status Monitor protocol (or NSM for short) is used to notify NFS peers of reboots. On Linux, two separate user-space components constitute the NSM service:

sm-notify

A helper program that notifies NFS peers after the local system reboots

rpc.statd

A daemon that listens for reboot notifications from other hosts, and manages the list of hosts to be notified when the local system reboots

The local NFS lock manager alerts its local rpc.statd of each remote peer that should be monitored. When the local system reboots, the sm-notify command notifies the NSM service on monitored peers of the reboot. When a remote reboots, that peer notifies the local rpc.statd, which in turn passes the reboot notification back to the local NFS lock manager.

## NSM OPERATION IN DETAIL
The first file locking interaction between an NFS client and server causes the NFS lock managers on both peers to contact their local NSM service to store information about the opposite peer. On Linux, the local lock manager contacts rpc.statd.

rpc.statd records information about each monitored NFS peer on persistent storage. This information describes how to contact a remote peer in case the local system reboots, how to recognize which monitored peer is reporting a reboot, and how to notify the local lock manager when a monitored peer indicates it has rebooted.

An NFS client sends a hostname, known as the client's caller_name, in each file lock request. An NFS server can use this hostname to send asynchronous GRANT calls to a client, or to notify the client it has rebooted.

The Linux NFS server can provide the client's caller_name or the client's network address to rpc.statd. For the purposes of the NSM protocol, this name or address is known as the monitored peer's mon_name. In addition, the local lock manager tells rpc.statd what it thinks its own hostname is. For the purposes of the NSM protocol, this hostname is known as my_name.

There is no equivalent interaction between an NFS server and a client to inform the client of the server's caller_name. Therefore NFS clients do not actually know what mon_name an NFS server might use in an SM_NOTIFY request. The Linux NFS client records the server's hostname used on the mount command to identify rebooting NFS servers.

### Reboot notification
When the local system reboots, the sm-notify command reads the list of monitored peers from persistent storage and sends an SM_NOTIFY request to the NSM service on each listed remote peer. It uses the mon_name string as the destination. To identify which host has rebooted, the sm-notify command normally sends my_name string recorded when that remote was monitored. The remote rpc.statd matches incoming SM_NOTIFY requests using this string, or the caller's network address, to one or more peers on its own monitor list.

If rpc.statd does not find a peer on its monitor list that matches an incoming SM_NOTIFY request, the notification is not forwarded to the local lock manager. In addition, each peer has its own NSM state number, a 32-bit integer that is bumped after each reboot by the sm-notify command. rpc.statd uses this number to distinguish between actual reboots and replayed notifications.

Part of NFS lock recovery is rediscovering which peers need to be monitored again. The sm-notify command clears the monitor list on persistent storage after each reboot.

## OPTIONS
-d

Keeps sm-notify attached to its controlling terminal and running in the foreground so that notification progress may be monitored directly.

-f

Send notifications even if sm-notify has already run since the last system reboot.

-m retry-time

Specifies the length of time, in minutes, to continue retrying notifications to unresponsive hosts. If this option is not specified, sm-notify attempts to send notifications for 15 minutes. Specifying a value of 0 causes sm-notify to continue sending notifications to unresponsive peers until it is manually killed.

Notifications are retried if sending fails, the remote does not respond, the remote's NSM service is not registered, or if there is a DNS failure which prevents the remote's mon_name from being resolved to an address.

Hosts are not removed from the notification list until a valid reply has been received. However, the SM_NOTIFY procedure has a void result. There is no way for sm-notify to tell if the remote recognized the sender and has started appropriate lock recovery.

-n

Prevents sm-notify from updating the local system's NSM state number.

-p port

Specifies the source port number sm-notify should use when sending reboot notifications. If this option is not specified, a randomly chosen ephemeral port is used.

This option can be used to traverse a firewall between client and server.

-P, --state-directory-path pathname

Specifies the pathname of the parent directory where NSM state information resides. If this option is not specified, sm-notify uses /var/lib/nfs by default.

After starting, sm-notify attempts to set its effective UID and GID to the owner and group of the subdirectory sm of this directory. After changing the effective ids, sm-notify only needs to access files in sm and sm.bak within the state-directory-path.

-v ipaddr | hostname

Specifies the network address from which to send reboot notifications, and the mon_name argument to use when sending SM_NOTIFY requests. If this option is not specified, sm-notify uses a wildcard address as the transport bind address, and uses the my_name recorded when the remote was monitored as the mon_name argument when sending SM_NOTIFY requests.

The ipaddr form can be expressed as either an IPv4 or an IPv6 presentation address. If the ipaddr form is used, the sm-notify command converts this address to a hostname for use as the mon_name argument when sending SM_NOTIFY requests.

This option can be useful in multi-homed configurations where the remote requires notification from a specific network address.

## CONFIGURATION FILE
Many of the options that can be set on the command line can also be controlled through values set in the [sm-notify] or, in one case, the [statd] section of the /etc/nfs.conf configuration file.

Values recognized in the [sm-notify] section include: retry-time, outgoing-port, and outgoing-addr. These have the same effect as the command line options m, p, and v respectively.

An additional value recognized in the [sm-notify] section is lift-grace. By default, sm-notify will lift lockd's grace period early if it has no hosts to notify. Some high availability configurations will run one sm-notify per floating IP address. In these configurations, lifting the grace period early may prevent clients from reclaiming locks. Setting lift-grace to n will prevent sm-notify from ending the grace period early. lift-grace has no corresponding command line option.

The value recognized in the [statd] section is state-directory-path.

## SECURITY
The sm-notify command is, generally, started as root to acquire privileges needed to access the state information database. It drops root privileges as soon as it starts up to reduce the risk of a privilege escalation attack.

During normal operation, the effective user ID it chooses is the owner of the state directory. This allows it to continue to access files in that directory after it has dropped its root privileges. To control which user ID rpc.statd chooses, simply use chown(1) to set the owner of the state directory.

The sm-notify command can also be started by the user ID that owns the state directory. That is useful for the situation when it is called from an rpc-stat ha-callout program that is already running as the non-privileged user. The non-root user will not have the capabilities to drop the root privileges as described above.

## ADDITIONAL NOTES
Lock recovery after a reboot is critical to maintaining data integrity and preventing unnecessary application hangs.

To help rpc.statd match SM_NOTIFY requests to NLM requests, a number of best practices should be observed, including:

The UTS nodename of your systems should match the DNS names that NFS peers use to contact them

The UTS nodenames of your systems should always be fully qualified domain names

The forward and reverse DNS mapping of the UTS nodenames should be consistent

The hostname the client uses to mount the server should match the server's mon_name in SM_NOTIFY requests it sends

Unmounting an NFS file system does not necessarily stop either the NFS client or server from monitoring each other. Both may continue monitoring each other for a time in case subsequent NFS traffic between the two results in fresh mounts and additional file locking.

On Linux, if the lockd kernel module is unloaded during normal operation, all remote NFS peers are unmonitored. This can happen on an NFS client, for example, if an automounter removes all NFS mount points due to inactivity.

### IPv6 and TI-RPC support
TI-RPC is a pre-requisite for supporting NFS on IPv6. If TI-RPC support is built into the sm-notify command ,it will choose an appropriate IPv4 or IPv6 transport based on the network address returned by DNS for each remote peer. It should be fully compatible with remote systems that do not support TI-RPC or IPv6.

Currently, the sm-notify command supports sending notification only via datagram transport protocols.

## FILES
/var/lib/nfs/sm

directory containing monitor list

/var/lib/nfs/sm.bak

directory containing notify list

/var/lib/nfs/state

NSM state number for this host

/proc/sys/fs/nfs/nsm_local_state

kernel's copy of the NSM state number

## SEE ALSO
rpc.statd(8), nfs(5), uname(2), hostname(7)

RFC 1094 - "NFS: Network File System Protocol Specification"

RFC 1813 - "NFS Version 3 Protocol Specification"

OpenGroup Protocols for Interworking: XNFS, Version 3W - Chapter 11

## AUTHORS
Olaf Kirch <okir@suse.de>

Chuck Lever <chuck.lever@oracle.com>


statd

title: statd(8)

summary: NSM service daemon

text:
# statd(8)

## NAME
rpc.statd - NSM service daemon

## SYNOPSIS
rpc.statd [-dh?FLNvV] [-H prog] [-n my-name] [-o outgoing-port] [-p listener-port] [-P path] [--nlm-port port] [--nlm-udp-port port]

## DESCRIPTION
File locks are not part of persistent file system state. Lock state is thus lost when a host reboots.

Network file systems must also detect when lock state is lost because a remote host has rebooted. After an NFS client reboots, an NFS server must release all file locks held by applications that were running on that client. After a server reboots, a client must remind the server of file locks held by applications running on that client.

For NFS version 2 [RFC1094] and NFS version 3 [RFC1813], the Network Status Monitor protocol (or NSM for short) is used to notify NFS peers of reboots. On Linux, two separate user-space components constitute the NSM service:

rpc.statd

A daemon that listens for reboot notifications from other hosts, and manages the list of hosts to be notified when the local system reboots

sm-notify

A helper program that notifies NFS peers after the local system reboots

The local NFS lock manager alerts its local rpc.statd of each remote peer that should be monitored. When the local system reboots, the sm-notify command notifies the NSM service on monitored peers of the reboot. When a remote reboots, that peer notifies the local rpc.statd, which in turn passes the reboot notification back to the local NFS lock manager.

## NSM OPERATION IN DETAIL
The first file locking interaction between an NFS client and server causes the NFS lock managers on both peers to contact their local NSM service to store information about the opposite peer. On Linux, the local lock manager contacts rpc.statd.

rpc.statd records information about each monitored NFS peer on persistent storage. This information describes how to contact a remote peer in case the local system reboots, how to recognize which monitored peer is reporting a reboot, and how to notify the local lock manager when a monitored peer indicates it has rebooted.

An NFS client sends a hostname, known as the client's caller_name, in each file lock request. An NFS server can use this hostname to send asynchronous GRANT calls to a client, or to notify the client it has rebooted.

The Linux NFS server can provide the client's caller_name or the client's network address to rpc.statd. For the purposes of the NSM protocol, this name or address is known as the monitored peer's mon_name. In addition, the local lock manager tells rpc.statd what it thinks its own hostname is. For the purposes of the NSM protocol, this hostname is known as my_name.

There is no equivalent interaction between an NFS server and a client to inform the client of the server's caller_name. Therefore NFS clients do not actually know what mon_name an NFS server might use in an SM_NOTIFY request. The Linux NFS client uses the server hostname from the mount command to identify rebooting NFS servers.

### Reboot notification
When the local system reboots, the sm-notify command reads the list of monitored peers from persistent storage and sends an SM_NOTIFY request to the NSM service on each listed remote peer. It uses the mon_name string as the destination. To identify which host has rebooted, the sm-notify command sends the my_name string recorded when that remote was monitored. The remote rpc.statd matches incoming SM_NOTIFY requests using this string, or the caller's network address, to one or more peers on its own monitor list.

If rpc.statd does not find a peer on its monitor list that matches an incoming SM_NOTIFY request, the notification is not forwarded to the local lock manager. In addition, each peer has its own NSM state number, a 32-bit integer that is bumped after each reboot by the sm-notify command. rpc.statd uses this number to distinguish between actual reboots and replayed notifications.

Part of NFS lock recovery is rediscovering which peers need to be monitored again. The sm-notify command clears the monitor list on persistent storage after each reboot.

## OPTIONS
-d, --no-syslog

Causes rpc.statd to write log messages on stderr instead of to the system log, if the -F option was also specified.

-F, --foreground

Keeps rpc.statd attached to its controlling terminal so that NSM operation can be monitored directly or run under a debugger. If this option is not specified, rpc.statd backgrounds itself soon after it starts.

-h, -?, --help

Causes rpc.statd to display usage information on stderr and then exit.

-H, --ha-callout prog

Specifies a high availability callout program. If this option is not specified, no callouts are performed. See the High-availability callouts section below for details.

-L, --no-notify

Prevents rpc.statd from running the sm-notify command when it starts up, preserving the existing NSM state number and monitor list.

Note: the sm-notify command contains a check to ensure it runs only once after each system reboot. This prevents spurious reboot notification if rpc.statd restarts without the -L option.

-n, --name ipaddr | hostname

This string is only used by the sm-notify command as the source address from which to send reboot notification requests.

The ipaddr form can be expressed as either an IPv4 or an IPv6 presentation address. If this option is not specified, rpc.statd uses a wildcard address as the transport bind address. See sm-notify(8) for details.

-N

Causes rpc.statd to run the sm-notify command, and then exit. Since the sm-notify command can also be run directly, this option is deprecated.

-o, --outgoing-port port

Specifies the source port number the sm-notify command should use when sending reboot notifications. See sm-notify(8) for details.

-p, --port port

Specifies the port number used for RPC listener sockets. If this option is not specified, rpc.statd will try to consult /etc/services, if gets port succeed, set the same port for all listener socket, otherwise chooses a random ephemeral port for each listener socket.

This option can be used to fix the port value of its listeners when SM_NOTIFY requests must traverse a firewall between clients and servers.

-T, --nlm-port port

Specifies the port number that lockd should listen on for NLM requests. This sets both the TCP and UDP ports unless the UDP port is set separately.

-U, --nlm-udp-port port

Specifies the UDP port number that lockd should listen on for NLM requests.

-P, --state-directory-path pathname

Specifies the pathname of the parent directory where NSM state information resides. If this option is not specified, rpc.statd uses /var/lib/nfs/statd by default.

After starting, rpc.statd attempts to set its effective UID and GID to the owner and group of the subdirectory sm of this directory. After changing the effective ids, rpc.statd only needs to access files in sm and sm.bak within the state-directory-path.

-v, -V, --version

Causes rpc.statd to display version information on stderr and then exit.

## CONFIGURATION FILE
Many of the options that can be set on the command line can also be controlled through values set in the [statd] or, in some cases, the [lockd] sections of the /etc/nfs.conf configuration file. Values recognized in the [statd] section include port, outgoing-port, name, state-directory-path, and ha-callout which each have the same effect as the option with the same name.

The values recognized in the [lockd] section include port and udp-port which have the same effect as the --nlm-port and --nlm-udp-port options, respectively.

## SECURITY
The rpc.statd daemon must be started as root to acquire privileges needed to create sockets with privileged source ports, and to access the state information database. Because rpc.statd maintains a long-running network service, however, it drops root privileges as soon as it starts up to reduce the risk of a privilege escalation attack.

During normal operation, the effective user ID it chooses is the owner of the state directory. This allows it to continue to access files in that directory after it has dropped its root privileges. To control which user ID rpc.statd chooses, simply use chown(1) to set the owner of the state directory.

You can also protect your rpc.statd listeners using the tcp_wrapper library or iptables(8). To use the tcp_wrapper library, add the hostnames of peers that should be allowed access to /etc/hosts.allow. Use the daemon name statd even if the rpc.statd binary has a different filename.

For further information see the tcpd(8) and hosts_access(5) man pages.

## ADDITIONAL NOTES
Lock recovery after a reboot is critical to maintaining data integrity and preventing unnecessary application hangs. To help rpc.statd match SM_NOTIFY requests to NLM requests, a number of best practices should be observed, including:

The UTS nodename of your systems should match the DNS names that NFS peers use to contact them

The UTS nodenames of your systems should always be fully qualified domain names

The forward and reverse DNS mapping of the UTS nodenames should be consistent

The hostname the client uses to mount the server should match the server's mon_name in SM_NOTIFY requests it sends

Unmounting an NFS file system does not necessarily stop either the NFS client or server from monitoring each other. Both may continue monitoring each other for a time in case subsequent NFS traffic between the two results in fresh mounts and additional file locking.

On Linux, if the lockd kernel module is unloaded during normal operation, all remote NFS peers are unmonitored. This can happen on an NFS client, for example, if an automounter removes all NFS mount points due to inactivity.

### High-availability callouts
rpc.statd can exec a special callout program during processing of successful SM_MON, SM_UNMON, and SM_UNMON_ALL requests, or when it receives SM_NOTIFY. Such a program may be used in High Availability NFS (HA-NFS) environments to track lock state that may need to be migrated after a system reboot.

The name of the callout program is specified with the -H option. The program is run with 3 arguments: The first is either add-client del-client or sm-notify depending on the reason for the callout. The second is the mon_name of the monitored peer. The third is the caller_name of the requesting lock manager for add-client or del-client , otherwise it is IP_address of the caller sending SM_NOTIFY. The forth is the state_value in the SM_NOTIFY request.

### IPv6 and TI-RPC support
TI-RPC is a pre-requisite for supporting NFS on IPv6. If TI-RPC support is built into rpc.statd, it attempts to start listeners on network transports marked 'visible' in /etc/netconfig. As long as at least one network transport listener starts successfully, rpc.statd will operate.

## ENVIRONMENT
RPC_STATD_NO_NOTIFY=

If set to a positive integer, has the same effect as --no-notify.

## FILES
/var/lib/nfs/statd/sm

directory containing monitor list

/var/lib/nfs/statd/sm.bak

directory containing notify list

/var/lib/nfs/statd/state

NSM state number for this host

/run/run.statd.pid

pid file

/etc/netconfig

network transport capability database

## SEE ALSO
sm-notify(8), nfs(5), rpc.nfsd(8), rpcbind(8), tcpd(8), hosts_access(5), iptables(8), netconfig(5)

RFC 1094 - "NFS: Network File System Protocol Specification"

RFC 1813 - "NFS Version 3 Protocol Specification"

OpenGroup Protocols for Interworking: XNFS, Version 3W - Chapter 11

## AUTHORS
Jeff Uphoff <juphoff@users.sourceforge.net>

Olaf Kirch <okir@monad.swb.de>

H.J. Lu <hjl@gnu.org>

Lon Hohberger <hohberger@missioncriticallinux.com>

Paul Clements <paul.clements@steeleye.com>

Chuck Lever <chuck.lever@oracle.com>


ganesha-cache-config

package: nfs-ganesha

title: ganesha-cache-config(8)

summary: NFS Ganesha Cache Configuration File

text:
# ganesha-cache-config(8)

## NAME
ganesha-cache-config - NFS Ganesha Cache Configuration File

## SYNOPSIS

```
/etc/ganesha/ganesha.conf
```

## DESCRIPTION
NFS-Ganesha reads the configuration data from: | /etc/ganesha/ganesha.conf

This file lists NFS-Ganesha Cache config options.

### MDCACHE {}
NParts (uint32, range 1 to 32633, default 7)

Partitions in the MDCACHE tree.

Cache_Size(uint32, range 1 to UINT32_MAX, default 32633)

Per-partition hash table size.

Use_Getattr_Directory_Invalidation(bool, default false)

Use getattr for directory invalidation.

Dir_Chunk_Enable(bool, default true)

Enable or disable directory chunking. Set this false in preference to setting Dir_Chunk to 0.

Dir_Chunk(uint32, range 0 to UINT32_MAX, default 128)

Size of per-directory dirent cache chunks, 0 means directory chunking is not enabled. Dir_Chunk should always be enabled. Most FSAL modules especially FSAL_RGW/FSAL_GLUSTER need it to make readdir work well. Note that if set to 0, Dir_Chunk_Enable will be set to false and Dir_Chunk will be set to the default of 128.

Detached_Mult(uint32, range 1 to UINT32_MAX, default 1)

Max number of detached directory entries expressed as a multiple of the chunk size.

Entries_HWMark(uint32, range 1 to UINT32_MAX, default 100000)

The point at which object cache entries will start being reused.

Entries_Release_Size(uint32, range 0 to UINT32_MAX, default 100)

The number of entries attempted to release each time when the handle cache has exceeded the entries high water mark.

Chunks_HWMark(uint32, range 1 to UINT32_MAX, default 1000)

The point at which dirent cache chunks will start being reused.

Chunks_LWMark(uint32, range 1 to UINT32_MAX, default 1000)

The target for reaping dirent cache chunks to drain the cache. Entries_HWMark, Dir_Chunk, Chunks_HWMark, Chunks_LWMark all play together. While a dirent chunk is cached, the object cache entries that are part of that dirent chunk will be retained in the cache indefinitely. Note that this means that possibly Chunks_LWMark * Dir_Chunk entries will be retained. If this is larger than Entries_HWMark, then the object cache may end up remaining above Entries_HWMark for a significant time. Consider the average size of the directories and the number of directories desired to be maintained in the cache and set Chunks_LWMark appropriately.

Note that the Chunks_LWMark defaults to the same value as Chunks_HWMark and these are set to 1/100 of Entries_HWMark suggesting an average directory size of 100. It may be desirable to set Chunks_LWMark less than Chunks_HWMark if it is desirable to allow large directory chunks to not immediately be re-used, but it is desirable to in the short term drain the dirent cache down to a smaller number.

LRU_Run_Interval(uint32, range 1 to 24 * 3600, default 90)

Base interval in seconds between runs of the LRU cleaner thread.

Cache_FDs(bool, default true)

If "Cache_FDs" is set to false, the reaper thread aggressively closes FDs , significantly reducing the number of open FDs. This will help to maintain a minimal number of open FDs. If "Cache_FDs" is set to true (default), FDs are cached, and the LRU reaper thread closes FDs only when the current open FD count reaches or exceeds the "fds_lowat" threshold.

Note, this setting has no effect when Close_Fast is set to true.

Close_Fast(bool, default false)

Whether to close files immediately after opening files and using them for read/write/commit.

FD_Limit_Percent(uint32, range 0 to 100, default 99)

The percentage of the system-imposed maximum of file descriptors at which Ganesha will deny requests.

FD_HWMark_Percent(uint32, range 0 to 100, default 90)

The percentage of the system-imposed maximum of file descriptors above which Ganesha will make greater efforts at reaping.

FD_LWMark_Percent(uint32, range 0 to 100, default 50)

The percentage of the system-imposed maximum of file descriptors below which Ganesha will not reap file descriptors.

Reaper_Work(uint32, range 1 to 2000, default 0)

Roughly, the amount of work to do on each pass through the thread under normal conditions. (Ideally, a multiple of the number of lanes.) This setting is deprecated. Please use Reaper_Work_Per_Lane

Reaper_Work_Per_Lane(uint32, range 1 to UINT32_MAX, default 50)

This is the number of handles per lane to scan when performing LRU maintenance. This task is performed by the Reaper thread.

Biggest_Window(uint32, range 1 to 100, default 40)

The largest window (as a percentage of the system-imposed limit on FDs) of work that we will do in extremis.

Required_Progress(uint32, range 1 to 50, default 5)

Percentage of progress toward the high water mark required in in a pass through the thread when in extremis

Futility_Count(uint32, range 1 to 50, default 8)

Number of failures to approach the high watermark before we disable caching, when in extremis.

Dirmap_HWMark(uint32, range 1 to UINT32_MAX, default 10000)

The point at which dirmap entries are reused. This puts a practical limit on the number of simultaneous readdirs that may be in progress on an export for a whence-is-name FSAL (currently only FSAL_RGW)

Files_Delegatable_Percent(int32, range 10 to 90, default 90)

Total number of files ganesha can delegate to clients as a percent of Entries_HWMark

Use_Cached_Owner_On_Owner_Override(bool, true)

This option allows mdcache_test_access to use the cached owner value for an object in case of owner override, even if the cache entry is not up to date. This could potentially lead to the wrong result, but can significantly improve performance saving the need to update attributes on many read/write operations.

## SEE ALSO
ganesha-config <>(8)


ganesha-config

title: ganesha-config(8)

summary: NFS Ganesha Configuration File

text:
# ganesha-config(8)

## NAME
ganesha-config - NFS Ganesha Configuration File

## SYNOPSIS

```
/etc/ganesha/ganesha.conf
```

## DESCRIPTION
NFS-Ganesha obtains configuration data from the configuration file:

/etc/ganesha/ganesha.conf

The configuration file consists of following parts:

### Comments
Empty lines and lines starting with '#' are comments.:

```
# This whole line is a comment
Protocol = TCP; # The rest of this line is a comment
```

### Blocks
Related options are grouped together into "blocks". A block is a name followed by parameters enclosed between "{" and "}". A block can contain other sub blocks as well.:

```
EXPORT
{

    Export_ID = 1;

    FSAL {

        Name = VFS:

    }
}
```

NOTE: FSAL is a sub block. Refer to BLOCKS section for list of blocks and options.

### Options
Configuration options can be of following types.

1. Numeric. Numeric options can be defined in octal, decimal, or hexadecimal. The format follows ANSI C syntax. eg.:

```
mode = 0755;  # This is octal 0755, 493 (decimal)
```

Numeric values can also be negated or logical NOT'd. eg.:

```
anonymousuid = -2; # this is a negative
mask = ~0xff; # Equivalent to 0xffffff00 (for 32 bit integers)
```

2. Boolean. Possible values are true, false, yes and no. 1 and 0 are not acceptable.

3. List. The option can contain a list of possible applicable values. Protocols = 3, 4, 9p;

4. String. String options such as export Path need not be enclosed in quotes but is recommended. If special characters are included, particularly non-ASCII characters, use of either single or double quotes may be required. Another set of strings that should be quoted are any strings that are a keyword or if spaces are part of the string.

### Including other config files
Additional files can be referenced in a configuration using '%include' or '%dir' or '%url' directives.:

```
%include <filename>
%dir <directory_name>
%url <url, e.g., rados://mypool/mynamespace/myobject>
```

The included file is inserted into the configuration text in place of the %include or %dir or %url line. Sub-inclusions may be to any depth. Filenames or directory or URLs may optionally use '"':

```
%include base.conf
%include "base.conf"
%dir /etc/ganesha/ganesha_config/
%dir "/etc/ganesha/ganesha_config/"
%url rados://mypool/mynamespace/myobject
%url "rados://mypool/mynamespace/myobject"
%url rados://mypool/myobject
%url "rados://mypool/myobject"
```

In the case of rados:// URLs, providing a two-component URL indicates that the default namespace should be used.

### Reloading Config
A config reload can be triggered by sending the ganesha.nfsd process a SIGHUP. Not all config options may be changed with reload, those that can will be documented in the individual sections.

In general, currently dynamic config is supported for EXPORT and LOG options.

## BLOCKS
NFS-Ganesha supports the following blocks:

### EXPORT {}
Along with its configuration options, the EXPORT block supports FSAL and CLIENT sub-blocks. See ganesha-export-config <>(8) for usage of this block and its sub-blocks.

### EXPORT_DEFAULTS {}
Refer to ganesha-export-config <>(8) for usage

### MDCACHE {}
Refer to ganesha-cache-config <>(8) for usage

### NFS_CORE_PARAM {}
Refer to ganesha-core-config <>(8) for usage

### NFS_IP_NAME {}
Refer to ganesha-core-config <>(8) for usage

### NFS_KRB5 {}
Refer to ganesha-core-config <>(8) for usage

### NFSv4 {}
Refer to ganesha-core-config <>(8) for usage

### _9P {}
Refer to ganesha-9p-config <>(8) for usage

### LOG {}
Refer to ganesha-log-config <>(8) for usage

1.**LOG { FACILITY {} }** 2.**LOG { FORMAT {} }**

### RADOS_KV {}
Refer to ganesha-core-config <>(8) for usage

### RADOS_URLS {}
Refer to ganesha-core-config <>(8) for usage

### FSAL_LIST {}
Refer to ganesha-core-config <>(8) for usage

### CEPH {}
Refer to ganesha-ceph-config <>(8) for usage

### GLUSTER {}
Refer to ganesha-gluster-config <>(8) for usage

### GPFS {}
Refer to ganesha-gpfs-config <>(8) for usage

### PROXY_V4 {}
Refer to ganesha-proxy-config <>(8) for usage

### PROXY_V3 {}
Refer to ganesha-proxy-v3-config <>(8) for usage

### RGW {}
Refer to ganesha-rgw-config <>(8) for usage

### VFS {}
Refer to ganesha-vfs-config <>(8) for usage

### XFS {}
Refer to ganesha-xfs-config <>(8) for usage

### QOS_DEFAULT_CONFIG {}
Refer to ganesha-qos-config <>(8) for usage

## EXAMPLE
Along with "ganesha.conf", for each installed FSAL, a sample config file is added at:

```
/etc/ganesha
```

## SEE ALSO
ganesha-log-config <>(8) ganesha-rgw-config <>(8) ganesha-vfs-config <>(8) ganesha-lustre-config <>(8) ganesha-xfs-config <>(8) ganesha-gpfs-config <>(8) ganesha-gluster-config <>(8) ganesha-9p-config <>(8) ganesha-proxy-config(8) ganesha-proxy-v3-config <>(8) ganesha-ceph-config <>(8) ganesha-core-config <>(8) ganesha-export-config <>(8) ganesha-qos-config <>(8)