pkgproxyctl
command line for everyone
pkgproxyctl is the pkgproxy binary under a second name, with commands for stats, setup, the cache, offline mode, the setup page and versions, talking to the daemon over a read-only stats socket and an admin socket.
On the map: setup and the command line
01 What this topic covers
pkgproxyctl is the pkgproxy binary under a second name, with a few commands that reach the daemon over two sockets.
pkgproxyctl is the command line for pkgproxy: you use it to read statistics, set up clients and change the running daemon. First you see why it is the daemon's own binary under a second name, then the commands it has, and the two sockets it uses to read from the daemon and to change it. Last comes the one layout that every command's help follows.
02 One binary, two names
pkgproxyctl is a symlink to pkgproxy, which
dispatches on the name it was invoked as. In the snap, if the shell cannot
find pkgproxyctl, use pkgproxy.pkgproxyctl.
Without the snap, every release from 0.12.0 has the binary for Linux on amd64
and arm64 on the releases page.
pkgproxyctl is not a second program. It is the pkgproxy binary under another name: the snap installs it as a symbolic link, and without the snap you make the link yourself. When the binary starts, it looks at the name it was run as. Run as pkgproxy, it is the daemon; run as pkgproxyctl, it is the command line. One binary keeps the download small: a separate client would ship much of the same code a second time.
03 The commands
pkgproxyctl -h lists the six commands; pkgproxyctl
setup -h and pkgproxyctl offline -h list theirs.
pkgproxyctl groups its commands under six names. Stats reports what is cached and how much downloading it saved. Setup holds one command per client, and status. Cache invalidate drops one cached apt file by its URL, and offline shows or changes the offline mode. Open opens the setup page in a browser, and version shows the version of pkgproxyctl and of the running daemon. The -h flag at any level lists what is below it.
04 Two sockets, one to read and one to change
stats.sock serves stats, version,
open and setup; admin.sock serves
cache and offline. Each command's
-socket-path points it elsewhere.
pkgproxyctl does not read the cache itself; it asks the running daemon over one of two UNIX sockets. The stats socket is read only, answering GET and nothing that changes anything, so stats, version, open and setup can use it without privileges. The admin socket takes the commands that change the daemon: cache invalidate and offline. Neither is on the network. In the snap both live in the snap's common directory, otherwise in /run/pkgproxy.
05 One help layout
Usage: … [OPTIONS] MODE, a description, then
Available options. A stray argument is an error, not
something to guess around.
Every command prints its help in one layout: a usage line that names its arguments, such as the mode that offline mode takes, a short description, and the options with their defaults. Help exits with status 64. A command that takes no arguments refuses stray ones rather than guessing: pkgproxyctl stats apt prints the usage, then an error naming the unexpected argument, and exits with status 1. Help and errors follow the locale, so on a Polish system they are in Polish.
06 Where to go next general version
Next: pkgproxyctl setup, to set up clients; Statistics, for what pkgproxyctl stats reports; Offline mode, for what pkgproxyctl offline switches.
With pkgproxyctl you read from the daemon over one socket, without privileges, and change it over the other. To set up clients with it, watch pkgproxyctl setup. To read what its stats command reports, watch Statistics. To switch the offline mode, watch Offline mode.
Read more
Every command
| Command | Arguments | Options | Socket | What it does |
|---|---|---|---|---|
stats | none | -json, -limit N (default 20), -r WHEN, -socket-path | stats | shows what is cached and how much downloading it saved |
setup TOOL | none | see below | stats, to read -addr | prints how to point a tool at pkgproxy: a guide on a terminal, a script for sh when piped |
cache invalidate | URL | -socket-path | admin | throws away the cached copy of one apt file |
offline | none | -socket-path | admin | the same as offline status |
offline status | none | -socket-path | admin | shows the mode and each upstream left alone for now |
offline on | none | -socket-path | admin | serves only from the cache: the mode offline |
offline off | none | -socket-path | admin | contacts upstreams as needed: the mode never |
offline mode | never, store-overloaded or offline | -keep-automatic, -socket-path | admin | sets the mode |
open | none | -socket-path | stats | opens the setup page in the desktop's browser |
version | none | -socket-path | stats | shows the version of pkgproxyctl and of the running daemon, and in the snap the snap's version and revision |
-hat any level lists what is below it;pkgproxyctl setup -hlists the tools.-rtakes a Unix timestamp, an RFC 3339 time or how long ago, such as30mor2h.-keep-automaticsets the mode that applies once the machine is online again, without ending an automatic offline; the snap's configure hook uses it.-socket-pathdefaults to/var/snap/pkgproxy/common/stats.sockoradmin.sockin the snap, and to/run/pkgproxy/stats.sockoradmin.sockotherwise.cache invalidatetakes thehttp://URL apt fetches the file from, withdists/orpool/in its path, such ashttp://deb.debian.org/debian/dists/bookworm/InRelease. Other kinds of download cannot be thrown away one by one.versionsays so when the running daemon is another build than pkgproxyctl, and how to restart it.- In the snap,
pkgproxy.openand the applications menu entry runpkgproxyctl open. If the shell cannot findpkgproxyctl, usepkgproxy.pkgproxyctl.
pkgproxyctl setup
| Tool | Sets up | Run the script as | Options besides -addr and -undo |
|---|---|---|---|
apt | apt's proxy | root | none |
snap | snapd's store, through a systemd drop-in; restarts snapd | root | none |
go | GOPROXY for the user | the user | -go-base-path (also -base-path), default /go |
docker | Docker Hub mirror; restarts Docker | root | none |
lxd | a pkgproxy profile for LXD containers, or a project's default profile | the user, in the lxd group | -project NAME |
lxd-remote | lxc image remotes through the HTTPS port, and their certificate | the user who runs lxc, not with sudo | -lxd-tls-addr, -lxd-base-path (also -base-path), -lxd-remote |
snapcraft | the snapcraft LXD project's build containers | the user, in the lxd group | none |
rockcraft | the rockcraft LXD project's build containers | the user, in the lxd group | none |
charmcraft | the charmcraft LXD project's build containers | the user, in the lxd group | none |
status | nothing: prints a script that reports what is set up | the user | -lxd-tls-addr, -go-base-path, -lxd-base-path, -lxd-remote; no -undo |
-addrand-lxd-tls-addrare read from the running daemon when not given;-go-base-path,-lxd-base-pathand-lxd-remoteare not, and default to the daemon's defaults.- The usual form is
pkgproxyctl setup apt | sudo sh, or| shfor the tools run as the user.-undoprints the script that removes the setup. - The address is checked as the daemon checks its own; a bad one prints
exit 1to the pipe, so the pipe fails. - Each script does nothing, and succeeds, on a machine without its tool.
setup statusreports, for each other tool: set up, not set up, set up for another address, needs setup again, not installed, or cannot check.
See Setting up clients for what each script writes.
Errors and exit status
- A missing or extra argument prints the usage and a
cannot …error, with exit status 1. Asking for help exits with status 64. - Help and messages follow the locale; on a Polish system they are in Polish.
In the documentation
- pkgproxy: installing it and the setup commands
- Running pkgproxy without the snap
- Which version is running
Roads from here
CORE · the path every side shares
- Offline mode — what pkgproxyctl offline switches
SETUP AND THE COMMAND LINE
- Setting up clients — the setup commands one by one
- The setup page — what pkgproxyctl open opens
OPERATIONS
- Statistics — what pkgproxyctl stats reports