xdp-filter

title: xdp-filter(8)

summary: a simple XDP-powered packet filter

text:
# xdp-filter(8)

## NAME
xdp-filter - a simple XDP-powered packet filter

## SYNOPSIS
XDP-filter is a packet filtering utility powered by XDP. It is deliberately simple and so does not have the same matching capabilities as, e.g., netfilter. Instead, thanks to XDP, it can achieve very high drop rates: tens of millions of packets per second on a single CPU core.

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

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

       load        - load xdp-filter on an interface

       unload      - unload xdp-filter from an interface

       port        - add a port to the filter list

       ip          - add an IP address to the filter list

       ether       - add an Ethernet MAC address to the filter list

       status      - show current xdp-filter status

       poll        - poll statistics output

       help        - show the list of available commands
```

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

## The LOAD command
To use xdp-filter, it must first be loaded onto an interface. This is accomplished with the load command, which takes the name of the interface as a parameter, and optionally allows specifying the features that should be included. By default all features are loaded, but de-selecting some features can speed up the packet matching, and increase performance by a substantial amount.

The syntax for the load command is:

xdp-filter load [options] <ifname>

Where <ifname> is the name of the interface to load xdp-filter onto, and must be specified. 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, or 'hw' which causes the program to be offloaded to the hardware.

### -p, --policy <policy>
This sets the policy xdp-filter applies to packets not matched by any of the filter rules. The default is allow, in which packets not matching any rules are allowed to pass. The other option is deny, in which all packets are dropped except those matched by the filter options.

xdp-filter cannot be loaded simultaneously in deny and allow policy modes on the system. Note that loading xdp-filter in deny mode will drop all traffic on the interface until suitable allow rules are installed, so some care is needed to avoid being locked out of a remote system.

### -f, --features <feats>
Use this option to select which features to include when loaded xdp-filter. The default is to load all available features. So select individual features specify one or more of these:

- tcp: Support filtering on TCP port number

- udp: Support filtering on UDP port number

- ipv6: Support filtering on IPv6 addresses

- ipv4: Support filtering on IPv4 addresses

- ethernet: Support filtering on Ethernet MAC addresses

Specify multiple features by separating them with a comma. E.g.: tcp,udp,ipv6.

### -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 unloads xdp-filter from one (or all) interfaces, and cleans up the program state.

The syntax for the load command is:

xdp-filter unload [options] <ifname>

Where <ifname> is the name of the interface to unload xdp-filter from, and must be specified unless the --all option is used. The supported options are:

### -a, --all
Specify this option to remove xdp-filter from all interfaces it was loaded onto. If this option is specified, no <ifname> is needed.

This option can also be used to clean up all xdp-filter state if the XDP program(s) were unloaded by other means.

### -k, --keep-maps
Specify this option to prevent xdp-filter from clearing its map state. By default, all BPF maps no longer needed by any loaded program are removed. However, this will also remove the contents of the maps (the filtering rules), so this option can be used to keep the maps around so the rules persist until xdp-filter is loaded again.

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

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

## The PORT command
Use the port command to add a TCP or UDP port to the xdp-filter match list. For this to work, xdp-filter must be loaded with either the udp or the tcp feature (or both) on at least one interface.

The syntax for the port command is:

xdp-filter port [options] <port>

Where <port> is the port number to add (or remove if the --remove is specified). The supported options are:

### -r, --remove
Remove the port instead of adding it.

### -m, --mode <mode>
Select filtering mode. Valid options are src and dst, both of which may be specified as src,dst. If src is specified, the port number will added as a source port match, while if dst is specified, the port number will be added as a destination port match. If both are specified, a packet will be matched if either its source or destination port is the specified port number.

### -p, --proto <proto>
Specify one (or both) of udp and/or tcp to match UDP or TCP ports, respectively.

### -s, --status
If this option is specified, the current list of matched ports will be printed after inserting the port number. Otherwise, nothing will be printed.

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

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

## The IP command
Use the ip command to add an IPv6 or an IPv4 address to the xdp-filter match list.

The syntax for the ip command is:

xdp-filter ip [options] <ip>

Where <ip> is the IP address to add (or remove if the --remove is specified). Either IPv4 or IPv6 addresses can be specified, but xdp-filter must be loaded with the corresponding features (ipv4 and ipv6, respectively). The supported options are:

### -r, --remove
Remove the IP address instead of adding it.

### -m, --mode <mode>
Select filtering mode. Valid options are src and dst, both of which may be specified as src,dst. If src is specified, the IP address will added as a source IP match, while if dst is specified, the IP address will be added as a destination IP match. If both are specified, a packet will be matched if either its source or destination IP is the specified IP address.

### -s, --status
If this option is specified, the current list of matched ips will be printed after inserting the IP address. Otherwise, nothing will be printed.

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

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

## The ETHER command
Use the ether command to add an Ethernet MAC address to the xdp-filter match list. For this to work, xdp-filter must be loaded with either the ethernet feature on at least one interface.

The syntax for the ether command is:

xdp-filter ether [options] <addr>

Where <addr> is the MAC address to add (or remove if the --remove is specified). The supported options are:

### -r, --remove
Remove the MAC address instead of adding it.

### -m, --mode <mode>
Select filtering mode. Valid options are src and dst, both of which may be specified as src,dst. If src is specified, the MAC address will added as a source MAC match, while if dst is specified, the MAC address will be added as a destination MAC match. If both are specified, a packet will be matched if either its source or destination MAC is the specified MAC address.

### -s, --status
If this option is specified, the current list of matched ips will be printed after inserting the MAC address. Otherwise, nothing will be printed.

### -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 prints the current status of xdp-filter: Which interfaces it is loaded on, the current list of rules, and some statistics for how many packets have been processed in total, and how many times each rule has been hit.

The syntax for the status command is:

xdp-filter status [options]

Where the supported options are:

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

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

## The POLL command
The poll command periodically polls the xdp-filter statistics map and prints out the total number of packets and bytes processed by xdp-filter, as well as the number in the last polling interval, converted to packets (and bytes) per second. This can be used to inspect the performance of xdp-filter, and to compare the performance of the different feature sets selectable by the load parameter.

The syntax for the poll command is:

xdp-filter poll [options]

Where the supported options are:

### -i, --interval <interval>
The polling interval, in milliseconds. Defaults to 1000 (1 second).

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

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

## Examples
To filter all packets arriving on port 80 on eth0, issue the following commands:

```
# xdp-filter load eth0 -f tcp,udp
# xdp-filter port 80
```

To filter all packets except those from IP address fc00:dead:cafe::1 issue the following commands (careful, this can lock you out of remote access!):

```
# xdp-filter load eth0 -f ipv6 -p deny
# xdp-filter ip fc00:dead:cafe::1 -m src
```

To allow packets from either IP fc00:dead:cafe::1 or arriving on port 22, issue the following (careful, this can lock you out of remote access!):

```
# xdp-filter load eth0 -f ipv6,tcp -p deny
# xdp-filter port 22
# xdp-filter ip fc00:dead:cafe::1 -m src
```

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

## AUTHOR
xdp-filter was written by Toke Høiland-Jørgensen and Jesper Dangaard Brouer. This man page was written by Toke Høiland-Jørgensen.


xdp-loader

package: xdp-tools

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: Solarflare cards (using the 'sfc' 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

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.


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-bench is:

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

       udp         - run in UDP mode

       tcp         - run in TCP mode
```

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 <port>
Number of packets to send before exiting. If not supplied, xdp-trafficgen will keep sending packets until interrupted.

### -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 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

## 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


xentrace

package: xen

title: xentrace(8)

summary: capture Xen trace buffer data

text:
# xentrace(8)

## NAME
xentrace - capture Xen trace buffer data

## SYNOPSIS
xentrace [ OPTIONS ] [ FILE ]

## DESCRIPTION
xentrace is used to capture trace buffer data from Xen. The data is output in the following binary format (host endian):

```
    CPU(uint) TSC(u64) EVENT(u32) D1 D2 D3 D4 D5 (all u32)
```

Where CPU is the processor number, TSC is the record's timestamp (the value of the CPU cycle counter), EVENT is the event ID and D1...D5 are the trace data.

Data is dumped onto the standard output (which must not be a TTY) or a FILE specified on the command line.

The output should be parsed using the tool xentrace_format, which can produce human-readable output in ASCII format.

## OPTIONS
-t l, --log-thresh=l

set the threshold number, l, of new records required to trigger a write of all new records to the output

-s p, --poll-sleep=p

set the time, p, (in milliseconds) to sleep between polling the buffers for new data.

-c [c|CPU-LIST|all], --cpu-mask=[c|CPU-LIST|all]

This can be: a hex value (of the form 0xNNNN...), or a set of cpu ranges as described below, or the string all. Hex values are limited to 32 bits. If not specified, the cpu-mask as set during bootup will be constructed. If using the CPU-LIST it expects decimal numbers, which may be specified as follows:

```
  "0-3"
      Trace only on CPUs 0 through 3
  "0,2,5-7"
      Trace only on CPUs 0, 2, and 5 through 7
  "-3"
      Trace only on CPUs 0 through 3
  "-3,7"
      Trace only on CPUs 0 through 3 and 7
  "3-"
      Trace only on CPUs 3 up to maximum numbers of CPUs the host has

```

If using all it will use all of the CPUs the host has.

-e mask, --evt-mask=mask

set event capture mask. If not specified the TRC_ALL will be used.

-?, --help

Give this help list

--usage

Give a short usage message

-V, --version

Print program version

### Event Classes (Masks)
The following event classes (masks) can be used to filter the events being gathered by xentrace:

```
        ID                  Description
        0x0001f000          TRC_GEN
        0x0002f000          TRC_SCHED
        0x0004f000          TRC_DOM0OP
        0x0008f000          TRC_HVM
        0x0010f000          TRC_MEM
        0xfffff000          TRC_ALL
```

### Event Subclasses (More Masks)
The following event subclasses (masks) can also be used to filter the events being gathered by xentrace:

```
        ID                  Description
        0x00081000          TRC_HVM_ENTRYEXIT
        0x00082000          TRC_HVM_HANDLER
```

### Events
xentrace collects the following events from the trace buffer:

```
        ID                 Description
        0x0001f001         TRC_LOST_RECORDS
        0x0002f001         TRC_SCHED_DOM_ADD
        0x0002f002         TRC_SCHED_DOM_REM
        0x0002f003         TRC_SCHED_SLEEP
        0x0002f004         TRC_SCHED_WAKE
        0x0002f005         TRC_SCHED_YIELD
        0x0002f006         TRC_SCHED_BLOCK
        0x0002f007         TRC_SCHED_SHUTDOWN
        0x0002f008         TRC_SCHED_CTL
        0x0002f009         TRC_SCHED_ADJDOM
        0x0002f010         TRC_SCHED_SWITCH
        0x0002f011         TRC_SCHED_S_TIMER_FN
        0x0002f012         TRC_SCHED_T_TIMER_FN
        0x0002f013         TRC_SCHED_DOM_TIMER_FN
        0x0002f014         TRC_SCHED_SWITCH_INFPREV
        0x0002f015         TRC_SCHED_SWITCH_INFNEXT
        0x00081001         TRC_HVM_VMENTRY
        0x00081002         TRC_HVM_VMEXIT
        0x00082001         TRC_HVM_PF_XEN
        0x00082002         TRC_HVM_PF_INJECT
        0x00082003         TRC_HVM_INJ_EXC
        0x00082004         TRC_HVM_INJ_VIRQ
        0x00082005         TRC_HVM_REINJ_VIRQ
        0x00082006         TRC_HVM_IO_READ
        0x00082007         TRC_HVM_IO_WRITE
        0x00082008         TRC_HVM_CR_READ
        0x00082009         TRC_HVM_CR_WRITE
        0x0008200A         TRC_HVM_DR_READ
        0x0008200B         TRC_HVM_DR_WRITE
        0x0008200C         TRC_HVM_MSR_READ
        0x0008200D         TRC_HVM_MSR_WRITE
        0x0008200E         TRC_HVM_CPUID
        0x0008200F         TRC_HVM_INTR
        0x00082010         TRC_HVM_NMI
        0x00082011         TRC_HVM_SMI
        0x00082012         TRC_HVM_VMMCALL
        0x00082013         TRC_HVM_HLT
        0x00082014         TRC_HVM_INVLPG
        0x0010f001         TRC_MEM_PAGE_GRANT_MAP
        0x0010f002         TRC_MEM_PAGE_GRANT_UNMAP
        0x0010f003         TRC_MEM_PAGE_GRANT_TRANSFER
```

## AUTHOR
Mark A. Williamson <mark.a.williamson@intel.com>

## SEE ALSO
xentrace_format(1)


xen-create-image

package: xen-tools

title: xen-create-image(8)

text:
# xen-create-image(8)

## NAME
xen-create-image - Easily create new Xen instances with networking and OpenSSH.

## SYNOPSIS
xen-create-image --hostname=<hostname> <further options>

## EXAMPLES
xen-create-image --hostname=some-domu --dist=wheezy --lvm=vg0

xen-create-image --hostname=some-domu --dist=precise --dir=/srv/xen

See below for more specific examples: LOOPBACK EXAMPLES, LVM EXAMPLE and EVMS EXAMPLE.

## OPTIONS

```
  Help Options:
   --help        Show the help information for this script.
   --manual      Read the manual, and examples, for this script.
   --(no)verbose (Don't) show more of what xen-create-image is
                 currently doing.
   --dumpconfig  Show current configuration.
   --version     Show the version number and exit.
  Size / General options:
   --(no)accounts
                (Don't) copy all non-system accounts to the guest
                image
   --admins     Specify that some administrators should be created for
                this image, using xen-shell.
   --(no)boot   (Don't) boot the new instance after creating it.
   --cache=bool Cache .deb files on the host when installing the new
                guest with the debootstrap tool. Accepted values:
                "yes" (default) and "no".
   --cachedir=/path/to/cache/directory
                Override the default .deb cache directory. Defaults to
                /var/cache/apt/archives/ if it exists (i.e. on Debian
                and Ubuntu) and /var/cache/xen-tools/archives/ else
                (i.e. on Fedora and CentOS).
   --config=file
                Read the specified file in addition to the global
                configuration file.
   --(no)copyhosts
                (Don't) copy entries from the dom0's /etc/hosts file
                to the guest
   --copy-cmd   NOP:  Ignored.
   --debootstrap-cmd=/path/to/command
                Specify which debootstrap command is used. Defaults to
                debootstrap if both, debootstrap and cdebootstrap are
                installed. Specifying the path is optional.
   --disk_device=diskname
                Use specified device name for virtual devices instead
                of the default value "xvda".
   --extension=ext
                Specify the suffix to give the Xen configuration
                file. (Default value: ".cfg")
   --(no)force  (Don't) force overwriting existing images. This will
                remove existing images or LVM volumes which match
                those which are liable to be used by the new
                invocation.
   --fs=fs      Specify the filesystem type to use for the new guest.
                Valid choices are 'ext2', 'ext3', 'ext4', 'reiserfs',
                'xfs' or 'btrfs'. (Note: pygrub *DOES NOT* support
                xfs)
   --genpass=1  Generate a random root password (default, set to 0 to
                turn off)
   --genpass_len=N
                Override the default password length of 8 and generate
                a random password of length N. Note: this only works
                in conjunction with --genpass
   --hash_method=algorithm
                Override the default hashing method of sha256 and use
                the provided algorithm. Can be : md5, sha256 or sha512
   --hooks=1    Specify whether to run hooks after the image is created.
   --ide        Use IDE names for virtual devices (i.e. hda not xvda)
   --image=str  Specify whether to create "sparse" or "full" disk
                images.  Full images are mandatory when using LVM, so
                this setting is ignored in that case.
   --image-dev=/path/to/device
                Specify a physical/logical volume for the disk image.
   --initrd=/path/to/initrd
                Specify the initial ramdisk. If an image is specified
                it must exist.
   --install=1  Specify whether to install the guest system or not.
   --(no)keep   (Don't) keep our images if installation fails. It
                maybe unmounted, though.
   --kernel=/path/to/kernel
                Set the path to the kernel to use for domU. If a
                kernel is specified it must exist.
   --memory=size
                Setup the amount of memory allocated to the new
                instance.  As suffix recognized size units are "M",
                "MB", "G" and "GB" (case does not matter). If there's
                no unit given, megabytes are assumed.
   --maxmem=size
                Setup the maximum amount of memory that can be allocated
                to the new instance. As suffix recognized size units are "M",
                "MB", "G" and "GB" (case does not matter). If there's
                no unit given, megabytes are assumed.
                Required for dynamic memory ballooning.
   --modules=/path/to/modules
                Set the path to the kernel modules to use for domU.
                If modules are specified they must exist.
   --nohosts    Don't touch /etc/hosts on the dom0.
   --noswap     Do not create a swap partition. When this option is
                used the system will not have a swap entry added to
                its /etc/fstab file either.
   --output=dir Specify the output directory to create the xen
                configuration file within.
   --partitions=file
                Use a specific partition layout configuration file.
                See /etc/xen-tools/partitions.d/sample-server for an
                example partitioning configuration.  Not supported
                with the image-dev and swap-dev options.  Parameters
                fs, size, swap and noswap are ignored when using this
                option.
   --password=passphrase
                Set the root password for the new guest.
   --(no)passwd (Don't) ask for a root password interactively during
                setup.  NOTE: This overrides --genpass --password.
   --(no)pygrub DomU should (not) be booted using pygrub.
   --role=role  Run the specified role script(s) post-install.  Role
                scripts are discussed later in this manpage.  Can be
                an absolute path. Otherwise it's relative to the value
                of --roledir.
   --role-args="--arg1 --arg2"
                Pass the named string literally to any role script.
                This is useful for site-specific roles.
   --finalrole=role
                Similar to role scripts. Run the specified role
                script(s) after cfg file creation.
   --roledir=/path/to/directory
                Specify the directory which contains the role scripts.
                This defaults to /etc/xen-tools/role.d/
   --scsi       Use SCSI names for virtual devices (i.e. sda not xvda)
   --serial_device=serialname
                Install a getty on the specified serial device instead
                of the default device.
   --size=size  Set the size of the primary disk image.
   --swap=size  Set the size of the swap partition.
   --swap-dev=/path/to/device
                Specify a physical/logical volume for swap usage.
   --tar-cmd    NOP: Ignored.
   --dontformat Do not format the devices specified for installation.
                Useful if you want tighter control over the filesystem
                creation. Requires the filesystems to be created
                beforehand.
   --vcpus=num
                Set the number of vcpus that the new instance will
                have instead of the default value of "1".
  Installation options:
   --arch=arch  Pass the given architecture to debootstrap, rinse, or
                rpmstrap when installing the system.  This argument is
                ignored for other install methods.
   --dist=dist  Specify the distribution you wish to install.
   --install-method=method
                Specify the installation method to use. Valid methods
                are:
                * debootstrap
                * cdebootstrap
                * rinse
                * rpmstrap (deprecated)
                * tar (needs --install-source=tarball.tar)
                * copy (needs --install-source=/path/to/copy/from)
                (Default value for Debian and Ubuntu: debootstrap)
   --install-source=/path/to/tarball
                Specify the source path to use when installing via
                a copy or tarball installation.
   --mirror=url Setup the mirror to use when installing via
                debootstrap. (Default value: mirror used in
                /etc/apt/sources.list or for Debian
                "http://http.debian.net/debian/" and for Ubuntu
                "http://archive.ubuntu.com/ubuntu/")
                The above mentioned Debian mirror hostname
                automatically tries to choose a more or less close
                Debian mirror. See http://http.debian.net/ for
                details.
   --apt_proxy=protocol://hostname:port/
                Specify a proxy to be used by debootstrap, and within
                the guest. Needs the same syntax as APT's
                Acquire::http::Proxy. See apt.conf(5).
   --template=tmpl
                Specify which template file to use when creating the
                Xen configuration file.
  Networking options:
   --bridge=brname
                Optionally, set a specific bridge for the new
                instance.  This can be especially useful when running
                multiple bridges on a dom0.
   --broadcast=123.456.789.ABC
                Setup the broadcast address for the new instance.
   --(no)dhcp   The guest will (not) be configured to fetch its
                networking details via DHCP.
   --gateway=gw Setup the network gateway for the new instance.
   --ip=123.456.789.ABC
                Setup the IP address of the machine, multiple IPs are
                allowed.  When specifying more than one IP the first
                one is setup as the "system" IP, and the additional
                ones are added as aliases.
                Note that Xen 3.x supports a maximum of three vif
                statements per guest. This option conflicts with
                --dhcp.
   --mac=AA:BB:CC:DD:EE:FF
                Specify the MAC address to use for a given interface.
                This is only valid for the first IP address specified,
                or for DHCP usage.  (ie. you can add multiple --ip
                flags, but the specific MAC address will only be used
                for the first interface.)
   --netmask=123.456.789.ABC
                Setup the netmask for the new instance.
   --nameserver="123.456.789.ABC 123.456.789.DEF"
                Setup the nameserver of the machine, multiple space
                separated nameservers are allowed.  If not provided,
                Dom0's /etc/resolv.conf will be copied to guest.
   --vifname=vifname
                Optionally, set a specific vif name for the new
                instance.
  Mandatory options:
   --dir=/path/to/directory
                Specify where the output images should go.
                Subdirectories will be created for each guest.
                If you do not wish to use loopback images specify
                --lvm or --evms.  (These three options are mutually
                exclusive.)
   --evms=lvm2/container
                Specify the container to save images within,
                i.e. '--evms lvm2/mycontainer'.  If you do not wish to
                use EVMS specify --dir or --lvm.  (These three options
                are mutually exclusive.)
   --hostname=host.example.org
                Set the hostname of the new guest system.  Ideally
                this will be fully-qualified since several of the hook
                scripts will expect to be able to parse a domain name
                out of it for various purposes.
   --lvm=vg     Specify the volume group to save images within.
                If you do not wish to use LVM specify --dir or --evms.
                (These three options are mutually exclusive.)
```

## NOTES

```
  This script is a wrapper around three distinct external tools which
 complete various aspects of the new system installation.
```

xt-install-image Install a new distribution.

xt-customize-image Run a collection of hook scripts to customise the freshly installed system.

xt-create-xen-config Create a Xen configuration file in so that xm/xl can start the new domain.

```
  The result of invoking these three scripts, and some minor glue between
 them, is a simple means of creating new Xen guest domains.
```

## DESCRIPTION

```
  xen-create-image is a simple script which allows you to create new
 Xen instances easily.  The new image will be given two volumes.  These
 volumes will be stored upon the host as either loopback files, or
 LVM logical volumes:
   1.  An image for the systems root disk.
   2.  An image for the systems swap device.
  The new virtual installations will be configured with networking,
 have OpenSSH installed upon it, and have most of its basic files
 setup correctly.
  If you wish you can configure arbitrary partitioning schemes, rather
 than being restricted to just the two standard volumes.  For more
 details on this please see the later section in this manual "PARTITIONING".
  If you wish to install additional packages or do any additional
 configuration of your new guests, please read the section on "ROLES".
```

## CONFIGURATION

```
  To reduce the length of the command line each of the supported options
 may be specified inside a configuration file.
  The global configuration file read for options is:
     /etc/xen-tools/xen-tools.conf
  The configuration file may contain comments which begin with the
 hash '#' character.  Otherwise the format is 'key = value'.
  A sample configuration file would look like this:
```

```
  #
  #  Output directory.  Images are stored beneath this directory, one
  # subdirectory per hostname.
  #
  dir = /home/xen
  #
  #  LVM users should disable the 'dir' setting above, and instead
  # specify the name of the volume group to use.
  #
  # lvm = myvolume
  #
  #  EVMS users should disable the dir setting above and instead specify
  # a container.  For example, if you have an lvm2 container named box,
  # put lvm2/box.  This is how it is named in the evms interface.
  #
  #  Warning... this has not been tested with anything but lvm2 but should
  # be generalizable.
  #
  # evms= lvm2/myvolume
  #
  #  Disk and Sizing options.
  #
  size       = 2Gb      # Disk image size.
  image      = full     # Allocate the full disk size immediately.
  memory     = 128Mb    # Memory size
  maxmem     = 512Mb    # Memory size
  swap       = 128Mb    # Swap size
  fs         = ext3     # use EXT3 filesystems
  dist       = stable   # Default distribution to install.
  #
  # Kernel options.
  #
  kernel      = /boot/vmlinuz-`uname -r`
  initrd      = /boot/initrd.img-`uname -r`
  #
  # Networking options.
  #
  gateway    = 192.168.1.1
  broadcast  = 192.168.1.255
  netmask    = 255.255.255.0
  #
  # Installation method:
  # One of "copy", "debootstrap", "cdebootstrap", "rinse", "rpmstrap", or "tar".
  #
  install-method = debootstrap
```

```
  Using this configuration file a new image may be created with the
 following command:
      xen-create-image --hostname=vm03.my.flat --ip=192.168.1.201
  This makes use of loopback images stored beneath /home/xen and
 will be installed via the debootstrap command.
```

## NETWORKING AUTO-SETUP

```
  We've already seen how the "gateway" and "netmask" options can
 be used to specify the networking options of the freshly created
 Xen guests.
  One other useful shortcut is the use of an automatic IP address.
 You can specify '--ip=auto' and the system will choose and use
 an IP address from those listed in /etc/xen-tools/ips.txt.
  For example if you wished to have Xen guests automatically
 take an address from the range 192.168.1.100-192.168.1.200 you
 would first prepare the system by running this:
```

```
  rm /etc/xen-tools/ips.txt
  for i in $(seq 100 200) ; do echo 192.168.1.$i >> /etc/xen-tools/ips.txt ; done
```

```
  Now you can create a guest with the command:
```

```
  xen-create-image --ip=auto --hostname=blah [--dist=...]
```

```
  The first time this ran the machine would receive an IP address
 from the pool which we've created.  This IP would be marked as used,
 and would no longer be available.  If all the IP addresses are taken
 then the system will fail.
```

## PARTITIONING

```
  By default all new guests are created with two "volumes", one
 for the root filesystem and one for the new system's swap.
  If you wish you may specify an alternative partitioning scheme.
 Simply create a file inside the directory /etc/xen-tools/partitions.d/
 specifying your partition layout.  (Use the existing file "sample-server"
 as a template).
  Now when you create a new image specify the name of this file with as
 an argument to the --partition option.
```

## XEN CONFIGURATION FILE

```
  Once a new image has been created an appropriate configuration file
 for Xen will be saved in the directory /etc/xen by default.  However
 you may change the output directory with the --output flag.
  The configuration file is built up using the template file
 /etc/xen-tools/xm.tmpl - which is a file processed via
 the Text::Template perl module.
  If you wish to modify the files which are generated please make your
 changes to that input file.
  Alternatively you can create multiple configuration files and
 specify the one to use with the --template option.
```

## LOOPBACK EXAMPLES

```
  The following will create a 2Gb disk image, along with a 128Mb
 swap file with Debian Stable setup and running via DHCP.
     xen-create-image --size=2Gb --swap=128Mb --dhcp --dist=stable \
          --dir=/home/xen --hostname=vm01.my.flat
  This next example sets up a host which has the name 'vm02.my.flat' and
 IP address 192.168.1.200, with the gateway address of 192.168.1.1
     xen-create-image --size=2Gb --swap=128Mb \
          --ip=192.168.1.200 \
          --netmask=255.255.255.0
          --gateway=192.168.1.1 \
          --nameserver=192.168.1.1 \
          --dir=/home/xen --hostname=vm02.my.flat
  The directory specified for the output will be used to store the volumes
 which are produced.  To avoid clutter each host will have its images
 stored beneath the specified directory, named after the hostname.
  For example the images created above will be stored as:
   $dir/domains/vm01.my.flat/
   $dir/domains/vm01.my.flat/disk.img
   $dir/domains/vm01.my.flat/swap.img
   $dir/domains/vm02.my.flat/
   $dir/domains/vm02.my.flat/disk.img
   $dir/domains/vm02.my.flat/swap.img
  The '/domains/' subdirectory will be created if necessary.
```

## LVM EXAMPLE

```
  If you wish to use an LVM volume group instead of a pair of loopback
 images as shown above you can instead use the --lvm argument to
 specify one.
     xen-create-image --size=2Gb --swap=128Mb --dhcp \
          --lvm=myvolumegroup --hostname=vm01.my.flat
  The given volume group will have two new logical volumes created within it:
   ${hostname}-swap
   ${hostname}-disk
  The disk image may be mounted, as you would expect, with the following
 command:
    mkdir -p /mnt/foo
    mount /dev/myvolumegroup/vm01.my.flat-disk /mnt/foo
```

## EVMS EXAMPLE

```
  If you wish to use an EVMS storage container instead of a pair of loopback
 images as shown above you can instead use the --evms argument to
 specify one.  The below example assumes an lvm2 container.
     xen-create-image --size=2Gb --swap=128Mb --dhcp \
          --evms=lvm2/myvolumegroup --hostname=vm01.my.flat
  The given storage container will have two new EVMS volumes created within it:
   ${hostname}-swap
   ${hostname}-disk
  The disk image may be mounted, as you would expect, with the following
 command:
    mkdir -p /mnt/foo
    mount /dev/evms/vm01.my.flat-disk /mnt/foo
```

## INSTALLATION METHODS

```
  The new guest images may be installed in several different ways:
  1.  Using the [c]debootstrap command, which must be installed and present.
  2.  Using the rpmstrap command, which must be installed and present.
  3.  using the rinse command, which must be installed and present.
  4.  By copying an existing installation.
  5.  By untarring a file containing a previous installation.
  These different methods can be selected by either the command line
 arguments, or settings in the configuration file.  Only one installation
 method may be specified at a time; they are mutually-exclusive.
```

## INSTALLATION SPEEDUPS

```
  After performing your first installation you can customize it, or
 use it untouched, as a new installation source.  By doing this you'll
 achieve a significant speedup, even above using the debootstrap caching
 support.
  There are two different ways you can use the initial image as source
 for a new image:
  1.  By tarring it up and using the tar-file as an installation source.
  2.  By mounting the disk image of the first system and doing a literal copy.
  Tarring up a pristine, or customised, image will allow you to install
 with a command such as:
     xen-create-image --size=2Gb --swap=128Mb --dhcp \
          --lvm=myvolumegroup --hostname=vm01.my.flat \
          --install-method=tar --install-source=/path/to/tar.file.tar
  The advantage of the tarfile approach is that you'll not need to
 keep a disk image mounted if you were to use the --copy argument
 to create a new image using the old one as source:
     xen-create-image --size=2Gb --swap=128Mb --dhcp \
          --lvm=myvolumegroup --hostname=vm01.my.flat \
          --install-method=copy --install-source=/path/to/copy/from
```

## DEBOOTSTRAP CACHING

```
  When installing new systems with the debootstrap tool there is
 a fair amount of network overhead.
  To minimize this the .deb files which are downloaded into the
 new instance are cached by default upon the host, in the directory
 /var/cache/apt/archives or, if this does not exist, in
 /var/cache/xen-tools/archives. This can be overridden with the
 --cache-dir command-line and configuration option.
  This feature can be disabled with the command line flag --cache=no,
 or by the matching setting in the configuration file.
  When a new image is created these packages are copied into the new
 image - before the debootstrap process runs - this should help avoid
 expensive network reading.
  If you wish to clean the host's apt cache (/var/cache/apt/archivees)
 you may do so with apt-get, namely:
  apt-get clean
  If you set your cache directory to anything else, simply rm the
 contents of the directory.
```

## ROLES

```
  Currently there are some roles scripts included which work for
 the Debian and Ubuntu distrubtions only. They are included
 primarily as examples of the kind of things you could accomplish.
  The supplied scripts are:
```

builder Setup the new virtual images with commonly used packages for rebuilding Debian packages from their source.

cfengine Install cfengine2 on the virtual image and copy the cfengine configuration from Dom0.

editor Allows generalised editing of files for guests.

This script works via a skeleton directory containing small sed files which will contain edits to be applied to an arbitrary tree of files upon the new domU. For example if we have the following sed file:

```
  /etc/xen-tools/sed.d/etc/ssh/sshd_config.sed

```

this will be applied to /etc/ssh/sshd_config upon the new guest *if* it exists. If the file encoded in the name doesn't exist then it will be ignored.

gdm Install an X11 server, using VNC and GDM

minimal Customise the generated images to remove some packages.

puppet Install puppet on the virtual image and copy the cfengine configuration from Dom0.

tmpfs Sets up /tmp, /var/run and /var/lock as tmpfs in the DomU.

udev Install udev in the DomU. Most distributions install udev by default nowadays, so this role is probably only interesting for legacy systems which need udev anyway.

xdm Install an X11 server, using VNC and XDM

```
  If you'd like to include your own role scripts you'll need to
 create a file in /etc/xen-tools/role.d, and then specify the
 name of that file with "--role=filename".  Additionally you
 may pass options to your role-script with the --role-args
 flag.
  For example the script /etc/xen-tools/role.d/gdm would be used
 by executing with "--role=gdm".
  Role scripts are invoked with the directory containing the
 installed system as their first argument, and anything passed
 as a role-arg will be passed allong as additional arguments.
  NOTE: Role scripts are invoked before the config file generation.
        If you need access to the config file from within your role,
        use --finalrole.
  NOTE: Multiple role scripts may be invoked if you separate their
 names with commas.
```

## THE SKELETON DIRECTORY

```
  Any files present in the directory /etc/xen-tools/skel will be copied
 across to each new guest image.  The role of this directory is analogous
 to the /etc/skel directory.
  A typical use for this would be to copy a public key across to each
 new system.  You could do this by running:
```

```
    mkdir -p /etc/xen-tools/skel/root/.ssh
    chmod -R 700 /etc/xen-tools/skel/root
    cp /root/.ssh/id_rsa.pub /etc/xen-tools/skel/root/.ssh/authorized_keys2
    chmod 644 /etc/xen-tools/skel/root/.ssh/authorized_keys2
```

## AUTHORS

```
 Steve Kemp, http://www.steve.org.uk/
 Axel Beckert, http://noone.org/abe/
 Dmitry Nedospasov, http://nedos.net/
 Stephane Jourdois
```

## LICENSE
Copyright (c) 2005-2009 by Steve Kemp, (c) 2010-2013 by The Xen-Tools Development Team. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.


xen-create-nfs

title: xen-create-nfs(8)

summary: Create a Xen configuration file for an NFS\-root guest.

text:
# xen-create-nfs(8)

## NAME
xen-create-nfs - Create a Xen configuration file for an NFS-root guest.

## SYNOPSIS

```
  xen-create-nfs [options]
  Help Options:
   --help     Show help information.
   --manual   Read the manual for this script.
   --version  Show the version information and exit.
   --verbose  Show diagnostic output.
  Networking Options:
   --broadcast  The broadcast address to use when configured with a static IP.
   --dhcp       Configure the guest to use DHCP for IP allocation.
   --gateway    The gateway address to use when configured with a static IP.
   --hostname   The hostname to configure for the guest.
   --ip         The IP address to use when configured with a static IP.
   --netmask    The netmask to use when configured with a static IP.
   --nameserver The nameserver to use when configured with a static IP.
  General options:
   --admins     Specify which users should be setup as xen-shell admins.
   --force      Force the overwriting of an existing configuration file.
   --initrd     Specify the initial ramdisk for the guest.
   --kernel     Specify the kernel to use for the guest.
   --memory     Specify the memory to allocate for this guest.
   --mac        Specify the MAC address to use for the guest.
   --template   Specify an alternative template file to use.
  NFS options:
   --nfs_server Specify the NFS server to mount the root partition from.
   --nfs_root   Specify the path, upon the NFS server, to mount.
```

## OPTIONS
--help Show help information.

--hostname Specify the hostname to delete.

--manual Read the manual for this script.

--version Show the version number and exit.

## DESCRIPTION

```
  xen-create-nfs is a simple script which allows you to easily create
 a single configuration file for a Xen guest which will mount its remote
 filesystem over an NFS root.
  It doesn't create any images to use for local storage, and it doesn't
 support more than the minimal number of options to completement the
 existing xen-create-image script, however it is hopefully useful.
```

## REFERENCE

```
  For more details on what you'll need to support NFS-root Xen guests
 the following article, written by the author, might be useful:
    http://www.debian-administration.org/articles/505
```

## AUTHORS

```
 Steve Kemp, http://www.steve.org.uk/
 Stephane Jourdois
```

## LICENSE
Copyright (c) 2005-2009 by Steve Kemp, (c) 2010 by The Xen-Tools Development Team. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.


xen-delete-image

title: xen-delete-image(8)

text:
# xen-delete-image(8)

## NAME
xen-delete-image - Delete previously created Xen instances.

## SYNOPSIS

```
  xen-delete-image [options] [--hostname=]imageName1 [--hostname=]imageName2
  Filename Options:
   --extension  Specify the file extension to use. An empty extension is equal
                to any extension.
  Help Options:
   --help     Show help information.
   --manual   Read the manual for this script.
   --version  Show the version information and exit.
   --verbose  Show diagnostic output.
  General options:
   --dir      Specify the output directory where images were previously saved.
   --evms     Specify the EVMS container to use.
   --lvm      Specify the LVM volume to use.
  Specifying hosts:
   --hostname Specify the image name to delete.
  Testing options:
   --test      Don't complain if we're not invoked by root.
```

## OPTIONS
--dir Specify the output directory where images were previously saved.

--evms Specify the EVMS container where images were previously saved.

--help Show help information.

--hostname Specify the hostname to delete.

--lvm Specify the LVM volume group where images were previously saved.

--manual Read the manual for this script.

--test Do not complain, or exit, if the script is not executed by the root user. (Only works in conjunction with --dir.)

--version Show the version number and exit.

## DESCRIPTION

```
  xen-delete-image is a simple script which allows you to delete
 Xen instances which have previously been created by xen-create-image.
  You must be root to run this script as it removes the Xen configuration
 file from /etc/xen and potentially removes LVM and EVMS volumes.
  (When invoked with the '--test' flag the script will continue running,
 but will fail to remove anything which the user does not have permission
 to delete.)
```

## LOOPBACK EXAMPLE

```
  Assuming that you have three images 'foo', 'bar', and 'baz', stored
 beneath /home/xen the first two may be deleted via:
    xen-delete-image --dir=/home/xen foo bar
  You may also delete them by running:
    xen-delete-image --dir=/home/xen --hostname=foo --hostname=bar
  (The matching Xen configuration files beneath /etc/xen will also be
 removed.)
```

## LVM EXAMPLE

```
  Assuming that you have the volume group 'skx-vol' containing three
 Xen instances 'foo', 'bar', and 'baz' the first two may be deleted via:
    xen-delete-image --lvm=skx-vol foo bar
  This will remove the volumes 'foo-disk', 'foo-swap', 'bar-disk',
 and 'bar-swap'.
  Note that if the images were created with "--noswap" then the swap
 volumes will not be present, so will not need to be deleted.
  The Xen configuration files will also be removed from beneath /etc/xen.
```

## EVMS EXAMPLE

```
  Assuming that you have the container 'mycontainer' containing three
 Xen instances 'foo', 'bar', and 'baz' the first two may be deleted via:
    xen-delete-image --evms=lvm2/mycontainer --hostname=foo --hostname=bar
  This will remove the volumes 'foo-disk', 'foo-swap', 'bar-disk',
 and 'bar-swap'.
  Note that if the images were created with "--noswap" then the swap
 volumes will not be present, so will not need to be deleted.
  The Xen configuration files will also be removed.
```

## AUTHORS

```
 Steve Kemp, http://www.steve.org.uk/
 Axel Beckert, http://noone.org/abe/
 Stephane Jourdois
```

## LICENSE
Copyright (c) 2005-2009 by Steve Kemp, (c) 2010-2013 by The Xen-Tools Development Team. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.


xen-list-images

title: xen-list-images(8)

text:
# xen-list-images(8)

## NAME
xen-list-images - List all the created and configured Xen images.

## SYNOPSIS

```
  xen-list-image [options]
  Filename Options:
   --extension  Specify the file extension to use. An empty extension is equal
                to any extension.
  Help Options:
   --help     Show this scripts help information.
   --manual   Read this scripts manual.
   --version  Show the version number and exit.
  Testing options:
   --test     Specify an alternate Xen configuration directory.
```

## OPTIONS
--help Show the scripts help information.

--manual Read the manual.

--test This flag causes the script to load the Xen configuration files from a different directory than the default of /etc/xen.

--version Show the version number and exit.

## DESCRIPTION

```
  xen-list-images is a simple script which will display all the
 Xen images which have been created.
  This works by iterating over all files matching the pattern
 /etc/xen/*.cfg which is what the xen-create-image script would
 create.
  For each instance which has been created we'll display the name,
 and then either the IP address configured, or "DHCP" to denote
 a dynamic host.
```

## TODO

```
  It should be possible to determine the disk(s) used by the images,
 and then display their sizes.
```

## AUTHORS

```
 Steve Kemp, http://www.steve.org.uk/
 Stephane Jourdois
```

## LICENSE
Copyright (c) 2005-2009 by Steve Kemp, (c) 2010-2013 by The Xen-Tools Development Team. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.


xen-resize-guest

title: xen-resize-guest(8)

text:
# xen-resize-guest(8)

## NAME
xen-resize-guest - Resize a loopback or LVM based xen guest.

## SYNOPSIS

```
  xen-resize-guest [options]
  Help Options:
   --help     Show help information.
   --manual   Read the manual for this script.
   --version  Show the version information and exit.
   --verbose  Show diagnostic output.
  General Options:
   --add      Specify the amount of space to add, e.g. --add=1gb
   --dir      Specify the path to the loopback image root.
   --force    Force the resize to happen without a last-chance delay.
   --hostname Specify the hostname of the guest to resize.
```

## OPTIONS
--add Specify the amount of storage to add to the primary disk.

--dir Specify the directory where the loopback files are based.

--force Don't pause for 10 seconds prior to commencing.

--help Show help information.

--hostname Specify the hostname to delete.

--lvm Specify the volume group to use.

--manual Read the manual for this script.

--version Show the version number and exit.

## DESCRIPTION

```
  This tool will ease the resizing of Xen guests, whether they are based
 upon loopback files or LVM partitions.
  Whilst the process of resizing a guest is pretty simple it can be fiddly
 to do the steps correctly in the right order:
```

1. Shutdown the guest. 2. Unmount the volume, if it is mounted. 3. Add to the space. 4. Check the filesystem. 5. Resize the filesystem. 6. Restart the guest.

```
  More than once I've heard of users making mistakes and breaking their
 filesystems; hence this tool.
```

## AUTHORS

```
 Steve Kemp, http://www.steve.org.uk/
 Axel Beckert, http://noone.org/abe/
```

## LICENSE
Copyright (c) 2005-2009 by Steve Kemp, (c) 2010 by The Xen-Tools Development Team. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.


xen-update-image

title: xen-update-image(8)

text:
# xen-update-image(8)

## NAME
xen-update-image - Update the software installed upon offline Xen images.

## SYNOPSIS

```
  xen-update-image [options] imageName1 imageName2 .. imageNameN
  Help Options:
   --help      Show this scripts help information.
   --manual    Read this scripts manual.
   --version   Show the version number and exit.
  General Options:
   --dir       Specify the directory which contains the image(s).
   --lvm       Specify the LVM volume group which contains the image(s).
   --evms      Specify the EVMS container which contains the image(s).
```

## OPTIONS
--dir Specify the directory which contains the image(s).

--evms Specify the EVMS container which contains the image(s).

--help Show the script help.

--lvm Specify the LVM volume group which contains the image(s).

--manual Read the manual.

--version Show the version number and exit.

## DESCRIPTION

```
  xen-update-image is a simple script which allows you to update
 a Xen image of Debian which has been created with xen-create-image.
  It does this by mounting the image inside a temporary directory
 then running:
      apt-get update
      apt-get upgrade
  NOTE If the image is already running within Xen this will cause
 corruption otherwise it will allow you to update your image without
 booting it.
```

## EXAMPLES

```
  The following assumes there are two images which are not currently
 running.  The images are called 'test.my.flat', and 'x11.my.flat'.
  Updating both images can be accomplished by executing:
     xen-update-images --dir=/home/xen test.my.flat x11.my.flat
```

## AUTHORS

```
 Steve Kemp, http://www.steve.org.uk/
 Axel Beckert, http://noone.org/abe/
 Stephane Jourdois
```

## LICENSE
Copyright (c) 2005-2009 by Steve Kemp, (c) 2010 by The Xen-Tools Development Team. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.


xt-create-xen-config

title: xt-create-xen-config(8)

text:
# xt-create-xen-config(8)

## NAME
xt-create-config - Create a Xen configuration file for a new guest

## SYNOPSIS

```
  xt-create-config [options]
  Filename Options:
    --output     Specify the output directory to use.
    --extension  Specify the file extension to use.
  General Options:
    --admins     Specify some administrator accounts which should be
                created for use by the xen-shell.
    --template   Specify the template file to use when creating the
                Xen configuration file.
  Help Options:
   --help        Show this scripts help information.
   --manual      Read this scripts manual.
   --version     Show the version number and exit.
  Debugging Options:
   --verbose  Be verbose in our execution.
  All other options from xen-create-image, such as the new IP address(es)
 to give to the new instance, will be passed as environmental variables.
```

## ABOUT

```
  This script is invoked by xen-create-image after it has created and
 customised a new Xen guest.  It is responsible for creating the
 configuration file which Xen will use to start the instance.
  The configuration file will be created in the directory /etc/xen using
 a template file to determine how the configuration file should be
 created.
  By default the script will use /etc/xen-tools/xm.tmpl as its input.
```

## INVOCATION

```
  This script will be invoked by the xen-create-image script, rather than
 directly.
  This is because it will expect to receive the values to insert into the
 output template in as environmental variables.
  You could execute it manually via a long command line, but that is
 error-prone and probably not useful:
```

```
   hostname=foo.my.flat ip=192.168.1.2 ... xm-create-xen-config \
     --output=/etc/xen --template=/etc/xen-tools/xm.tmpl
```

## ARGUMENT PASSING

```
  This script will be invoked with a full copy of the arguments from
 xen-create-image in its environment, along with several command line
 arguments.
  This has several implications for customization.  If you wish to
 setup a new variable in the output template such as "foo=bar" you
 could update the script to include "${foo}", then invoke
 xen-create-image with this environmental variable set.
```

```
     $ foo=bar xen-create-image --hostname=test.my.flat ...
```

```
  The environment will be duplicated/inheritted by this script when
 it is executed, and your variable will be included in the output file.
  For details on the template file syntax please see the documentation
 for the "Text::Template" perl module.   (If you have the perldoc
 package installed you can read this with "perldoc Text::Template".)
```

## AUTHORS

```
 Steve Kemp, http://www.steve.org.uk/
 Axel Beckert, http://noone.org/abe/
 Stephane Jourdois
```

## LICENSE
Copyright (c) 2005-2009 by Steve Kemp, (c) 2010-2012 by The Xen-Tools Development Team. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.


xt-customize-image

title: xt-customize-image(8)

text:
# xt-customize-image(8)

## NAME
xt-customize-image - Customize a freshly installed copy of GNU/Linux

## SYNOPSIS

```
  xt-customize-image [options]
  Help Options:
   --help     Show this scripts help information.
   --manual   Read this scripts manual.
   --version  Show the version number and exit.
  Debugging Options:
   --verbose  Be verbose in our execution.
  Mandatory Options:
   --location The location of the new installation
   --dist     The name of the distribution which has been installed.
  All other options from xen-create-image, such as the new IP address(es)
 to give to the new instance, will be passed as environmental variables.
```

## NOTES

```
  This script is invoked by xen-create-image after it has created a
 fresh installation of Linux withing a temporary location.
  This script will be invoked with a full copy of the arguments from
 xen-create-image in its environment, along with several command line
 arguments.
  The command line arguments which are mandatory are:
   --location  - The temporary installation root of the new install
   --dist      - The distribution which has been installed.
```

## HOOK SCRIPTS

```
  The distribution name is used to locate an appropriate collection
 of scripts, or hooks, to execute to do the actual customisation.
  The hooks will each be executed with a single parameter which is
 the directory path to the new instance.  This argument is taken from
 the --location option.
  For the distribution named 'foo' the scripts will be loaded and
 executed from '/usr/share/xen-tools/foo.d'.  Each executable will
 be loaded and executed in sorted order.
  The systems administrator can optionally provide site-specific
 revisions of those same hooks by placing them in the directory
 '/etc/xen-tools/hooks.d/' in which case a script with the same name
 as the one in the 'foo.d' directory above will take precedence. In
 this way certain hooks can be prevented from running, expanded with
 site-specific features which won't get overwritten on upgrades, or
 patched with critical bug-fixes before the upstream OS distribution
 provider reacts.
```

## AUTHORS

```
 Steve Kemp, http://www.steve.org.uk/
 Axel Beckert, http://noone.org/abe/
 Stephane Jourdois
```

## LICENSE
Copyright (c) 2005-2009 by Steve Kemp, (c) 2010 by The Xen-Tools Development Team. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.


xt-guess-suite-and-mirror

title: xt-guess-suite-and-mirror(8)

text:
# xt-guess-suite-and-mirror(8)

## NAME
xt-guess-suite-and-mirror - Tries to guess the most suitable suite and mirror for DomUs on Debian and Ubuntu Dom0s.

## SYNOPSIS

```
  --suite       Show suite
  --mirror      Show mirror
  Shows both if no parameter is given.
  Help Options:
   --help       Show the help information for this script.
   --manual     Show the manual for this script.
   --version    Show the version number and exit.
```

## DESCRIPTION
xt-guess-suite-and-mirror tries to find the mirror and suite the Xen Dom0 is currently using and returns them in a way suitable for xen-create-image(1) or the backticks feature in xen-tools.conf.

## AUTHORS

```
 Axel Beckert, http://noone.org/abe/
 Stephane Jourdois
```

## LICENSE
Copyright (C) 2010-2012 by The Xen-Tools Development Team. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.


xt-install-image

title: xt-install-image(8)

text:
# xt-install-image(8)

## NAME
xt-install-image - Install a fresh copy of GNU/Linux into a directory

## SYNOPSIS

```
  xt-install-image [options]
  Help Options:
   --help           Show this scripts help information.
   --manual         Read this scripts manual.
   --version        Show the version number and exit.
  Debugging Options:
   --verbose        Be verbose in our execution.
  Mandatory Options:
   --location       The location to use for the new installation
   --dist           The name of the distribution which has been installed.
  Misc Options:
   --arch           Pass the given arch setting to debootstrap or rpmstrap.
   --config         Read the specified config file in addition to the global
                    configuration file.
   --mirror         The mirror to use when installing with 'debootstrap'.
   --apt_proxy      The proxy to use when installing with 'debootstrap'.
  Installation Options:
   --install-method  Specify the installation method to use.
   --install-source  Specify the installation source to use.
   --debootstrap-cmd Specify which debootstrap command to
                     use. Defaults to debootstrap if both, debootstrap
                     and cdebootstrap are installed.
  All other options from xen-create-image will be passed as environmental
 variables.
```

## NOTES

```
  This script is invoked by xen-create-image after to create a new
 distribution of Linux.  Once the script has been created the companion
 script xt-customize-image will be invoked to perform the network
 configuration, etc.
```

## INSTALLATION METHODS

```
  There are several available methods of installation, depending upon the
 users choice.  Only one option may be chosen at any given time.
  The methods available are:
```

debootstrap Install the distribution specified by the --dist argument using the debootstrap. If you use this option you must specify a mirror with --mirror.

copy Copy the given directory recursively. This local directory is assumed to contain a complete installation. Specify the directory to copy with the --install-source argument.

rinse Install the distribution specified by --dist using the rinse command.

rpmstrap Install the distribution specified by --dist using the rpmstrap command.

tar Untar a .tar file into the new installation location. This tarfile is assumed to contain a complete archived system. Specify the directory to copy with the --install-source argument.

## AUTHORS

```
 Steve Kemp, http://www.steve.org.uk/
 Axel Beckert, http://noone.org/abe/
 Dmitry Nedospasov, http://nedos.net/
 Stephane Jourdois
```

## LICENSE
Copyright (c) 2005-2009 by Steve Kemp, (c) 2010 by The Xen-Tools Development Team. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.