Settings
operations for administrators for CI operators
How every daemon setting is one name set by a flag, a PKGPROXY_ environment variable or a snap option, with flag over environment over default, checked before it applies, applied by the snap's configure hook with a restart or a live offline switch, and how the daemon is given an egress proxy.
On the map: operations
01 What this topic covers
Every daemon setting is one name, set by a flag, an environment variable or a snap option, checked before it applies.
Settings are how you change what the pkgproxy daemon does, such as how long it trusts a list or where it listens. You see that each setting has one name you can set three ways, how snap set reaches the daemon's environment, and the check before a change applies. Then come the restart or live switch that follows, what is deliberately not a snap option, and how the daemon reaches the internet through a proxy.
02 One name, three ways to set it
-revalidate-ttl 10m,
PKGPROXY_REVALIDATE_TTL=10m and snap set pkgproxy
revalidate-ttl=10m set one setting. Precedence: flag, then
environment, then default.
Every daemon setting has one name and three ways to set it. On the command line it is a flag, such as the -revalidate-ttl flag. In the environment it is the same name in capitals, with dashes turned into underscores, prefixed with pkgproxy and an underscore. In the snap it is a snap option of the same name. A flag wins over the environment, and the environment over the built in default. The rule is generic, so a new flag can be set from the environment the moment it exists.
03 From snap set to the environment
pkgproxy-env runs snapctl get for each key it
lists and exports PKGPROXY_*, then execs the daemon.
snap unset pkgproxy KEY restores the default.
Snapd keeps snap options where only the snap can read them, and the daemon's command line is fixed. So the snap starts pkgproxy through a small wrapper, pkgproxy-env, in its command chain. It asks snapd for each option on a fixed list, exports each one that is set as the matching environment variable, and runs the daemon. An unset option is left out, so the daemon's own default applies. Snap unset goes back to the default, and snap get shows what you have set.
04 Checked before it applies
The configure hook runs pkgproxy-env pkgproxy -check-config.
A bad value fails snap set; the daemon is not touched.
When you run snap set, the configure hook first runs the daemon with the check config flag, through the same wrapper. It parses every flag and variable, listen addresses included, and exits without starting. An invalid value fails the hook, and snapd refuses the change, so a typo is reported by snap set instead of putting the service into a restart loop. Without the snap, pkgproxy refuses to start on an invalid value and says which one.
05 Restart, or switch the running daemon
$SNAP_DATA/configured.env holds the last
PKGPROXY_* set minus PKGPROXY_OFFLINE_MODE. Same:
pkgproxyctl offline mode -keep-automatic. Different:
snapctl restart.
The hook cannot ask snapd which options changed. Instead it builds the environment the daemon would start with, leaves out the offline mode, and compares it with configured.env, the copy its previous run saved. If they are equal, at most the offline mode changed, and the hook switches the running daemon with pkgproxyctl offline mode, keeping any automatic offline in place. If they differ, the copy is missing, or that command fails, the hook restarts the service. A stopped daemon is left alone.
06 What is not a snap option for administrators
Not options: cache-dir, the socket paths,
check-config, offline, the upstream URLs, the
base paths, lxd-remote, go-sumdb.
snap set accepts any other key and ignores it; the Settings
table in DEPLOYMENT.md lists the options.
Some flags are deliberately not snap options. The cache directory and the content sockets are pinned on the snap's command line, and a flag beats the environment. The socket path flags would replace the TCP listener the snap's interfaces and setup commands rely on. The offline flag is only short for offline mode, and the upstream and base path flags are not offered yet. Snap set accepts any key, but one that is not an option has no effect. The settings table in the deployment guide lists every option and its default.
07 Reaching the internet through a proxy
http-proxy, https-proxy, no-proxy:
over /etc/environment, none for off, a restart
to apply. Then snap unset system proxy.http, so snapd reaches
pkgproxy directly.
On a network that reaches the internet only through a proxy, pkgproxy needs that proxy too. Its snap has the http-proxy, https-proxy and no-proxy options for it, where none turns one off. Unset, pkgproxy uses the proxy variables in /etc/environment. Snapd writes its own proxy there on Ubuntu Core, but not on classic Ubuntu. Snapd's proxy setting also gets in the way once snapd fetches through pkgproxy, because snapd then sends those requests through the proxy as well. So give pkgproxy the proxy first, then unset it for snapd.
08 Where to go next general version
Next: Immutable or not, for the TTL settings; Offline mode, for the offline-mode setting; Statistics, for what the daemon reports.
You can now change any setting with a flag, an environment variable or snap set, and an invalid value is refused instead of applied. For the settings that say how long lists are trusted, watch Immutable or not. For the offline mode setting, watch Offline mode. To see what the daemon then reports, watch Statistics.
Read more
How a value is chosen
Every setting is one name, such as revalidate-ttl. It is set by:
| Route | Form | Example |
|---|---|---|
| Command line | -name value | pkgproxy -revalidate-ttl 10m |
| Environment | PKGPROXY_ and the name in capitals, - as _ | PKGPROXY_REVALIDATE_TTL=10m |
| Snap option | the name, for the options listed below | sudo snap set pkgproxy revalidate-ttl=10m |
- A flag on the command line wins over the environment, which wins over the built-in default. An empty variable counts as unset.
- The snap turns each snap option that is set into its variable before the daemon starts. An unset option is left out, so the default applies;
sudo snap unset pkgproxy NAMEgoes back to it, andsnap get pkgproxyshows what you set. snap setaccepts any key. A key that is not a snap option below is stored and has no effect.- An error about a value names the variable when the environment, and so a snap option, set it, and the flag otherwise.
- Times are written like
90s,10mor1h30m. Sizes like8Gor500M.
Checking a value: -check-config
pkgproxy -check-config reads every flag and PKGPROXY_* variable, checks them and exits without starting the daemon. The snap's configure hook runs it on every snap set, so a bad value fails snap set and the running daemon is not touched. It refuses:
- a value a setting cannot parse, such as
revalidate-ttl=ten, an unknownoffline-modeorauto-offlineword, or a bad size; - an
addrorlxd-tls-addrthat is nothost:portor:port, a port outside 0 to 65535, or a host that is neither an IP address nor a host name (whether the name resolves is found only when the daemon starts); - a
revalidate-ttl, or one side's TTL, of zero or less; - a
trusted-networksentry that is neither an address nor a network, or a network of every address (0.0.0.0/0,::/0); -offlinetogether with an-offline-modethat names a different mode;- an argument after the options.
Migrating a 0.11 cache: -migrate-cache
pkgproxy -migrate-cache copies the .meta.json file of each file pkgproxy 0.11 cached into the file's extended attribute, keeps the .meta.json files, prints how many it migrated, and exits without starting the daemon. It stops after -migrate-cache-timeout (2m); a file it did not reach still works. The snap runs it after every refresh and keeps its output in /var/snap/pkgproxy/current/migrate-cache.log. Without the snap, nothing requires it. See The store.
for administrators
After snap set
The configure hook compares the settings the daemon would start with, the proxy options included and offline-mode left out, with the copy it saved last time in /var/snap/pkgproxy/current/configured.env.
| Case | What happens |
|---|---|
| The daemon is not running | nothing; the new values apply when it starts |
Only offline-mode changed, or nothing | pkgproxyctl offline mode -keep-automatic MODE switches the running daemon; no restart |
| Anything else changed, the copy is missing, or the switch fails | the service restarts |
pkgproxyctl offline also writes offline-mode back as a snap option, without running the hook, so the mode survives a restart.
Listening and the setup page
| Setting | Variable | Snap option | Default | Meaning |
|---|---|---|---|---|
-addr | PKGPROXY_ADDR | addr | :3142 | address of the main HTTP port, for every client and the setup page |
-lxd-tls-addr | PKGPROXY_LXD_TLS_ADDR | lxd-tls-addr | :3143 | address of the HTTPS port lxc needs for image servers; off turns it off |
-socket-path | PKGPROXY_SOCKET_PATH | flag or environment only | (none) | listen on this UNIX socket instead of -addr; setup still names -addr |
-lxd-tls-socket-path | PKGPROXY_LXD_TLS_SOCKET_PATH | flag or environment only | (none) | serve HTTPS on this UNIX socket instead of -lxd-tls-addr |
-content-socket-path | PKGPROXY_CONTENT_SOCKET_PATH | pinned by the snap | (none); snap: $SNAP_COMMON/sockets/pkgproxy.sock | also serve the main port on this UNIX socket, to share the cache with another snap |
-lxd-tls-content-socket-path | PKGPROXY_LXD_TLS_CONTENT_SOCKET_PATH | pinned by the snap | (none); snap: $SNAP_COMMON/sockets/pkgproxy-lxd-tls.sock | the same for the HTTPS port |
-stats-socket-path | PKGPROXY_STATS_SOCKET_PATH | flag or environment only | /run/pkgproxy/stats.sock; snap: $SNAP_COMMON/stats.sock | UNIX socket that pkgproxyctl stats, open and setup read |
-admin-socket-path | PKGPROXY_ADMIN_SOCKET_PATH | flag or environment only | /run/pkgproxy/admin.sock; snap: $SNAP_COMMON/admin.sock | UNIX socket that pkgproxyctl cache and offline change pkgproxy through |
-setup-page | PKGPROXY_SETUP_PAGE | setup-page | true | serve the setup page at / and its scripts under /setup/; false also hides the applications menu entry |
-public-url | PKGPROXY_PUBLIC_URL | public-url | (the address the visitor used) | http://host[:port] the setup page tells visitors to use |
-trusted-networks | PKGPROXY_TRUSTED_NETWORKS | trusted-networks | (none: this machine only) | networks in CIDR notation, separated by commas, such as 192.168.0.0/24,fd00::/8, whose visitors see the cache page and what the cache holds as visitors on this machine do; see The cache page |
-read-header-timeout | PKGPROXY_READ_HEADER_TIMEOUT | read-header-timeout | 30s | how long a client may take to send its request headers |
-shutdown-grace | PKGPROXY_SHUTDOWN_GRACE | shutdown-grace | 10s | how long requests in progress get to finish when pkgproxy stops |
See One listener for what each port and socket answers.
Cache and downloads
| Setting | Variable | Snap option | Default | Meaning |
|---|---|---|---|---|
-cache-dir | PKGPROXY_CACHE_DIR | pinned by the snap | /var/cache/pkgproxy; snap: $SNAP_COMMON/cache | directory that holds the cache and the LXD certificate; it must be on a file system that keeps extended attributes (ext4, XFS, btrfs, ZFS, tmpfs from Linux 6.6), or pkgproxy refuses to start; see The store |
-fill-drain-timeout | PKGPROXY_FILL_DRAIN_TIMEOUT | fill-drain-timeout | 10m | how long a failed-hash download of an apt package, snap or LXD image keeps going to clients already receiving it; Docker layers and files are cut short |
-cache-metadata | PKGPROXY_CACHE_METADATA | cache-metadata | xattr | where pkgproxy writes what it knows of each cached file: xattr to the file's extended attribute, and to a .meta.json file beside it so that going back to 0.11 keeps the cache; meta-json to the .meta.json files alone, as 0.11 did, only to test the migration of such a cache |
-upstream-idle-timeout | PKGPROXY_UPSTREAM_IDLE_TIMEOUT | upstream-idle-timeout | 1m | how long an upstream may send nothing before its request fails; 0 waits forever |
-upstream-retry-for | PKGPROXY_UPSTREAM_RETRY_FOR | upstream-retry-for | 2m | how long after an upstream last sent a byte of a snap, LXD image or file by checksum that broke off pkgproxy still asks it for the rest; 0 never asks again |
-stats-checkpoint-interval | PKGPROXY_STATS_CHECKPOINT_INTERVAL | stats-checkpoint-interval | 30s | how often statistics are saved; a crash loses what changed since |
-lxd-checkpoint-interval | PKGPROXY_LXD_CHECKPOINT_INTERVAL | lxd-checkpoint-interval | 30s | how often LXD image file hashes are saved |
See The store and Stalled upstreams.
Freshness
| Setting | Variable | Snap option | Default | Meaning |
|---|---|---|---|---|
-revalidate-ttl | PKGPROXY_REVALIDATE_TTL | revalidate-ttl | 5m | how long what changes is served before it is checked again, for every side without its own value |
-apt-revalidate-ttl | PKGPROXY_APT_REVALIDATE_TTL | apt-revalidate-ttl | revalidate-ttl | the same, apt indexes alone |
-snap-revalidate-ttl | PKGPROXY_SNAP_REVALIDATE_TTL | snap-revalidate-ttl | revalidate-ttl | the same, snap details and assertions alone |
-go-revalidate-ttl | PKGPROXY_GO_REVALIDATE_TTL | go-revalidate-ttl | revalidate-ttl | the same, Go module version lists alone |
-docker-revalidate-ttl | PKGPROXY_DOCKER_REVALIDATE_TTL | docker-revalidate-ttl | revalidate-ttl | the same, Docker image tags alone |
-lxd-revalidate-ttl | PKGPROXY_LXD_REVALIDATE_TTL | lxd-revalidate-ttl | revalidate-ttl | the same, LXD image lists alone |
-min-forced-revalidate-interval | PKGPROXY_MIN_FORCED_REVALIDATE_INTERVAL | min-forced-revalidate-interval | 30s | how soon after a check an apt index is still served from the cache when a client asks for a fresh copy |
Every TTL must be longer than zero. See Immutable or revalidated.
Offline
| Setting | Variable | Snap option | Default | Meaning |
|---|---|---|---|---|
-offline-mode | PKGPROXY_OFFLINE_MODE | offline-mode | store-overloaded | store-overloaded, never or offline; switch at run time with pkgproxyctl offline. The default was never up to 0.12.0 |
-offline | PKGPROXY_OFFLINE | flag or environment only | (unset) | short for -offline-mode offline; -offline=false is -offline-mode never |
-auto-offline | PKGPROXY_AUTO_OFFLINE | auto-offline | network on Linux, off elsewhere | off, network (no network, airplane mode included) or airplane-mode (all radios off) |
See Offline mode.
Upstreams and paths
| Setting | Variable | Snap option | Default | Meaning |
|---|---|---|---|---|
-snap-store-url | PKGPROXY_SNAP_STORE_URL | flag or environment only | https://api.snapcraft.io | Snap Store API that snaps and assertions come from |
-snap-external-url | PKGPROXY_SNAP_EXTERNAL_URL | flag or environment only | (the address the client used) | http://host[:port] put in the download links handed to snapd |
-go-upstream | PKGPROXY_GO_UPSTREAM | flag or environment only | https://proxy.golang.org | Go module proxy that modules come from |
-go-sumdb | PKGPROXY_GO_SUMDB | flag or environment only | sum.golang.org | checksum database modules are checked against before they are cached; off caches them unchecked |
-go-base-path | PKGPROXY_GO_BASE_PATH | flag or environment only | /go | URL path of the Go module proxy |
-docker-upstream | PKGPROXY_DOCKER_UPSTREAM | flag or environment only | https://registry-1.docker.io | registry Docker Hub images come from; off turns the mirror off |
-lxd-remote | PKGPROXY_LXD_REMOTE | flag or environment only | five remotes, see LXD image servers | name=url of an image server to cache; repeatable; name= drops a default; off caches none |
-lxd-base-path | PKGPROXY_LXD_BASE_PATH | flag or environment only | /lxd | URL path image servers are served under, each at /lxd/NAME |
apt has no upstream setting: apt names its mirror in each request.
Files by checksum
| Setting | Variable | Snap option | Default | Meaning |
|---|---|---|---|---|
-files-allow-host | PKGPROXY_FILES_ALLOW_HOST | files-allow-host | (empty: every host) | comma-separated hosts files may come from; .example.org allows every host under it; * allows all |
-files-allow-network | PKGPROXY_FILES_ALLOW_NETWORK | files-allow-network | (empty) | comma-separated private networks in CIDR form that files may come from; other private addresses are refused |
-files-max-size | PKGPROXY_FILES_MAX_SIZE | files-max-size | 8G | largest file fetched; 0 means no limit |
See Files by checksum.
Reaching the internet through a proxy
These are snap options without flags. The snap exports them as the standard variables, upper and lower case, for pkgproxy alone; without the snap, set those variables in pkgproxy's environment.
| Snap option | Variables | Unset | Meaning |
|---|---|---|---|
http-proxy | HTTP_PROXY, http_proxy | http_proxy of /etc/environment | proxy for http:// mirrors and registries; none for no proxy |
https-proxy | HTTPS_PROXY, https_proxy | https_proxy of /etc/environment | the same, for https:// |
no-proxy | NO_PROXY, no_proxy | no_proxy of /etc/environment | hosts and networks reached without the proxy, such as .example.com,10.0.0.0/8; none for no exceptions |
snap setrefuses a proxy that is not anhttp://orhttps://URL, and a change restarts pkgproxy.- On Ubuntu Core, snapd writes its own
proxy.httpandproxy.httpsinto/etc/environment; on classic Ubuntu it does not, so pkgproxy has no proxy there unless one of these is set. - The proxy may be on loopback or the local network; files by checksum still refuse a client's request for that address.
- The tunnels for apt's
https://sources connect directly and do not use the proxy.
In the documentation
- Changing settings
- Settings: every setting with its default
- Reaching the internet through a proxy
Roads from here
CORE · the path every side shares
- Immutable or revalidated — the TTL settings
- Stalled upstreams — the timeout settings
- Offline mode — the offline-mode setting
- One listener — addr and the sockets
FILES
- Files by checksum — the files settings
OPERATIONS
- Statistics — what the daemon reports