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
- What pkgproxy gives a garden — what pkgproxy caches and why guests use it
01 One setting, four answers
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:3142and=none(README.md:211-221). - "
noneexists mainly for cases like snapd.git's spread suite, where some tests aren't yet adjusted for the injectedSNAPPY_FORCE_API_URLenvironment variable or the extra/etc/hostsentries" (proxy/README.md:132-136). truemeanscomponentandfalsemeansnone(configure:18-24).
Read more
02 snap set runs the configure hook
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 pkgproxyand mapped to a mode:component,none,snaporexternal(configure:17-39). A URL must match^http://[A-Za-z0-9.-]+(:[0-9]+)?/?$; anything else exits 1 withpkgproxy must be component, snap, none or a URL such as http://192.0.2.1:3142, which fails thesnap set(derived: a failing configure hook fails the change). componentrunssnapctl start --enable image-garden.pkgproxy; every other mode runssnapctl stop --disableand removespkgproxy.sock,stats.sockandpkgproxy-lxd-tls.sock(configure:6-9, configure:41-74).- The hook writes
$SNAP_COMMON/pkgproxy-mode, and$SNAP_COMMON/pkgproxy-urlfor 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.
Read more
03 The default, the bundled pkgproxy
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,snapandgo; 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 statsprints per-snap download, hit and revision counts and bandwidth saved, and the apt packages saving the most;-jsonand-limit Nchange the output (proxy/README.md:206-217).- Set explicitly to
componentortruewith the component missing, the hook runssnapctl install +pkgproxy, or printscannot 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_COMMONis/var/snap/image-garden/common, one directory for the whole machine, kept across revisions.
Read more
04 The pkgproxy snap, through its sockets
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'ssocketsslot (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 needssnap 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 withpkgproxy=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
- A socket, through guestfwd, the GitHub action, which connects the plug and sets this mode.
- Optional: the snapd map's content interface.
05 When the pkgproxy snap goes away
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-socketshook: withpkgproxyset tosnap, it printsThe pkgproxy snap's sockets are disconnected: setting pkgproxy=component, the bundled pkgproxy, runssnapctl set pkgproxy=componentand then execs the configure hook, because "asnapctl setin this hook does not run the configure hook" (disconnect-plug-pkgproxy-sockets:6-15). - When the mode file already says
snapand the plug is not connected, the configure hook printspkgproxy=snap, but the pkgproxy snap's sockets are not connected: guests get no pkgproxy until snap connect image-garden:pkgproxy-sockets pkgproxy:socketsand carries on, so a refresh or anothersnap setdoes not fail (configure:57-68). - Systems made in
snapmode keep the bridge topkgproxy-host-snap/socketsin their.runscript; see no rebuild.
Read more
06 A URL, or none
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 withgetent ahostsv4when it makes a system's files, and warnscannot use pkgproxy at "URL": want http://host[:port] with a host that resolves to IPv4; guests get no pkgproxywhen it cannot (010-qemu.mk:24-29). noneorfalse: the service is stopped and disabled, its sockets removed (configure:71-73).- Image downloads in the snap use the same pkgproxy unless
PKGPROXY_URLorGARDEN_DL_PKGPROXYis 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).
Read more
07 Where to go from here
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
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).
| Value | Mode | Who answers the guests | What the hook does |
|---|---|---|---|
unset, true, component | component (the default) | the bundled pkgproxy daemon, image-garden.pkgproxy | installs the pkgproxy component when it is missing after a refresh in another mode, then starts and enables the daemon (configure:41-55) |
snap | snap | the separate pkgproxy snap, through its sockets | needs snap connect image-garden:pkgproxy-sockets pkgproxy:sockets; refuses to switch without it; stops the bundled daemon (configure:56-70) |
http://host[:port] | external | a pkgproxy elsewhere | checks the URL's form, stops the bundled daemon, saves the URL (configure:28-33) |
none, false | none | nobody | stops 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
.runscripts 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:3142through QEMU'sguestfwd; with a URL, at that address: see reaching the host. - Image downloads use the same pkgproxy unless
GARDEN_DL_PKGPROXYsays otherwise: see image downloads.
Messages
| When | Message | Source |
|---|---|---|
snap set with a value of another form | pkgproxy must be component, snap, none or a URL such as http://192.0.2.1:3142 | configure:28-38 |
pkgproxy=snap without the plug connected | pkgproxy=snap needs the pkgproxy snap's sockets: snap connect image-garden:pkgproxy-sockets pkgproxy:sockets | configure: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 disconnected | The pkgproxy snap's sockets are disconnected: setting pkgproxy=component, the bundled pkgproxy | disconnect-plug-pkgproxy-sockets:11-14 |
component set again, the component cannot be installed | cannot install the pkgproxy component: snap install image-garden+pkgproxy | configure:48-53 |
| make, a URL that does not resolve | cannot use pkgproxy at "URL": want http://host[:port] with a host that resolves to IPv4; guests get no pkgproxy | 010-qemu.mk:29 |
Files in /var/snap/image-garden/common
| File | Written by | What |
|---|---|---|
pkgproxy-mode | the configure hook | component, snap, external or none |
pkgproxy-url | the configure hook, URL mode only | the URL, without a trailing slash |
pkgproxy.sock, pkgproxy-lxd-tls.sock, stats.sock | the bundled service | removed when another mode is chosen |
cache/pkgproxy/ | the bundled service | its cache: apt, snap, go |
pkgproxy-host-snap/sockets/ | snapd, through the pkgproxy-sockets plug | the pkgproxy snap's sockets, in snap mode |
Roads from here
BUILT ON IT · CI integrations
- image-garden-action for GitHub — the GitHub action, which uses the pkgproxy snap or a URL
PKGPROXY · caching for guests
- How a guest reaches pkgproxy — how make turns the recorded choice into a path for the guest
- Changing the proxy does not rebuild — why systems made earlier keep the old choice, and what to make again
- Cloud images through pkgproxy — image downloads, which follow the same setting
SNAP · snap-only features
- Snap components — the pkgproxy component that the default runs from
- The image-garden snap — the rest of the snap
pkgproxy map ↗
- Snap Store relay — on the pkgproxy map, the Snap Store relay guests use