Multihome

Example Path: examples/MultiHome

Multihome Application

A NetBurner TCP/IP Stack example demonstrating IPv4 multihoming capabilities.

Overview

This application demonstrates how to put multiple IP addresses on a single NetBurner device using the Multihome functionality. The device runs one HTTP server that responds on every configured address at once:

• Physical interface: Obtains its address from DHCP (or AutoIP if no DHCP server answers)
• Fixed multihome address: A second IP address (10.1.1.240) added in software at runtime
• Auto-picked multihome address: A third address chosen automatically on the same subnet as the physical interface, after an ARP check confirms no other device is already using it

Browse to any of the device's addresses and you reach the same web server; the served page reports which address the request actually arrived on.

Features

• Multiple IP addresses on one device (up to 10 interfaces)
• Self-contained, styled web page (plain CSS, no framework or CDN) that:
  • shows which device IP served the current request, and the requesting client's IP
  • lists every interface/address on the device, tagging the one you reached
• Interfaces enumerated dynamically, so the page is correct regardless of how many addresses exist
• Real-time IP address listing on the debug serial port at boot
• Responds to HTTP requests on any configured IP address

Prerequisites

Required System Configuration

Before building and running this application, you must enable multihome support:

The application example includes a predef-overload.h file that automatically enables:

• MULTIHOME functionality
• Support for up to 10 network interfaces (NUM_MULTI_INTERFACES)

The file utilizes the NetBurner overload feature by locating the file at: \MultiHome\overload\nbrtos\include\predef-overload.h

This way NetBurner system file predef.h does not need to be mofified. See the OverloadDirectory example or the Overload section of this manual for more information.

Alternatively, you can modify the NetBurner predef.h system file as described below:

1. Navigate to \nburn\nbrtos\include\predef.h
2. Uncomment the MULTIHOME definition
3. Rebuild the system files

Application Behavior

Network Interface Setup

1. Physical interface: Brought up by init() and addressed via DHCP (falling back to AutoIP if no DHCP server responds)
2. Fixed multihome address: A fixed IP address (10.1.1.240, mask 255.255.255.0, no gateway) added at runtime with AddInterface()
3. Auto-picked multihome address: AddSameSubnetMultihome() reads the physical interface's address/mask/gateway, scans its subnet for a free address, and adds the first one that passes a conflict check

Picking a free address (conflict detection)

Adding a second address on the same subnet risks colliding with another device, so the example checks before it claims one. ICMP echo (ping) alone is unreliable — many hosts drop ping but still answer ARP — so the check is ARP-based (the mechanism behind RFC 5227 Address Conflict Detection):

1. AddressInUse() pings a candidate to trigger ARP resolution, then reads the ARP cache with GetArpMacFromIp(). A cache hit means a host answered ARP, so the address is taken.
2. The first free candidate is added with AddInterface(addr, mask, gateway, physicalIfNum).
3. IsMyAddressUsedArpDetect() runs a final RFC-5227 conflict check on the now-assigned address; on conflict the example calls Removeinterface() and tries the next candidate.
4. sendGratuitousArp() announces the claimed address to update neighbor caches.

Note that probing only detects addresses that are currently online; choosing from outside any DHCP pool is still advisable.

Web Interface

The application starts an HTTP server that answers on every configured address. Access the web page using any of the device's IP addresses to see:

• How you reached this device – the device IP that served the request and the requesting client's IP
• Addresses on this device – a live table of every interface (name, IPv4 address, mask, gateway, link state), with the address that served the current page tagged you are here

The page is built from a static HTML shell; the device fills in the live values through CPPCALL handlers (ShowRequestPath and ShowInterfaceTable). Reloading through a different device address changes the highlighted row – a concrete demonstration of multihoming.

Debug Output

At boot the application prints every interface and its IP address to the debug serial port.

Code Structure

Key Files

• main.cpp: Application logic and the web page's CPPCALL handlers
• html/index.html: Static page shell with CPPCALL placeholders for the live data
• html/style.css, html/logo.png: Self-contained styling for the page (no framework or CDN)
• predef-overload.h: Compiler definitions for multihome support

Key Functions

• UserMain(): Main application entry point; starts HTTP and adds the multihome addresses
• AddInterface(): Adds a multihome IP address at runtime
• AddSameSubnetMultihome(): Finds and adds a free address on the physical interface's subnet
• AddressInUse(): ARP-based conflict probe for a candidate address
• ShowRequestPath(): CPPCALL handler – reports the local (served) and client IP for the request
• ShowInterfaceTable(): CPPCALL handler – enumerates all interfaces and emits the address table

Usage

1. Ensure multihome support is enabled in system configuration
2. Build and deploy the application to your NetBurner device
3. Connect the device to your network
4. Monitor the debug serial output for IP address assignments
5. Access the web interface using any of the assigned IP addresses

Network Configuration

The fixed multihome interface is configured with:

• IP Address: 10.1.1.240
• Subnet Mask: 255.255.255.0
• Gateway: Not configured (IPADDR4::NullIP())

The null gateway is intentional and illustrative: a multihome address only needs to answer requests that arrive on it (a purely local exchange), so no gateway is required. You would supply one only if the device had to originate traffic off that subnet through this interface. By contrast, the auto-picked multihome address copies the primary interface's mask and gateway, so on the same subnet it shares the primary's gateway.

Ensure your network topology can accommodate this address range if you plan to access the multihome address.

Related Examples

• VLan (examples/VLan): the VLAN counterpart of this example — uses the same MULTIHOME support to add tagged VLAN interfaces (VLAN IDs) on one Ethernet port.
• ShowInterfaces (examples/ShowInterfaces): displays interface details in a web page; a good companion to the address table here.
• Configuration/Web/BasicWebConfig: configure a device's network settings (IP, mask, gateway, DHCP) from a web page.
• OverloadDirectory: how the overload/ mechanism used here enables MULTIHOME without editing system headers.

Error Handling

The application includes a compile-time check to ensure multihome support is enabled. If MULTIHOME is not defined, compilation will fail with an informative error message directing you to enable the feature in the system configuration.