Advanced networking with eryph

Documentation status

This part of the documentation is a work in progress.
A more detailed documentation of networking features will be added soon.

Using overlay networks with eryph-zero

Eryph-zero uses NAT overlay by default, so there is no need to configure networking initially. However, if you are using eryph-zero for shared access or want to access catlets from other network clients, you will need to configure an overlay network.

Get IT's approval

Before adding an eryph overlay network to your corporate network, check with your IT department for approval and IP ranges to use.
Most network administrators are not amused when someone adds network services that may cause IP address conflicts.

Identify the network layout

To create an overlay network, you will need the following information about the network

Network subnet and mask (must be in CIDR notation)
Gateway address
VLAN ID if VLAN is to be used
unused IP address range(s)

In addition, you must decide how to connect the eryph-zero host to the network. The best practice is to use a dedicated network interface. However, if you only have a single network adapter, you will need to be especially careful when creating the network provider (see below).

In any case, select a network adapter on your host to use for eryph networking and note its name (e.g. 'Ethernet 2').

Defining the network provider

Now you need to map these settings to a network provider. This is best explained with an example.

Let's say your physical network has the following settings:

network address: 172.16.20.0/24
Gateway: 172.16.20.1
ip range: 172.16.20.5 - 172.16.20.244

Then you can define your network provider like this:

# file: new_config.yaml
network_provider:
- name: default
  type: overlay
  bridge_name: br-pif
  bridge_options:
    # set this if you have only one interface on the host
    default_ip_mode: dhcp 
  adapters:
  - 'Ethernet 2'
  subnets:
  - name: default
    network: 172.16.20.0/24
    gateway: 172.16.20.1
    ip_pools:
    - name: default
      first_ip: 172.16.20.5
      next_ip: 172.16.20.244

Import network provider

You can now use the command

eryph-zero networks import --inFile <new_config.yaml>

to import the new configuration into eryph-zero.
The command will show you all necessary changes to be applied (e.g. removal of NAT networking). Apply these changes to update the networks.

Now, catlets will get IPs from the range defined as external IP address and can be accessed from anywhere in the network using this IP.