Network Manager

Introduction

The Network Manager is the SM subcomponent responsible for all service-level networking. It creates isolated network environments for each service instance using Linux network namespaces, configures connectivity through CNI (Container Network Interface) plugins, manages bridge and VLAN interfaces, and monitors traffic with configurable bandwidth limits and accounting periods.

When SM launches a service instance, the Network Manager sets up the instance's network namespace, allocates an IP address from the service's subnet, configures firewall rules for isolation, applies bandwidth shaping, and begins traffic accounting. When the instance is removed, the Network Manager tears down all network resources and stops monitoring.

Architecture

The Network Manager is split into two layers: a core orchestration layer (NetworkManager) and platform-specific implementations for CNI execution and traffic monitoring.

Interfaces

Interface	Direction	Purpose
NetworkManagerItf	Implements	Network lifecycle management — create/remove networks, add/remove instances, query IPs and traffic
SystemTrafficProviderItf	Implements	Provide aggregate system-level traffic statistics
InstanceTrafficProviderItf	Implements	Provide per-instance traffic statistics
StorageItf	Depends on	Persist network info, instance-network mappings, and traffic counter data
CNIItf	Depends on	Execute CNI plugin chains for network setup/teardown
TrafficMonitorItf	Depends on	Track per-instance and system-wide traffic via iptables
NamespaceManagerItf	Depends on	Create and delete Linux network namespaces
InterfaceManagerItf	Depends on	Query and manage existing network interfaces
InterfaceFactoryItf	Depends on	Create bridge and VLAN network interfaces
RandomItf	Depends on	Generate random interface names

Component Relationships

The core NetworkManager orchestrates the overall flow. It delegates:

• Network namespace creation to NamespaceManagerItf
• Bridge/VLAN interface creation to InterfaceFactoryItf
• CNI plugin execution (IP allocation, firewall, DNS, bandwidth) to CNIItf
• Traffic accounting to TrafficMonitorItf
• State persistence to StorageItf

The platform-specific layer (aos_core_cpp/src/sm/networkmanager/) provides concrete implementations:

• CNI class — executes CNI plugin binaries as external processes
• TrafficMonitor class — uses iptables packet counters for traffic accounting
• Exec class — launches plugin binaries with proper CNI environment variables

Network Lifecycle

Creating Networks

When UpdateNetworks is called with a set of network parameters, the Network Manager:

1. Compares the requested networks against currently active networks
2. Removes networks that are no longer needed (deleting bridges, VLANs, and stored state)
3. Creates new networks by:
   • Generating a unique bridge interface name (prefixed br-)
   • Optionally creating a VLAN interface (prefixed vlan-) if a VLAN ID is specified
   • Storing the network info (network ID, subnet, IP, VLAN ID, interface names) in persistent storage

Adding an Instance to a Network

When AddInstanceToNetwork is called, the Network Manager executes the following sequence:

1. Create network namespace — allocates an isolated network namespace for the instance via NamespaceManagerItf
2. Prepare CNI configuration — builds the plugin chain configuration:
   • Bridge plugin — connects the instance to the network bridge with IPAM (IP Address Management) for automatic IP allocation from the subnet
   • DNS plugin — configures DNS resolution with the instance's hostname and aliases
   • Firewall plugin — applies per-instance firewall rules controlling inbound/outbound access
   • Bandwidth plugin — enforces ingress/egress rate limits (in kbit/s)
3. Execute CNI ADD — runs the plugin chain, which creates the network interface inside the namespace, assigns an IP, and applies all rules
4. Create hosts file — writes a /etc/hosts file for the instance with configured host entries
5. Create resolv.conf — writes DNS resolver configuration for the instance
6. Start traffic monitoring — begins iptables-based traffic accounting with configured upload/download limits
7. Update cache — stores the instance's IP and hostname mappings in memory and persistent storage

Removing an Instance from a Network

When RemoveInstanceFromNetwork is called:

1. Stop traffic monitoring — removes iptables chains for the instance
2. Execute CNI DEL — runs the plugin chain with the DELETE command, tearing down network interfaces and releasing the IP
3. Delete network namespace — removes the instance's isolated namespace
4. Clean up files — removes hosts file and resolv.conf
5. Update storage — removes instance-network mapping from persistent storage

CNI Plugin Chain

The Network Manager uses a chain of four CNI plugins executed sequentially. Each plugin receives the output of the previous plugin as input.

Plugin Execution Order

Order	Plugin	Binary	Purpose
1	Bridge	/opt/cni/bin/bridge	Creates a bridge network, allocates IP via IPAM, sets up routing
2	DNS	/opt/cni/bin/dnsname	Configures DNS resolution with hostname aliases
3	Firewall	/opt/cni/bin/aos-firewall	Applies per-instance firewall rules (input/output access control)
4	Bandwidth	/opt/cni/bin/bandwidth	Enforces ingress/egress rate and burst limits

Bridge Plugin Configuration

The bridge plugin creates a Linux bridge connecting the instance's network namespace to the host network:

• Bridge name — derived from the network ID (e.g., br-<networkID>)
• Gateway mode — enabled, making the bridge act as the default gateway for instances
• IP masquerading — enabled for outbound NAT
• Hairpin mode — enabled for intra-bridge communication
• IPAM — host-local IP allocation from the configured subnet range

Firewall Plugin Configuration

The aos-firewall plugin provides per-instance network access control:

• Input access rules — define which ports and protocols accept inbound connections (exposed ports)
• Output access rules — define which destination IPs, ports, and protocols the instance can reach
• Public connections — configurable flag to allow or deny general internet access
• Admin chain — per-instance iptables chain (prefixed INSTANCE_) for rule management

Bandwidth Plugin Configuration

The bandwidth plugin enforces traffic shaping:

• Ingress rate/burst — maximum inbound data rate and burst size
• Egress rate/burst — maximum outbound data rate and burst size
• Rates are specified in bits per second; burst length defaults to 12800 bytes

Plugin Execution Mechanism

The Exec class launches each CNI plugin binary as an external process:

1. Prepares a JSON payload containing the plugin configuration and previous result
2. Sets CNI environment variables: CNI_COMMAND, CNI_ARGS, CNI_PATH, CNI_CONTAINERID, CNI_NETNS, CNI_IFNAME
3. Executes the plugin binary at /opt/cni/bin/<plugin-name>
4. Passes the JSON payload via stdin
5. Captures the result from stdout (containing interface, IP, route, and DNS information)
6. Implements retry logic for transient "text file busy" errors

Configuration Caching

After a successful ADD operation, the CNI component caches the full network configuration (plugin configs, runtime args, result) to a file. This cache enables proper cleanup during DEL operations even if the original configuration is no longer available.

Traffic Monitoring

The Traffic Monitor provides network traffic accounting using Linux iptables packet counters.

System-Level Monitoring

On initialization, the Traffic Monitor creates two system-wide iptables chains:

• AOS_SYSTEM_IN — inserted into the INPUT chain to count all inbound traffic
• AOS_SYSTEM_OUT — inserted into the OUTPUT chain to count all outbound traffic

Local/private network traffic is excluded from accounting (127.0.0.0/8, 10.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12, and related subnets).

Per-Instance Monitoring

When instance monitoring starts, the Traffic Monitor:

1. Generates a hash-based chain name from the instance ID
2. Creates AOS_<hash>_IN and AOS_<hash>_OUT chains
3. Inserts rules into the FORWARD chain to redirect instance traffic to these chains
4. Adds accounting rules matching the instance's IP address

Traffic Accounting Periods

Traffic counters reset at configurable period boundaries:

Period	Reset Boundary
Minute	Start of each minute
Hour	Start of each hour
Day	Start of each day (default)
Month	Start of each month
Year	Start of each year

Bandwidth Limit Enforcement

When an instance exceeds its configured upload or download limit within the current period:

1. The accounting rule is replaced with a DROP rule, blocking further traffic
2. Traffic remains blocked until the next period boundary resets the counters
3. When the new period starts and counters reset below the limit, the DROP rule is removed and normal accounting resumes

Data Persistence

Traffic counters are persisted to storage via StorageItf:

• Each chain's cumulative byte count and last-update timestamp are stored
• On restart, counters are restored from storage to maintain continuity
• The update period (default: 1 minute) controls how frequently counters are read from iptables and persisted

Network Isolation Model

Each service instance operates in its own Linux network namespace, providing complete network stack isolation:

• Separate interfaces — each instance has its own eth0 interface inside its namespace
• Independent routing — per-instance routing tables
• Firewall isolation — per-instance iptables rules via the aos-firewall plugin
• DNS isolation — per-instance resolv.conf and hosts files
• Bandwidth isolation — per-instance traffic shaping prevents one service from consuming all available bandwidth

Instances on the same network can communicate through the shared bridge. Cross-network communication is controlled by firewall rules.

Platform Requirements

The Network Manager requires:

• Linux operating system with network namespace support
• CNI plugin binaries in /opt/cni/bin/: bridge, dnsname, aos-firewall, bandwidth
• iptables command-line tool
• Root or CAP_NET_ADMIN capability for network operations
• Kernel support for bridge interfaces and optional VLAN interfaces

Related Pages

• Service Manager — parent component overview and SM architecture
• Architecture Overview — system-wide component relationships
• CM Network Manager — CM-level network management (distinct from SM's per-instance networking)
• Launcher — service instance launch mechanism that triggers network setup
• Resource Manager — resource allocation including network-related quotas

• Network Configuration — configuration reference for network parameters