NetworkManager: Detection of Captive Portals on Debian Jessie/Stretch (self-hosted)

NetworkManager provides connectivity checking to test for captive portals since GNOME 3.14. This performs recurring checks on a configurable URL. In case this does not deliver the expected response, NetworkManager knows we are very probably behind a captive portal and opens the corresponding login page.

This connectivity checking is an optional feature and not enabled by default in Debian Jessie or Squeeze. To enable this we can simple add a configuration file in /etc/NetworkManager/conf.d containing three settings:

[connectivity]
uri=http://network-test.debian.org/nm
response=NetworkManager is online
interval=300

This will check http://network-test.debian.org/nm every 300 seconds and expects to find the string “NetworkManager is online” in the HTML response.

For privacy reasons you might not want to test a public URL though. We could however simply host the URL to be checked ourselves. The NetworkManager documentation gives a few more details about the three settings. We mainly need to set the URI to a web site that either returns the header “X-NetworkManager-Status” with a value of “online” or returns the string specified using “response” in its body.

Given a running Apache web server with mod_headers enabled we can simply define a vhost like this:

<VirtualHost *:80>
  ServerName connectivity-check.example.net

  ## Vhost docroot
  DocumentRoot "/var/www/empty"

  ## Directories, there should at least be a declaration for /var/www/empty

  <Directory "/var/www/empty">
    Header Set X-NetworkManager-Status "online"
    AllowOverride None
    Require all granted
  </Directory>

  ## Logging
  ErrorLog "/var/log/apache2/connectivity-check.example.net_error.log"
  ServerSignature Off
  CustomLog "/var/log/apache2/connectivity-check.example.net_access.log" combined
</VirtualHost>

and configure NetworkManager using the following in /etc/NetworkManager/conf.d/10-connectivity.conf:

[connectivity]
uri=http://connectivity-check.example.net
interval=300

Sources:

  • Enabling captive portal detection in GNOME 3.14 on Debian Jessie by L Guruprasad
  • NetworkManager.conf documentation