xdp-loader

title: xdp-loader(8)

summary: an XDP program loader

text:
# xdp-loader(8)

## NAME
xdp-loader - an XDP program loader

## SYNOPSIS
XDP-loader is a simple loader for XDP programs with support for attaching multiple programs to the same interface. To achieve this it exposes the same load and unload semantics exposed by the libxdp library. See the libxdp(3) man page for details of how this works, and what kernel features it relies on.

### Running xdp-loader
The syntax for running xdp-loader is:

```
xdp-loader COMMAND [options]
Where COMMAND can be one of:

       load        - load an XDP program on an interface

       unload      - unload an XDP program from an interface

       status      - show current XDP program status

       features    - show XDP features supported by the NIC

       clean       - clean up detached program links in XDP bpffs directory

       help        - show the list of available commands
```

Each command, and its options are explained below. Or use xdp-loader COMMAND --help to see the options for each command.

## The LOAD command
The load command loads one or more XDP programs onto an interface.

The syntax for the load command is:

xdp-loader load [options] <ifname> <programs>

Where <ifname> is the name of the interface to load the programs onto, and the <programs> is one or more file names containing XDP programs. The programs will be loaded onto the interface in the order of their preference, as specified by the program metadata (see libxdp(3)).

The supported options are:

### -m, --mode <mode>
Specifies which mode to load the XDP program to be loaded in. The valid values are 'native', which is the default in-driver XDP mode, 'skb', which causes the so-called skb mode (also known as generic XDP) to be used, 'hw' which causes the program to be offloaded to the hardware, or 'unspecified' which leaves it up to the kernel to pick a mode (which it will do by picking native mode if the driver supports it, or generic mode otherwise). Note that using 'unspecified' can make it difficult to predict what mode a program will end up being loaded in. For this reason, the default is 'native'. Note that hardware with support for the 'hw' mode is rare: Netronome/Corigine cards (using the 'nfp' driver) are the only devices with support for this in the mainline Linux kernel.

### -p, --pin-path <path>
This specifies a root path under which to pin any maps that define the 'pinning' attribute in their definitions. This path must be located on a bpffs file system. If not set, maps will not be pinned, even if they specify pinning in their definitions. When pinning maps, if the pinned location for a map already exist, the map pinned there will be reused if it is compatible with the type of the map being loaded.

### -s, --section <section>
Specify which ELF section to load the XDP program(s) from in each file. The default is to use the first program in each file. If this option is set, it applies to all programs being loaded.

### -n, --prog-name <prog_name>
Specify which BPF program with the name to load the XDP program(s) from in each file. The default is to use the first program in each file. Only one of --section and --prog-name may be specified. If this option is set, it applies to all programs being loaded.

### -P, --prio <priority>
Specify the priority to load the XDP program(s) with (this affects the order of programs running on the interface). The default is to use the value from the metadata in the program ELF file, or a value of 50 if the program has no such metadata. If this option is set, it applies to all programs being loaded.

### -A, --actions <actions>
Specify the "chain call actions" of the loaded XDP program(s). These are the XDP actions that will cause the next program loaded on the interface to be called, instead of returning immediately. The default is to use the value set in the metadata in the program ELF file, or XDP_PASS if no such metadata is set. If this option is set, it applies to all programs being loaded.

### -v, --verbose
Enable debug logging. Specify twice for even more verbosity.

### -h, --help
Display a summary of the available options

## The UNLOAD command
The unload command is used for unloading programs from an interface.

The syntax for the unload command is:

xdp-loader unload [options] <ifname>

Where <ifname> is the name of the interface to load the programs onto. Either the --all or --id options must be used to specify which program(s) to unload.

The supported options are:

### -i, --id <id>
Unload a single program from the interface by ID. Use xdp-loader status to obtain the ID of the program being unloaded. If this program is the last program loaded on the interface, the dispatcher program will also be removed, which makes the operation equivalent to specifying --all.

### -a, --all
Unload all XDP programs on the interface, as well as the multi-program dispatcher.

### -v, --verbose
Enable debug logging. Specify twice for even more verbosity.

### -h, --help
Display a summary of the available options

## The STATUS command
The status command displays a list of interfaces in the system, and the XDP program(s) loaded on each interface. For each interface, a list of programs are shown, with the run priority and "chain actions" for each program. See the section on program metadata for the meaning of this metadata.

### -v, --verbose
Enable debug logging. Specify twice for even more verbosity.

### -h, --help
Display a summary of the available options

## The FEATURES command
The features command displays the XDP features supported by the NIC.

Currently supported XDP features are:

### NETDEV_XDP_ACT_BASIC
The networking device has basic support for running XDP programs, and can handle the base set of return codes (XDP_ABORTED, XDP_DROP, XDP_PASS, XDP_TX).

### NETDEV_XDP_ACT_REDIRECT
The network device supports handling the XDP_REDIRECT return code. This means packets can be redirected from this device by XDP.

### NETDEV_XDP_ACT_NDO_XMIT
The networking interfaces implements the ndo_xdp_xmit callback. This means packets can be redirected to this device by XDP.

### NETDEV_XDP_ACT_XSK_ZEROCOPY
The networking device supports AF_XDP in zero copy mode.

### NETDEV_XDP_ACT_HW_OFFLOAD
The networking device supports XDP hw offloading.

### NETDEV_XDP_ACT_RX_SG
The networking device supports non-linear XDP frames on the receive side. This means XDP can be used with big MTUs on this device (if the XDP program is compiled with fragments support)

### NETDEV_XDP_ACT_NDO_XMIT_SG
The networking device supports non-linear XDP frames on the transmit side. This means non-linear frames can be redirected to this device.

## The CLEAN command
The syntax for the clean command is:

xdp-loader clean [options] [ifname]

The clean command cleans up any detached program links in the XDP bpffs directory. When a network interface disappears, any programs loaded in software mode (e.g. skb, native) remain pinned in the bpffs directory, but become detached from the interface. These need to be unlinked from the filesystem. The clean command takes an optional interface parameter to only unlink detached programs corresponding to the interface. By default, all detached programs for all interfaces are unlinked.

The supported options are:

### -v, --verbose
Enable debug logging. Specify twice for even more verbosity.

### -h, --help
Display a summary of the available options

## Examples
To load an XDP program on the eth0 interface simply do:

```
# xdp-loader load eth0 xdp_drop.o
# xdp-loader status
CURRENT XDP PROGRAM STATUS:
Interface        Prio  Program name     Mode     ID   Tag               Chain actions
-------------------------------------------------------------------------------------
lo               <no XDP program>
eth0                   xdp_dispatcher   native   50   d51e469e988d81da

 =>              50    xdp_drop                  55   57cd311f2e27366b  XDP_PASS
```

Which shows that a dispatcher program was loaded on the interface, and the xdp_drop program was installed as the first (and only) component program after it. In this instance, the program does not specify any of the metadata above, so the defaults (priority 50 and XDP_PASS as its chain call action) was used.

To use the automatic map pinning, include the pinning attribute into the map definition in the program, something like:

```
struct {

        __uint(type, BPF_MAP_TYPE_ARRAY);

        __uint(max_entries, 10);

        __type(key, __u32);

        __type(value, __u64);

        __uint(pinning, LIBBPF_PIN_BY_NAME);
} my_map SEC(".maps");
```

And load it with the --pin-path attribute:

```
# xdp-loader load eth0 my_prog.o --pin-path /sys/fs/bpf/my-prog
```

This will pin the map at /sys/fs/bpf/my-prog/my_map. If this already exists, the pinned map will be reused instead of creating a new one, which allows different BPF programs to share the map.

## SEE ALSO
libxdp(3) for details on the XDP loading semantics and kernel compatibility requirements.

## BUGS
Please report any bugs on Github: https://github.com/xdp-project/xdp-tools/issues

## AUTHOR
xdp-loader and this man page were written by Toke Høiland-Jørgensen.


xdp-monitor

package: xdp-tools

title: xdp-monitor(8)

text:
# xdp-monitor(8)

## NAME
XDP-monitor - a simple BPF-powered XDP monitoring tool

## SYNOPSIS
XDP-monitor is a tool that monitors various XDP related statistics and events using BPF tracepoints infrastructure, trying to be as low overhead as possible.

Note that by default, statistics for successful XDP redirect events is disabled, as that leads to a per-packet BPF tracing overhead, which while being low overhead, can lead to packet processing degradation.

This tool relies on the BPF raw tracepoints infrastructure in the kernel.

There is more information on the meaning of the output in both default (terse) and verbose output mode, in the Output Format Description section.

### Running xdp-monitor
The syntax for running xdp-monitor is:

```
xdp-monitor [options]
```

The supported options are:

### -i, --interval <SECONDS>
Set the polling interval for collecting all statistics and displaying them to the output. The unit of interval is in seconds.

### -s, --stats
Enable statistics for successful redirection. This option comes with a per packet tracing overhead, for recording all successful redirections.

### -e, --extended
Start xdp-bench in "extended" output mode. If not set, xdp-bench will start in "terse" mode. The output mode can be switched by hitting C-$ while the program is running. See also the Output Format Description section below.

### -v, --verbose
Enable verbose logging. Supply twice to enable verbose logging from the underlying libxdp and libbpf libraries.

### --version
Show the application version and exit.

### -h, --help
Display a summary of the available options

## Output Format Description
By default, redirect success statistics are disabled, use --stats to enable. The terse output mode is default, extended output mode can be activated using the --extended command line option.

SIGQUIT (Ctrl + \) can be used to switch the mode dynamically at runtime.

Terse mode displays at most the following fields:

```
rx/s		Number of packets received per second
redir/s	Number of packets successfully redirected per second
err,drop/s	Aggregated count of errors per second (including dropped packets)
xmit/s	Number of packets transmitted on the output device per second
```

Verbose output mode displays at most the following fields:

```
FIELD		  DESCRIPTION
receive	       Displays the number of packets received and errors encountered

                        Whenever an error or packet drop occurs, details of per CPU error

                        and drop statistics will be expanded inline in terse mode.

                                        pkt/s		- Packets received per second

                                        drop/s		- Packets dropped per second

                                        error/s		- Errors encountered per second

                                        redirect	- Displays the number of packets successfully redirected

                       Errors encountered are expanded under redirect_err field

                       Note that passing -s to enable it has a per packet overhead

                                        redir/s		- Packets redirected successfully per second
redirect_err	  Displays the number of packets that failed redirection

                        The errno is expanded under this field with per CPU count

                       The recognized errors are:

                                        EINVAL:		Invalid redirection

                                        ENETDOWN:	Device being redirected to is down

                                        EMSGSIZE:	Packet length too large for device

                                        EOPNOTSUPP:	Operation not supported

                                        ENOSPC:		No space in ptr_ring of cpumap kthread

                                        error/s		- Packets that failed redirection per second
enqueue to cpu N Displays the number of packets enqueued to bulk queue of CPU N

                       Expands to cpu:FROM->N to display enqueue stats for each CPU enqueuing to CPU N

                       Received packets can be associated with the CPU redirect program is enqueuing

                       packets to.

                                        pkt/s		- Packets enqueued per second from other CPU to CPU N

                                        drop/s		- Packets dropped when trying to enqueue to CPU N

                                        bulk-avg	- Average number of packets processed for each event
kthread	       Displays the number of packets processed in CPUMAP kthread for each CPU

                       Packets consumed from ptr_ring in kthread, and its xdp_stats (after calling

                       CPUMAP bpf prog) are expanded below this. xdp_stats are expanded as a total and

                       then per-CPU to associate it to each CPU's pinned CPUMAP kthread.

                                        pkt/s		- Packets consumed per second from ptr_ring

                                        drop/s		- Packets dropped per second in kthread

                                        sched		- Number of times kthread called schedule()

                       xdp_stats (also expands to per-CPU counts)

                                        pass/s		- XDP_PASS count for CPUMAP program execution

                                        drop/s		- XDP_DROP count for CPUMAP program execution

                                        redir/s		- XDP_REDIRECT count for CPUMAP program execution
xdp_exception	  Displays xdp_exception tracepoint events

                        This can occur due to internal driver errors, unrecognized

                       XDP actions and due to explicit user trigger by use of XDP_ABORTED

                       Each action is expanded below this field with its count

                                        hit/s		- Number of times the tracepoint was hit per second
devmap_xmit      Displays devmap_xmit tracepoint events

                        This tracepoint is invoked for successful transmissions on output

                       device but these statistics are not available for generic XDP mode,

                       hence they will be omitted from the output when using SKB mode

                                        xmit/s		- Number of packets that were transmitted per second

                                        drop/s		- Number of packets that failed transmissions per second

                                        drv_err/s	- Number of internal driver errors per second

                                        bulk-avg	- Average number of packets processed for each event
```

## BUGS
Please report any bugs on Github: https://github.com/xdp-project/xdp-tools/issues

## AUTHOR
The original xdp-monitor tool was written by Jesper Dangaard Brouer. It was then rewritten to support more features by Kumar Kartikeya Dwivedi. This man page was written by Kumar Kartikeya Dwivedi.

branch: sisyphus


xdp-trafficgen

title: xdp-trafficgen(8)

summary: an XDP-based traffic generator

text:
# xdp-trafficgen(8)

## NAME
XDP-trafficgen - an XDP-based traffic generator

## SYNOPSIS
XDP-trafficgen is a packet generator utilising the XDP kernel subsystem to generate packets transmit them through a network interface. Packets are dynamically generated and transmitted in the kernel, allowing for high performance (millions of packets per second per core).

XDP-trafficgen supports generating UDP traffic with fixed or dynamic destination ports, and also has basic support for generating dummy TCP traffic on a single flow.

### Running xdp-traffigen
The syntax for running xdp-trafficgen is:

```
Usage: xdp-trafficgen COMMAND [options]
COMMAND can be one of:

       udp         - run in UDP mode

       xsk-udp     - run in UDP mode (using AF_XDP sockets)

       tcp         - run in TCP mode

       probe       - probe kernel support
```

Each command, and its options are explained below. Or use xdp-trafficgen COMMAND --help to see the options for each command.

## The UDP command
The UDP command generates UDP traffic to a given destination IP and either a fixed destination port, or a range of port numbers. Only IPv6 traffic is supported, and the generated packets will have their IP hop limit set to 1, so they can't be routed.

The syntax for the udp command is:

xdp-trafficgen udp [options] <ifname>

Where <ifname> is the name of the destination interface that packets will be transmitted on. Note that the network driver of this network interface must support being the target of XDP redirects (it must implement the ndo_xdp_xmit driver operation).

The supported options are:

### -m, --dst-mac <mac addr>
Set the destination MAC address of generated packets. The default is to generate packets with an all-zero destination MAC.

### -M, --src-mac <mac addr>
Set the source MAC address of the generated packets. The default is to use the MAC address of the interface packets are transmitted on.

### -a, --dst-addr <addr>
Destination IP address of generated packets. The default is the link-local fe80::2 address.

### -A, --src-addr <addr>
Source IP address of generated packets. The default is the link-local fe80::1 address.

### -p, --dst-port <port>
Destination UDP port of generated packets, or the first port in the range if running with --dyn-ports set. Defaults to 1.

### -P, --src-port <port>
Source UDP port of generated packets. Defaults to 1.

### -d, --dyn-ports <num ports>
Enable dynamic port mode where the destination port is varied over a range of <num ports> starting from the --dst-port.

### -n, --num-packets <num packets>
Number of packets to send before exiting. If not supplied, xdp-trafficgen will keep sending packets until interrupted.

### -s, --pkt-size <bytes>
Size of each UDP packet being sent, including the Ethernet header and checksum. Since xdp-trafficgen generates IPv6 traffic, the minimum size, which is also the default, is 66 bytes.

Older versions of xdp-trafficgen failed to account for the four-byte ethernet checksum that is added at the end of packet, which meant that 64 was allowed (and the default) for size, even though this really generated 68-byte packets on the wire. To be able to fix this bug without breaking existing users, values of 64 or 65 will be clamped to the actual minimum value of 66 with a warning, instead of producing an error.

### -t, --threads <threads>
Number of simultaneous threads to transmit from. Each thread will be pinned to a separate CPU core if possible. Defaults to 1.

### -I, --interval <s>
Output transmission statistics with this interval (in seconds).

### -v, --verbose
Enable verbose logging (-vv: more verbose).

### --version
Display version information and exit.

### -h, --help
Display a summary of the available options

## The XSK-UDP command
The xsk-udp command also generates UDP traffic, but does so using an AF_XDP socket generates the traffic in userspace. This can be used to test and benchmark AF_XDP sockets for transmitting.

The code for this commands is derived from the xdpsock utility previously part of the kernel sources, and more recently the bpf-examples repository. This command corresponds to the --txonly option of xdpsock.

The syntax for this command is:

xdp-trafficgen xsk-udp [options] <ifname>

The supported options are:

### -m, --dst-mac <mac addr>
Set the destination MAC address of generated packets. The default is to generate packets with an all-zero destination MAC.

### -M, --src-mac <mac addr>
Set the source MAC address of the generated packets. The default is to use the MAC address of the interface packets are transmitted on.

### -y, --timestamp
Add a timestamp to each packet, using the same header format used by the kernel pktgen utility.

### -V, --vlan-tag
Add a vlan tag to packets, using the ID and PRI specified using the --vlan-id and --vlan-pri options.

### -J, --vlan-id
Set the vlan ID used for packets. Only has an effect when the --vlan-tag option is set. Default: 1.

### -K, --vlan-pri
Set the vlan PRI used for packets. Only has an effect when the --vlan-tag option is set. Default: 0.

### -P, --fill-pattern <pattern>
Use this pattern to fill the packet data. The data pattern is specified as a 32-bit hex value, and defaults to 0.

### -T, --tx-cycle-time <us>
Specify an interval between packet bursts, in microseconds. Each interval, a burst of --batch-size packets are sent. The default is 0 (send packets as fast as possible).

### -q, --queue <queue>
Select the hardware receive queue to use for the test. The AF_XDP socket is bound to this queue, which means that xdp-trafficgen will process all packets arriving on it. The default is to use queue 0.

### -i, --interval <seconds>
Set the polling interval for collecting all statistics and displaying them to the output. The default interval is 2 seconds.

### -O, --retries <number>
Set the maximum number retries when completing the last packets of a test run. When ending a test run, xdp-trafficgen will try to release the last packet ring descriptors before exiting, retrying this many times with a 1-second interval in-between. This is only used when --pkt-count is set.

### -f, --frame-size <size>
Set the size of the memory frames used to transmit packets. Packets will always use a memory chunk of this size, regardless of the size of the packet on the wire. The size must be a power of two, unless the --unaligned flag is used. The default is 4096 bytes (which corresponds to the page size on most systems).

### -s, --pkt-size <size>
Set the size of the packets being transmitted. This must be between 64 and 9728 bytes, and defaults to 64.

### -d, --duration <seconds>
Set the test duration, in seconds. The default is 0 (run forever, or until --pkt-count packets have been sent).

### -c, --pkt-count <number>
Set the total number of packets to transmit before exiting. The default is 0 (which means run forever, or until --duration is reached).

### -b, --batch-size <packets>
Set the batch size for the packet processing loop. This is the number of packets sent at once each time the loop runs. The default is 64 packets. See also --tx-cycle-time.

### -I, --irq-string <irq-string>
Enable printing of interrupt statistics for the interrupt number associated with irq-string in /proc/interrupts. The string is used to find a matching IRQ number by simple substring matching. No default (which means no IRQ statistics are printed).

### -p, --poll
Use the poll() system call to get notifications for when a socket is ready to transmit new packets, instead of running in a loop constantly attempting to transmit.

### -m, --no-need-wakeup
Don't set the XDP_USE_NEED_WAKEUP flag when binding the AF_XDP socket. The flag is set by default, and causes the kernel driver to occasionally go to sleep and yield the CPU to the userspace application when processing packets.

### -u, --unaligned
Support sending unaligned packets, i.e., packets that are not aligned to the beginning of a data frame. When set, xdp-trafficgen will enable huge pages for the userspace memory buffer used to hold the packet data being transmitted. Setting this option enables frame sizes that are not a power of two (see the --frame-size option).

### -M, --shared-umem
Enable shared userspace memory across multiple AF_XDP sockets. When this option is set, xdp-trafficgen will create four sockets that share the same userspace memory buffer, and packets will be sent on each socket in a round-robin fashion.

### -x, --extra-stats
Print extra packet statistics at each output interval.

### -Q, --quiet
Don't print any statistics at each output interval.

### -a, --app-stats
Print additional application-level statistics at each output interval.

### -C, --copy-mode <mode>
Select the copying mode for the packets. Set to one of auto, copy, or zero-copy. The default is auto, which lets the kernel pick. Using zero-copy requires kernel and driver support, and can only be used when attaching the XDP program in native mode (see --attach-mode).

### -w, --clock <clock>
Choose the clock that will be used for all timer events in the application. The valid values are MONOTONIC, REALTIME, TAI and BOOTTIME, and the default is MONOTONIC.

### -W, --policy <policy>
Set the scheduler policy for the application before running. Valid values are SCHED_OTHER and SCHED_FIFO, and the default is SCHED_OTHER.

### -U, --schpri <priority>
Set the scheduler priority when using SCHED_FIFO. Defaults to 0.

### -A, --attach-mode <mode>
Set the XDP program attach mode (native or skb) of the XDP program that xdp-trafficgen attaches to the interface to enable XDP support. The default is native mode. Note that zero-copy can only be used in native mode.

### -v, --verbose
Enable verbose logging. Supply twice to enable verbose logging from the underlying libxdp and libbpf libraries.

### --version
Show the application version and exit.

### -h, --help
Display a summary of the available options

## The TCP command
The TCP command generates dummy TCP traffic in a single TCP flow. This relies on first installing an ingress XDP program on the interface used to transmit on. Then, a regular TCP socket connection is established from userspace, and once the handshake is completed, the XDP program will take over and start generating traffic on that flow tuple. The ingress XDP program will intercept ACK packets from the receiver, and keep track of the receive window.

The traffic generator has no congestion control, and only very basic retransmit tracking: in essence, any duplicate ACKs from the receiver will cause the sender to reset its send sequence number to the last ACKed value and restart from there. The same thing happens if no progress on the window is made within two seconds. This means that the traffic generator can generate a large amount of dummy traffic, but if there's packet loss a lot of this can be retransmissions.

The syntax for the tcp command is:

xdp-trafficgen tcp [options] -i <ifname> <hostname>

Where <ifname> is the name of the destination interface that packets will be transmitted on and <hostname> is the peer hostname or IP address to connect to (only IPv6 is supported). Note that the network driver of this network interface must support being the target of XDP redirects (it must implement the ndo_xdp_xmit driver operation).

The supported options are:

### -p, --dst-port <port>
Connect to destination <port>. Default 10000.

### -m, --mode <mode>
Load ingress XDP program in <mode>; default native (valid values: native,skb,hw)

### -n, --num-packets <port>
Number of packets to send before exiting. If not supplied, xdp-trafficgen will keep sending packets until interrupted.

### -I, --interval <s>
Output transmission statistics with this interval (in seconds).

### -v, --verbose
Enable verbose logging (-vv: more verbose).

### --version
Display version information and exit.

### -h, --help
Display a summary of the available options

## The PROBE command
The PROBE command probes the kernel to discover whether it supports the features needed to run xdp-trafficgen. This can be used to discover whether the running kernel is compatible with xdp-trafficgen, as well as to discover whether a particular interface supports sending packets generated by xdp-trafficgen.

The syntax for the probe command is:

xdp-trafficgen probe [options]

After probing, xdp-trafficgen will print the results of the probing of the kernel, and (if an interface name is supplied), whether the interface supports sending packets generated by xdp-trafficgen. The exit code will be 0 if all probes succeed, and 1 otherwise.

Note that the probing relies on the kernel XDP feature reporting, which was added after the XDP support itself. This means that with some older kernel versions, the probing may fail even though xdp-trafficgen would in fact be able to transmit packets.

The supported options are:

### -i, --ifname <ifname>
Probe the supplied interface name, in addition to doing the general kernel probing.

### -v, --verbose
Enable verbose logging (-vv: more verbose).

### --version
Display version information and exit.

### -h, --help
Display a summary of the available options

## BUGS
Please report any bugs on Github: https://github.com/xdp-project/xdp-tools/issues

## AUTHOR
xdp-trafficgen and this man page were written by Toke Høiland-Jørgensen.


xdpdump

title: xdpdump(8)

text:
# xdpdump(8)

## NAME
xdpdump - a simple tcpdump like tool for capturing packets at the XDP layer

## SYNOPSIS
xdpdump is a simple XDP packet capture tool that tries to behave similar to tcpdump, however, it has no packet filter or decode capabilities.

This can be used for debugging XDP programs that are already loaded on an interface. Packets can be dumped/inspected before on entry to XDP program, or after at exit from an XDP program. Furthermore, at exit the XDP action is also captured. This means that even packets that are dropped at the XDP layer can be captured via this tool.

xdpdump works by attaching a bpf trace program to the XDP entry and/or exit function which stores the raw packet in a perf trace buffer. If no XDP program is loaded this approach can not be used and the tool will use a libpcap live-capture to be backward compatible.

### Running xdpdump
The syntax for running xdpdump is:

```
Usage: xdpdump [options]

 XDPDump tool to dump network traffic
Options:

     --rx-capture <mode>    Capture point for the rx direction (valid values: entry,exit)

 -D, --list-interfaces      Print the list of available interfaces

 -i, --interface <ifname>   Name of interface to capture on

     --perf-wakeup <events>  Wake up xdpdump every <events> packets

 -p, --program-names <prog>  Specific program to attach to

 -s, --snapshot-length <snaplen>  Minimum bytes of packet to capture

     --use-pcap             Use legacy pcap format for XDP traces

 -w, --write <file>         Write raw packets to pcap file

 -x, --hex                  Print the full packet in hex

 -v, --verbose              Enable verbose logging (-vv: more verbose)

     --version              Display version information

 -h, --help                 Show this help
```

## The options explained
The xdpdump tool tries to mimic the basic tcpdump options, but just in case below each of the available options is explained:

### --rx-capture <mode>
Specify where the ingress packet gets captured. Either at the entry of the XDP program and/or exit of the XDP program. Valid options are entry, exit, or both entry,exit. The packet at exit can be modified by the XDP program. If you are interested to see both the original and modified packet, use the entry,exit option. With this, each packet is captured twice. The default value for this is entry.

### -D, --list-interfaces
Display a list of available interfaces and any XDP program loaded

### --load-xdp-mode
Specifies which loader mode to use with the --load-xdp-program option. The valid values are ‘native’, which is the default in-driver XDP mode, ‘skb’, which causes the so-called skb mode (also known as generic XDP) to be used, ‘hw’ which causes the program to be offloaded to the hardware, or ‘unspecified’ which leaves it up to the kernel to pick a mode (which it will do by picking native mode if the driver supports it, or generic mode otherwise). Note that using ‘unspecified’ can make it difficult to predict what mode a program will end up being loaded in. For this reason, the default is ‘native’.

### --load-xdp-program
If no XDP program is loaded on the interface, by default, xdpdump will fallback to libpcap's live capture mode to capture the packets. Alternatively, with this option, you can ask xdpdump to load an XDP program to capture the packets directly.

### -i, --interface <ifname>
Listen on interface ifname. Note that if no XDP program is loaded on the interface it will use libpcap's live capture mode to capture the packets.

### --perf-wakeup <events>
Let the Kernel wake up xdpdump once for every <events> being posted in the perf ring buffer. The higher the number the less the impact is on the actual XDP program. The default value is 0, which automatically calculates the value based on the available CPUs/buffers. Use -v to see the actual used value.

### -p, --program-names [<prog>|all]
This option allows you to capture packets for a specific, set of, or all XDP programs loaded on the interface. You can either specify the actual program names or program IDs separated by commas. In the case where multiple programs are attached with the same name, you should use the program ID. Use the -D option to see the loaded programs and their IDs.

In addition, the Linux API does not provide the full name of the attached eBPF entry function if it's longer than 15 characters. xdpdump will try to guess the correct function name from the available BTF debug information. However, if multiple functions exist with the same leading name, it can not pick the correct one. It will dump the available functions, and you can choose the correct one, and supply it with this option. If you have programs with duplicate long names, you also need to specify the program ID with the full name. This can be done by adding the id to the name with the @<id> suffix.

### -P, --promiscuous-mode
This option puts the interface into promiscuous mode.

### -s, --snapshot-length <snaplen>
Capture snaplen bytes of a packet rather than the default 262144 bytes.

### --use-pcap
Use legacy pcap format for XDP traces. By default, it will use the PcapNG format so that it can store various metadata.

### -w, --write <file>
Write the raw packets to a pcap file rather than printing them out hexadecimal. Standard output is used if file is -.

### -x, --hex
When dumping packets on the console also print the full packet content in hex.

### -v, --verbose
Enable debug logging. Specify twice for even more verbosity.

### --version
Display xpdump version information and exit.

### -h, --help
Display a summary of the available options

## Examples
The below will load the xdp-filter program on eth0, but it does not do any actual filtering:

```
# xdp-filter load --mode skb eth0
#
# xdpdump -D
Interface        Prio  Program name      Mode     ID   Tag               Chain actions
--------------------------------------------------------------------------------------
lo                     <No XDP program loaded!>
eth0                   xdp_dispatcher    skb      10651 d51e469e988d81da

 =>              10     xdpfilt_alw_all           10669 0b394f43ab24501c  XDP_PASS
```

Now we can try xdpdump:

```
# xdpdump -i eth0 -x
listening on eth0, ingress XDP program ID 10651 func xdp_dispatcher, capture mode entry, capture size 262144 bytes
1584373839.460733895: xdp_dispatcher()@entry: packet size 102 bytes, captured 102 bytes on if_index 2, rx queue 0, id 1

  0x0000:  52 54 00 db 44 b6 52 54 00 34 38 da 08 00 45 48  RT..D.RT.48...EH

  0x0010:  00 58 d7 dd 40 00 40 06 ec c3 c0 a8 7a 01 c0 a8  .X..@.@.....z...

  0x0020:  7a 64 9c de 00 16 0d d5 c6 bc 46 c9 bb 11 80 18  zd........F.....

  0x0030:  01 f5 7b b4 00 00 01 01 08 0a 77 0a 8c b8 40 12  ..{.......w...@.

  0x0040:  cc a6 00 00 00 10 54 ce 6e 20 c3 e7 da 6c 08 42  ......T.n ...l.B

  0x0050:  d6 d9 ee 42 42 f0 82 c9 4f 12 ed 7b 19 ab 22 0d  ...BB...O..{..".

  0x0060:  09 29 a9 ee df 89                                .)....
1584373839.462340808: xdp_dispatcher()@entry: packet size 66 bytes, captured 66 bytes on if_index 2, rx queue 0, id 2

  0x0000:  52 54 00 db 44 b6 52 54 00 34 38 da 08 00 45 48  RT..D.RT.48...EH

  0x0010:  00 34 d7 de 40 00 40 06 ec e6 c0 a8 7a 01 c0 a8  .4..@.@.....z...

  0x0020:  7a 64 9c de 00 16 0d d5 c6 e0 46 c9 bc 85 80 10  zd........F.....

  0x0030:  01 f5 74 0c 00 00 01 01 08 0a 77 0a 8c ba 40 12  ..t.......w...@.

  0x0040:  d2 34                                            .4
^C
2 packets captured
0 packets dropped by perf ring
```

Below are two more examples redirecting the capture file to tcpdump or tshark:

```
# xdpdump -i eth0 -w - | tcpdump -r - -n
listening on eth0, ingress XDP program ID 10651 func xdp_dispatcher, capture mode entry, capture size 262144 bytes
reading from file -, link-type EN10MB (Ethernet)
15:55:09.075887 IP 192.168.122.1.40928 > 192.168.122.100.ssh: Flags [P.], seq 3857553815:3857553851, ack 3306438882, win 501, options [nop,nop,TS val 1997449167 ecr 1075234328], length 36
15:55:09.077756 IP 192.168.122.1.40928 > 192.168.122.100.ssh: Flags [.], ack 37, win 501, options [nop,nop,TS val 1997449169 ecr 1075244363], length 0
15:55:09.750230 IP 192.168.122.1.40928 > 192.168.122.100.ssh: Flags [P.], seq 36:72, ack 37, win 501, options [nop,nop,TS val 1997449842 ecr 1075244363], length 36
```

```
# xdpdump -i eth0 -w - | tshark -r - -n
listening on eth0, ingress XDP program ID 10651 func xdp_dispatcher, capture mode entry, capture size 262144 bytes

    1   0.000000 192.168.122.1 → 192.168.122.100 SSH 102 Client: Encrypted packet (len=36)

    2   0.000646 192.168.122.1 → 192.168.122.100 TCP 66 40158 → 22 [ACK] Seq=37 Ack=37 Win=1467 Len=0 TSval=1997621571 TSecr=1075416765

    3  12.218164 192.168.122.1 → 192.168.122.100 SSH 102 Client: Encrypted packet (len=36)
```

One final example capturing specific XDP programs loaded on the interface:

```
# xdpdump -D
Interface        Prio  Program name      Mode     ID   Tag               Chain actions
--------------------------------------------------------------------------------------
lo                     <No XDP program loaded!>
eth0                   xdp_dispatcher    skb      10558 d51e469e988d81da

 =>              5      xdp_test_prog_w           10576 b5a46c6e9935298c  XDP_PASS

 =>              10     xdp_pass                  10582 3b185187f1855c4c  XDP_PASS

 =>              10     xdp_pass                  10587 3b185187f1855c4c  XDP_PASS
```

We would like to see the packets on the xdp_dispatcher() and the 2nd xdp_pass() program:

```
# xdpdump -i eth0 --rx-capture=entry,exit -p xdp_dispatcher,xdp_pass@10587

  or
# xdpdump -i eth0 --rx-capture=entry,exit -p 10558,10587
listening on eth0, ingress XDP program ID 10558 func xdp_dispatcher, ID 10587 func xdp_pass, capture mode entry/exit, capture size 262144 bytes
1607694215.501287259: xdp_dispatcher()@entry: packet size 102 bytes on if_index 2, rx queue 0, id 1
1607694215.501371504: xdp_pass()@entry: packet size 102 bytes on if_index 2, rx queue 0, id 1
1607694215.501383099: xdp_pass()@exit[PASS]: packet size 102 bytes on if_index 2, rx queue 0, id 1
1607694215.501394709: xdp_dispatcher()@exit[PASS]: packet size 102 bytes on if_index 2, rx queue 0, id 1
^C
4 packets captured
0 packets dropped by perf ring
```

## BUGS
Please report any bugs on Github: https://github.com/xdp-project/xdp-tools/issues

## AUTHOR
xdpdump was written by Eelco Chaudron


xfsdump

package: xfsdump

title: xfsdump(8)

summary: XFS filesystem incremental dump utility

text:
# xfsdump(8)

## NAME
xfsdump - XFS filesystem incremental dump utility

## SYNOPSIS

```
xfsdump -h
xfsdump [ options ] -f dest [ -f dest ... ] filesystem
xfsdump [ options ] - filesystem
xfsdump -I [ subopt=value ... ]
```

## DESCRIPTION
xfsdump backs up files and their attributes in a filesystem. The files are dumped to storage media, a regular file, or standard output. Options allow the operator to have all files dumped, just files that have changed since a previous dump, or just files contained in a list of pathnames.

The xfsrestore(8) utility re-populates a filesystem with the contents of the dump.

Each invocation of xfsdump dumps just one filesystem. That invocation is termed a dump session. The dump session splits the filesystem into one or more dump streams, one per destination. The split is done in filesystem inode number (ino) order, at boundaries selected to equalize the size of each stream. Furthermore, the breakpoints between streams may be in the middle of very large files (at extent boundaries) if necessary to achieve reasonable stream size equalization. Each dump stream can span several media objects, and a single media object can contain several dump streams. The typical media object is a tape cartridge. The media object records the dump stream as one or more media files. A media file is a self-contained partial dump, intended to minimize the impact of media dropouts on the entire dump stream at the expense of increasing the time required to complete the dump. By default only one media file is written unless a media file size is specified using the -d option. Other techniques, such as making a second copy of the dump image, provide more protection against media failures than multiple media files will.

xfsdump maintains an online dump inventory in /var/lib/xfsdump/inventory. The -I option displays the inventory contents hierarchically. The levels of the hierarchy are: filesystem, dump session, stream, and media file.

The options to xfsdump are:

-a

Specifies that files for which the Data Migration Facility (DMF) has complete offline copies (dual-state files) be treated as if they were offline (OFL). This means that the file data will not be dumped by xfsdump, resulting in a smaller dump file. If the file is later restored the file data is still accessible through DMF. If both '-a option' and '-z option' are specified, the '-a option' takes precedence (see '-z option' below).

-b blocksize

Specifies the blocksize, in bytes, to be used for the dump. The same blocksize must be specified to restore the tape. If the -m option is not used, then -b does not need to be specified. Instead, a default blocksize of 1Mb will be used.

-c progname

Use the specified program to alert the operator when a media change is required. The alert program is typically a script to send a mail or flash a window to draw the operator's attention.

-d filesize

Specifies the size, in megabytes, of dump media files. If not specified, xfsdump will dump data to tape using a single media file per media object. The specified media file size may need to be adjusted if, for example, xfsdump cannot fit a media file onto a single tape.

-e

Allow files to be excluded from the dump. This will cause xfsdump to skip files which have the "no dump" file attribute set. See the "Excluding individual files" section below for details on setting this file attribute.

-f dest [ -f dest ... ]

Specifies a dump destination. A dump destination can be the pathname of a device (such as a tape drive), a regular file or a remote tape drive (see rmt(8)). This option must be omitted if the standard output option (a lone - preceding the source filesystem specification) is specified.

-l level

Specifies a dump level of 0 to 9. The dump level determines the base dump to which this dump is relative. The base dump is the most recent dump at a lesser level. A level 0 dump is absolute - all files are dumped. A dump level where 1 <= level <= 9 is referred to as an incremental dump. Only files that have been changed since the base dump are dumped. Subtree dumps (see the -s option below) cannot be used as the base for incremental dumps.

-m

Use the minimal tape protocol for non-scsi tape destinations or remote tape destinations which are not scsi Linux tape drives nor IRIX tape drives. This option cannot be used without specifying a blocksize to be used (see -b option above).

-o

Overwrite the tape. With this option, xfsdump does not read the tape first to check the contents. This option may be used if xfsdump is unable to determine the block size of a tape .

-p interval

Causes progress reports to be printed at the specified interval. interval is given in seconds. The progress report indicates how many files have been dumped, the total number of files to dump, the percentage of data dumped, and the elapsed time.

-q

Destination tape drive is a QIC tape. QIC tapes only use a 512 byte blocksize, for which xfsdump must make special allowances.

-s pathname [ -s pathname ... ]

Restricts the dump to files contained in the specified pathnames (subtrees). A pathname must be relative to the mount point of the filesystem. For example, if a filesystem is mounted at /d2, the pathname argument for the directory /d2/users is ``users''. A pathname can be a file or a directory; if it is a directory, the entire hierarchy of files and subdirectories rooted at that directory is dumped. Subtree dumps cannot be used as the base for incremental dumps (see the -l option above).

-t file

Sets the dump time to the modification time of file rather than using the current time. xfsdump uses the dump time to determine what files need to be backed up during an incremental dump. This option should be used when dumping snapshots so that the dump time matches the time the snapshot was taken. Otherwise files modified after a snapshot is taken may be skipped in the next incremental dump.

-v verbosity

-v subsys=verbosity[,subsys=verbosity,...]

Specifies the level of detail used for messages displayed during the course of the dump. The verbosity argument can be passed as either a string or an integer. If passed as a string the following values may be used: silent, verbose, trace, debug, or nitty. If passed as an integer, values from 0-5 may be used. The values 0-4 correspond to the strings already listed. The value 5 can be used to produce even more verbose debug output. The first form of this option activates message logging across all dump subsystems. The second form allows the message logging level to be controlled on a per-subsystem basis. The two forms can be combined (see the example below). The argument subsys can take one of the following values: general, proc, drive, media, inventory, inomap and excluded_files.

For example, to dump the root filesystem with tracing activated for all subsystems:

```
# xfsdump -v trace -f /dev/tape /
```

To enable debug-level tracing for drive and media operations:

```
# xfsdump -v drive=debug,media=debug -f /dev/tape /
```

To enable tracing for all subsystems, and debug level tracing for drive operations only:

```
# xfsdump -v trace,drive=debug -f /dev/tape /
```

To list files that will be excluded from the dump:

```
# xfsdump -e -v excluded_files=debug -f /dev/tape /
```

-z size

Specifies the maximum size, in kilobytes, of files to be included in the dump. Files over this size, will be excluded from the dump, except for DMF dual-state files when '-a option' is specified (see '-a option' above). When specified, '-a option' takes precedence over '-z option'. The size is an estimate based on the number of disk blocks actually used by the file, and so does not include holes. In other words, size refers to the amount of space the file would take in the resulting dump. On an interactive restore, the skipped file is visible with xfsrestore's 'ls' and while you can use the 'add' and 'extract' commands, nothing will be restored.

-A

Do not dump extended file attributes. When dumping a filesystem managed within a DMF environment this option should not be used. DMF stores file migration status within extended attributes associated with each file. If these attributes are not preserved when the filesystem is restored, files that had been in migrated state will not be recallable by DMF. Note that dumps containing extended file attributes cannot be restored with older versions of xfsrestore(8).

-B session_id

Specifies the ID of the dump session upon which this dump session is to be based. If this option is specified, the -l (level) and -R (resume) options are not allowed. Instead, xfsdump determines if the current dump session should be incremental and/or resumed, by looking at the base session's level and interrupted attributes. If the base session was interrupted, the current dump session is a resumption of that base at the same level. Otherwise, the current dump session is an incremental dump with a level one greater than that of the base session. This option allows incremental and resumed dumps to be based on any previous dump, rather than just the most recent.

-D

Controls which directories are backed up during an incremental dump. By default unchanged directories are dumped if files or directories beneath them have changed. This results in a self-contained dump -- if a base dump is lost, or you know the file(s) you wish to restore is in an incremental dump, you can restore just that dump without loading the base dump(s) first. However, this method requires a potentially expensive traversal through the filesystem. When -D is specified, unchanged directories are not dumped. This results in a faster dump, but files will end up in the xfsrestore(8) orphanage directory unless the base dump(s) is loaded first.

-E

Pre-erase media. If this option is specified, media is erased prior to use. The operator is prompted for confirmation, unless the -F option is also specified.

-F

Don't prompt the operator. When xfsdump encounters a media object containing non-xfsdump data, xfsdump normally asks the operator for permission to overwrite. With this option the overwrite is performed, no questions asked. When xfsdump encounters end-of-media during a dump, xfsdump normally asks the operator if another media object will be provided. With this option the dump is instead interrupted.

-I

Displays the xfsdump inventory (no dump is performed). xfsdump records each dump session in an online inventory in /var/lib/xfsdump/inventory. xfsdump uses this inventory to determine the base for incremental dumps. It is also useful for manually identifying a dump session to be restored. Suboptions to filter the inventory display are described later.

-J

Inhibits the normal update of the inventory. This is useful when the media being dumped to will be discarded or overwritten.

-K

Generate a format 2 dump instead of the current format. This is useful if the dump will be restored on a system with an older xfsrestore which does not understand the current dump format. Use of this option is otherwise not recommended.

-L session_label

Specifies a label for the dump session. It can be any arbitrary string up to 255 characters long.

-M label [ -M label ... ]

Specifies a label for the first media object (for example, tape cartridge) written on the corresponding destination during the session. It can be any arbitrary string up to 255 characters long. Multiple media object labels can be specified, one for each destination.

-O options_file

Insert the options contained in options_file into the beginning of the command line. The options are specified just as they would appear if typed into the command line. In addition, newline characters (\n) can be used as whitespace. The options are placed before all options actually given on the command line, just after the command name. Only one -O option can be used. Recursive use is ignored. The source filesystem cannot be specified in options_file.

-R

Resumes a previously interrupted dump session. If the most recent dump at this dump's level (-l option) was interrupted, this dump contains only files not in the interrupted dump and consistent with the incremental level. However, files contained in the interrupted dump that have been subsequently modified are re-dumped.

-T

Inhibits interactive dialogue timeouts. When the -F option is not specified, xfsdump prompts the operator for labels and media changes. Each dialogue normally times out if no response is supplied. This option prevents the timeout.

-Y length

Specify I/O buffer ring length. xfsdump uses a ring of output buffers to achieve maximum throughput when dumping to tape drives. The default ring length is 3. However, this is not currently enabled on Linux yet, making this option benign.

-

A lone - causes the dump stream to be sent to the standard output, where it can be piped to another utility such as xfsrestore(8) or redirected to a file. This option cannot be used with the -f option. The - must follow all other options and precede the filesystem specification.

The filesystem, filesystem, can be specified either as a mount point or as a special device file (for example, /dev/dsk/dks0d1s0). The filesystem must be mounted to be dumped.

## NOTES

### Dump Interruption
A dump can be interrupted at any time and later resumed. To interrupt, type control-C (or the current terminal interrupt character). The operator is prompted to select one of several operations, including dump interruption. After the operator selects dump interruption, the dump continues until a convenient break point is encountered (typically the end of the current file). Very large files are broken into smaller subfiles, so the wait for the end of the current file is brief.

### Dump Resumption
A previously interrupted dump can be resumed by specifying the -R option. If the most recent dump at the specified level was interrupted, the new dump does not include files already dumped, unless they have changed since the interrupted dump.

### Media Management
A single media object can contain many dump streams. Conversely, a single dump stream can span multiple media objects. If a dump stream is sent to a media object already containing one or more dumps, xfsdump appends the new dump stream after the last dump stream. Media files are never overwritten. If end-of-media is encountered during the course of a dump, the operator is prompted to insert a new media object into the drive. The dump stream continuation is appended after the last media file on the new media object.

### Inventory
Each dump session updates an inventory database in /var/lib/xfsdump/inventory. xfsdump uses the inventory to determine the base of incremental and resumed dumps.

This database can be displayed by invoking xfsdump with the -I option. The display uses tabbed indentation to present the inventory hierarchically. The first level is filesystem. The second level is session. The third level is media stream (currently only one stream is supported). The fourth level lists the media files sequentially composing the stream.

The following suboptions are available to filter the display.

-I depth=n

(where n is 1, 2, or 3) limits the hierarchical depth of the display. When n is 1, only the filesystem information from the inventory is displayed. When n is 2, only filesystem and session information are displayed. When n is 3, only filesystem, session and stream information are displayed.

-I level=n

(where n is the dump level) limits the display to dumps of that particular dump level.

The display may be restricted to media files contained in a specific media object.

-I mobjid=value

(where value is a media ID) specifies the media object by its media ID.

-I mobjlabel=value

(where value is a media label) specifies the media object by its media label.

Similarly, the display can be restricted to a specific filesystem.

-I mnt=mount_point

(that is, [hostname:]pathname), identifies the filesystem by mountpoint. Specifying the hostname is optional, but may be useful in a clustered environment where more than one host can be responsible for dumping a filesystem.

-I fsid=filesystem_id

identifies the filesystem by filesystem ID.

-I dev=device_pathname

(that is, [hostname:]device_pathname) identifies the filesystem by device. As with the mnt filter, specifying the hostname is optional.

More than one of these suboptions, separated by commas, may be specified at the same time to limit the display of the inventory to those dumps of interest. However, at most four suboptions can be specified at once: one to constrain the display hierarchy depth, one to constrain the dump level, one to constrain the media object, and one to constrain the filesystem.

For example, -I depth=1,mobjlabel="tape 1",mnt=host1:/test_mnt would display only the filesystem information (depth=1) for those filesystems that were mounted on host1:/test_mnt at the time of the dump, and only those filesystems dumped to the media object labeled "tape 1".

Dump records may be removed (pruned) from the inventory using the xfsinvutil program.

An additional media file is placed at the end of each dump stream. This media file contains the inventory information for the current dump session. Its contents may be merged back into the online inventory database at a later time using xfsrestore(1M).

The inventory files stored in /var/lib/xfsdump are not included in the dump, even if that directory is contained within the filesystem being dumped. Including the inventory in the dump may lead to loss or corruption of data, should an older version be restored overwriting the current version. To backup the xfsdump inventory, the contents of /var/lib/xfsdump should be copied to another location which may then be safely dumped. Upon restoration, those files may be copied back into /var/lib/xfsdump, overwriting whatever files may be there, or xfsinvutil(1M) may be used to selectively merge parts of the restored inventory back into the current inventory. Prior to version 1.1.8, xfsdump would include the /var/lib/xfsdump directory in the dump. Care should be taken not to overwrite the /var/lib/xfsdump directory when restoring an old dump, by either restoring the filesystem to another location or by copying the current contents of /var/lib/xfsdump to a safe place prior to running xfsrestore(1M).

### Labels
The operator can specify a label to identify the dump session and a label to identify a media object. The session label is placed in every media file produced in the course of the dump, and is recorded in the inventory.

The media label is used to identify media objects, and is independent of the session label. Each media file on the media object contains a copy of the media label. An error is returned if the operator specifies a media label that does not match the media label on a media object containing valid media files. Media labels are recorded in the inventory.

### UUIDs
UUIDs (Universally Unique Identifiers) are used in three places: to identify the filesystem being dumped (using the filesystem UUID, see xfs(5) for more details), to identify the dump session, and to identify each media object. The inventory display (-I) includes all of these.

### Dump Level Usage
The dump level mechanism provides a structured form of incremental dumps. A dump of level level includes only files that have changed since the most recent dump at a level less than level. For example, the operator can establish a dump schedule that involves a full dump every Friday and a daily incremental dump containing only files that have changed since the previous dump. In this case Friday's dump would be at level 0, Saturday's at level 1, Sunday's at level 2, and so on, up to the Thursday dump at level 6.

The above schedule results in a very tedious restore procedure to fully reconstruct the Thursday version of the filesystem; xfsrestore would need to be fed all 7 dumps in sequence. A compromise schedule is to use level 1 on Saturday, Monday, and Wednesday, and level 2 on Sunday, Tuesday, and Thursday. The Monday and Wednesday dumps would take longer, but the worst case restore requires the accumulation of just three dumps, one each at level 0, level 1, and level 2.

### Quotas
If the filesystem being dumped contains user quotas, xfsdump will use xfs_quota(8) to store the quotas in a file called xfsdump_quotas in the root of the filesystem to be dumped. This file will then be included in the dump. Upon restoration, xfs_quota (8) can be used to reactivate the quotas for the filesystem. Note, however, that the xfsdump_quotas file will probably require modification to change the filesystem or UIDs if the filesystem has been restored to a different partition or system. Group and project quotas will be handled in a similar fashion and saved in files called xfsdump_quotas_group and xfsdump_quotas_proj , respectively.

### Excluding individual files
It may be desirable to exclude particular files or directories from the dump. The -s option can be used to limit the dump to a specified directory, and the -z option can be used to exclude files over a particular size. Additionally, when xfsdump is run with the -e option, files that are tagged with the "no dump" file attribute will not be included in the dump. The chattr(1) command can be used to set this attribute on individual files or entire subtrees.

To tag an individual file for exclusion from the dump:

```
$ chattr +d file
```

To tag all files in a subtree for exclusion from the dump:

```
$ chattr -R +d directory
```

Note that any new files or directories created in a directory which has the "no dump" attribute set will automatically inherit this attribute. Also note that xfsdump does not check directories for the "no dump" attribute.

Care should be taken to note which files have been tagged. Under normal operation, xfsdump will only report the number of files it will skip. The -v excluded_files=debug option, however, will cause xfsdump to list the inode numbers of the individual files affected.

## EXAMPLES
To perform a level 0, single stream dump of the root filesystem to a locally mounted tape drive, prompting for session and media labels when required:

```
# xfsdump -f /dev/tape /
```

To specify session and media labels explicitly:

```
# xfsdump -L session_1 -M tape_0 -f /dev/tape /
```

To perform a dump to a remote tape using the minimal rmt protocol and a set blocksize of 64k:

```
# xfsdump -m -b 65536 -f otherhost:/dev/tape /
```

To perform a level 0, multi-stream dump to two locally mounted tape drives:

```
# xfsdump -L session_2 -f /dev/rmt/tps4d6v -M tape_1 \

          -f /dev/rmt/tps5d6v -M tape_2 /
```

To perform a level 1 dump relative to the last level 0 dump recorded in the inventory:

```
# xfsdump -l 1 -f /dev/tape /
```

To copy the contents of a filesystem to another directory (see xfsrestore(8)):

```
# xfsdump -J - / | xfsrestore -J - /new
```

## FILES
/var/lib/xfsdump/inventory

dump inventory database

## SEE ALSO
attr(1), rmt(8), xfsrestore(8), xfsinvutil(8), xfs_quota(8), attr_get(2).

## DIAGNOSTICS
The exit code is 0 on normal completion, non-zero if an error occurs or the dump is terminated by the operator.

For all verbosity levels greater than 0 (silent) the final line of the output shows the exit status of the dump. It is of the form:

```
xfsdump: Dump Status: code
```

Where code takes one of the following values: SUCCESS (normal completion), INTERRUPT (interrupted), QUIT (media no longer usable), INCOMPLETE (dump incomplete), FAULT (software error), and ERROR (resource error). Every attempt will be made to keep both the syntax and the semantics of this log message unchanged in future versions of xfsdump. However, it may be necessary to refine or expand the set of exit codes, or their interpretation at some point in the future.

The message ``xfsdump: WARNING: unable to open directory: ino N: Invalid argument'' can occur with filesystems which are actively being modified while xfsdump is running. This can happen to either directory or regular file inodes - affected files will not end up in the dump, files below affected directories will be placed in the orphanage directory by xfsrestore.

## BUGS
xfsdump does not dump unmounted filesystems.

The dump frequency field of /etc/fstab is not supported.

xfsdump uses the alert program only when a media change is required.

xfsdump requires root privilege (except for inventory display).

xfsdump can only dump XFS filesystems.

The media format used by xfsdump can only be understood by xfsrestore.

xfsdump does not know how to manage CD-ROM or other removable disk drives.

xfsdump can become confused when doing incremental or resumed dumps if on the same machine you dump two XFS filesystems and both filesystems have the same filesystem identifier (UUID). Since xfsdump uses the filesystem identifier to identify filesystems, xfsdump maintains one combined set of dump inventories for both filesystems instead of two sets of dump inventories. This scenario can happen only if dd or some other block-by-block copy program was used to make a copy of an XFS filesystem. See xfs_copy(8) and xfs(5) for more details.


xfsinvutil

title: xfsinvutil(8)

text:
# xfsinvutil(8)

## NAME
xfsinvutil - xfsdump inventory database checking and pruning utility

## SYNOPSIS

```
xfsinvutil [-F|-i] [-m media_label] -M mount_point mm/dd/yyyy
xfsinvutil [-F|-i] [-m media_label] -u UUID mm/dd/yyyy
xfsinvutil [-F] -s SESSION_ID
xfsinvutil -i
xfsinvutil -C
```

## DESCRIPTION
xfsdump maintains an online dump inventory in /var/lib/xfsdump/inventory. The -I option of xfsdump displays the inventory contents hierarchically. The levels of the hierarchy are: filesystem, dump session, stream, and media file.

xfsinvutil is a utility to check this inventory database for consistency, to remove entries of dump sessions which may no longer be of relevance, and to browse the contents of the inventory.

The following command line options are available:

-F

Don't prompt the operator. When xfsinvutil encounters a matching dump session, xfsinvutil will normally ask the operator for permission to delete the entry. With this option the deletion is performed, no questions asked.

-i

Interactive mode. Causes xfsinvutil to run in a mode that will allow the operator to browse and modify the contents of the inventory. Please refer to the Interactive Mode section below for more information.

-M mount_point mm/dd/yyyy

Prunes dump sessions identified by the given mount point which were created prior to the specified date. Optionally -m may be be specified to further limit the matching dump sessions by media label. xfsinvutil will prompt the operator prior to pruning a dump session unless the -F or -i options are given.

-u UUID mm/dd/yyyy

Like -M, except the matching filesystem is specified using its universally unique identifier (UUID) instead of its mount point.

-m media_label

If specified, only sessions with at least one media file whose label matches this value will be eligible for pruning. This restriction is in addition to those imposed by the date and the -M or -u options. This option allows the pruning of all inventory references to media which may have been overwritten or lost. Note that this option does not apply to sessions with no media files.

-s SESSION_ID

Prunes the dump session identified by the given session id. xfsinvutil will prompt the operator prior to pruning a dump session unless the -F option is given.

-C

With this option, xfsinvutil performs consistency checks for all entries in the inventory database. It fixes any problems found. If no consistent entries are found , the corresponding inventory database file is removed.

### Interactive Mode
When run with -i, xfsinvutil will present the operator with a hierarchical representation of the xfsdump inventory. In this mode, the operator can use the arrow keys (or the h j k l keys) to navigate the inventory and also use the following keys and functionality:

+

Expand a branch of the tree.

-

Collapse a branch of the tree.

*

Fully expand a branch of the tree.

%

Fully collapse a branch of the tree.

h

Move selection to the parent entry.

l

Move selection to the child entry.

j

Move selection to next entry.

k

Move selection to previous entry.

d

Mark the current record, and all sub-records, to be deleted.

u

Clear the current record and all parent records from being deleted.

i

Import another xfsdump inventory.

?

Show help window.

x

Commit any changes made to the inventory, and exit the program.

q

Exit the program without committing any changes to the inventory.

Inventories from other hosts can be imported to create a larger common inventory. It is recommended that the contents of /var/lib/xfsdump/inventory on the remote host be copied to a temporary local directory prior to running xfsinvutil. When xfsinvutil is run in interactive mode, and the operator hits i, they will be prompted for the path to the inventory to be imported. xfsinvutil will then add the contents of the imported inventory to the main window, and all entries will be marked as imported. The operator can then delete any of these entries that are not to be imported. When the operator commits the changes, xfsinvutil will import any entries which were not marked as deleted. Deleted entries are not actually deleted from the original imported inventory.

## NOTES

### Inventory
Each dump session updates an inventory database in /var/lib/xfsdump/inventory. xfsdump uses the inventory to determine the base of incremental and resumed dumps.

This database can be displayed by invoking xfsdump with the -I option. The display uses tabbed indentation to present the inventory hierarchically. The first level is filesystem. The second level is session. The third level is media stream (currently only one stream is supported). The fourth level lists the media files sequentially composing the stream.

## FILES
/var/lib/xfsdump/inventory

dump inventory database

## SEE ALSO
xfsdump(8), xfsrestore(8).


xfsrestore

title: xfsrestore(8)

text:
# xfsrestore(8)

## NAME
xfsrestore - XFS filesystem incremental restore utility

## SYNOPSIS

```
xfsrestore -h
xfsrestore [ options ] -f source [ -f source ... ] dest
xfsrestore [ options ] - dest
xfsrestore -I [ subopt=value ... ]
```

## DESCRIPTION
xfsrestore restores filesystems from dumps produced by xfsdump(8). Two modes of operation are available: simple and cumulative.

The default is simple mode. xfsrestore populates the specified destination directory, dest, with the files contained in the dump media.

The -r option specifies the cumulative mode. Successive invocations of xfsrestore are used to apply a chronologically ordered sequence of delta dumps to a base (level 0) dump. The contents of the filesystem at the time each dump was produced is reproduced. This can involve adding, deleting, renaming, linking, and unlinking files and directories.

A delta dump is defined as either an incremental dump (xfsdump -l option with level > 0) or a resumed dump (xfsdump -R option). The deltas must be applied in the order they were produced. Each delta applied must have been produced with the previously applied delta as its base.

xfsrestore keeps state information in the xfsrestorehousekeepingdir, to inform subsequent invocations when used in cumulative mode, or in the event a restore is interrupted. To ensure that the state information can be processed, a compatible version of xfsrestore must be used for each subsequent invocation. Additionally, each invocation must run on a system of the same endianness and page size.

The options to xfsrestore are:

-a housekeeping

Each invocation of xfsrestore creates a directory called xfsrestorehousekeepingdir. This directory is normally created directly under the dest directory. The -a option allows the operator to specify an alternate directory, housekeeping, in which xfsrestore creates the xfsrestorehousekeepingdir directory. When performing a cumulative (-r option) restore or resuming (-R option) a restore, each successive invocation must specify the same alternate directory.

-b blocksize

Specifies the blocksize, in bytes, to be used for the restore. For other drives such as DAT or 8 mm , the same blocksize used for the xfsdump operation must be specified to restore the tape. The default block size is 1Mb.

-c progname

Use the specified program to alert the operator when a media change is required. The alert program is typically a script to send a mail or flash a window to draw the operator's attention.

-e

Prevents xfsrestore from overwriting existing files in the dest directory.

-f source [ -f source ... ]

Specifies a source of the dump to be restored. This can be the pathname of a device (such as a tape drive), a regular file or a remote tape drive (see rmt(8)). This option must be omitted if the standard input option (a lone - preceding the dest specification) is specified.

-i

Selects interactive operation. Once the on-media directory hierarchy has been read, an interactive dialogue is begun. The operator uses a small set of commands to peruse the directory hierarchy, selecting files and subtrees for extraction. The available commands are given below. Initially nothing is selected, except for those subtrees specified with -s command line options.

ls [arg]

List the entries in the current directory or the specified directory, or the specified non-directory file entry. Both the entry's original inode number and name are displayed. Entries that are directories are appended with a `/'. Entries that have been selected for extraction are prepended with a `*'.

cd [arg]

Change the current working directory to the specified argument, or to the filesystem root directory if no argument is specified.

pwd

Print the pathname of the current directory, relative to the filesystem root.

add [arg]

The current directory or specified file or directory within the current directory is selected for extraction. If a directory is specified, then it and all its descendents are selected. Entries that are selected for extraction are prepended with a `*' when they are listed by ls.

delete [arg]

The current directory or specified file or directory within the current directory is deselected for extraction. If a directory is specified, then it and all its descendents are deselected. The most expedient way to extract most of the files from a directory is to select the directory and then deselect those files that are not needed.

extract

Ends the interactive dialogue, and causes all selected subtrees to be restored.

quit

xfsrestore ends the interactive dialogue and immediately exits, even if there are files or subtrees selected for extraction.

help

List a summary of the available commands.

-m

Use the minimal tape protocol. This option cannot be used without specifying a blocksize to be used (see -b option above).

-n file

Allows xfsrestore to restore only files newer than file. The modification time of file (i.e., as displayed with the ls -l command) is compared to the inode modification time of each file on the source media (i.e., as displayed with the ls -lc command). A file is restored from media only if its inode modification time is greater than or equal to the modification time of file.

-o

Restore file and directory owner/group even if not root. When run with an effective user id of root, xfsrestore restores owner and group of each file and directory. When run with any other effective user id it does not, unless this option is specified.

-p interval

Causes progress reports to be printed at intervals of interval seconds. The interval value is approximate, xfsrestore will delay progress reports to avoid undue processing overhead.

-q

Source tape drive is a QIC tape. QIC tapes only use a 512 byte blocksize, for which xfsrestore must make special allowances.

-r

Selects the cumulative mode of operation. The -a and destination options must be the same for each invocation.

-s subtree

Specifies a subtree to restore. Any number of -s options are allowed. The restore is constrained to the union of all subtrees specified. Each subtree is specified as a pathname relative to the restore dest. If a directory is specified, the directory and all files beneath that directory are restored.

-t

Displays the contents of the dump, but does not create or modify any files or directories. It may be desirable to set the verbosity level to silent when using this option.

-x

This option may be useful to fix an issue which the files are restored to orphanage directory because of xfsdump (v3.1.7 - v3.1.9) problem. A normal dump cannot be restored with this option. This option works only for a corrupted dump. If a dump is created by problematic xfsdump (v3.1.7 - v3.1.9), you should see the contents of the dump with -t option before restoring. Then, if a file is placed to the orphanage directory, you need to use this -x option to restore the dump. Otherwise, you can restore the dump without this option. In the cumulative mode, this option is required only for a base (level 0) dump. You no longer need this option for level 1+ dumps.

-v verbosity

-v subsys=verbosity[,subsys=verbosity,...]

Specifies the level of detail used for messages displayed during the course of the restore. The verbosity argument can be passed as either a string or an integer. If passed as a string the following values may be used: silent, verbose, trace, debug, or nitty. If passed as an integer, values from 0-5 may be used. The values 0-4 correspond to the strings already listed. The value 5 can be used to produce even more verbose debug output. The first form of this option activates message logging across all restore subsystems. The second form allows the message logging level to be controlled on a per-subsystem basis. The two forms can be combined (see the example below). The argument subsys can take one of the following values: general, proc, drive, media, inventory, and tree.

For example, to restore the root filesystem with tracing activated for all subsystems:

```
# xfsrestore -v trace -f /dev/tape /
```

To enable debug-level tracing for drive and media operations:

```
# xfsrestore -v drive=debug,media=debug -f /dev/tape /
```

To enable tracing for all subsystems, and debug level tracing for drive operations only:

```
# xfsrestore -v trace,drive=debug -f /dev/tape /
```

-A

Do not restore extended file attributes. When restoring a filesystem managed within a DMF environment this option should not be used. DMF stores file migration status within extended attributes associated with each file. If these attributes are not preserved when the filesystem is restored, files that had been in migrated state will not be recallable by DMF. Note that dumping of extended file attributes is also optional.

-B

Change the ownership and permissions of the destination directory to match those of the root directory of the dump.

-D

Restore DMAPI (Data Management Application Programming Interface) event settings. If the restored filesystem will be managed within the same DMF environment as the original dump it is essential that the -D option be used. Otherwise it is not usually desirable to restore these settings.

-E

Prevents xfsrestore from overwriting newer versions of files. The inode modification time of the on-media file is compared to the inode modification time of corresponding file in the dest directory. The file is restored only if the on-media version is newer than the version in the dest directory. The inode modification time of a file can be displayed with the ls -lc command.

-F

Inhibit interactive operator prompts. This option inhibits xfsrestore from prompting the operator for verification of the selected dump as the restore target and from prompting for any media change.

-I

Causes the xfsdump inventory to be displayed (no restore is performed). Each time xfsdump is used, an online inventory in /var/lib/xfsdump/inventory is updated. This is used to determine the base for incremental dumps. It is also useful for manually identifying a dump session to be restored (see the -L and -S options). Suboptions to filter the inventory display are described later.

-J

Inhibits inventory update when on-media session inventory encountered during restore. xfsrestore opportunistically updates the online inventory when it encounters an on-media session inventory, but only if run with an effective user id of root and only if this option is not given.

-K

Force xfsrestore to use dump format 2 generation numbers. Normally the need for this is determined automatically, but this option is required on the first xfsrestore invocation in the rare case that a cumulative restore begins with a format 3 (or newer) dump and will be followed by a format 2 dump.

-L session_label

Specifies the label of the dump session to be restored. The source media is searched for this label. It is any arbitrary string up to 255 characters long. The label of the desired dump session can be copied from the inventory display produced by the -I option.

-O options_file

Insert the options contained in options_file into the beginning of the command line. The options are specified just as they would appear if typed into the command line. In addition, newline characters (\n) can be used as whitespace. The options are placed before all options actually given on the command line, just after the command name. Only one -O option can be used. Recursive use is ignored. The destination directory cannot be specified in options_file.

-Q

Force completion of an interrupted restore session. This option is required to work around one specific pathological scenario. When restoring a dump session which was interrupted due to an EOM condition and no online session inventory is available, xfsrestore cannot know when the restore of that dump session is complete. The operator is forced to interrupt the restore session. In that case, if the operator tries to subsequently apply a resumed dump (using the -r option), xfsrestore refuses to do so. The operator must tell xfsrestore to consider the base restore complete by using this option when applying the resumed dump.

-R

Resume a previously interrupted restore. xfsrestore can be interrupted at any time by pressing the terminal interrupt character (see stty(1)). Use this option to resume the restore. The -a and destination options must be the same.

-S session_id

Specifies the session UUID of the dump session to be restored. The source media is searched for this UUID. The UUID of the desired dump session can be copied from the inventory display produced by the -I option.

-T

Inhibits interactive dialogue timeouts. xfsrestore prompts the operator for media changes. This dialogue normally times out if no response is supplied. This option prevents the timeout.

-X subtree

Specifies a subtree to exclude. This is the converse of the -s option. Any number of -X options are allowed. Each subtree is specified as a pathname relative to the restore dest. If a directory is specified, the directory and all files beneath that directory are excluded.

-Y io_ring_length

Specify I/O buffer ring length. xfsrestore uses a ring of input buffers to achieve maximum throughput when restoring from tape drives. The default ring length is 3. However, this is not currently enabled on Linux yet, making this option benign.

-

A lone - causes the standard input to be read as the source of the dump to be restored. Standard input can be a pipe from another utility (such as xfsdump(8)) or a redirected file. This option cannot be used with the -f option. The - must follow all other options, and precede the dest specification.

The dumped filesystem is restored into the dest directory. There is no default; the dest must be specified.

## NOTES

### Cumulative Restoration
A base (level 0) dump and an ordered set of delta dumps can be sequentially restored, each on top of the previous, to reproduce the contents of the original filesystem at the time the last delta was produced. The operator invokes xfsrestore once for each dump. The -r option must be specified. The dest directory must be the same for all invocations. Each invocation leaves a directory named xfsrestorehousekeeping in the dest directory (however, see the -a option above). This directory contains the state information that must be communicated between invocations. The operator must remove this directory after the last delta has been applied.

xfsrestore also generates a directory named orphanage in the dest directory. xfsrestore removes this directory after completing a simple restore. However, if orphanage is not empty, it is not removed. This can happen if files present on the dump media are not referenced by any of the restored directories. The orphanage has an entry for each such file. The entry name is the file's original inode number, a ".", and the file's generation count modulo 4096 (only the lower 12 bits of the generation count are used).

xfsrestore does not remove the orphanage after cumulative restores. Like the xfsrestorehousekeeping directory, the operator must remove it after applying all delta dumps.

### Media Management
A dump consists of one or more media files contained on one or more media objects. A media file contains all or a portion of the filesystem dump. Large filesystems are broken up into multiple media files to minimize the impact of media dropouts, and to accommodate media object boundaries (end-of-media).

A media object is any storage medium: a tape cartridge, a remote tape device (see rmt(8)), a regular file, or the standard input (currently other removable media drives are not supported). Tape cartridges can contain multiple media files, which are typically separated by (in tape parlance) file marks. If a dump spans multiple media objects, the restore must begin with the media object containing the first media file dumped. The operator is prompted when the next media object is needed.

Media objects can contain more than one dump. The operator can select the desired dump by specifying the dump label (-L option), or by specifying the dump UUID (-S option). If neither is specified, xfsrestore scans the entire media object, prompting the operator as each dump session is encountered.

The inventory display (-I option) is useful for identifying the media objects required. It is also useful for identifying a dump session. The session UUID can be copied from the inventory display to the -S option argument to unambiguously identify a dump session to be restored.

Dumps placed in regular files or the standard output do not span multiple media objects, nor do they contain multiple dumps.

### Inventory
Each dump session updates an inventory database in /var/lib/xfsdump/inventory. This database can be displayed by invoking xfsrestore with the -I option. The display uses tabbed indentation to present the inventory hierarchically. The first level is filesystem. The second level is session. The third level is media stream (currently only one stream is supported). The fourth level lists the media files sequentially composing the stream.

The following suboptions are available to filter the display.

-I depth=n

(where n is 1, 2, or 3) limits the hierarchical depth of the display. When n is 1, only the filesystem information from the inventory is displayed. When n is 2, only filesystem and session information are displayed. When n is 3, only filesystem, session and stream information are displayed.

-I level=n

(where n is the dump level) limits the display to dumps of that particular dump level.

The display may be restricted to media files contained in a specific media object.

-I mobjid=value

(where value is a media ID) specifies the media object by its media ID.

-I mobjlabel=value

(where value is a media label) specifies the media object by its media label.

Similarly, the display can be restricted to a specific filesystem.

-I mnt=mount_point

(that is, [hostname:]pathname), identifies the filesystem by mountpoint. Specifying the hostname is optional, but may be useful in a clustered environment where more than one host can be responsible for dumping a filesystem.

-I fsid=filesystem_id

identifies the filesystem by filesystem ID.

-I dev=device_pathname

(that is, [hostname:]device_pathname) identifies the filesystem by device. As with the mnt filter, specifying the hostname is optional.

More than one of these suboptions, separated by commas, may be specified at the same time to limit the display of the inventory to those dumps of interest. However, at most four suboptions can be specified at once: one to constrain the display hierarchy depth, one to constrain the dump level, one to constrain the media object, and one to constrain the filesystem.

For example, -I depth=1,mobjlabel="tape 1",mnt=host1:/test_mnt would display only the filesystem information (depth=1) for those filesystems that were mounted on host1:/test_mnt at the time of the dump, and only those filesystems dumped to the media object labeled "tape 1".

Dump records may be removed (pruned) from the inventory using the xfsinvutil program.

An additional media file is placed at the end of each dump stream. This media file contains the inventory information for the current dump session. If the online inventory files in /var/lib/xfsdump/inventory are missing information for the current dump session, then the inventory information in the media file is automatically added to the files in /var/lib/xfsdump/inventory. If you wish to incorporate the inventory information from the media file without restoring any data, you may do so using the -t option:

```
# xfsrestore -t -f /dev/tape
```

This is useful to rebuild the inventory database if it is ever lost or corrupted. The only caveat is that xfsrestore needs to read through the entire dump in order to reach the inventory media file. This could become time consuming for dump sessions with large media files.

### Media Errors
xfsdump is tolerant of media errors, but cannot do error correction. If a media error occurs in the body of a media file, the filesystem file represented at that point is lost. The bad portion of the media is skipped, and the restoration resumes at the next filesystem file after the bad portion of the media.

If a media error occurs in the beginning of the media file, the entire media file is lost. For this reason, large dumps are broken into a number of reasonably sized media files. The restore resumes with the next media file.

### Quotas
When xfsdump dumps a filesystem with user quotas, it creates a file in the root of the dump called xfsdump_quotas. xfsrestore can restore this file like any other file included in the dump. This file can be processed by the restore command of xfs_quota(8) to reactivate the quotas. However, the xfsdump_quotas file contains information which may first require modification; specifically the filesystem name and the user ids. If you are restoring the quotas for the same users on the same filesystem from which the dump was taken, then no modification will be necessary. However, if you are restoring the dump to a different filesystem, you will need to:

- ensure the new filesystem is mounted with the quota option

- modify the xfsdump_quotas file to contain the new filesystem name

- ensure the uids in the xfsdump_quotas file are correct

Once the quota information has been verified, the restore command of xfs_quota (8) can be used to apply the quota limits to the filesystem.

Group and project quotas are handled in a similar fashion and will be restored in files called xfsdump_quotas_group and xfsdump_quotas_proj, respectively.

## EXAMPLES
To restore the root filesystem from a locally mounted tape:

```
# xfsrestore -f /dev/tape /
```

To restore from a remote tape, specifying the dump session id:

```
# xfsrestore -L session_1 -f otherhost:/dev/tape /new
```

To restore the contents a of a dump to another subdirectory:

```
# xfsrestore -f /dev/tape /newdir
```

To copy the contents of a filesystem to another directory (see xfsdump(8)):

```
# xfsdump -J - / | xfsrestore -J - /new
```

## FILES
/var/lib/xfsdump/inventory

dump inventory database

## SEE ALSO
rmt(8), xfsdump(8), xfsinvutil(8), xfs_quota(8), attr_set(2).

## DIAGNOSTICS
The exit code is 0 on normal completion, and non-zero if an error occurred or the restore was terminated by the operator.

For all verbosity levels greater than 0 (silent) the final line of the output shows the exit status of the restore. It is of the form:

```
xfsdump: Restore Status: code
```

Where code takes one of the following values: SUCCESS (normal completion), INTERRUPT (interrupted), QUIT (media no longer usable), INCOMPLETE (restore incomplete), FAULT (software error), and ERROR (resource error). Every attempt will be made to keep both the syntax and the semantics of this log message unchanged in future versions of xfsrestore. However, it may be necessary to refine or expand the set of exit codes, or their interpretation at some point in the future.

## BUGS
Pathnames of restored non-directory files (relative to the dest directory) must be 1023 characters (MAXPATHLEN) or less. Longer pathnames are discarded and a warning message displayed.

There is no verify option to xfsrestore. This would allow the operator to compare a filesystem dump to an existing filesystem, without actually doing a restore.

The interactive commands (-i option) do not understand regular expressions.

When the minimal rmt option is specified, xfsrestore applies it to all remote tape sources. The same blocksize (specified by the -b option) is used for all these remote drives.

xfsrestore uses the alert program only when a media change is required.

Cumulative mode (-r option) requires that the operator invoke xfsrestore for the base and for each delta to be applied in sequence to the base. It would be better to allow the operator to identify the last delta in the sequence of interest, and let xfsrestore work backwards from that delta to identify and apply the preceding deltas and base dump, all in one invocation.


fsck.xfs

package: xfsprogs

title: fsck.xfs(8)

summary: do nothing, successfully

text:
# fsck.xfs(8)

## NAME
fsck.xfs - do nothing, successfully

## SYNOPSIS
fsck.xfs [ filesys ... ]

## DESCRIPTION
fsck.xfs is called by the generic Linux fsck(8) program at startup to check and repair an XFS filesystem. XFS is a journaling filesystem and performs recovery at mount(8) time if necessary, so fsck.xfs simply exits with a zero exit status.

If you wish to check the consistency of an XFS filesystem, or repair a damaged or corrupt XFS filesystem, see xfs_repair(8).

However, the system administrator can force fsck.xfs to run xfs_repair(8) at boot time by creating a /forcefsck file or booting the system with "fsck.mode=force" on the kernel command line.

## FILES
/etc/fstab.

## SEE ALSO
fsck(8), fstab(5), xfs(5), xfs_repair(8).