diff --git a/docs/network/README.md b/docs/network/README.md new file mode 100644 index 000000000..2d66d3e6a --- /dev/null +++ b/docs/network/README.md @@ -0,0 +1,41 @@ +# Network Overview + +## Table of Contents +1) Network Overview (this page) +2) [Addresses](addresses.md) +3) [Add a new network service](add_new_service.md) + +Test Run provides several built-in network services that can be utilized for testing purposes. These services are already available and can be used without any additional configuration. + +The following network services are provided: + +### Internet Connectivity (Gateway Service) + +The gateway service provides internet connectivity to the test network. It allows devices in the network to access external resources and communicate with the internet. + +### DHCPv4 Service + +The DHCPv4 service provides Dynamic Host Configuration Protocol (DHCP) functionality for IPv4 addressing. It includes the following components: + +- Primary DHCP Server: A primary DHCP server is available to assign IPv4 addresses to DHCP clients in the network. +- Secondary DHCP Server (Failover Configuration): A secondary DHCP server operates in failover configuration with the primary server to provide high availability and redundancy. + +#### Configuration + +The configuration of the DHCPv4 service can be modified using the provided GRPC (gRPC Remote Procedure Call) service. + +### IPv6 SLAAC Addressing + +The primary DHCP server also provides IPv6 Stateless Address Autoconfiguration (SLAAC) addressing for devices in the network. IPv6 addresses are automatically assigned to devices using SLAAC where test devices support it. + +### NTP Service + +The Network Time Protocol (NTP) service provides time synchronization for devices in the network. It ensures that all devices have accurate and synchronized time information. + +### DNS Service + +The DNS (Domain Name System) service resolves domain names to their corresponding IP addresses. It allows devices in the network to access external resources using domain names. + +### 802.1x Authentication (Radius Module) + +The radius module provides 802.1x authentication for devices in the network. It ensures secure and authenticated access to the network. The issuing CA (Certificate Authority) certificate can be specified by the user if required. \ No newline at end of file diff --git a/docs/network/add_new_service.md b/docs/network/add_new_service.md new file mode 100644 index 000000000..1ad07b60d --- /dev/null +++ b/docs/network/add_new_service.md @@ -0,0 +1,94 @@ +# Adding a New Network Service + +The Test Run framework allows users to add their own network services with ease. A template network service can be used to get started quickly, this can be found at [modules/network/template](../../modules/network/template). Otherwise, see below for details of the requirements for new network services. + +To add a new network service to Test Run, follow the procedure below: + +1. Create a folder under `modules/network/` with the name of the network service in lowercase, using only alphanumeric characters and hyphens (`-`). +2. Inside the created folder, include the following files and folders: + - `{module}.Dockerfile`: Dockerfile for building the network service image. Replace `{module}` with the name of the module. + - `conf/`: Folder containing the module configuration files. + - `bin/`: Folder containing the startup script for the network service. + - Any additional application code can be placed in its own folder. + +### Example `module_config.json` + +```json +{ + "config": { + "meta": { + "name": "{module}", + "display_name": "Network Service Name", + "description": "Description of the network service" + }, + "network": { + "interface": "veth0", + "enable_wan": false, + "ip_index": 2 + }, + "grpc": { + "port": 5001 + }, + "docker": { + "depends_on": "base", + "mounts": [ + { + "source": "runtime/network", + "target": "/runtime/network" + } + ] + } + } +} +``` + +### Example of {module}.Dockerfile + +```Dockerfile +# Image name: test-run/{module} +FROM test-run/base:latest + +ARG MODULE_NAME={module} +ARG MODULE_DIR=modules/network/$MODULE_NAME + +# Install network service dependencies +# ... + +# Copy over all configuration files +COPY $MODULE_DIR/conf /testrun/conf + +# Copy over all binary files +COPY $MODULE_DIR/bin /testrun/bin + +# Copy over all python files +COPY $MODULE_DIR/python /testrun/python + +# Do not specify a CMD or Entrypoint as Test Run will automatically start your service as required +``` + +### Example of start_network_service script + +```bash +#!/bin/bash + +CONFIG_FILE=/etc/network_service/config.conf +# ... + +echo "Starting Network Service..." + +# Perform any required setup steps +# ... + +# Start the network service +# ... + +# Monitor for changes in the config file +# ... + +# Restart the network service when the config changes +# ... +``` + + + + diff --git a/docs/network/addresses.md b/docs/network/addresses.md new file mode 100644 index 000000000..ecaacfd36 --- /dev/null +++ b/docs/network/addresses.md @@ -0,0 +1,18 @@ +# Network Addresses + +Each network service is configured with an IPv4 and IPv6 address. For IPv4 addressing, the last number in the IPv4 address is fixed (ensuring the IP is unique). See below for a table of network addresses: + +| Name | Mac address | IPv4 address | IPv6 address | +|---------------------|----------------------|--------------|------------------------------| +| Internet gateway | 9a:02:57:1e:8f:01 | 10.10.10.1 | fd10:77be:4186::1 | +| DHCP primary | 9a:02:57:1e:8f:02 | 10.10.10.2 | fd10:77be:4186::2 | +| DHCP secondary | 9a:02:57:1e:8f:03 | 10.10.10.3 | fd10:77be:4186::3 | +| DNS server | 9a:02:57:1e:8f:04 | 10.10.10.4 | fd10:77be:4186::4 | +| NTP server | 9a:02:57:1e:8f:05 | 10.10.10.5 | fd10:77be:4186::5 | +| Radius authenticator| 9a:02:57:1e:8f:07 | 10.10.10.7 | fd10:77be:4186::7 | +| Active test module | 9a:02:57:1e:8f:09 | 10.10.10.9 | fd10:77be:4186::9 | + + +The default network range is 10.10.10.0/24 and devices will be assigned addresses in that range via DHCP. The range may change when requested by a test module. In which case, network services will be restarted and accessible on the new range, with the same final host ID. The default IPv6 network is fd10:77be:4186::/64 and addresses will be assigned to devices on the network using IPv6 SLAAC. + +When creating a new network module, please ensure that the ip_index value in the module_config.json is unique otherwise unexpected behaviour will occur. \ No newline at end of file