How to configure network forwards¶

Note

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

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).

Create a network forward¶

Use the following command to create a network forward:

lxc network forward create <network_name> [<listen_address>] [--allocate=ipv{4,6}] [configuration_options...]

Each forward is assigned to a network. Specify a single external listen address (see Requirements for listen addresses for more information about which addresses can be forwarded, depending on the network that you are using). If the network type supports IP allocation, you don’t need to specify a listen address. If you leave it out, you must provide the --allocate flag.

You can specify an optional default target address by adding the target_address=<IP_address> configuration option. If you do, any traffic that does not match a port specification is forwarded to this address. Note that this target address must be within the same subnet as the network that the forward is associated to.

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.

Requirements for listen addresses¶

The requirements for valid listen addresses vary depending on which network type the forward is associated to.

Bridge network

Any non-conflicting listen address is allowed.
The listen address must not overlap with a subnet that is in use with another network.
The --allocate flag is not supported.

OVN network

Allowed listen addresses must be defined in the uplink network’s ipv{n}.routes settings or the project’s restricted.networks.subnets setting (if set).
The listen address must not overlap with a subnet that is in use with another network.
The --allocate flag is supported. If used, the OVN network driver will allocate an IP address from the uplink network’s ipv{n}.routes or the project’s restricted.networks.subnets setting (if set).

Configure ports¶

You can add port specifications to the network forward to forward traffic from specific ports on the listen address to specific ports on the target address. This target address must be different from the default target address. It must be within the same subnet as the network that the forward is associated to.

Use the following command to add a port specification:

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. If you want to forward the traffic to different ports, you have two options:

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.

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>