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

▶ Watch this deck — 8 scenes, ~5 min

01 What this topic covers

ABOUT THIS TOPIC Settings how you change what the pkgproxy daemon does 1 one name 2 snap set 3 checked 4 restart or switch 5 not options 6 through a proxy
About this topic: Settings, for administrators and CI operators; its scenes: one name, snap set, checked, restart or switch, not options, through a proxy

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

ONE NAME revalidate-ttl -revalidate-ttl 10m a flag PKGPROXY_REVALIDATE_TTL=10m the environment snap set … revalidate-ttl=10m a snap option flag > environment > default a new flag is settable from the environment the moment it exists
One setting, revalidate-ttl, written three ways: a flag, a PKGPROXY_ environment variable and a snap option; the flag beats the environment, which beats the default

-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

SNAP OPTIONS $ sudo snap set pkgproxy revalidate-ttl=10m snapd's options pkgproxy -cache-dir $SNAP_COMMON/cache -content-socket-path … the snap's fixed command line pkgproxy-env in the daemon's command-chain snapctl get KEY, for each listed key PKGPROXY_* then exec the daemon $ sudo snap unset pkgproxy revalidate-ttl $ snap get pkgproxy unset: the default applies again
snap set stores an option in snapd; at start the pkgproxy-env wrapper reads each listed option from snapd, exports it as a PKGPROXY_ variable and runs the daemon, whose command line is fixed

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

-CHECK-CONFIG $ sudo snap set pkgproxy addr=:31x2 configure hook pkgproxy-env pkgproxy -check-config parse flags and PKGPROXY_*, then exit invalid: hook fails snapd refuses the change, and snap set prints the error, naming the setting running daemon untouched reported by snap set not a service in a restart loop
snap set runs the configure hook, which runs pkgproxy -check-config through pkgproxy-env; a bad value fails the hook and snap set reports the error while the running daemon is untouched

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

RESTART OR NOT settings the daemon would start with PKGPROXY_REVALIDATE_TTL=10m PKGPROXY_ADDR=:3142 minus PKGPROXY_OFFLINE_MODE configured.env saved by the hook's previous run =? equal: only the mode, if anything pkgproxyctl offline mode -keep-automatic MODE switched live, no restart different, missing, or that failed snapctl restart pkgproxy.pkgproxy the service restarts a stopped daemon is left alone · the new settings are saved for next time
The configure hook compares the new PKGPROXY_ settings without the offline mode against configured.env; if equal it switches the offline mode with pkgproxyctl; if different it restarts the service

$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 SNAP OPTIONS pinned on the snap's command line cache-dir content-socket-path lxd-tls-content-… sockets the snap and pkgproxyctl rely on socket-path lxd-tls-socket-path stats-/admin-socket-path: pkgproxyctl's default a shorthand, or a one-shot action offline (offline-mode is the option) check-config not offered yet snap-store-url go-upstream go-sumdb docker-upstream lxd-remote *-base-path $ sudo snap set pkgproxy cache-dir=/srv accepted, and has no effect every option and its default: the Settings table in DEPLOYMENT.md
Flags that are not snap options, grouped by reason: pinned on the snap's command line, replacing the TCP listener, a shorthand or one-shot action, and not offered yet; snap set accepts any other key and ignores it, and DEPLOYMENT.md lists the options

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

THROUGH A PROXY $ sudo snap set pkgproxy http-proxy=http://proxy.example:3128 https-proxy=… http-proxy · https-proxy · no-proxy none: off, even if /etc/environment names one /etc/environment when unset pkgproxy egress proxy Ubuntu Core: snapd writes its proxy here classic Ubuntu: snapd does not snapd's proxy.http, once snapd fetches through pkgproxy snapd egress proxy pkgproxy an error, such as 503 $ sudo snap set pkgproxy http-proxy="$(sudo snap get system proxy.http)" $ sudo snap unset system proxy.http
pkgproxy's own proxy options, http-proxy, https-proxy and no-proxy, take precedence over /etc/environment, which snapd fills on Ubuntu Core but not on classic Ubuntu; snapd's proxy.http sends its requests to pkgproxy through the proxy too, so the proxy is given to pkgproxy and unset for snapd

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

WHERE NEXT change any setting; an invalid value is refused you are here Settings Immutable or not the revalidate TTL settings Offline mode the offline-mode setting Statistics what the daemon reports
Where next from Settings: Immutable or not, the revalidate TTL settings; Offline mode, the offline-mode setting; Statistics, what the daemon reports

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:

RouteFormExample
Command line-name valuepkgproxy -revalidate-ttl 10m
EnvironmentPKGPROXY_ and the name in capitals, - as _PKGPROXY_REVALIDATE_TTL=10m
Snap optionthe name, for the options listed belowsudo 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 NAME goes back to it, and snap get pkgproxy shows what you set.
  • snap set accepts 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, 10m or 1h30m. Sizes like 8G or 500M.

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 unknown offline-mode or auto-offline word, or a bad size;
  • an addr or lxd-tls-addr that is not host:port or :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-networks entry that is neither an address nor a network, or a network of every address (0.0.0.0/0, ::/0);
  • -offline together with an -offline-mode that 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.

CaseWhat happens
The daemon is not runningnothing; the new values apply when it starts
Only offline-mode changed, or nothingpkgproxyctl offline mode -keep-automatic MODE switches the running daemon; no restart
Anything else changed, the copy is missing, or the switch failsthe 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

SettingVariableSnap optionDefaultMeaning
-addrPKGPROXY_ADDRaddr:3142address of the main HTTP port, for every client and the setup page
-lxd-tls-addrPKGPROXY_LXD_TLS_ADDRlxd-tls-addr:3143address of the HTTPS port lxc needs for image servers; off turns it off
-socket-pathPKGPROXY_SOCKET_PATHflag or environment only(none)listen on this UNIX socket instead of -addr; setup still names -addr
-lxd-tls-socket-pathPKGPROXY_LXD_TLS_SOCKET_PATHflag or environment only(none)serve HTTPS on this UNIX socket instead of -lxd-tls-addr
-content-socket-pathPKGPROXY_CONTENT_SOCKET_PATHpinned by the snap(none); snap: $SNAP_COMMON/sockets/pkgproxy.sockalso serve the main port on this UNIX socket, to share the cache with another snap
-lxd-tls-content-socket-pathPKGPROXY_LXD_TLS_CONTENT_SOCKET_PATHpinned by the snap(none); snap: $SNAP_COMMON/sockets/pkgproxy-lxd-tls.sockthe same for the HTTPS port
-stats-socket-pathPKGPROXY_STATS_SOCKET_PATHflag or environment only/run/pkgproxy/stats.sock; snap: $SNAP_COMMON/stats.sockUNIX socket that pkgproxyctl stats, open and setup read
-admin-socket-pathPKGPROXY_ADMIN_SOCKET_PATHflag or environment only/run/pkgproxy/admin.sock; snap: $SNAP_COMMON/admin.sockUNIX socket that pkgproxyctl cache and offline change pkgproxy through
-setup-pagePKGPROXY_SETUP_PAGEsetup-pagetrueserve the setup page at / and its scripts under /setup/; false also hides the applications menu entry
-public-urlPKGPROXY_PUBLIC_URLpublic-url(the address the visitor used)http://host[:port] the setup page tells visitors to use
-trusted-networksPKGPROXY_TRUSTED_NETWORKStrusted-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-timeoutPKGPROXY_READ_HEADER_TIMEOUTread-header-timeout30show long a client may take to send its request headers
-shutdown-gracePKGPROXY_SHUTDOWN_GRACEshutdown-grace10show long requests in progress get to finish when pkgproxy stops

See One listener for what each port and socket answers.

Cache and downloads

SettingVariableSnap optionDefaultMeaning
-cache-dirPKGPROXY_CACHE_DIRpinned by the snap/var/cache/pkgproxy; snap: $SNAP_COMMON/cachedirectory 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-timeoutPKGPROXY_FILL_DRAIN_TIMEOUTfill-drain-timeout10mhow 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-metadataPKGPROXY_CACHE_METADATAcache-metadataxattrwhere 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-timeoutPKGPROXY_UPSTREAM_IDLE_TIMEOUTupstream-idle-timeout1mhow long an upstream may send nothing before its request fails; 0 waits forever
-upstream-retry-forPKGPROXY_UPSTREAM_RETRY_FORupstream-retry-for2mhow 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-intervalPKGPROXY_STATS_CHECKPOINT_INTERVALstats-checkpoint-interval30show often statistics are saved; a crash loses what changed since
-lxd-checkpoint-intervalPKGPROXY_LXD_CHECKPOINT_INTERVALlxd-checkpoint-interval30show often LXD image file hashes are saved

See The store and Stalled upstreams.

Freshness

SettingVariableSnap optionDefaultMeaning
-revalidate-ttlPKGPROXY_REVALIDATE_TTLrevalidate-ttl5mhow long what changes is served before it is checked again, for every side without its own value
-apt-revalidate-ttlPKGPROXY_APT_REVALIDATE_TTLapt-revalidate-ttlrevalidate-ttlthe same, apt indexes alone
-snap-revalidate-ttlPKGPROXY_SNAP_REVALIDATE_TTLsnap-revalidate-ttlrevalidate-ttlthe same, snap details and assertions alone
-go-revalidate-ttlPKGPROXY_GO_REVALIDATE_TTLgo-revalidate-ttlrevalidate-ttlthe same, Go module version lists alone
-docker-revalidate-ttlPKGPROXY_DOCKER_REVALIDATE_TTLdocker-revalidate-ttlrevalidate-ttlthe same, Docker image tags alone
-lxd-revalidate-ttlPKGPROXY_LXD_REVALIDATE_TTLlxd-revalidate-ttlrevalidate-ttlthe same, LXD image lists alone
-min-forced-revalidate-intervalPKGPROXY_MIN_FORCED_REVALIDATE_INTERVALmin-forced-revalidate-interval30show 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

SettingVariableSnap optionDefaultMeaning
-offline-modePKGPROXY_OFFLINE_MODEoffline-modestore-overloadedstore-overloaded, never or offline; switch at run time with pkgproxyctl offline. The default was never up to 0.12.0
-offlinePKGPROXY_OFFLINEflag or environment only(unset)short for -offline-mode offline; -offline=false is -offline-mode never
-auto-offlinePKGPROXY_AUTO_OFFLINEauto-offlinenetwork on Linux, off elsewhereoff, network (no network, airplane mode included) or airplane-mode (all radios off)

See Offline mode.

Upstreams and paths

SettingVariableSnap optionDefaultMeaning
-snap-store-urlPKGPROXY_SNAP_STORE_URLflag or environment onlyhttps://api.snapcraft.ioSnap Store API that snaps and assertions come from
-snap-external-urlPKGPROXY_SNAP_EXTERNAL_URLflag or environment only(the address the client used)http://host[:port] put in the download links handed to snapd
-go-upstreamPKGPROXY_GO_UPSTREAMflag or environment onlyhttps://proxy.golang.orgGo module proxy that modules come from
-go-sumdbPKGPROXY_GO_SUMDBflag or environment onlysum.golang.orgchecksum database modules are checked against before they are cached; off caches them unchecked
-go-base-pathPKGPROXY_GO_BASE_PATHflag or environment only/goURL path of the Go module proxy
-docker-upstreamPKGPROXY_DOCKER_UPSTREAMflag or environment onlyhttps://registry-1.docker.ioregistry Docker Hub images come from; off turns the mirror off
-lxd-remotePKGPROXY_LXD_REMOTEflag or environment onlyfive remotes, see LXD image serversname=url of an image server to cache; repeatable; name= drops a default; off caches none
-lxd-base-pathPKGPROXY_LXD_BASE_PATHflag or environment only/lxdURL 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

SettingVariableSnap optionDefaultMeaning
-files-allow-hostPKGPROXY_FILES_ALLOW_HOSTfiles-allow-host(empty: every host)comma-separated hosts files may come from; .example.org allows every host under it; * allows all
-files-allow-networkPKGPROXY_FILES_ALLOW_NETWORKfiles-allow-network(empty)comma-separated private networks in CIDR form that files may come from; other private addresses are refused
-files-max-sizePKGPROXY_FILES_MAX_SIZEfiles-max-size8Glargest 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 optionVariablesUnsetMeaning
http-proxyHTTP_PROXY, http_proxyhttp_proxy of /etc/environmentproxy for http:// mirrors and registries; none for no proxy
https-proxyHTTPS_PROXY, https_proxyhttps_proxy of /etc/environmentthe same, for https://
no-proxyNO_PROXY, no_proxyno_proxy of /etc/environmenthosts and networks reached without the proxy, such as .example.com,10.0.0.0/8; none for no exceptions
  • snap set refuses a proxy that is not an http:// or https:// URL, and a change restarts pkgproxy.
  • On Ubuntu Core, snapd writes its own proxy.http and proxy.https into /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

Roads from here

CORE · the path every side shares

FILES

OPERATIONS