Network Configuration

Introduction

This page documents the network configuration settings for AosCore components. Network configuration spans two components:

• Communication Manager (CM) — operates the DNS server and manages IP subnet allocation from predefined network pools
• Service Manager (SM) — executes CNI plugins for per-instance network setup, manages traffic monitoring, and creates bridge/VLAN interfaces

Most network behavior is automatic — the CM allocates subnets and IPs from built-in pools, and the SM configures instance networking through CNI plugins. The OEM integrator configures only the DNS server binding address, storage paths, and CNI plugin locations.

For architectural details on how these components interact, see CM Network Manager and SM Network Manager.

CM DNS Configuration

The Communication Manager configuration file (aos_communicationmanager.json) includes two fields that control the local DNS server used for service name resolution:

{
  "dnsStoragePath": "/var/aos/dns",
  "dnsIp": "0.0.0.0:5353"
}

Field	Type	Required	Default	Description
dnsStoragePath	string	No	"/var/aos/dns"	Directory where the DNS server stores its hosts file (addnhosts) and PID file (pidfile). The CM writes hostname-to-IP mappings here and signals the DNS process to reload.
dnsIp	string	No	"" (empty)	IP address and port the DNS server listens on. Format: address:port. This address is provided to service instances as their DNS resolver.

DNS Server Operation

The CM does not start the DNS server process itself — it expects an external DNS server (such as dnsmasq) to be running and configured to read the hosts file from dnsStoragePath. The CM interacts with the DNS server through:

1. Hosts file (addnhosts) — the CM writes hostname-to-IP mappings in standard /etc/hosts format (IP followed by tab-separated hostnames)
2. PID file (pidfile) — the CM reads this file to locate the DNS server process
3. SIGHUP signal — the CM sends SIGHUP to the DNS process to trigger a configuration reload after updating the hosts file

DNS IP Address Usage

The dnsIp value serves two purposes:

• It identifies the DNS server's listening address for the CM's internal reference
• It is distributed to service instances as part of their network parameters, so instances configure their /etc/resolv.conf to point to this address

If dnsIp is not configured, DNS resolution for service instances is not available.

Network Pools

The CM allocates subnets for service networks from a set of hardcoded private network ranges. These are not configurable through the JSON configuration file — they are compiled into the binary.

Predefined Pool Ranges

Base Network	Target Prefix	Resulting Subnets
172.17.0.0/16	/16	1 subnet
172.18.0.0/16	/16	1 subnet
172.19.0.0/16	/16	1 subnet
172.20.0.0/14	/16	4 subnets
172.24.0.0/14	/16	4 subnets
172.28.0.0/14	/16	4 subnets

This yields 14 available /16 subnets, each providing approximately 65,533 usable host addresses.

Allocation Behavior

• Subnets are allocated on demand when a new service network is created
• The allocator checks the system routing table to avoid overlapping with existing routes
• IP addresses within a subnet are assigned sequentially (starting from the third address — network address + 2)
• When all instances are removed from a network, the subnet is released back to the pool
• VLAN IDs are generated randomly in the range 0–4095 (standard 802.1Q range)

Implications for OEM Integrators

Since the network pools use the 172.16.0.0/12 private range, ensure that:

• The host system's existing network configuration does not use addresses in the 172.17.0.0 – 172.31.255.255 range
• Any external routing or VPN configurations do not conflict with these subnets
• The route overlap check at allocation time will skip conflicting subnets, but if all 14 subnets conflict with existing routes, network allocation will fail

SM Network Configuration

The Service Manager does not have explicit network configuration fields in its JSON configuration file (aos_servicemanager.json). Instead, SM network behavior is determined by:

1. Network parameters received from CM — subnet, IP, VLAN ID, and DNS servers pushed via the UpdateNetworks gRPC message
2. CNI plugin binaries — must be present at the expected filesystem path
3. System capabilities — Linux kernel support for network namespaces, bridges, VLANs, and iptables

CNI Plugin Path

CNI plugin binaries must be installed at:

/opt/cni/bin/

The following plugins are required:

Plugin	Binary	Purpose
Bridge	/opt/cni/bin/bridge	Creates bridge networks with IPAM for IP allocation
DNS	/opt/cni/bin/dnsname	Provides DNS resolution within the service network
Firewall	/opt/cni/bin/aos-firewall	Applies per-instance firewall rules for network isolation
Bandwidth	/opt/cni/bin/bandwidth	Enforces ingress/egress rate limits

This path is compiled into the binary (/opt/cni/bin) and is not configurable through the JSON configuration file.

CNI Configuration Directory

The CNI component uses a configuration directory for caching network state. This directory is set internally by the SM during initialization and stores cached plugin configurations that enable proper cleanup during instance removal.

Network Parameters (Cloud-Managed)

Network parameters for service instances are defined in the desired-state document pushed from AosCloud. These parameters are not configured locally — they arrive as part of the instance deployment specification.

Per-Instance Network Parameters

Each service instance receives network parameters as part of its InstanceInfo:

Field	Type	Description
network_id	string	Identifier of the network this instance belongs to
subnet	string	CIDR notation subnet (e.g., 172.17.0.0/16)
ip	string	IP address assigned to this instance within the subnet
dns_servers	array of strings	DNS server addresses for the instance's resolver configuration
rules	array of FirewallRule	Firewall rules controlling instance connectivity

Firewall Rules

Each firewall rule in the rules array specifies:

Field	Type	Description
dst_ip	string	Destination IP address
dst_port	string	Destination port
proto	string	Transport protocol (tcp or udp)
src_ip	string	Source IP address

Network Update Parameters

When the CM pushes network configuration to an SM Node via UpdateNetworks, each network entry contains:

Field	Type	Description
network_id	string	Unique identifier for the network
subnet	string	CIDR notation subnet allocated from the pool
ip	string	Gateway IP address for this Node on the network
vlan_id	uint64	VLAN ID for Layer 2 isolation (0–4095)

The SM uses these parameters to create bridge and VLAN interfaces on the Node.

Traffic Monitoring Configuration

Traffic monitoring is configured through the SM's runtime behavior rather than static configuration files. The following parameters control traffic accounting:

Monitoring Periods

Traffic counters reset at configurable period boundaries:

Period	Reset Boundary	Use Case
Minute	Start of each minute	Fine-grained debugging
Hour	Start of each hour	Short-term analysis
Day	Start of each day	Default — daily traffic accounting
Month	Start of each month	Monthly quota enforcement
Year	Start of each year	Annual reporting

The default traffic period is day. The period is set programmatically via the SetTrafficPeriod interface — it is not configured through a JSON file.

Traffic Counter Update Period

The Traffic Monitor reads iptables counters and persists them to storage at a default interval of 1 minute. This ensures traffic data survives SM restarts with at most 1 minute of data loss.

Bandwidth Limits

Per-instance bandwidth limits (ingress and egress rates in kbit/s) are specified in the instance's network parameters from the desired-state document. When an instance exceeds its configured limit within the current accounting period:

1. The accounting iptables rule is replaced with a DROP rule
2. All traffic to/from the instance is blocked
3. At the next period boundary, counters reset and normal traffic resumes

Local Traffic Exclusion

The following network ranges are excluded from traffic accounting (treated as local traffic):

• 127.0.0.0/8 — loopback
• 10.0.0.0/8 — private (Class A)
• 192.168.0.0/16 — private (Class C)
• 172.16.0.0/12 — private (Class B, includes the service network pools)

Only internet-bound traffic is counted toward bandwidth limits.

Platform Requirements

Network configuration requires the following platform capabilities:

Requirement	Purpose
Linux kernel with network namespace support	Per-instance network isolation
iptables command-line tool	Traffic monitoring and bandwidth enforcement
CNI plugin binaries in /opt/cni/bin/	Instance network setup/teardown
Root or CAP_NET_ADMIN capability	Network interface and iptables operations
Bridge kernel module	Service network bridge interfaces
802.1Q VLAN kernel module (optional)	VLAN-based network isolation
External DNS server process (e.g., dnsmasq)	Service name resolution

Configuration Summary

Setting	Location	Configurable	Default
DNS storage path	CM config (dnsStoragePath)	Yes	/var/aos/dns
DNS IP address	CM config (dnsIp)	Yes	Empty (disabled)
Network pools	Compiled into binary	No	14 × /16 subnets in 172.17–172.31 range
CNI plugin path	Compiled into binary	No	/opt/cni/bin/
Traffic update period	Runtime	No (hardcoded)	1 minute
Traffic accounting period	Runtime API	Programmatic only	Day
Bandwidth limits	Desired-state document	Cloud-managed	Per-instance
Firewall rules	Desired-state document	Cloud-managed	Per-instance
VLAN IDs	Auto-generated by CM	No	Random 0–4095

Related Pages

• CM Network Manager — architectural overview of CM's network management (subnet allocation, DNS, firewall rules)
• SM Network Manager — architectural overview of SM's per-instance networking (CNI plugins, traffic monitoring, namespaces)
• Configuration Reference — overview of the AosCore configuration system
• Unit Configuration — cloud-managed per-Unit policies including alert rules for network traffic
• SM Controller — how CM distributes network configuration to SM instances on each Node