The pkgproxy snap setting

component, snap, URL or none for CI operators

snap set image-garden pkgproxy= picks the pkgproxy that guests and image downloads use: the bundled daemon from the pkgproxy component (the default), a pkgproxy snap through the pkgproxy-sockets plug, one at an http URL, or none. The configure hook checks the value, starts or stops the daemon and records the choice for make; losing the pkgproxy snap falls back to the bundled one.

On the map: snap

▶ Watch this deck — 7 scenes, ~5 min

Worth seeing first

01 One setting, four answers

ONE SETTING guests bundled pkgproxy component a test suite not ready for pkgproxy's changes none the pkgproxy snap already runs here snap one pkgproxy for the whole team http://host[:port] $ snap set image-garden pkgproxy=… component, snap, a URL or none; component is the default
Guests use the bundled pkgproxy by default; a suite not ready for pkgproxy's changes picks none, a host with the pkgproxy snap picks snap, a team pkgproxy picks a URL; all through snap set image-garden pkgproxy=

snap set image-garden pkgproxy= takes component (the default), snap, http://host[:port] or none.

In the snap, guests use pkgproxy without you lifting a finger. Sometimes you want a different one, or none at all. Maybe a test suite isn't ready for the hosts entry and the snap store override that pkgproxy adds, as with snapd's own spread tests. Maybe the pkgproxy snap already runs on this machine, with a cache you'd like to share. Or your team runs one pkgproxy on the network. One snap setting covers all of it, called pkgproxy, with four kinds of value: component, the default, snap, a URL, or none. This deck shows what each one does, and what happens when you change it.

Details and sources

Details

  • The README's four commands: snap set image-garden pkgproxy=component (the default), =snap, =http://pkgproxy.example.lan:3142 and =none (README.md:211-221).
  • "none exists mainly for cases like snapd.git's spread suite, where some tests aren't yet adjusted for the injected SNAPPY_FORCE_API_URL environment variable or the extra /etc/hosts entries" (proxy/README.md:132-136).
  • true means component and false means none (configure:18-24).

02 snap set runs the configure hook

THE CONFIGURE HOOK $ snap set image-garden pkgproxy=snap configure hook 1. check the value: component, true, none, false, snap, URL pkgproxy must be component, snap, none or a URL such as http://192.0.2.1:3142 2. start the bundled service, or stop and disable it 3. pkgproxy-mode, pkgproxy-url make reads in /var/snap/image-garden/common
snap set image-garden pkgproxy=snap runs the configure hook, which checks the value and rejects others with pkgproxy must be component, snap, none or a URL; starts or stops and disables image-garden.pkgproxy; and writes pkgproxy-mode and pkgproxy-url, which make reads

The hook checks the value, starts or stops image-garden.pkgproxy, and writes pkgproxy-mode and pkgproxy-url in /var/snap/image-garden/common for make.

When you run snap set image-garden with a pkgproxy value, snapd runs the snap's configure hook, and the hook does three things. First it checks the value: component or true, none or false, snap, or an http URL with a host and maybe a port. Anything else fails, and snap set prints pkgproxy must be component, snap, none or a URL. Then it starts the bundled pkgproxy service, or stops and disables it and removes its sockets. Last, it writes the mode, and the URL if there is one, into two small files in the snap's common directory. make reads them every time it runs.

Details and sources

Details

  • The value is read with snapctl get pkgproxy and mapped to a mode: component, none, snap or external (configure:17-39). A URL must match ^http://[A-Za-z0-9.-]+(:[0-9]+)?/?$; anything else exits 1 with pkgproxy must be component, snap, none or a URL such as http://192.0.2.1:3142, which fails the snap set (derived: a failing configure hook fails the change).
  • component runs snapctl start --enable image-garden.pkgproxy; every other mode runs snapctl stop --disable and removes pkgproxy.sock, stats.sock and pkgproxy-lxd-tls.sock (configure:6-9, configure:41-74).
  • The hook writes $SNAP_COMMON/pkgproxy-mode, and $SNAP_COMMON/pkgproxy-url for a URL (without a trailing slash) or removes it (configure:76-81). make reads both at every run (010-qemu.mk:20-23).
  • The same hook also handles spread-variant; see choosing a spread.

03 The default, the bundled pkgproxy

COMPONENT, THE DEFAULT +pkgproxy component image-garden.pkgproxy a service /var/snap/image-garden/common/ pkgproxy.sock guests come in here cache/pkgproxy: apt, snap, go every user's; not trimmed $ snap logs image-garden.pkgproxy $ image-garden.pkgproxyctl stats what the cache saves set back to component: a missing +pkgproxy is reinstalled
The pkgproxy component runs as the image-garden.pkgproxy service, listening on pkgproxy.sock and caching apt, snap and go in /var/snap/image-garden/common/cache/pkgproxy; snap logs image-garden.pkgproxy and image-garden.pkgproxyctl stats inspect it; set back to component, the hook reinstalls a missing component

image-garden.pkgproxy listens on pkgproxy.sock and caches in /var/snap/image-garden/common/cache/pkgproxy. snap logs image-garden.pkgproxy, image-garden.pkgproxyctl stats.

The default, component, runs pkgproxy from the snap's own pkgproxy component, as a service. It listens on a unix socket in the snap's common directory, and keeps its cache there too, split into apt, snap and Go, and shared by every user of the machine. Nothing reclaims that space for you, so keep an eye on it. The service logs to the journal: snap logs image-garden.pkgproxy shows them. And image-garden.pkgproxyctl stats tells you what the cache saves, per snap and per apt package. If you come back to component from another mode, the hook reinstalls the component when a refresh has left it out.

Details and sources

Details

  • The service: pkgproxy -addr pkgproxy:3142 -socket-path $SNAP_COMMON/pkgproxy.sock -cache-dir $SNAP_COMMON/cache/pkgproxy -lxd-tls-socket-path $SNAP_COMMON/pkgproxy-lxd-tls.sock, daemon: simple, restart-condition: always (snapcraft.yaml:227-246). Its stats socket defaults to $SNAP_COMMON/stats.sock (snapcraft.yaml:228-231).
  • The cache is split into apt, snap and go; logs go to the journal (snap logs image-garden.pkgproxy); "there is no mechanism to reclaim used storage" (proxy/README.md:138-143).
  • image-garden.pkgproxyctl stats prints per-snap download, hit and revision counts and bandwidth saved, and the apt packages saving the most; -json and -limit N change the output (proxy/README.md:206-217).
  • Set explicitly to component or true with the component missing, the hook runs snapctl install +pkgproxy, or prints cannot install the pkgproxy component: snap install image-garden+pkgproxy; it does not do so for an unset value, during the snap's own install (configure:41-53).
  • Derived: $SNAP_COMMON is /var/snap/image-garden/common, one directory for the whole machine, kept across revisions.

04 The pkgproxy snap, through its sockets

PKGPROXY=SNAP pkgproxy snap slot sockets pkgproxy.sock image-garden snap plug pkgproxy-sockets pkgproxy-host-snap/sockets content guest QEMU's bridge $ snap connect image-garden:pkgproxy-sockets pkgproxy:sockets automatic from the store pkgproxy=snap needs the pkgproxy snap's sockets: snap connect image-garden:pkgproxy-sockets … until connected Accepted: the bundled service stops.
The pkgproxy snap's sockets slot is mounted into the image-garden snap by the pkgproxy-sockets content plug at pkgproxy-host-snap/sockets; guests reach it through the same QEMU bridge; snap connect is needed for a sideloaded snap, and without the connection the hook refuses pkgproxy=snap; the bundled service stops

snap connect image-garden:pkgproxy-sockets pkgproxy:sockets, then snap set image-garden pkgproxy=snap. The sockets appear in $SNAP_COMMON/pkgproxy-host-snap/sockets.

If the pkgproxy snap runs on the same machine, the value snap uses it instead. The two snaps meet through a content interface. The pkgproxy snap offers the directory with its sockets, and image-garden's pkgproxy-sockets plug mounts it inside its own common directory. Guests then reach that pkgproxy through the same QEMU bridge as the bundled one, so its ports play no part. snapd connects the plug by itself when both snaps come from the store. A sideloaded snap needs snap connect first. Until the plug is connected, the hook refuses, saying the mode needs the pkgproxy snap's sockets. Once it accepts, the bundled service stops.

Details and sources

Details

  • The plug: interface: content, content: pkgproxy-sockets, target: $SNAP_COMMON/pkgproxy-host-snap; snapd mounts the pkgproxy snap's sockets slot (its $SNAP_COMMON/sockets) at $SNAP_COMMON/pkgproxy-host-snap/sockets. The comment there says snapd auto-connects it for two store snaps of the same publisher, and a sideloaded snap needs snap connect image-garden:pkgproxy-sockets pkgproxy:sockets (snapcraft.yaml:254-266).
  • With mode snap, make looks for the sockets in that directory and bridges them exactly as for the bundled pkgproxy (010-qemu.mk:22-23, proxy/README.md:112-115).
  • Not connected, and the previous mode was not snap: exit 1 with pkgproxy=snap needs the pkgproxy snap's sockets: snap connect image-garden:pkgproxy-sockets pkgproxy:sockets. Accepted: the bundled service is stopped and disabled (configure:56-70).
  • Every app that may run QEMU has the plug (snapcraft.yaml:126-131).

Read more

05 When the pkgproxy snap goes away

WHEN IT GOES AWAY $ snap remove pkgproxy pkgproxy-sockets disconnected disconnect hook pkgproxy=component configure hook the bundled service starts; new systems use it Mode already snap, plug missing, as in a refresh: pkgproxy=snap, but the pkgproxy snap's sockets are not connected: guests get no pkgproxy until snap connect … a warning, not a failure
snap remove pkgproxy disconnects the plug; the disconnect hook sets pkgproxy=component and runs the configure hook, so the bundled service starts again for new systems; when the mode already was snap and the plug is missing, configure only warns that guests get no pkgproxy

Disconnecting pkgproxy-sockets sets pkgproxy=component and applies it. A mode that already was snap only warns when the plug is missing.

And if you remove the pkgproxy snap later? Removing it disconnects the plug, and snapd runs another of image-garden's hooks, the one for that disconnect. If the mode is snap, the hook sets it back to component and runs the configure hook itself, so the bundled service starts again and systems you make from then on use it. The configure hook is lenient here, too. When the mode already was snap and the plug isn't connected, as in a refresh after the pkgproxy snap went away, it doesn't fail. It warns that guests get no pkgproxy until you connect the plug again.

Details and sources

Details

  • The disconnect-plug-pkgproxy-sockets hook: with pkgproxy set to snap, it prints The pkgproxy snap's sockets are disconnected: setting pkgproxy=component, the bundled pkgproxy, runs snapctl set pkgproxy=component and then execs the configure hook, because "a snapctl set in this hook does not run the configure hook" (disconnect-plug-pkgproxy-sockets:6-15).
  • When the mode file already says snap and the plug is not connected, the configure hook prints pkgproxy=snap, but the pkgproxy snap's sockets are not connected: guests get no pkgproxy until snap connect image-garden:pkgproxy-sockets pkgproxy:sockets and carries on, so a refresh or another snap set does not fail (configure:57-68).
  • Systems made in snap mode keep the bridge to pkgproxy-host-snap/sockets in their .run script; see no rebuild.

06 A URL, or none

A URL, OR NONE $ snap set image-garden pkgproxy=http://pkgproxy.example.lan:3142 check the form stop the service pkgproxy-url make host to IPv4, per system $ snap set image-garden pkgproxy=none service stopped, no proxy image downloads follow the same choice only systems made afterwards; make old ones again
pkgproxy=http://pkgproxy.example.lan:3142: the hook checks the form, stops the bundled service and saves the URL, and make resolves the host to IPv4 each time it prepares a system; pkgproxy=none stops the service; image downloads follow the setting; only systems made afterwards use it

pkgproxy=http://pkgproxy.example.lan:3142 or pkgproxy=none. Downloads follow the setting; systems made earlier keep the old one until made again.

The last two values are simpler. A URL names a pkgproxy elsewhere, such as one your team shares: plain http, a host, and maybe a port. The hook checks its form, stops the bundled service and saves the URL. make resolves the host later, each time it prepares a system. none, or false, stops the service and leaves guests without a proxy. Whatever you pick, image downloads on the host follow the same choice. And remember that the setting only shapes systems made after you change it. A system you built before keeps what was written into it, so make its files again.

Details and sources

Details

  • A URL: http://host[:port], port 80 when none is given; the hook checks the form, stops the bundled service and saves the URL (configure:28-33, configure:71-80). make resolves the host with getent ahostsv4 when it makes a system's files, and warns cannot use pkgproxy at "URL": want http://host[:port] with a host that resolves to IPv4; guests get no pkgproxy when it cannot (010-qemu.mk:24-29).
  • none or false: the service is stopped and disabled, its sockets removed (configure:71-73).
  • Image downloads in the snap use the same pkgproxy unless PKGPROXY_URL or GARDEN_DL_PKGPROXY is set (README.md:273-278).
  • "The setting only affects instances built after the change; already provisioned VMs keep whatever cloud-init wrote at creation time" (README.md:223-226).

07 Where to go from here

ROADS pkgproxy= Reaching pkgproxy bridge or network No rebuild old systems, old choice Snap components the pkgproxy component The GitHub action pkgproxy snap or a URL Image downloads
Roads from the pkgproxy setting: how a guest reaches pkgproxy, why nothing is rebuilt, the components, the GitHub action and image downloads

Next: how a guest reaches pkgproxy, why nothing is rebuilt, the components, the GitHub action and image downloads.

So one setting picks the pkgproxy: the bundled one, the pkgproxy snap's, one at a URL, or none, and the configure hook records it for make. Next, see how make turns that record into a path a guest can follow, through QEMU's bridge or the network. Then why systems you made earlier keep their old choice. The components deck has the pkgproxy component itself. The GitHub action uses the pkgproxy snap or a URL. And image downloads follow the same setting.

Details and sources

Read more

Basis of the statements on this page

Read in the snap's hooks, snap/snapcraft.yaml, mk/010-qemu.mk and proxy/README.md of image-garden v0.8.0 ("code"). That a failing configure hook fails snap set, and where $SNAP_COMMON is, are snapd's behaviour ("derived"). Nothing was run for this page.

The values of the pkgproxy setting

snap set image-garden pkgproxy=VALUE is handled by the configure hook (configure:11-39).

ValueModeWho answers the guestsWhat the hook does
unset, true, componentcomponent (the default)the bundled pkgproxy daemon, image-garden.pkgproxyinstalls the pkgproxy component when it is missing after a refresh in another mode, then starts and enables the daemon (configure:41-55)
snapsnapthe separate pkgproxy snap, through its socketsneeds snap connect image-garden:pkgproxy-sockets pkgproxy:sockets; refuses to switch without it; stops the bundled daemon (configure:56-70)
http://host[:port]externala pkgproxy elsewherechecks the URL's form, stops the bundled daemon, saves the URL (configure:28-33)
none, falsenonenobodystops the bundled daemon and removes its sockets (configure:6-9)

The hook writes the mode to $SNAP_COMMON/pkgproxy-mode and, for a URL, the URL to $SNAP_COMMON/pkgproxy-url (configure:76-82); mk/010-qemu.mk reads both when it makes the user-data and the .run script (010-qemu.mk:20-44).

When the pkgproxy snap goes away

Disconnecting pkgproxy-sockets, as removing the pkgproxy snap does, sets pkgproxy=component and runs the configure hook again, so guests go back to the bundled pkgproxy (disconnect-plug-pkgproxy-sockets:6-15).

Things to remember

  • The setting is read when a system's files are made. Images and .run scripts made earlier keep the pkgproxy they were made with: see no rebuild.
  • In component and snap modes the guest reaches pkgproxy at 10.0.2.100:3142 through QEMU's guestfwd; with a URL, at that address: see reaching the host.
  • Image downloads use the same pkgproxy unless GARDEN_DL_PKGPROXY says otherwise: see image downloads.

Messages

WhenMessageSource
snap set with a value of another formpkgproxy must be component, snap, none or a URL such as http://192.0.2.1:3142configure:28-38
pkgproxy=snap without the plug connectedpkgproxy=snap needs the pkgproxy snap's sockets: snap connect image-garden:pkgproxy-sockets pkgproxy:socketsconfigure:63-66
a refresh or snap set with the mode already snap and the plug missing (a warning)pkgproxy=snap, but the pkgproxy snap's sockets are not connected: guests get no pkgproxy until snap connect …configure:67
the pkgproxy snap's sockets disconnectedThe pkgproxy snap's sockets are disconnected: setting pkgproxy=component, the bundled pkgproxydisconnect-plug-pkgproxy-sockets:11-14
component set again, the component cannot be installedcannot install the pkgproxy component: snap install image-garden+pkgproxyconfigure:48-53
make, a URL that does not resolvecannot use pkgproxy at "URL": want http://host[:port] with a host that resolves to IPv4; guests get no pkgproxy010-qemu.mk:29

Files in /var/snap/image-garden/common

FileWritten byWhat
pkgproxy-modethe configure hookcomponent, snap, external or none
pkgproxy-urlthe configure hook, URL mode onlythe URL, without a trailing slash
pkgproxy.sock, pkgproxy-lxd-tls.sock, stats.sockthe bundled serviceremoved when another mode is chosen
cache/pkgproxy/the bundled serviceits cache: apt, snap, go
pkgproxy-host-snap/sockets/snapd, through the pkgproxy-sockets plugthe pkgproxy snap's sockets, in snap mode

Roads from here

BUILT ON IT · CI integrations

PKGPROXY · caching for guests

SNAP · snap-only features

pkgproxy map ↗