|
23 | 23 | <link rel="apple-touch-icon" href="/favicon.ico"> |
24 | 24 | <link rel="stylesheet" href="/assets/css/site.css?v=b310d7c992"> |
25 | 25 | <link rel="stylesheet" href="/assets/css/main.css?v=ccd72260b9"> |
26 | | - <script type="application/ld+json">[{"@context": "https://schema.org", "@type": "TechArticle", "headline": "Networking from zero", "description": "Every networking concept behind Droidspaces gateway mode, from the start: IP addresses, LAN, WAN, DHCP, DNS, NAT, bridges, veth pairs, network namespaces and OpenWRT.", "url": "https://www.droidspaces.org/docs/networking-from-zero.html", "inLanguage": "en", "dateModified": "2026-10-03", "author": {"@type": "Organization", "name": "Droidspaces", "url": "https://www.droidspaces.org/", "sameAs": ["https://github.com/ravindu644/Droidspaces-OSS", "https://t.me/Droidspaces"]}, "publisher": {"@type": "Organization", "name": "Droidspaces", "url": "https://www.droidspaces.org/", "sameAs": ["https://github.com/ravindu644/Droidspaces-OSS", "https://t.me/Droidspaces"]}, "isPartOf": {"@type": "WebSite", "name": "Droidspaces", "url": "https://www.droidspaces.org/"}}, {"@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [{"@type": "ListItem", "position": 1, "name": "Home", "item": "https://www.droidspaces.org/"}, {"@type": "ListItem", "position": 2, "name": "Documentation", "item": "https://www.droidspaces.org/docs/"}, {"@type": "ListItem", "position": 3, "name": "Networking from zero", "item": "https://www.droidspaces.org/docs/networking-from-zero.html"}]}]</script> |
| 26 | + <script type="application/ld+json">[{"@context": "https://schema.org", "@type": "TechArticle", "headline": "Networking from zero", "description": "Every networking concept behind Droidspaces gateway mode, from the start: IP addresses, LAN, WAN, DHCP, DNS, NAT, bridges, veth pairs, network namespaces and OpenWRT.", "url": "https://www.droidspaces.org/docs/networking-from-zero.html", "inLanguage": "en", "dateModified": "2026-10-08", "author": {"@type": "Organization", "name": "Droidspaces", "url": "https://www.droidspaces.org/", "sameAs": ["https://github.com/ravindu644/Droidspaces-OSS", "https://t.me/Droidspaces"]}, "publisher": {"@type": "Organization", "name": "Droidspaces", "url": "https://www.droidspaces.org/", "sameAs": ["https://github.com/ravindu644/Droidspaces-OSS", "https://t.me/Droidspaces"]}, "isPartOf": {"@type": "WebSite", "name": "Droidspaces", "url": "https://www.droidspaces.org/"}}, {"@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [{"@type": "ListItem", "position": 1, "name": "Home", "item": "https://www.droidspaces.org/"}, {"@type": "ListItem", "position": 2, "name": "Documentation", "item": "https://www.droidspaces.org/docs/"}, {"@type": "ListItem", "position": 3, "name": "Networking from zero", "item": "https://www.droidspaces.org/docs/networking-from-zero.html"}]}]</script> |
27 | 27 | <script>(function(){const t=localStorage.getItem('theme');if(t)document.documentElement.setAttribute('data-theme',t);})();</script> |
28 | 28 | </head> |
29 | 29 | <body> |
@@ -359,7 +359,7 @@ <h3 id="how-nat-mode-uses-bridges-and-veths">How NAT mode uses bridges and veths |
359 | 359 | wlan0 / rmnet0 |
360 | 360 | (Android's real network) |
361 | 361 | </code></pre></div> |
362 | | -<p>The bridge <code>ds-br0</code> holds the gateway IP <code>172.28.0.1</code>, which every NAT container uses as its default gateway. The veth pair is named after the container's init process ID: the host side is <code>ds-v<PID></code>, and the container side starts as <code>ds-p<PID></code> and is renamed to <code>eth0</code> inside the container.</p> |
| 362 | +<p>The bridge <code>ds-br0</code> holds the gateway IP <code>172.28.0.1</code>, which every NAT container uses as its default gateway. Its MAC is pinned from its name on every start, because an unpinned bridge borrows the lowest MAC among its ports and would change it whenever that container stops, leaving every other container with a stale ARP entry for the gateway. The veth pair is named after the container's init process ID: the host side is <code>ds-v<PID></code>, and the container side starts as <code>ds-p<PID></code> and is renamed to <code>eth0</code> inside the container.</p> |
363 | 363 | <p>Droidspaces runs a small per-container DHCP server on the container's host-side veth. The whole <code>172.28.0.0/16</code> subnet belongs to Droidspaces. The <code>172.28.0.x</code> row is reserved for the gateway itself, so containers always get an address from <code>172.28.1.x</code> to <code>172.28.254.x</code>, and all of it is NATed out through Android's real interface.</p> |
364 | 364 | <hr /> |
365 | 365 | <h2 id="part-7-network-namespaces-how-containers-are-isolated">Part 7: Network namespaces (how containers are isolated) <a class="header-anchor" href="#part-7-network-namespaces-how-containers-are-isolated">#</a></h2> |
@@ -483,15 +483,15 @@ <h3 id="why-bridge-nf-call-iptables-is-set-to-0">Why bridge-nf-call-iptables is |
483 | 483 | <p>The bridge <code>ds-lan</code> carries traffic between OpenWRT and Kali. By default, Linux can pass bridged traffic through the host's iptables. Android's iptables rules, which may drop or NAT packets unexpectedly, would then interfere with traffic OpenWRT is supposed to manage.</p> |
484 | 484 | <p>Setting it to <code>0</code> tells Linux not to run iptables on bridged traffic. OpenWRT's firewall is then the <em>only</em> firewall that sees this traffic, which is what we want.</p> |
485 | 485 | <h3 id="start-order-and-automatic-self-healing">Start order and automatic self-healing <a class="header-anchor" href="#start-order-and-automatic-self-healing">#</a></h3> |
486 | | -<p>All wiring for a gateway-mode client is done <strong>from the host side</strong> by one function, <code>gateway_wire_client()</code>. It makes sure the bridge and the gateway-side cable exist, creates the client's app veth, and moves and renames the peer into the client's namespace as <code>eth0</code> (with a pinned MAC, brought up). The client's own boot code only brings up <code>lo</code>. Because the host owns every step, the same function wires a client whether it is starting or already running.</p> |
| 486 | +<p>All wiring for a gateway-mode client is done <strong>from the host side</strong> by one function, <code>gateway_wire_client()</code>. It makes sure the bridge and the gateway-side cable exist, then creates the client's app veth with its peer born inside the client's namespace as <code>eth0</code> (with a pinned MAC, brought up). The client's own boot code only brings up <code>lo</code>. Because the host owns every step, the same function wires a client whether it is starting or already running.</p> |
487 | 487 | <p>That leads to one simple rule, keyed on <strong>whether the gateway is running</strong>:</p> |
488 | 488 | <ul> |
489 | 489 | <li><strong>Gateway already running when a client starts</strong> → the client is wired immediately (its own monitor calls <code>gateway_wire_client</code>).</li> |
490 | 490 | <li><strong>Gateway not running when a client starts</strong> → the client wires <strong>nothing at all</strong> (no bridge, no veth, no <code>eth0</code>) and boots. The work is left entirely to the gateway.</li> |
491 | 491 | </ul> |
492 | 492 | <p>So healing is driven by <strong>the gateway</strong>, not the clients. On every boot cycle, the gateway container's monitor calls <code>ds_net_rewire_gateway_clients()</code>. It scans the running containers, finds those that delegate to this gateway, and runs <code>gateway_wire_client</code> for each, setting up the gateway-side <code>eth1</code> cable and every client's <code>eth0</code> in the gateway's <em>current</em> namespace. When the gateway <strong>starts or reboots</strong>, every running client is (re)wired <strong>without restarting the client</strong>.</p> |
493 | 493 | <p>Wiring nothing while the gateway is down, instead of half-wiring a bridge and a dangling veth, also closes a race. A client started before its gateway can have its gateway and LAN settings (<code>--gateway-net</code>, <code>--host-bridge</code>, …) edited before the gateway comes up, and the gateway then wires each client from that client's <em>current</em> config, never a stale one.</p> |
494 | | -<p>There is exactly <strong>one actor</strong> (the gateway) doing the wiring, so there is nothing to poll and no thundering herd. Wiring is serialised per segment with an advisory file lock, so concurrent client starts and the gateway's re-wire cannot race. Both <code>eth1</code> (gateway side) and each <code>eth0</code> (client side) keep a <strong>stable MAC</strong> and are moved and renamed into their namespace in one atomic step, so the container's own <code>netifd</code>/DHCP sees one persistent device instead of one that keeps being re-created.</p> |
| 494 | +<p>There is exactly <strong>one actor</strong> (the gateway) doing the wiring, so there is nothing to poll and no thundering herd. Wiring is serialised per segment with an advisory file lock, so concurrent client starts and the gateway's re-wire cannot race. Both <code>eth1</code> (gateway side) and each <code>eth0</code> (client side) keep a <strong>stable MAC</strong> and are created inside their namespace under their final name, in the one request that creates the pair. Nothing is moved or renamed afterwards: a rename is announced by the kernel before the device can be looked up by its new name, and a <code>netifd</code> inside the gateway that hears the announcement first fails to claim the device for good (seen on a 4.14 kernel, where that gap is tens of milliseconds).</p> |
495 | 495 | <h3 id="what-happens-when-containers-stop">What happens when containers stop <a class="header-anchor" href="#what-happens-when-containers-stop">#</a></h3> |
496 | 496 | <p>Cleanup in gateway mode is deliberately minimal, in line with "plumbing only":</p> |
497 | 497 | <ul> |
@@ -568,7 +568,7 @@ <h3 id="what---gateway-net-does">What --gateway-net does <a class="header-anchor |
568 | 568 | <p>Inside OpenWRT, the <code>lan</code> clients arrive on <code>eth1</code> and the <code>vpn</code> clients on <code>eth2</code>. Each segment gets its own veth, because <code>openwrt:lan</code> and <code>openwrt:vpn</code> hash differently.</p> |
569 | 569 | <h3 id="what---gateway-iface-does">What --gateway-iface does <a class="header-anchor" href="#what---gateway-iface-does">#</a></h3> |
570 | 570 | <p>This sets <strong>the name of the LAN interface inside the gateway container's network namespace</strong>.</p> |
571 | | -<p>When Droidspaces creates the gateway veth for a segment, it moves one end into OpenWRT's netns and renames it from its raw hash name (<code>ds-hXXXXXXXX</code>) to the name you pass here (default <code>eth1</code>).</p> |
| 571 | +<p>When Droidspaces creates the gateway veth for a segment, the gateway's end is born directly inside OpenWRT's netns under the name you pass here (default <code>eth1</code>); only the host end carries a hash name (<code>ds-gXXXXXXXX</code>).</p> |
572 | 572 | <p><strong>Why it matters:</strong> OpenWRT's configuration is keyed on interface names. If your OpenWRT <code>/etc/config/network</code> says:</p> |
573 | 573 | <div class="code-block"><button class="icon-button copy-btn" onclick="copyCode(this)" aria-label="Copy"><span class="icon" aria-hidden="true">content_copy</span></button><pre><code>config interface 'lan' |
574 | 574 | option device 'eth1' |
|
0 commit comments