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

▶ Watch this deck — 9 scenes, ~5 min

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 cache page 6 offline notice
About this topic: The setup page, for users and administrators; its scenes: page at /, read it first, the address, desktop, cache page, offline notice

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

A PAGE AT / a browser pkgproxy GET / on :3142 an HTML page curl http://host:3142/ the same, as plain text one section per tool, each only when its side is turned on apt snap go docker lxd lxd-remote snapcraft rockcraft charmcraft $ curl -fsSL 'http://host:3142/setup/apt' | sudo sh $ curl -fsSL 'http://host:3142/setup/apt?undo=1' | sudo sh set up undo on by default · snap set pkgproxy setup-page=false turns it off
A browser and curl ask pkgproxy for /; the browser gets an HTML page and curl plain text; the page has one section per tool, each with a curl command that pipes /setup/apt to sudo sh

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

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 served as text/plain a browser shows it · the page also lists the plain commands, to paste without curl 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; below, the page also lists the plain commands, and the scripts travel over plain HTTP

/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

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 A link to the cache page, for this machine and trusted networks

THE CACHE PAGE the setup page, opened on this machine pkgproxy This is pkgproxy, a caching proxy for … The cache takes 12.4 GB; its disk has 180 GB free. See what is cached. the cache page what is cached · what is downloading now a topic of its own: The cache page the line and the page: local visitors and trusted networks only another machine, not trusted through a proxy Via · Forwarded · X-Forwarded-* 404, as for any unknown path
On the machine that runs pkgproxy, the setup page has one line with the cache size and free space linking to the cache page, which shows what is cached and what is being downloaded; a request from another machine, unless its network is trusted, or through a proxy gets a 404

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

WHILE IT CANNOT FETCH pkgproxy upstreams offline, or some failing hosts left alone for now the setup page, above the tools This pkgproxy is leaving some upstream servers alone for now, because they recently failed or asked it to slow down. What it has cached from them is still served; … deb.debian.org: next attempt in 30s api.snapcraft.io: being tried again now Try again later or, if you need something now, undo the setup below to download directly. no command: a visitor cannot change the mode
While pkgproxy is offline or leaving failing upstream hosts alone, the setup page shows a notice above the tools: what fails, each host left alone with when it is tried again, and to try later or undo the setup; it names no command

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

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

Roads from here

CORE · the path every side shares

SETUP AND THE COMMAND LINE

OPERATIONS