How to configure network forwards

Note

Network forwards are available for the OVN network and the Bridge network.

▶ Watch on YouTube

Network forwards allow an external IP address (or specific ports on it) to be forwarded to an internal IP address (or specific ports on it) in the network that the forward belongs to.

This feature can be useful if you have limited external IP addresses and want to share a single external address between multiple instances. There are two different ways how you can use network forwards in this case:

  • Forward all traffic from the external address to the internal address of one instance. This method makes it easy to move the traffic destined for the external address to another instance by simply reconfiguring the network forward.

  • Forward traffic from different port numbers of the external address to different instances (and optionally different ports on those instances). This method allows to “share” your external IP address and expose more than one instance at a time.

Tip

Network forwards are very similar to using a proxy device in NAT mode.

The difference is that network forwards are applied on a network level, while a proxy device is added for an instance. In addition, proxy devices can be used to proxy traffic between different connection types (for example, TCP and Unix sockets).

View network forwards

View a list of forwards configured on a network:

lxc network forward list <network_name>

Example:

lxc network forward list lxdbr0

View a network forward

View information about a specific network forward:

lxc network forward show <network_name> <listen_address>

Example:

lxc network forward list lxdbr0 192.0.2.1

Create a network forward

Requirements for listen addresses

Before you can create a network forward, you must understand the requirements for listen addresses.

For both OVN and bridge networks, the listen addresses must not overlap with any subnet in use by other networks on the host. Otherwise, the listen address requirements differ by network type.

For an OVN network, the allowed listen addresses must be defined in at least one of the following configuration options, using CIDR notation:

Create a forward in an OVN network

Note

You must configure the allowed listen addresses before you can create a forward in an OVN network.

Use the following command to create a forward in an OVN network:

lxc network forward create <ovn_network_name> [<listen_address>|--allocate=ipv{4,6}] [target_address=<target_address>] [user.<key>=<value>]

  • For <ovn_network_name>, specify the name of the OVN network on which to create the forward.

  • Immediately following the network name, provide only one of the following for the listen address:

    • A listen IP address allowed by the Requirements for listen addresses (no port number)

    • The --allocate= flag with a value of either ipv4 or ipv6 for automatic allocation of an allowed IP address

  • Optionally provide a default target_address (no port number). Any traffic that does not match a port specification is forwarded to this address. This must be an IP range within the OVN network’s subnet.

  • Optionally provide custom user.* keys to be stored in the network forward’s configuration.

This example shows how to create a network forward on a network named ovn1 with an allocated listen address and no default target address:

lxd network forward create ovn1 --allocate=ipv4

This example shows how to create a network forward on a network named ovn1 with a specific listen address and a target address:

lxd network forward create ovn1 192.0.2.1 target_address=10.41.211.2

Note

The IP addresses shown in the example above are only examples. It is up to you to choose the allowed and available addresses on your setup.

Create a forward in a bridge network

Use the following command to create a forward in a bridge network:

lxc network forward create <bridge_network_name> <listen_address> [target_address=<target_address>] [user.<key>=<value>]

  • For <bridge_network_name>, specify the name of the bridge network on which to create the forward.

  • Immediately following the network name, provide a listen IP address allowed by the Requirements for listen addresses (no port number).

  • Optionally provide a default target_address (no port number). Any traffic that does not match a port specification is forwarded to this address. This must be an IP address within the bridge network’s subnet.

  • Optionally provide custom user.* keys to be stored in the network forward’s configuration.

  • You cannot use the --allocate flag with bridge networks.

This example shows how to create a network forward on a network named ovn1 with a specific listen address and a target address:

lxd network forward create bridge1 192.0.2.1 target_address=10.41.211.2

Note

The IP addresses shown in the example above are only examples. It is up to you to choose the allowed and available addresses on your setup.

Forward properties

Network forwards have the following properties:

config

User-provided free-form key/value pairs

Key: config
Type:

string set
Required:

no

The only supported keys are target_address and user.* custom keys.

description

Description of the network forward

Key: description
Type:

string
Required:

yes
listen_address

IP address to listen on

Key: listen_address
Type:

string
Required:

no
ports

List of port specifications

Key: ports
Type:

port list
Required:

no

See Configure ports.

Configure ports

Once a forward is created on a network (whether bridge or OVN), it can be configured with port specifications. These specifications allow forwarding traffic from ports on the listen address to ports on a target address. This target address must be within the network’s subnet, and it must be different from the network forward’s default target address.

Use the following command to add port specifications on a network forward:

lxc network forward port add <network_name> <listen_address> <protocol> <listen_ports> <target_address> [<target_ports>]

  • You can specify a single listen port or a set of ports.

  • Use either tcp or udp as the protocol.

  • Optionally specify a target port or ports. You can:

    • Specify a single target port to forward traffic from all listen ports to this target port.

    • Specify a set of target ports with the same number of ports as the listen ports to forward traffic from the first listen port to the first target port, the second listen port to the second target port, and so on.

This example shows how to configure a forward with a single listen port mapped to a single target port:

lxc network forward port add network1 192.0.2.1 tcp 22 10.41.211.2 22

This example shows how to configure a forward with a set of listen ports (including a range) mapped to a single target port:

lxc network forward port add network1 192.0.2.1 tcp 80,90-100 10.41.211.2 80

This example shows how to configure a forward with a set of listen ports mapped to a set of target ports:

lxc network forward port add network1 192.0.2.1 tcp 22,80 10.41.211.2 22,80

Port properties

Network forward ports have the following properties:

description

Description of the port or ports

Key: description
Type:

string
Required:

no
listen_port

Listen port or ports

Key: listen_port
Type:

string
Required:

yes

For example: 80,90-100

protocol

Protocol for the port or ports

Key: protocol
Type:

string
Required:

yes

Possible values are tcp and udp.

target_address

IP address to forward to

Key: target_address
Type:

string
Required:

yes
target_port

Target port or ports

Key: target_port
Type:

string
Default:

same as listen_port
Required:

no

For example: 70,80-90 or 90

Edit a network forward

Use the following command to edit a network forward:

lxc network forward edit <network_name> <listen_address>

This command opens the network forward in YAML format for editing. You can edit both the general configuration and the port specifications.

Delete a network forward

Use the following command to delete a network forward:

lxc network forward delete <network_name> <listen_address>