CUPT.CONF(5)

📦
version 2.10.4 · 4 versions
, in ubuntu noble, ubuntu resolute

okay so bestie, this is the man page for cupt.conf — aka CUPT.CONF(5) if you're being formal about it — and it's literally the entire vibe guide to how Cupt's config file works. grab a snack, we're going through all of it. 💖

🎀 NAME 🎀

cupt.conf — the configuration file for Cupt. that's it, that's the name, periodt. 💅

✨ SYNOPSIS ✨

$APT_CONFIG, /etc/apt/apt.conf, /etc/apt/apt.conf.d/*, $CUPT_PRE_CONFIG,
/etc/cupt/pre.conf, /etc/cupt/cupt.conf, /etc/cupt/cupt.conf.d/*

🦋 DESCRIPTION 🦋

Cupt uses the exact same configuration syntax as apt.conf(5) — which see. and when I say same, I mean identical, no new grammar, no plot twist. if you already know apt config syntax you are already slaying this file. 🫶

👑 CONFIGURATION VARIABLES 👑

🍓 the APT ones first (we're borrowing, and we're grateful) 🍓

Firstly, Cupt reads all of these APT configuration variables:

acquire::*::dl-limit, acquire::*::timeout, acquire::*::proxy,
acquire::http::allowredirect, acquire::retries, apt::cache::allversions,
apt::cache::important, apt::cache::namesonly,
apt::cache::recursedepends, apt::default-release,
apt::install-recommends, apt::install-suggests, apt::neverautoremove,
apt::get::assume-yes, apt::get::allowunauthenticated,
apt::get::automaticremove, apt::get::list-cleanup, apt::get::purge,
apt::update::pre-invoke, apt::update::post-invoke,
apt::update::post-invoke-success, dir, dir::bin::dpkg, dir::cache,
dir::cache::archives, dir::etc, dir::etc::sourcelist,
dir::etc::sourceparts, dir::etc::parts, dir::etc::main,
dir::etc::preferences, dir::ignore-files-silently, dir::state,
dir::state::extendedstates, dir::state::status, dir::etc::trusted,
dir::etc::trustedparts dpkg::options, dpkg::pre-invoke,
dpkg::post-invoke, dpkg::pre-install-pkgs, quiet

and what do they all mean, you ask? apt.conf(5), bestie. go read that one, it's all in there. we're not re-explaining apt's whole lore in this house. 💀

Secondly, Cupt introduces its own cupt-specific configuration variables — and those are the ones we're about to go through in full, because they're the main character here. 👑

🌈 variable types 🌈

every variable here is one of these four, so let's get the types straight first:

  • boolean — false may be specified as "0" or "false" or "no", and literally everything else gets interpreted as true. If it's undefined, it's interpreted as false.
  • integer — a signed 32-bit integer on 32-bit systems, and a signed 64-bit integer on 64-bit systems. If it's undefined, it's interpreted as 0.
  • string — interpreted as is. If it's undefined, it's interpreted as an empty string.
  • list — a list of strings. If it's undefined, it's interpreted as an empty list.

💜 variables 💜

okay this is the long part, stay with me, we're going one by one. every single one. no skipping. 🧚

  • cupt::cache::limit-releases::by-*::type — string, determines the type of limiting repository releases to use. All repository indexes which are disallowed by this option are not added to the package cache — in other words, they're completely hidden. 👀 '*' can be archive or codename. Possible values:
    • none — no limiting will be done for this category. The default.
    • include — only values of the 'cupt::cache::limit-releases::by-*' option will be allowed.
    • exclude — only values which are not present in the value of the 'cupt::cache::limit-releases::by-*' option will be allowed. Example: if you set 'cupt::cache::limit-releases::by-archive::type' to 'include' and 'cupt::cache::limit-releases::by-archive' to '{ "stable", "testing" };', only repositories with archive names 'stable' and 'testing' will be added to the cache.
  • cupt::cache::limit-releases::by-* — list of allowed/disallowed release attributes, see above ⬆️
  • cupt::cache::pin::addendums::but-automatic-upgrades — integer, specifies the priority change for versions that come only from sources which have both 'not automatic' and 'but automatic upgrades' flags. Defaults to 4200.
  • cupt::cache::pin::addendums::downgrade — integer, specifies the priority change for versions that are smaller than currently installed. Defaults to -10000.
  • cupt::cache::pin::addendums::hold — integer, specifies the priority increase for versions that are put on hold. Defaults to 1000000. Set this option to 0 if you do not want to obey holds. You may want to increase this option in (very unlikely to happen) situations: when you have thousands of manually installed packages and a very large query; when you have a manually crafted pin priorities system with very large pin values.
  • cupt::cache::pin::addendums::not-automatic — integer, specifies the priority increase for versions that come only from 'not automatic' sources. Defaults to -4000. If you change the value of this option, you might want to change the value of the option "cupt::cache::pin::addendums::but-automatic-upgrades" accordingly.
  • cupt::cache::release-file-expiration::ignore — boolean, if set to true, Cupt will ignore the fact that a Release file is expired and use it anyway. False by default.
⚠️ Warning! Setting this option to true will make the system vulnerable to a replay attack on package manager indexes. like, actually. don't do it casually, bestie. 😭
  • cupt::console::allow-untrusted — boolean, don't treat using untrusted packages as a dangerous action.
  • cupt::console::assume-yes — boolean, see cupt(1) --assume-yes.
  • cupt::console::actions-preview::package-indicators::manually-installed — boolean, whether to print the {m} prefix for manually installed packages in non-color mode. Enabled by default.
  • cupt::console::actions-preview::package-indicators::automatically-installed — boolean, whether to print the {a} prefix for automatically installed packages in non-color mode. Disabled by default.
  • cupt::console::actions-preview::show-not-preferred — string, determines whether packages which will have a not preferred version after the proposed changes are done should be shown in the actions preview. Defaults to 'for-upgrades'. Possible values:
    • no — do not show.
    • for-upgrades — show for upgrade subcommands (namely, for "full-upgrade", "safe-upgrade" and the second part of "dist-upgrade").
    • yes — show always.
  • cupt::console::actions-preview::show-archives — boolean, if true, release archive(s) will be shown for each package in the actions preview. False by default.
  • cupt::console::actions-preview::show-codenames — boolean, if true, release codename(s) will be shown for each package in the actions preview. False by default.
  • cupt::console::actions-preview::show-components — boolean, if true, release component(s) will be shown for each package in the actions preview. False by default.
  • cupt::console::actions-preview::show-details — boolean, if true, details of planned actions will be shown in the actions preview. True by default.
  • cupt::console::actions-preview::show-empty-versions — boolean, if true, empty versions (i.e. removed or not installed packages) will be shown as '<empty>' instead of being omitted.
  • cupt::console::actions-preview::show-size-changes — boolean, if true, a change in the disk space usage will be shown for each package in the actions preview. False by default.
  • cupt::console::actions-preview::show-reasons — boolean, see cupt(1) --show-reasons.
  • cupt::console::actions-preview::show-summary — string, tristate ("yes", "no" or "auto"), controls whether the summary of planned actions will be shown in the actions preview or not. Defaults to "yes". Currently, "auto" means that the summary will be shown when there are >= 100 change entries in total.
  • cupt::console::actions-preview::show-versions — boolean, if true, a version will be shown for each package in the actions preview. False by default.
  • cupt::console::actions-preview::show-vendors — boolean, if true, a version will be shown for each package in the actions preview. False by default.
  • cupt::console::show-progress-messages — boolean, if true, package management actions will print stage messages ("Building a cache", "Resolving possible unmet dependencies" etc.). True by default.
  • cupt::console::use-colors — string, specifies whether to use colors in the console interface. Defaults to "auto". For now concerns only the action preview. Available values:
    • no — don't use colors.
    • yes — use colors.
    • auto — use colors if the standard output is a terminal and a terminal type seem to allow colors.
  • cupt::console::warnings::removal-of-essential — boolean, treat removals of essential packages as a dangerous action. True by default.
  • cupt::console::warnings::removal-of-important — boolean, treat removals of important packages as a dangreous action. True by default.
  • cupt::directory — string, base directory for all cupt::directory::* options.
  • cupt::directory::configuration — string, base directory for Cupt-specific configuration files.
  • cupt::directory::configuration::main — string, relative file path for the Cupt main configuration file (same format as apt.conf(5)).
  • cupt::directory::configuration::main-parts — string, relative directory path for additional Cupt configuration files (same format as apt.conf(5)).
  • cupt::directory::configuration::pre — string, relative file path for the Cupt preconfiguration file which is read before paths of any other configuration files are calculated. This is the only place where one can effectively override default values of dir::etc and cupt::directory::configuration options and/or their suboptions. The environment variable CUPT_PRE_CONFIG overrides this option if defined.
  • cupt::directory::log — string, relative file path for the log file.
  • cupt::directory::state — string, directory which contains Cupt state info.
  • cupt::directory::state::lists — string, directory for repository indexes.
  • cupt::downloader::max-simultaneous-downloads — integer, positive, specifies the maximum number of simultaneous downloads. Defaults to 2.
  • cupt::downloader::protocols::protocol::priority — integer, positive, defines the priority of download protocol protocol, and determines an order in which different URIs for the same file will be tried. Defaults to 100.
  • cupt::downloader::protocols::protocol::methods::method::priority — positive number, defines the priority of download method method; the method with maximum priority will be used for downloading the URI of protocol protocol. Defaults to 100.
  • cupt::downloader::protocols::protocol::methods — list, names of the methods available to download protocol protocol.
  • cupt::languages::indexes — string, specifies localizations of what languages should be used for repository indexes. Defaults to "environment,en". The value is a comma-delimited (no spaces allowed) list of localization specificators. A localization specificator is either:
    • environment — a special string which is substituted by the current locale (precisely, by a value of the environment variable LC_MESSAGES).
    • none — a special string which indicates no localization.
    • language_code[_country_code] — a language code (for example: 'fi', 'fr', 'ru') or a language code with a country code (for example, 'pt_BR', 'zh_CN').

If your localization specificator has a country code in it, then the extra specifier without a country code gets implicitly used as a fallback. Auto. Built in. No cap. 🫶

Localization specifiers go in preference order — most-wanted first, bestie. Duplicates? Allowed... but ignored. 💀 So don't bother.

Examples:

fi,ru,fr : Download Finnish, Russian and French translations. For every description, try Finnish first; if it's not there, try Russian; if that's not there either, try French; and if literally none of them show up, you get the original one. 🌈

pt_BR : Download Portuguese (Brazil) and Portuguese localizations. Use Portuguese (Brazil); if it's not available, use Portuguese; else original. Periodt. 👑

de,environment,fr_FR : (Assuming LC_MESSAGES is pl_PL.UTF-8.) Download and use these translations, in this exact order: German, Polish (Poland), Polish, French (France), French. Slay. ✨

  • cupt::update::check-release-files — boolean. If it's set, Release files get their validity checked (expiration check included, plus a signature if there is one) right at the download stage. True by default. 💖
  • cupt::update::compression-types::*::priority — integer. Sets the preference for downloading compressed files — higher priority goes first. 100 by default.

That * can be gz, bz2, lzma, xz, and uncompressed, bestie. 🎀

Want something to be low-precedence compared to default? Set it to a value <100. Want it high-precedence? >100. It's giving math but make it fashion. 💅

If some methods end up with the equal priority (which is the default setting), then the files with the smaller size get chosen over the bigger ones.

Example:

So imagine you've got a low-speed CPU but a pretty high-speed internet connection, and you'd rather have gzip over lzma, and lzma over bzip2. Then you set options like:

cupt::update::compression-types
{
  gz::priority "200";
  lzma::priority "150";
}

Also — if you have a local mirror, one that may store uncompressed indexes too (an official Debian archive doesn't store them, jsyk 🙈), you may set also:

cupt::update::compression-types::uncompressed::priority "300";
  • cupt::update::generate-index-of-index — boolean. Specifies whether to build an "index-of-index" for every Packages and Sources. If you set it to true, it slightly increases the time of postprocessing after downloading new metadata files, but it speeds up significantly the initialization time for every single invocation. True by default. ⭐
  • cupt::update::use-index-diffs — boolean. Specifies whether to try downloading repository index deltas and apply them locally before downloading the full index. True by default. 🦋

Turned on, this option saves bandwidth but increases CPU and disk usage while updating. On fast unlimited connections (say, >= 2 Mbit/s, though honestly it heavily depends on many other factors), you'd probably wanna turn this one off. 😭

  • cupt::resolver::keep-recommends — boolean. Specifies whether the resolver should try to keep already installed recommended packages or not. True by default. ✨
  • cupt::resolver::keep-suggests — boolean. Specifies whether the resolver should try to keep already installed suggested packages or not. False by default. 🍓
  • cupt::resolver::auto-remove — boolean, see cupt(1) --no-auto-remove. 👀
  • cupt::resolver::max-leaf-count — integer. Specifies how many leaves the solution tree will grow before the resolver gives up. -1 means infinite. -1 by default. 🌸
  • cupt::resolver::max-solution-count — integer, positive, see cupt(1) --max-solution-count.
  • cupt::resolver::no-autoremove-if-rdepends-exist — list of regular expressions. If the package name matches any of those regular expressions, it will not be considered for auto-removal while there are any reverse dependencies installed. Empty by default.

Example (a simplified real situation):

Package: xserver-xorg
Depends: xserver-xorg-video-all | xorg-driver-video

Package: xserver-xorg-video-nv
Provides: xorg-driver-video

Package: xserver-xorg-video-radeon
Provides: xorg-driver-video

You have:

  • xserver-xorg: manually installed
  • xserver-xorg-video-all: not installed
  • xserver-xorg-video-nv: automatically installed
  • xserver-xorg-video-radeon: automatically installed

Both xserver-xorg-video-nv and xserver-xorg-video-radeon satisfy the dependency of xserver-xorg, so only one of them is needed on the system. Which means, by default, one of these two will be considered for auto-removal. 🙈 But if you add the regular expression xserver-xorg-video.* to the value of this option, then none of the packages providing xorg-driver-video will be considered for auto-removal for as long as xserver-xorg is installed. Iconic. 👑

  • cupt::resolver::no-remove — boolean, see cupt(1) --no-remove.
  • cupt::resolver::synchronize-by-source-versions — string. This option controls whether and how the native resolver will attempt to keep all binary packages from the same source package at the same source version.

This option uses the information from source packages. No synchronization will be performed for the versions which don't have a corresponding source version in the repository.

Possible values:

  • none — Don't attempt to synchronize. This is the default value. 🧚
  • soft — Don't forbid any modifications to the packages, and attempt to synchronize related binary packages when possible upon the modifications of a certain binary package.
  • hard — Forbid any modifications to the packages when at least one related binary package cannot be synchronized with the modified one. Strict! 💀
  • cupt::resolver::track-reasons — boolean. Specifies whether suggestedPackages::reasons is filled in the Resolver::Offer. False by default. 🎀
  • cupt::resolver::type — string, see cupt(1) --resolver.
  • cupt::resolver::score::<part> — a whole group of integer options that control the internal resolver's score calculation. Values are absolute. 💅

<part> can be one of:

  • new — installing a new package
  • removal — removal of an existing package
  • removal-of-essential — removal of an existing essential package (a general removal option is applied as well)
  • removal-of-autoinstalled — removal of an automatically installed package (a general removal option is applied as well)
  • upgrade — installing a higher version of an existing package
  • downgrade — installing a lower version of an existing package
  • position-penalty — when several actions may be performed to resolve a problem, apply N penalties to the N-th action (counting from 0)
  • quality-adjustment — the value will be added to each action's score
  • unsatisfied-recommends — some recommends dependency is not satisfied (when requested)
  • unsatisfied-suggests — some suggests dependency is not satisfied (when requested)
  • failed-synchronization — some source version synchronization cannot be performed (when cupt::resolver::synchronize-source-versions is soft)
  • version-factor::common — defines (in percents) how much version score difference affects the action score
  • version-factor::negative — defines (in percents) scaling of negative version scores (applied after version-factor)
  • version-factor::priority-downgrade — defines (in percents) scaling of version score if the version priority difference is negative. For calculations regarding this factor: if there is no original version, its priority is 0; if there is no supposed version, its priority is the default priority for versions from a default package archive.
  • cupt::worker::archives-space-limit — integer, bytes, positive. If it's set, it limits the worker to not download more than the specified amount of archives, and uses the download-install-clean algorithm (download archives, install packages, clean just the downloaded archives). The worker will try to split all actions into unrelated changesets so each changeset requires only limited download space. Any system changes will be started only if the changesets are generated successfully. ✨
  • cupt::worker::defer-triggers — string. Specifies whether the worker should defer dpkg trigger processing to the end of the whole operation or not. When enabled, it speeds up large-amount actions — but if the operation gets interrupted for some reason, it leaves the system in the interim trigger state, which can be fixed by manually running dpkg --triggers-only --pending. Defaults to "auto". 🌸

Available values:

  • no — Disable deferring triggers.
  • yes — Enable deferring triggers.
  • auto — Enable deferring triggers if a recent enough version of dpkg is installed (1.16.1, where that tiresome trigger-related bug (Debian BTS #526774) is fixed). 🎀
  • cupt::worker::download-only — boolean, see cupt(1) --download-only.
  • cupt::worker::log — boolean. Whether to log performed actions or not. True by default. 📖
  • cupt::worker::log::levels::metadata — non-negative integer. The log level for the metadata updates. 1 by default.
  • cupt::worker::log::levels::packages — non-negative integer. The log level for the package changes (install/upgrade/remove etc.). 2 by default.
  • cupt::worker::log::levels::snapshots — non-negative integer. The log level for the snapshot actions. 1 by default.
  • cupt::worker::purge — boolean. Specifies whether to purge packages in addition to removing them or not. False by default. 🍓
  • cupt::worker::simulate — boolean, see cupt(1) --simulate.
  • cupt::worker::use-locks — boolean. Specifies whether Cupt protects simultaneous runs of itself against the misuse of the common resources. True by default. 🔒
Warning! Setting this option to false will allow several non-simulating Cupt instances to break the system when misused. Not the vibe. 💀
  • debug::resolver — boolean. If true, the resolver will print a lot of debug information to the standard error. False by default. 😭
  • debug::worker — boolean. If true, the worker will print some debug information to the standard error. False by default.
  • debug::gpgv — boolean. If true, the cache will print some debug information while verifying signatures, to the standard error. False by default. 🦋
  • debug::downloader — it's a boolean, bestie 💅 set it to true and the downloader manager will spill some debug messages your way. Default is false, so if you do nothing it stays quiet. yes boo, silence is the default setting
  • debug::logger — also a boolean 🎀 if true, the logger itself starts printing debug messages. False by default, so again, no noise unless you ask for it. turn it on and watch the logs get chatty fr fr

✨ SEE ALSO ✨

  • cupt(1) — the main character, the actual program 👑
  • apt.conf(5) — the config file format it's giving, in case you wanna compare notes 💖

and that's the whole page, bestie 🫶 no cap, you made it to the end. this was CUPT.CONF(5), brought to you by perl v5.38.2 and dated 2024-03-31 — iconic, timeless, slay 💅✨

📦 where this page comes from