The setup page
remote machines for users for administrators
The daemon serves a page at / that tells any machine how to use it, with setup scripts under /setup/, a notice while it cannot fetch, and on its own machine and trusted networks a link to the cache page.
On the map: setup and the command line
01 What this topic covers
The page at the proxy's own address that sets up any machine, with the desktop entry, the link to the cache page and the offline notice.
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 scripts, why you can read a script first, the address the commands name, and opening the page from the desktop. Last come the link to the cache page and the notice shown while pkgproxy cannot fetch.
02 A page at the proxy's own address
GET / is HTML for a browser and plain text for curl. Each
tool's script is at /setup/<tool>, its undo at
?undo=1. -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, and curl gets the same page as plain text. It has a section for each tool whose side is turned on, and each section gives one command that fetches a script from /setup and pipes it to sh, with the undo command beside it. The page is on by default; the setup page option turns it off.
03 The same script, read before it runs
/setup/apt is #!/bin/sh plus what
pkgproxyctl setup apt | sh would run, served as
text/plain. 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. It is served as plain text, so a browser shows it to be read rather than downloading it, and the page lists the same commands under each one liner, for pasting on a machine without curl. 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
-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
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 A link to the cache page, for this machine and trusted networks
The line links to /pkgproxy/cache, at the address the visitor
used. A request from another machine, unless
trusted-networks names its network, or carrying Forwarded,
Via or X-Forwarded-*, gets a 404.
On the machine that runs the proxy, the setup page carries one more line: the cache's size and its disk's free space, linking to the cache page, which shows what the cache holds and what is being downloaded right now. It has a topic of its own. Only a local visitor sees the line or the page, or one from a network the administrator trusts. Anyone else, or a request that came through a proxy, gets a 404 for the cache page, as for any unknown path.
07 A notice while the proxy cannot fetch
Shown in the offline mode offline, while the machine has no
network or is in airplane mode, and in store-overloaded while
some upstream host is left alone. It is rendered without JavaScript.
While pkgproxy is not going upstream, because it is offline or is leaving some failing upstream servers alone, the setup page shows a notice above the tools. It says what fails, names each host left alone and when it is tried again, and suggests trying later, or undoing the setup to download directly. It names no command, since a visitor cannot change the mode.
08 Where to go next for administrators in place of the general version
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
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
In the documentation
Roads from here
CORE · the path every side shares
- Offline mode — the notice the page shows while offline
SETUP AND THE COMMAND LINE
- Setting up clients — the same scripts from pkgproxyctl setup
- pkgproxyctl — pkgproxyctl open and the stats socket
OPERATIONS
- The cache page — what the cache page shows