The setup page

remote machines for users for administrators

The daemon serves a page at / that sets up any machine, with one script for every tool at /setup/all and a page per tool, a status bar on every page, a 30-day summary of the upstream servers, and on its own machine and trusted networks links to the cache page and the upstream status.

On the map: setup and the command line

▶ Watch this deck — 9 scenes, ~6 min

Part of journeys

01 What this topic covers

ABOUT THIS TOPIC The setup page a web page that sets up any machine, at pkgproxy's own address 1 page at / 2 read it first 3 the address 4 desktop 5 the bar 6 cache, upstreams
About this topic: The setup page, for users and administrators; its scenes: page at /, read it first, the address, desktop, the bar, cache and upstreams

The page at the proxy's own address that sets up any machine, with a page per tool, the desktop entry, the status bar, and the cache and upstream lines.

The setup page is the web page pkgproxy serves at its own address, so that a machine without pkgproxy installed can start using it. If you have not seen pkgproxyctl setup, start there. You see the page and its one command for every tool, each tool's own page, the address the commands name, and opening the page from the desktop. Last come the bar every page opens with, and what the page says of the cache and the upstream servers.

02 A page at the proxy's own address

A PAGE AT / a browser GET / on :3142 the setup page $ curl -fsSL http://host:3142/setup/all | sh every tool at once each tool found on the machine · sudo only where root is needed · goes on past a failure one tool at a time: a tile for each tool whose proxy engine is turned on apt snap go docker lxd lxd-remote snapcraft rockcraft charmcraft /setup/apt curl http://host:3142/ plain text: every tool's commands on by default · snap set pkgproxy setup-page=false turns it off
A browser asks pkgproxy for / and gets the setup page: one command, curl /setup/all piped to sh, sets up every tool found on the machine; below it a tile per tool links to /setup/apt and the others; curl gets plain text

curl -fsSL http://host:3142/setup/all | sh, run as yourself; its undo is ?undo=1. Each tool's page is at /setup/<tool>. GET / is HTML for a browser, plain text for curl. -setup-page=false turns it off.

A machine without pkgproxy installed can still use it. Opened in a browser, the proxy's own address on port 3142 shows a setup page. Its first command fetches the script at /setup/all and pipes it to sh: that sets up every tool it finds on your machine, asking for sudo for those that need root, and goes on past one that fails. Below it, a tile for each tool whose proxy engine is turned on leads to that tool's own page. Curl gets plain text with every tool's commands. The setup page option turns the page off.

03 The same script, read before it runs

THE SAME SCRIPT from the setup page $ curl -fsSL http://host:3142/setup/apt #!/bin/sh { if command -v apt-get …; then mkdir -p /etc/apt/apt.conf.d && echo '…' > …/99pkgproxy && … from pkgproxyctl, piped $ pkgproxyctl setup apt | cat { if command -v apt-get …; then mkdir -p /etc/apt/apt.conf.d && echo '…' > …/99pkgproxy && … = built the same way: they cannot drift apart curl gets the script · a browser gets the tool's page: the command, the commands it runs, the undo plain HTTP: piping to sh trusts the network to the proxy, as using the proxy does
Left, the script served at /setup/apt; right, the output of pkgproxyctl setup apt when piped; they are the same lines after #!/bin/sh; a browser at the same address gets the tool's page with the commands it runs and its undo; the scripts travel over plain HTTP

/setup/apt is #!/bin/sh plus what pkgproxyctl setup apt | sh would run, as text/plain for curl; a browser gets the apt page. Minimal Debian and Ubuntu images have no curl: paste the commands instead.

Each script under /setup is the shell's first line followed by exactly what pkgproxyctl setup prints when piped: pkgproxy builds both the same way, so they cannot drift apart. Curl gets the script. A browser at the same address gets the tool's own page instead: the command, the commands it runs, to read first or to paste on a machine without curl, and how to undo it. The scripts travel over plain HTTP, so piping one to sh trusts the network between you and the proxy, as using the proxy does.

04 The address the page names for administrators

WHICH ADDRESS THE PAGE NAMES the request what the page's commands name Host: pi-drive.local:3142 http://pi-drive.local:3142/setup/apt the address the visitor just reached the proxy at Host: evil;rm -rf /:3142 http://192.0.2.9:3142/setup/apt -addr not a plain host[:port]: it would end up in a shell command, so -addr instead -public-url http://proxy.example.com:8080 Host: 192.168.0.50:3142 http://proxy.example.com:8080/setup/apt for an instance behind NAT, or reached by another name or port -public-url › Host › -addr
Three requests: a plain Host header is used in the page's commands; a Host that is not a plain host and port falls back to -addr; with -public-url set, it is used whatever the Host

-public-url http://host[:port] (snap option public-url) beats the request's Host, which beats -addr.

The commands on the page must name an address the visitor can reach, and the listen address usually cannot be that: its host is a wildcard. So the page uses the Host header the request arrived with, the address the visitor just reached the proxy at. That header ends up inside shell commands, so it is used only when it is a plain host name or IP address with an optional port; anything else falls back to the listen address. The -public-url flag overrides both, for an instance behind NAT or reached by another name.

05 Opening it from the desktop

FROM THE APPLICATIONS MENU applications menu pkgproxy pkgproxy.open pkgproxyctl open · desktop plug only stats socket pkgproxy {"addr":":3142","setup_page":true,…} retried briefly while the daemon starts http://localhost:3142/ wildcard → localhost · -public-url ignored xdg-open the browser $ pkgproxy.open pkgproxyctl error: cannot open the setup page: it is turned off. …
The applications menu entry runs pkgproxy.open, which asks the daemon for its info over the stats socket, turns the wildcard address into http://localhost:3142/ and hands it to xdg-open and the browser; a failure is printed when run in a terminal

pkgproxy.open runs pkgproxyctl open: it reads /pkgproxy/v1/info, opens http://localhost:3142/ with xdg-open, and on failure says why on stderr.

On the machine that runs it, the snap adds pkgproxy to the applications menu. The entry runs pkgproxy.open, which is pkgproxyctl open with only the desktop plug. It asks the daemon on the stats socket where it listens and whether it serves the page, retrying briefly while the daemon starts. A wildcard host becomes localhost, and the public URL is ignored, as it is meant for other machines. Then xdg-open hands the address to the desktop's browser. A menu entry has no terminal, so to see why it fails, run pkgproxy.open in one.

06 One bar on every page

ONE BAR ON EVERY PAGE pkgproxy host:3142 Home Upstreams Cache Degraded · 1 left alone online · degraded · offline Degraded for 4h49m api.snapcraft.io catalog: next try in 4m Upstream status stays current while the page is open: /pkgproxy/status every 30 seconds Degraded for 4h49m. Some upstream servers keep failing, so pkgproxy has stopped asking them for a while. It answers from its cache meanwhile. a public visitor: the state and why, no server named this machine and trusted networks: each part left alone, and a link to the upstream status
The bar at the top of every page: the pkgproxy name and address, the pages Home, Upstreams and Cache, and a status element reading Degraded; opened, it says for how long and why; a banner under the bar says what fails; a public visitor sees no server named

The status element is re-read from /pkgproxy/status every 30 seconds while the page is visible; offline shows a hollow dot, so it reads without colour. In plain text, the setup page shows a notice instead. The footer has a language switcher.

Every page pkgproxy serves opens with the same bar: its name and the address to use, the pages you may open, and a status element. The status shows the worst state pkgproxy is in: online, degraded while it leaves a failing server alone, or offline. Opened, it says for how long and why. It stays current while the page is open. While something is wrong, a banner under the bar says so too, and that what is cached is still served. Unless you are on its machine or a trusted network, neither names a server.

07 The cache and the upstream servers

THE CACHE AND THE UPSTREAMS How the upstream servers have answered, last 30 days Snap Store Go modules Other servers no other server named this machine, or a trusted network: The cache takes 12.4 GB; its disk has 180 GB free. See what is cached. Upstream servers: none failing or left alone. See the upstream status. another machine, not trusted through a proxy 404 for the cache and upstream pages
The setup page shows everyone a 30-day summary of how the snap store, Go modules, Docker Hub and other servers answered; on this machine or a trusted network it adds a line linking to the cache page and one linking to the upstream status; anyone else gets a 404 for those pages

"How the upstream servers have answered, last 30 days"; "Other servers" is shown only once three or more were asked. The lines link to /pkgproxy/cache and /pkgproxy/upstreams; a request from an untrusted network, or carrying Forwarded, Via or X-Forwarded-*, gets a 404.

Everyone who opens the page sees how the upstream servers have answered over the last thirty days, once any was asked: the snap store, Go modules, Docker Hub and the other servers summed up, with no other server named. On the machine that runs the proxy, or from a network the administrator trusts, the page has two more lines: the cache's size, linking to the cache page, and how many servers are failing, linking to the upstream status. Anyone else, or a request that came through a proxy, gets a 404 for those pages, as for any unknown path.

08 Where to go next for administrators in place of the general version

WHERE NEXT any machine sets itself up with one command you are here The setup page The cache page what the page on this machine shows Offline mode what fails while the proxy is offline pkgproxyctl setup the same scripts from the command line
Where next from The setup page: The cache page, what the page on this machine shows; Offline mode, what fails while the proxy is offline; pkgproxyctl setup, the same scripts from the command line

Next: The cache page, for what it shows; Offline mode, for what fails while offline; pkgproxyctl setup, for the same scripts from the command line.

Any machine on your network can now set itself up with one command from the page, and the page tells you when pkgproxy cannot fetch. To see what the cache page shows, watch The cache page. To see what fails while the proxy is offline, watch Offline mode. For the same scripts from the command line, watch pkgproxyctl setup.

09 Where to go next general version

WHERE NEXT any machine sets itself up with one command you are here The setup page pkgproxyctl setup the same scripts on the proxy's machine Offline mode what fails while the proxy is offline
Where next from The setup page: pkgproxyctl setup, the same scripts on the proxy's machine; Offline mode, what fails while the proxy is offline

Next: pkgproxyctl setup, for the same scripts on the proxy's machine; Offline mode, for what fails while it is offline.

Any machine on your network can now set itself up with one command from the page, and the page tells you when pkgproxy cannot fetch. For the same scripts on the proxy's own machine, watch pkgproxyctl setup. To see what fails while the proxy is offline, watch Offline mode.

Read more

What the page serves

AddressA browser getscurl gets
/The setup page: one command for every tool, a tile per tool, the 30-day summaryEvery tool's commands, as plain text
/setup/allThe scriptA script that runs, for each tool found on the machine, that tool's script; sudo only where root is needed. It goes on past a tool that fails and exits non-zero if any did.
/setup/all?undo=1The scriptThe same, undoing each tool, in the reverse order
/setup/<tool>The tool's page: the command, the commands it runs, and the undoThe tool's script
/setup/<tool>?undo=1The tool's pageThe undo script
/pkgproxy/statusThe status element alone, never cachedThe same

The tools are those whose proxy engine is turned on: apt, snap, go, docker, lxd, lxd-remote, snapcraft, rockcraft and charmcraft. /setup/all checks for each with command -v (for docker, also /var/snap/docker/current), and prints pkgproxy: <tool> before each.

Language

Every page has a language switcher in its footer. The page's language is, in order: ?lang=, the pkgproxy-lang cookie the switcher sets for a year, then the browser's Accept-Language.

Roads from here

CORE · the path every proxy engine shares

SETUP AND THE COMMAND LINE

OPERATIONS