NAME

appjail-network — Create, remove or manage virtual networks for jails

SYNOPSIS

DESCRIPTION

The appjail network utility creates, removes, and manages virtual networks and bridges. A virtual network consists of one configured if_bridge(4) interface and zero or more if_epair(4) interfaces.

Virtual networks are an essential part of AppJail since with them we can use features such as port forwarding and NAT. Furthermore, this represents a better organization of our jails without the need for a DHCP server.

The options are as follows:

add [-O] [-d description] [-m mtu] name address/cidr

Create a new network called name.

address must be a valid IPv4 address and cidr must be a non-negative number between 0 and 30.

-O

By default, an overlay test is performed to check if the network to be created overlaps an existing network. This test may be a bit slow if you have many networks but it avoids some problems.

-d description

A brief description about the network.

-m mtu

Network MTU. A valid MTU is a non-negative number between 576 and 65535. If a network does not have an MTU defined, it uses what is specified by the DEFAULT_VIRTUALNET_MTU parameter.

assign -e interface -j jail -n network [-d] [-a [auto|forceauto|address]]

Assign a non-reserved IPv4 address from network to the if_epair(4) interface inside jail.

If -d is specified, network will be set as the default route. No checking is done if a default route already exists.

See reserve to learn how the IPv4 address is reserved.

attach [-b bridge] [epair|iface:]interface ...

Attach interface to bridge.

If bridge does not exist, it is created. The default bridge is the one specified by the SHARED_BRIDGE parameter.

If an interface type of epair (default when none is specified) is specified, an if_epair(4) interface is created if it does not exist and if the interface type is iface, an existing interface is attached to the bridge. Remember that all interfaces on a bridge must have the same MTU. The first MTU interface is used, so first specify an iface interface type before an epair interface type. In the case where an interface of type epair is specified first, the MTU specified by the DEFAULT_MTU parameter is used, but note that this may not make sense if an interface of type iface is specified with a different MTU.

For an interface of type epair, two interfaces are created since that is how if_epair(4) works, but the interfaces will be called sa_interface and sb_interface, where the first is for the host and the second for the jail.

auto-create

Call the add subcommand with the parameters AUTO_NETWORK_ADDR, AUTO_NETWORK_NAME, and AUTO_NETWORK_DESC to create a new network. This is the preferred method for creating a network implicitly as it is more portable and simpler. It is mainly used by appjail-quick(1).

detach [-Ddfi] [-b bridge] [epair|iface:]interface ...

Detach or destroy interface from bridge.

-D

Destroy bridge after detaching or destroying the interfaces.

-d

Destroy interfaces instead of simply removing them from the bridge.

To destroy an interface, it must belong to the epair group; otherwise it is silently ignored. This group is added automatically using the attach subcommand.

-f

If the interface is to be removed as a member of the bridge but does not belong to it, an error may occur. This flag forces this behavior.

-i

Removes or destroys the interface even if it is not a member of the bridge.

fix [all|dup|addr] [-n network]

Fixes some problems that may occur when using virtual networks.

Problems commonly occur because appjail-jail(1) is used to import a jail with non-portable parameters, such as an IPv4 address that does not belong to any existing virtual network or even the IPv4 may be duplicated. These “problems” may not be problems at all, as they may occur due to a backup when you need to duplicate all settings from another system. It is preferable to use appjail-quick(1) to import a jail as it forcibly reserves an IPv4 address but only when using a virtual network, but when you need to export/import a jail in a portable way use appjail-image(1) instead.

If -n is specified, this subcommand operates on the specified network; otherwise, it operates on all networks.

get [-eHIpt] network [keyword ...]

Get information about a network, that is, the keyword that represent the information to be obtained. Multiple keywords can be specified, which are displayed as a table-like interface in the order in which they are specified. If no keyword is specified, the defaults are name, network, cidr, broadcast, gateway, minaddr, maxaddr, addresses, description and mtu.

See KEYWORDS for a list of available keywords.

-e

Not required when using -p. The \t character is used to delimit columns, so as not to show strange values, this option shows <TAB> instead of \t in the case that a value contains the latter.

-H

Shows the name of the columns.

-I

Include empty values. By default, a minus sign is displayed when a value is empty.

-p

Columnate the list.

-t

Tabulate columns and values.

hosts -a -n network

List available IPv4 addresses in network.

hosts -d -n network

List the IPv4 addresses that are duplicated in network.

hosts -e -j jail

List the networks to which jail belongs.

hosts -l -n network

List all IPv4 addresses in network.

hosts -R -j jail [-E] [-n network]

List assigned IPv4 addresses for jail. If -E is specified, the network to which the IPv4 addresses belong is displayed.

Specify -e to display only IPv4 addresses assigned solely for this network.

hosts -r -n network [-H|-N] [-s]

List assigned IPv4 addresses in network.

If -N is specified, the jail name is displayed after its IPv4 address. The network is shown as Default gateway and the broadcast as Broadcast.

Shows the jail's hostname. If -H is specified only once and if the jail does not have a hostname defined in its template, the jail name plus the value specified by the HOST_DOMAIN parameter is displayed as the hostname. If -H is specified twice, the jail name plus the network name plus the value specified by the HOST_DOMAIN parameter is displayed as the hostname, and if -s or SHORTEN_DOMAIN_NAMES is enabled, the jail name is used as secondary hostname for the network specified by the NETWORK_TO_SHORTEN parameter.

An additional hostname will be added if the current jail has the appjail.dns.alt-name label. This is useful especially when a third-party tool creates a random name but you want to use a human-readable hostname.

list [-eHIpt] [-n network] [keyword ...]

Similar to get but shows each keyword for each network in a nice table.

-e, -H, -I, -p, -t

All of these options perform the opposite task of the options described in get.

-n network

Only show information for network.

plug -e interface -n network [-d description]

Create a new if_epair(4) interface and an if_bridge(4) interface if it does not exist. The if_epair(4) interface is added as a member of the bridge.

This subcommand assumes that if the bridge is not in the appjail_bridge group, the bridge is not configured correctly, so it proceeds to configure the parameters specified by the add subcommand.

The interfaces ea_interface and eb_interface represent the cloned if_epair(4), the first being for the host and the second for the jail. After the interfaces are created, the MTU is configured as set by the add subcommand. The appjail_epair group is added to ea_interface. If -d is specified, a description is added to ea_interface. And finally, ea_interface is added to the bridge.

remove [-df] network

Destroy a bridge. To destroy a bridge, it must be in the appjail_bridge group and must have no members unless -f is specified.

If -d is specified, the network is also destroyed, so you can create it again using the add subcommand.

reserve -j jail -n network [-a [auto|forceauto|address]]

Reserve an IPv4 address for jail from network.

If -a is set to auto or forceauto, an IPv4 address is automatically assigned from the network address pool. The difference between auto and forceauto is that the former does not assign an IPv4 address if the jail has one, the exception is when the IPv4 is invalid depending on the network configuration, and the latter is that the IPv4 address is forcibly assigned, that is, the IPv4 address is assigned even if the jail has one.

An IPv4 address can be specified. To be considered valid, it must be a valid IPv4 address and have a correct range depending on the network address and CIDR. The IPv4 address must not also be reserved by another host.

unplug network interface

Destroy ea_interface. To destroy the interface, it must be a member of the bridge network, must exist, and be in the appjail_epair group.

KEYWORDS

address

Address used when add was executed.

addresses

Total number of hosts.

broadcast

Broadcast address.

cidr

Network prefix.

description

Network description.

gateway

Default gateway.

maxaddr

Last host of the network.

minaddr

First host of the network.

name

Network name.

netmask

Network mask of the network.

network

Network address.

wildcard

Network mask with its bits inverted.

EXIT STATUS

The appjail network utility exits 0 on success, and >0 if an error occurs.

SEE ALSO

appjail-expose(1) appjail-jail(1) appjail-nat(1) appjail-quick(1) sysexits(3) if_epair(4) if_bridge(4)

AUTHORS

Jesús Daniel Colmenares Oviedo <DtxdF@disroot.org>