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

▶ Watch this deck — 6 scenes, ~3 min

01 What this topic covers

ABOUT THIS TOPIC pkgproxyctl the command line for pkgproxy and its running daemon 1 one binary 2 the commands 3 two sockets 4 help
About this topic: pkgproxyctl, for everyone; its scenes: one binary, the commands, two sockets, help

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

ONE BINARY, TWO NAMES $ sudo install -m 755 pkgproxy-linux-amd64 /usr/local/bin/pkgproxy $ sudo ln -sf pkgproxy /usr/local/bin/pkgproxyctl the snap ships the same link pkgproxy pkgproxyctl a link to it one binary which name was I run as? the daemon the command line one binary keeps the download small: a separate client would ship much of the same code a second time
A release binary is installed as pkgproxy and ln -s adds pkgproxyctl as a link to it; the one binary runs the daemon when invoked as pkgproxy and the command line when invoked as pkgproxyctl

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

THE COMMANDS pkgproxyctl stats what is cached and how much it saved setup apt snap go docker lxd lxd-remote snapcraft rockcraft charmcraft status cache invalidate URL drop one cached apt file offline status on off mode MODE open open the setup page in your browser version this pkgproxyctl and the running pkgproxy -h at any level lists what is below it
The pkgproxyctl command tree: stats, setup with one command per client and status, cache invalidate, offline with status on off and mode, open, and version

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

TWO SOCKETS pkgproxy the running daemon stats version open setup stats.sock read only: GET and HEAD cache invalidate offline admin.sock changes the daemon snap: /var/snap/pkgproxy/common/ otherwise: /run/pkgproxy/ not on the network
stats, version, open and setup talk to pkgproxy over the read-only stats socket; cache invalidate and offline talk over the admin socket; both sockets are in the snap's common directory or /run/pkgproxy

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

ONE HELP LAYOUT $ pkgproxyctl offline mode -h Usage: pkgproxyctl offline mode [OPTIONS] MODE Set how pkgproxy uses its upstreams. MODE is one of: nevercontact upstreams as needed store-overloadedserve from the cache while … offlineserve only from the cache Available options: -keep-automatic -socket-path string pkgproxy's admin socket (default: …) names the arguments a short description options and defaults exit status 64 $ pkgproxyctl stats apt pkgproxyctl error: cannot run pkgproxyctl stats: unexpected arguments: "apt" usage first · exit status 1 in a Polish locale: Użycie: pkgproxyctl offline mode [OPCJE] TRYB
The help of pkgproxyctl offline mode: a usage line naming MODE, a description listing the modes, and the options; below, pkgproxyctl stats apt fails with an error naming the unexpected argument

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

WHERE NEXT it reads over one socket, changes over the other you are here pkgproxyctl pkgproxyctl setup set up clients with it Statistics what pkgproxyctl stats reports Offline mode what pkgproxyctl offline switches
Where next from pkgproxyctl: pkgproxyctl setup, set up clients with it; Statistics, what pkgproxyctl stats reports; Offline mode, what pkgproxyctl offline switches

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

CommandArgumentsOptionsSocketWhat it does
statsnone-json, -limit N (default 20), -r WHEN, -socket-pathstatsshows what is cached and how much downloading it saved
setup TOOLnonesee belowstats, to read -addrprints how to point a tool at pkgproxy: a guide on a terminal, a script for sh when piped
cache invalidateURL-socket-pathadminthrows away the cached copy of one apt file
offlinenone-socket-pathadminthe same as offline status
offline statusnone-socket-pathadminshows the mode and each upstream left alone for now
offline onnone-socket-pathadminserves only from the cache: the mode offline
offline offnone-socket-pathadmincontacts upstreams as needed: the mode never
offline modenever, store-overloaded or offline-keep-automatic, -socket-pathadminsets the mode
opennone-socket-pathstatsopens the setup page in the desktop's browser
versionnone-socket-pathstatsshows the version of pkgproxyctl and of the running daemon, and in the snap the snap's version and revision
  • -h at any level lists what is below it; pkgproxyctl setup -h lists the tools.
  • -r takes a Unix timestamp, an RFC 3339 time or how long ago, such as 30m or 2h.
  • -keep-automatic sets the mode that applies once the machine is online again, without ending an automatic offline; the snap's configure hook uses it.
  • -socket-path defaults to /var/snap/pkgproxy/common/stats.sock or admin.sock in the snap, and to /run/pkgproxy/stats.sock or admin.sock otherwise.
  • cache invalidate takes the http:// URL apt fetches the file from, with dists/ or pool/ in its path, such as http://deb.debian.org/debian/dists/bookworm/InRelease. Other kinds of download cannot be thrown away one by one.
  • version says so when the running daemon is another build than pkgproxyctl, and how to restart it.
  • In the snap, pkgproxy.open and the applications menu entry run pkgproxyctl open. If the shell cannot find pkgproxyctl, use pkgproxy.pkgproxyctl.

pkgproxyctl setup

ToolSets upRun the script asOptions besides -addr and -undo
aptapt's proxyrootnone
snapsnapd's store, through a systemd drop-in; restarts snapdrootnone
goGOPROXY for the userthe user-go-base-path (also -base-path), default /go
dockerDocker Hub mirror; restarts Dockerrootnone
lxda pkgproxy profile for LXD containers, or a project's default profilethe user, in the lxd group-project NAME
lxd-remotelxc image remotes through the HTTPS port, and their certificatethe user who runs lxc, not with sudo-lxd-tls-addr, -lxd-base-path (also -base-path), -lxd-remote
snapcraftthe snapcraft LXD project's build containersthe user, in the lxd groupnone
rockcraftthe rockcraft LXD project's build containersthe user, in the lxd groupnone
charmcraftthe charmcraft LXD project's build containersthe user, in the lxd groupnone
statusnothing: prints a script that reports what is set upthe user-lxd-tls-addr, -go-base-path, -lxd-base-path, -lxd-remote; no -undo
  • -addr and -lxd-tls-addr are read from the running daemon when not given; -go-base-path, -lxd-base-path and -lxd-remote are not, and default to the daemon's defaults.
  • The usual form is pkgproxyctl setup apt | sudo sh, or | sh for the tools run as the user. -undo prints the script that removes the setup.
  • The address is checked as the daemon checks its own; a bad one prints exit 1 to the pipe, so the pipe fails.
  • Each script does nothing, and succeeds, on a machine without its tool.
  • setup status reports, 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

Roads from here

CORE · the path every side shares

SETUP AND THE COMMAND LINE

OPERATIONS