LookingGlass: a public ping and traceroute front end you host yourself

A diagnostic tool turned into a web form

A looking glass, in the network operations sense, is a machine from which outsiders can run path and latency commands against your own infrastructure, usually at the request of a customer who cannot reach you. The classic version is a login shell, which is unfriendly and unpleasant to operate. LookingGlass takes the same idea and wraps it in a web page.

The documentation describes it as a network utility made user-friendly for everyone to use, allowing network related commands to be executed within a remote network, usually that of an ISP. The feature list names the Bootstrap 5 interface, real time command output using JavaScript, support for ping, ping6, traceroute, traceroute6, mtr and mtr6, a latency feature that measures from the visitor to the looking glass itself, and a dark, light or auto theme.

The audience is narrow and specific: a hosting provider, a network operator, a transit provider, or a lab that wants to publish a diagnostics page without handing out shell accounts. It is not a monitoring tool and it does not collect data over time. Each request runs a command and streams the result.

How a query becomes a shell command

The repository is small enough to read. The top level holds LookingGlass.php, backend.php, bootstrap.php, config.dist.php, index.php and a docker directory, which is the shape of a request-driven PHP application rather than a framework project.

The execution model traces back to an earlier project. The documentation states that LookingGlass is inspired by the LookingGlass project of @telephone and uses his procExecute() function, slightly modified. The two entry points in the tree suggest the split: index.php serves the interface, and backend.php is the side that talks to the operating system and streams the command output back.

Two safety-relevant details appear in the feature list. DNS checking exists to prevent unnecessary executions, so a hostname that does not resolve is rejected before a command runs. And the latency feature measures from the visitor to the looking glass, which is a measure of the client path rather than of the target host.

What the README does not do is enumerate the exact command templates that are executed for each method. The METHODS configuration key controls which of them are enabled, and the docker-compose.yml comment shows the default list, but the templates themselves live in the PHP source, not in the documentation.

Docker Compose, with images you build yourself

The Docker route is the one to take if you can run containers. The compose file defines two services, nginx and php-fpm, both on the host network so the container can reach the network tools and the outside world directly:

services:
  nginx:
    image: hybula/lookingglass-nginx:1
    container_name: lg-nginx
    build:
      context: .
      dockerfile: docker/nginx/Dockerfile
    network_mode: host
    restart: unless-stopped

The images are named hybula/lookingglass-nginx:1 and hybula/lookingglass-php:1, but the install documentation states plainly that the Docker images are not hosted on an image repository, so you have to build them yourself with docker compose build. Both services carry a build section with a context and a Dockerfile, which is what makes that work.

The php-fpm service has a healthcheck that probes cgi-fcgi against localhost:9000, with a 20 second start period, a 30 second interval, five retries and a 3 second timeout. Restart policy is unless-stopped on both.

One consequence of network_mode: host is worth thinking about before you deploy. The containers share the host network namespace, which is what lets the PHP process reach ping, traceroute and MTR, and it also means port binding is your responsibility rather than the compose file's.

The configuration keys that shape the page

Everything the page shows comes from environment variables in compose, mirrored in config.dist.php for manual installs. The default values are placeholders:

    environment:
      LOCATION: Location
      FACILITY: Facility
      FACILITY_URL: http://localhost/
      IPV4_ADDRESS: 127.0.0.1
      IPV6_ADDRESS: ::1
      MAPS_QUERY: Amsterdam

LOCATION and FACILITY name the site and the operator, FACILITY_URL links back to your own site, and LOGO and LOGO_DARK carry a light and a dark variant of the header. IPV4_ADDRESS and IPV6_ADDRESS are what the latency feature measures against, and MAPS_QUERY is the place passed to the embedded map.

Three blocks can be switched off individually by uncommenting DISABLE_BLOCK_NETWORK, DISABLE_BLOCK_LOOKINGGLASS or DISABLE_BLOCK_SPEEDTEST, and the compose file notes that passing any arbitrary value disables the respective block. A custom block is enabled with ENABLE_CUSTOM_BLOCK, and terms acceptance is turned on by pointing LG_TERMS at the URL of the terms.

The methods list is a comma-separated value. The compose file shows the default as all methods enabled and gives an example beginning with ping,ping6,mtr,mtr6,tracero, which is truncated in the file itself. That single key is the main knob for controlling what the public can run.

The manual install runs on root, SELinux and symlinks

The manual path assumes AlmaLinux 8 or 9, and it is the more fragile of the two. The network tools come from dnf install mtr traceroute, the web server from dnf install httpd mod_ssl php php-posix, and Apache and PHP-FPM are enabled with systemctl enable --now.

Two steps exist purely to satisfy MTR's expectations. The README asks you to symlink /usr/sbin/mtr to /usr/bin/mtr and to do the same for the mtr-packet helper, which is the mechanism MTR uses to spawn its helper processes.

Then comes the part that trips people up on RHEL-family systems: SELinux has to be configured before anything works, or you can disable it with setenforce 0 and make it permanent by editing /etc/selinux/config to SELINUX=disabled. The install guide gives you the choice, which is honest but also makes the easier path the one that weakens the host.

After that you upload the ZIP contents to /var/www/html, rename config.dist.php to config.php, and adjust the settings. The optional step of generating a large test file with dd is there for people who want to try the speed test path before pointing it at a real server. Requirements listed up front are PHP 8.0 or higher, IPv6 connectivity if you want the v6 equivalents, and root access. Testing is on RHEL 8 and 9, with NetBSD users pointed at issue 47.

iPerf3 belongs on a different host

The speed test is an optional add-on and the documentation attaches a clear warning to it: install iPerf3 on a different server from the looking glass to avoid network congestion. That is not a formality. The container and the iPerf3 endpoint share the same uplink, so measuring throughput through them will show you the capacity of the looking glass host rather than the capacity of the path.

The manual install is short. Install iperf3, launch it as a daemon with iperf3 -sD -p 5201, optionally add a systemd unit so it starts at boot, then locate the two lines in config.php holding LG_SPEEDTEST_CMD_INCOMING and LG_SPEEDTEST_CMD_OUTGOING and replace hostname with the IPv4 address of the iPerf3 server.

In the Docker setup the same two variables are edited in docker/php-fpm/src/config.php. The iperf3 section of docker-compose.yml is commented out by default and has to be uncommented, or copied to a separate docker-compose.yml on another server. The variable names are self-describing, and they are the clearest signal that incoming and outgoing throughput are separate measurements with separate endpoints.

Releases, licensing and the missing rate limiting

The repository is not archived. The last push was on 2026-05-04, and the 1.5.0 release carries the same date, with 1.4.0 in August 2025 and 1.3.6 in May 2025 before it. Releases are frequent enough that an operator should expect to keep up, and the upgrade procedure is correspondingly simple: overwrite the installation with the new files, then update config.php, and the script checks for missing variables on startup.

The licence is the one genuinely awkward detail. The license section lists it as Apache License, Version 2.0 and the Commons Clause Restriction, and GitHub shows it simply as Other because it is a custom combination. The Apache 2.0 part is familiar; the Commons Clause is the commercial restriction on selling the software as a service. No legal advice is offered here, but if your organisation resells hosting or operates a looking glass as a paid service, read the LICENSE.md file before you rely on it.

The bigger operational caveat is stated in the install guide itself: the guide does not cover any security hardening or rate limiting. A public page that runs ping and traceroute on request, with root access underneath, without request limits, is exactly the kind of thing that attracts abuse. The DNS check reduces pointless executions, and the methods key lets you narrow what runs, but neither is a substitute for a front end that caps request volume.

Editorial conclusion

LookingGlass fits network operators, hosting providers and anyone who wants a friendly diagnostic page in front of a machine they already own, and the Docker Compose path gets you a working instance without touching SELinux. It does not fit a public launch on a box you cannot lock down, because the project ships no rate limiting and the installation guide says so explicitly, and it does not fit a team that wants a hosted service instead of software they operate. Before exposing it, put the container behind a reverse proxy with its own request limits, decide whether the three-organisation Apache 2.0 plus Commons Clause licensing fits your redistribution plans, and set the MAPS_QUERY, FACILITY and DISABLE_BLOCK values in config.dist.php to something real rather than shipping the placeholders.

Frequently asked questions

Official sources

1. hybula/lookingglass on GitHub
2. Issues
3. Project website
4. README
5. Releases