Hotspot captive portal: welcome page with the WROLPi's address

Devices that join the hotspot probe a fixed plain-HTTP URL to check for
Internet access.  NetworkManager's shared-mode dnsmasq now resolves those
probe hostnames (and `wrolpi`) to the hotspot address via an include the
Controller writes when the hotspot starts, the probes land on the Controller
(port 80), and are redirected to /portal: "This is your WROLPi, its address is
10.42.0.1, open WROLPi / open the Controller".

Only the probe hostnames are hijacked so the hotspot keeps forwarding
everything else when the WROLPi has an uplink.  The include is corrected and
the connection re-activated once if NetworkManager picked a non-default
subnet.  Writing the include is best-effort; the hotspot starts regardless.

`hotspot.captive_portal` (controller.yaml, default true) toggles the probe
redirects and the include; like the other hotspot settings it applies on the
next hotspot start, so saving while the hotspot is up reports
restart_required and both Controller UIs say so.  The status endpoint gains
the hotspot address and portal URL, shown in both UIs.  repair.sh only
creates the include directory so a disabled setting survives upgrades.
Native only: Docker has no hotspot.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Roland 2026-09-13 19:09:12 -06:00
parent 91f92683ba
commit 6bea09600e
No known key found for this signature in database
GPG key ID: 1BA620CE6C9A4680
17 changed files with 772 additions and 15 deletions

View file

@ -8,6 +8,7 @@ import pytest
import yaml
from controller.lib.config import reload_config_from_drive
from controller.lib import captive_portal
from controller.lib.admin import (
apply_timezone_from_config,
block_bluetooth,
@ -558,6 +559,23 @@ class TestGetHotspotStatusDict:
assert result["available"] is True
assert result["enabled"] is True
def test_ip_and_portal_url_when_connected(self, reset_runtime_config):
with mock.patch("controller.lib.admin.get_hotspot_status", return_value=HotspotStatus.connected), \
mock.patch("controller.lib.captive_portal.get_hotspot_ip", return_value='10.42.0.1'), \
mock.patch("controller.lib.captive_portal.is_docker_mode", return_value=False):
result = get_hotspot_status_dict()
assert result["ip"] == '10.42.0.1'
assert result["captive_portal"] is True
assert result["portal_url"] == 'http://10.42.0.1/portal'
def test_no_ip_when_off(self, reset_runtime_config):
with mock.patch("controller.lib.admin.get_hotspot_status", return_value=HotspotStatus.off), \
mock.patch("controller.lib.captive_portal.get_hotspot_ip") as get_ip:
result = get_hotspot_status_dict()
assert result["ip"] is None
assert result["portal_url"] is None
get_ip.assert_not_called()
class TestHotspotSettingsMigration:
"""Legacy hotspot settings in wrolpi.yaml are copied into controller.yaml on startup."""
@ -654,6 +672,28 @@ class TestUpdateHotspotSettings:
saved = yaml.safe_load(mock_config_path.read_text())
assert saved['hotspot']['protocol'] == 'wpa3'
def test_updates_captive_portal(self, mock_config_path, reset_runtime_config):
"""The captive portal toggle is saved to controller.yaml and returned."""
with mock.patch("controller.lib.admin.is_docker_mode", return_value=False), \
mock.patch("controller.lib.captive_portal.is_docker_mode", return_value=False):
result = update_hotspot_settings(captive_portal=False)
assert result["success"] is True
assert result["captive_portal"] is False
saved = yaml.safe_load(mock_config_path.read_text())
assert saved['hotspot']['captive_portal'] is False
def test_restart_required_only_while_hotspot_up(self, mock_config_path, reset_runtime_config):
"""A change applies on the next hotspot start, so say so when the hotspot is running."""
with mock.patch("controller.lib.admin.is_docker_mode", return_value=False), \
mock.patch("controller.lib.admin.get_hotspot_status", return_value=HotspotStatus.connected):
assert update_hotspot_settings(captive_portal=False)["restart_required"] is True
# Nothing changed: nothing to apply.
assert update_hotspot_settings()["restart_required"] is False
with mock.patch("controller.lib.admin.is_docker_mode", return_value=False), \
mock.patch("controller.lib.admin.get_hotspot_status", return_value=HotspotStatus.off):
assert update_hotspot_settings(captive_portal=True)["restart_required"] is False
def test_rejects_invalid_protocol(self, mock_config_path, reset_runtime_config):
"""Only wpa2 and wpa3 are valid protocols."""
with mock.patch("controller.lib.admin.is_docker_mode", return_value=False):
@ -897,6 +937,9 @@ class TestDockerModeErrors:
assert "Docker" in error
HOTSPOT_IP_JSON = '[{"ifname": "wlan0", "addr_info": [{"family": "inet", "local": "10.42.0.1"}]}]'
class TestStartHotspot:
"""Tests for start_hotspot function."""
@ -924,8 +967,10 @@ class TestStartHotspot:
device_ready = mock.Mock(returncode=0, stdout="wlan1:disconnected\n", stderr="")
ok = mock.Mock(returncode=0, stdout="", stderr="")
# The final call reads the hotspot's address for the captive portal.
ip_addr = mock.Mock(returncode=0, stdout=HOTSPOT_IP_JSON, stderr="")
with mock.patch("subprocess.run",
side_effect=[radio_on, device_ready, ok, ok, ok]) as mock_subprocess:
side_effect=[radio_on, device_ready, ok, ok, ok, ip_addr]) as mock_subprocess:
with mock.patch("time.sleep"):
start_hotspot()
@ -938,15 +983,68 @@ class TestStartHotspot:
assert "TestSSID" in cmd_args
assert "testpassword123" in cmd_args
@staticmethod
def _start_with_nmcli(ip_json=HOTSPOT_IP_JSON):
"""Run start_hotspot with nmcli mocked; returns the subprocess mock and the include path."""
radio_on = mock.Mock(returncode=0, stdout="", stderr="")
device_ready = mock.Mock(returncode=0, stdout="wlan0:disconnected\n", stderr="")
ok = mock.Mock(returncode=0, stdout="", stderr="")
ip_addr = mock.Mock(returncode=0, stdout=ip_json, stderr="")
with mock.patch("controller.lib.admin.is_docker_mode", return_value=False), \
mock.patch("controller.lib.captive_portal.is_docker_mode", return_value=False), \
mock.patch("subprocess.run", side_effect=[radio_on, device_ready, ok, ok, ok, ip_addr, ok]) as run, \
mock.patch("time.sleep"):
result = start_hotspot()
return result, run
def test_writes_captive_portal_config_before_creating_hotspot(self, reset_runtime_config):
"""dnsmasq reads the include at activation, so it must exist before `nmcli ... hotspot`."""
include = captive_portal.INCLUDE_FILE
result, run = self._start_with_nmcli()
assert result["success"] is True
assert include.exists()
assert 'address=/captive.apple.com/10.42.0.1' in include.read_text()
# The address is only read after the hotspot exists; the include was written before that.
hotspot_call_index = next(i for i, c in enumerate(run.call_args_list) if 'hotspot' in c[0][0])
ip_call_index = next(i for i, c in enumerate(run.call_args_list) if c[0][0][0] == 'ip')
assert hotspot_call_index < ip_call_index
def test_disabled_removes_captive_portal_config(self, reset_runtime_config):
include = captive_portal.INCLUDE_FILE
include.write_text('address=/captive.apple.com/10.42.0.1\n')
with mock.patch("controller.lib.captive_portal.get_config_value", return_value=False):
result, run = self._start_with_nmcli()
assert result["success"] is True
assert not include.exists()
# No `ip` read and no extra re-activation when the portal is off.
assert not [c for c in run.call_args_list if c[0][0][0] == 'ip']
def test_rewrites_config_when_networkmanager_picked_another_subnet(self, reset_runtime_config):
"""10.42.1.1 is used when another shared connection holds 10.42.0.1."""
other = '[{"ifname": "wlan0", "addr_info": [{"family": "inet", "local": "10.42.1.1"}]}]'
result, run = self._start_with_nmcli(ip_json=other)
assert result["success"] is True
assert 'address=/captive.apple.com/10.42.1.1' in captive_portal.INCLUDE_FILE.read_text()
# Re-activated once more so dnsmasq re-reads the corrected include.
ups = [c for c in run.call_args_list if c[0][0][:3] == ['nmcli', 'connection', 'up']]
assert len(ups) == 2
def test_no_reactivation_when_ip_matches(self, reset_runtime_config):
result, run = self._start_with_nmcli()
ups = [c for c in run.call_args_list if c[0][0][:3] == ['nmcli', 'connection', 'up']]
assert len(ups) == 1
@staticmethod
def _run_enable(protocol: str, results: list) -> tuple:
"""Run start_hotspot() with the given hotspot.protocol and subprocess results."""
def mock_get_config(key, default=None):
return {'hotspot.protocol': protocol}.get(key, default)
# After a successful start the hotspot's address is read once for the captive portal.
ip_addr = mock.Mock(returncode=0, stdout=HOTSPOT_IP_JSON, stderr="")
with mock.patch("controller.lib.admin.is_docker_mode", return_value=False):
with mock.patch("controller.lib.admin.get_config_value", side_effect=mock_get_config):
with mock.patch("subprocess.run", side_effect=results) as mock_subprocess:
with mock.patch("subprocess.run", side_effect=results + [ip_addr]) as mock_subprocess:
with mock.patch("time.sleep"):
result = start_hotspot()
return result, mock_subprocess.call_args_list
@ -1028,6 +1126,7 @@ class TestStartHotspot:
hotspot_result, # nmcli device wifi hotspot
hotspot_result, # nmcli connection modify Hotspot
hotspot_result, # nmcli connection up Hotspot
mock.Mock(returncode=0, stdout=HOTSPOT_IP_JSON, stderr=""), # ip -4 -j addr show
]):
with mock.patch("time.sleep"): # Don't actually sleep in tests
result = start_hotspot()

View file

@ -92,7 +92,7 @@ class TestHotspotSettingsEndpoint:
response = test_client.get("/api/hotspot/settings")
assert response.status_code == 200
assert response.json() == {"device": "wlan0", "ssid": "WROLPi", "password": "wrolpi hotspot",
"protocol": "wpa2"}
"protocol": "wpa2", "captive_portal": True, "restart_required": False}
def test_post_settings(self, test_client, mock_config_path):
"""Should update settings and persist them to controller.yaml."""
@ -102,10 +102,18 @@ class TestHotspotSettingsEndpoint:
)
assert response.status_code == 200
assert response.json() == {"device": "wlp2s0", "ssid": "RafaelPi", "password": "password123",
"protocol": "wpa3"}
"protocol": "wpa3", "captive_portal": True, "restart_required": False}
assert "wlp2s0" in mock_config_path.read_text()
assert "wpa3" in mock_config_path.read_text()
def test_post_captive_portal(self, test_client, mock_config_path):
"""The captive portal toggle round-trips and is persisted."""
response = test_client.post("/api/hotspot/settings", json={"captive_portal": False})
assert response.status_code == 200
assert response.json()["captive_portal"] is False
assert "captive_portal: false" in mock_config_path.read_text()
assert test_client.get("/api/hotspot/settings").json()["captive_portal"] is False
def test_post_rejects_short_password(self, test_client, mock_config_path):
"""Should reject a password shorter than 8 characters."""
response = test_client.post("/api/hotspot/settings", json={"password": "short"})

View file

@ -0,0 +1,189 @@
"""
Tests for the hotspot captive portal: dnsmasq include, landing page, and probe redirects.
"""
import json
import subprocess
from unittest import mock
import pytest
from controller.lib import captive_portal
from controller.lib.captive_portal import (
DEFAULT_HOTSPOT_IP,
FRIENDLY_NAME,
PROBE_HOSTS,
PROBE_PATHS,
apply_dnsmasq_config,
dnsmasq_config_ip,
get_hotspot_ip,
is_captive_portal_enabled,
render_dnsmasq_config,
)
IP_JSON = json.dumps([{
"ifname": "wlan0",
"addr_info": [{"family": "inet", "local": "10.42.0.1", "prefixlen": 24}],
}])
@pytest.fixture
def native_mode():
with mock.patch("controller.lib.captive_portal.is_docker_mode", return_value=False):
yield
class TestRenderDnsmasqConfig:
def test_every_probe_host_and_friendly_name(self):
"""Each probe hostname and `wrolpi` resolve to the given IP."""
config = render_dnsmasq_config('10.42.0.1')
for host in PROBE_HOSTS:
assert f'address=/{host}/10.42.0.1' in config
assert f'address=/{FRIENDLY_NAME}/10.42.0.1' in config
def test_no_wildcard(self):
"""A wildcard would break the hotspot's Internet passthrough."""
assert '/#/' not in render_dnsmasq_config('10.42.0.1')
def test_uses_given_ip(self):
config = render_dnsmasq_config('10.42.1.1')
assert '10.42.1.1' in config
assert '10.42.0.1' not in config
class TestApplyDnsmasqConfig:
def test_enabled_writes_file(self, native_mode, reset_runtime_config, tmp_path):
include = tmp_path / 'shared.d' / 'portal.conf'
with mock.patch.object(captive_portal, 'INCLUDE_FILE', include):
assert apply_dnsmasq_config('10.42.0.1') is True
assert include.read_text() == render_dnsmasq_config('10.42.0.1')
assert include.stat().st_mode & 0o777 == 0o644
assert dnsmasq_config_ip() == '10.42.0.1'
def test_disabled_removes_stale_file(self, native_mode, reset_runtime_config, tmp_path):
include = tmp_path / 'portal.conf'
include.write_text('address=/captive.apple.com/10.42.0.1\n')
with mock.patch.object(captive_portal, 'INCLUDE_FILE', include), \
mock.patch("controller.lib.captive_portal.get_config_value", return_value=False):
assert apply_dnsmasq_config('10.42.0.1') is True
assert not include.exists()
assert dnsmasq_config_ip() is None
def test_disabled_without_file_is_fine(self, native_mode, reset_runtime_config, tmp_path):
include = tmp_path / 'portal.conf'
with mock.patch.object(captive_portal, 'INCLUDE_FILE', include), \
mock.patch("controller.lib.captive_portal.get_config_value", return_value=False):
assert apply_dnsmasq_config() is True
def test_write_failure_is_best_effort(self, native_mode, reset_runtime_config, tmp_path, caplog):
"""A read-only /etc must not stop the hotspot from starting."""
include = tmp_path / 'portal.conf'
with mock.patch.object(captive_portal, 'INCLUDE_FILE', include), \
mock.patch("pathlib.Path.write_text", side_effect=PermissionError("read-only")):
assert apply_dnsmasq_config('10.42.0.1') is False
assert 'Could not update captive portal' in caplog.text
def test_docker_never_writes(self, reset_runtime_config, tmp_path):
include = tmp_path / 'portal.conf'
with mock.patch.object(captive_portal, 'INCLUDE_FILE', include), \
mock.patch("controller.lib.captive_portal.is_docker_mode", return_value=True):
assert is_captive_portal_enabled() is False
apply_dnsmasq_config('10.42.0.1')
assert not include.exists()
class TestIsCaptivePortalEnabled:
def test_default_true(self, native_mode, reset_runtime_config):
assert is_captive_portal_enabled() is True
def test_setting_false(self, native_mode, reset_runtime_config):
with mock.patch("controller.lib.captive_portal.get_config_value", return_value=False):
assert is_captive_portal_enabled() is False
class TestGetHotspotIp:
def test_parses_ip_json(self, native_mode):
result = mock.Mock(returncode=0, stdout=IP_JSON)
with mock.patch("subprocess.run", return_value=result) as run:
assert get_hotspot_ip('wlan0') == '10.42.0.1'
assert run.call_args[0][0] == ['ip', '-4', '-j', 'addr', 'show', 'dev', 'wlan0']
def test_no_address_when_hotspot_down(self, native_mode):
result = mock.Mock(returncode=0, stdout=json.dumps([{"ifname": "wlan0", "addr_info": []}]))
with mock.patch("subprocess.run", return_value=result):
assert get_hotspot_ip('wlan0') is None
def test_missing_device(self, native_mode):
result = mock.Mock(returncode=1, stdout='')
with mock.patch("subprocess.run", return_value=result):
assert get_hotspot_ip('wlan9') is None
@pytest.mark.parametrize("error", [FileNotFoundError(), subprocess.TimeoutExpired('ip', 5)])
def test_ip_unavailable(self, native_mode, error):
with mock.patch("subprocess.run", side_effect=error):
assert get_hotspot_ip('wlan0') is None
def test_docker(self):
with mock.patch("controller.lib.captive_portal.is_docker_mode", return_value=True):
assert get_hotspot_ip('wlan0') is None
class TestProbeRedirects:
"""OS connectivity probes are redirected to the portal when the feature is on."""
@pytest.mark.parametrize("path", PROBE_PATHS)
def test_probe_redirects_when_enabled(self, test_client, path):
response = test_client.get(path, follow_redirects=False)
assert response.status_code == 302
assert response.headers['location'] == '/portal'
assert response.headers['cache-control'] == 'no-store'
def test_head_probe_redirects(self, test_client):
response = test_client.head('/hotspot-detect.html', follow_redirects=False)
assert response.status_code == 302
def test_probe_404_when_disabled(self, test_client):
with mock.patch("controller.api.captive_portal.is_captive_portal_enabled", return_value=False):
response = test_client.get('/generate_204', follow_redirects=False)
assert response.status_code == 404
def test_probe_404_in_docker(self, test_client_docker_mode):
response = test_client_docker_mode.get('/hotspot-detect.html', follow_redirects=False)
assert response.status_code == 404
class TestPortalPage:
def test_shows_address_and_links(self, test_client):
with mock.patch("controller.api.captive_portal.get_hotspot_ip", return_value='10.42.0.1'):
response = test_client.get('/portal')
assert response.status_code == 200
assert response.headers['cache-control'] == 'no-store'
body = response.text
assert '10.42.0.1' in body
assert 'https://10.42.0.1/' in body
assert 'https://10.42.0.1/controller/' in body
assert 'WROLPi' in body # the SSID
def test_404_when_hotspot_down(self, test_client):
"""A page with no address is worse than no page."""
with mock.patch("controller.api.captive_portal.get_hotspot_ip", return_value=None):
assert test_client.get('/portal').status_code == 404
def test_404_in_docker(self, test_client_docker_mode):
assert test_client_docker_mode.get('/portal').status_code == 404
def test_served_even_when_probes_disabled(self, test_client):
"""The setting controls the automatic sheet, not the page itself."""
with mock.patch("controller.api.captive_portal.get_hotspot_ip", return_value='10.42.0.1'), \
mock.patch("controller.api.captive_portal.is_captive_portal_enabled", return_value=False):
assert test_client.get('/portal').status_code == 200
class TestDefaultIp:
def test_default_is_networkmanager_shared_subnet(self):
assert DEFAULT_HOTSPOT_IP == '10.42.0.1'

View file

@ -111,6 +111,7 @@ class TestHotspotConfig:
("device", "wlan0"),
("ssid", "WROLPi"),
("password", "wrolpi hotspot"),
("captive_portal", True),
])
def test_hotspot_defaults(self, key, expected):
"""Hotspot should have expected default values."""