Hi, A. Costa wrote:
> Please consider moving the 'man cupt' text under "CONFIGURATION VARIABLES" > to its own man page, e.g. 'cupt.conf(5)'. Sounds reasonable. Here's a first sketch; what do you think? (As you can see, I'm lazy. Improvements welcome.) --- debian/install_pods | 2 +- doc/cupt.1.pod | 397 +----------------------------------------------- doc/cupt.conf.5.pod | 421 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 424 insertions(+), 396 deletions(-) create mode 100644 doc/cupt.conf.5.pod diff --git a/debian/install_pods b/debian/install_pods index 373e4057..28eb8c94 100644 --- a/debian/install_pods +++ b/debian/install_pods @@ -5,7 +5,7 @@ use strict; foreach my $pod_file (glob("doc/*.pod")) { # example: doc/cupt.1.pod - my ($name, $section) = ($pod_file =~ m{.*/((?:\w|_|-)+)\.(\d)\.pod}) or + my ($name, $section) = ($pod_file =~ m{.*/((?:\w|_|-|\.)+)\.(\d)\.pod}) or die "badly formatted POD name $pod_file"; my $man_page_name = "$name.$section"; my $uppercased_name = uc $name; diff --git a/doc/cupt.1.pod b/doc/cupt.1.pod index be0f79c6..ffef2ddf 100644 --- a/doc/cupt.1.pod +++ b/doc/cupt.1.pod @@ -851,400 +851,7 @@ don't output anything to standard output =head1 CONFIGURATION VARIABLES -Firstly, Cupt uses following APT configuration variables: - -acquire::*::timeout, acquire::*::proxy, acquire::http::allowredirect, -acquire::retries, apt::acquire::translation, 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::state, -dir::state::extendedstates, dir::state::status, dpkg::options, -dpkg::pre-invoke, dpkg::post-invoke, dpkg::pre-install-pkgs, -gpgv::trustedkeyring, quiet - -See L<apt.conf(5)> for their meanings. - -Secondly, Cupt recognizes (but doesn't use) following configuration variables: - -apt::archives::*, acquire::pdiffs, apt::cache-limit, apt::periodic::*, -dir::state::lists, unattended-upgrade::*, acquire::compressiontypes, -apt::get::show-upgraded, apt::get::build-dep-automatic, rpm::pre-invoke, -rpm::post-invoke - -Thirdly, Cupt introduces cupt-specific configuration variables. - -=head2 variable types - -=over - -=item boolean - -false may be specified as "0" or "false" or "no", everything else interpretes as true - -if undefined, interpretes as false - -=item integer - -signed 32-bit integer on 32-bit systems, signed 64-bit integer on 64-bit systems - -if undefined, interpretes as 0 - -=item string - -interpreted as is - -if undefined, interpretes as empty string - -=item list - -list of strings - -if undefined, intepretes as empty list - -=back - -=head2 variables - -=over - -=item cupt::cache::pin::addendums::downgrade - -integer, specifies priority change for versions that are smaller than currently -installed. Defaults to -10000. - -=item cupt::cache::pin::addendums::hold - -integer, specifies 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 very large query; -when you have a manually crafted pin priorities system with very large pin -values. - -=item cupt::cache::pin::addendums::not-automatic - -integer, specifies priority increase for versions that come only from 'not -automatic' sources. Defaults to -4000. - -=item 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. - -B<Warning! Setting this option to true will make the system vulnerable to a replay attack on package manager indexes.> - -=item cupt::console::allow-untrusted - -boolean, don't treat using untrusted packages as dangerous action - -=item cupt::console::assume-yes - -boolean, see L<--assume-yes|/--assume-yes> - -=item cupt::directory - -string, base directory for all cupt::directory::* options - -=item cupt::directory::configuration - -string, base directory for Cupt-specific configuration files - -=item cupt::directory::configuration::main - -string, relative file path for the Cupt main configuration file (same format as -L<apt.conf(5)>) - -=item cupt::directory::configuration::main-parts - -string, relative directory path for additional Cupt configuration files (same -format as L<apt.conf(5)>) - -=item cupt::directory::log - -string, relative file path for the log file - -=item cupt::directory::state - -string, directory which contains Cupt state info - -=item cupt::directory::state::lists - -string, directory for repository indexes - -=item cupt::downloader::max-simultaneous-downloads - -integer, positive, specifies maximum number of simultaneous downloads. Defaults to 2. - -=item cupt::downloader::protocols::I<protocol>::priority - -integer, positive, defines the priority of download protocol I<protocol>, determines an order in which -different URIs for the same file will be tried. Defaults to 100. - -=item cupt::downloader::protocols::I<protocol>::methods::I<method>::priority - -positive number, defines the priority of download method I<method>, the method -with maximum priority will be used for downloading the URI of protocol -I<protocol>. -Defaults to 100. - -=item cupt::downloader::protocols::I<protocol>::methods - -list, names of the methods available to download protocol I<protocol> - -=item cupt::update::check-release-files - -boolean, if set, Release files will be checked for the validity (including the -expiration check and a signature if present) at the download stage. True by default. - -=item cupt::update::compression-types::*::priority - -integer, defines preference to download compressed files with higher priority first. 100 by default. - -'*' can be 'gz', 'bz2', 'lzma', 'xz', and 'uncompressed'. - -Set some option to <100 value to make it low-precedence than default, and >100 -to make it high-precedence than default. - -If some methods have the equal priority (which is the default setting), then -files with smaller size with be chosen over the files with bigger size. - -Example: - -You have a low-speed CPU but rather high-speed internet connection and want to -prefer gzip over lzma and lzma over bzip2. Then you have to set options like: - - cupt::update::compression-types - { - gz::priority "200"; - lzma::priority "150"; - } - -Also, if you have a local mirror, which may store uncompressed indexes too -(an official Debian archive doesn't store them), you may set also - -cupt::update::compression-types::uncompressed::priority "300"; - -=item cupt::update::keep-bad-signatures - -boolean, specifies whether to keep signature files that failed GPG check -when doing update. True by default. Setting this option to false will not have -an effect if the option L<cupt::update::check-release-files> is set to false. - -=item 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. - -When turned on, this option saves bandwidth but increases CPU and disk usage -while updating. On the fast unlimited connections (say, >= 2 Mbit/s, but -heavily depends on many other factors) you would likely want to turn off this -option. - -=item cupt::resolver::keep-recommends - -boolean, specifies whether should resolver try to keep already installed -recommended packages or not. True by default. - -=item cupt::resolver::keep-suggests - -boolean, specifies whether should resolver try to keep already installed -suggested packages or not. False by default. - -=item cupt::resolver::auto-remove - -boolean, see L<--no-auto-remove/|--no-auto-remove> - -=item cupt::resolver::max-solution-count - -integer, positive, see L<--max-solution-count|/--max-solution-count> - -=item cupt::resolver::external-command - -string, a preview-only, experimental option to use external resolver using CUDF -protocol. Don't use it unless you know what you are doing. - -Example: C<< cupt -s safe-upgrade -o "cupt::resolver::external-command=cat > cudfout.txt" >> - -=item cupt::resolver::no-remove - -boolean, see L<--no-remove|/--no-remove> - -=item 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 have not a corresponding source version in -the repository. - -Possible values: - -=over - -=item none - -Don't attempt to synchronize. This is the default value. - -=item soft - -Don't forbid any modifications to the packages and attempt to synchronize -related binary packages when possible upon the modifications of certain binary -package. - -=item hard - -Forbid any modifications to the packages when at least one related binary -package cannot be synchronized with the modified one. - -=back - -=item cupt::resolver::track-reasons - -boolean, see L<--show-reasons|/--show-reasons,--show-deps,-D> - -=item cupt::resolver::type - -string, see L<--resolver|/--resolver> - -=item cupt::resolver::score::<part> - -The group of integer options which control internal resolver's score -calculation. Values are absolute. - -<part> can be one of: - -=over - -=item new - -installing a new package - -=item removal - -removal of an existing package - -=item removal-of-essential - -removal of an existing essential package (a general B<removal> option is applied as well) - -=item upgrade - -installing a higher version of an existing package - -=item downgrade - -installing a lower version of an existing package - -=item position-penalty - -when several actions may be performed to resolve a problem, apply N penalties -to N-th action (counting from 0) - -=item quality-adjustment - -the value will be added to each action's score - -=item unsatisfied-recommends - -some 'recommends' dependency is not satisfied (when requested) - -=item unsatisfied-suggests - -some 'suggests' dependency is not satisfied (when requested) - -=item failed-synchronization - -some source version synchronization cannot be performed (when -L<cupt::resolver::synchronize-source-versions|/cupt::resolver::synchronize-source-versions> -is 'soft') - -=back - -=item cupt::worker::archives-space-limit - -integer, bytes, positive, if set, limits the worker to not download more than specified -amount of archives, and use download-install-clean algorithm (download -archives, install packages, clean just downloaded archives). Worker will try -to split all actions into unrelated changesets so each changeset require only -limited download space. Any system changes will be started only if changesets -are generated successfully. - -=item cupt::worker::defer-triggers - -boolean, specifies whether should worker defer dpkg trigger processing to -the end of the whole operation or not. Being set to true, speeds up -large-amount actions, but if the operation will somewhy be interrupted, leaves -system in the interim trigger state, which can be fixed by manual run of 'dpkg ---triggers-only --pending' command. False by default due to tiresome dpkg bug -(Debian BTS #526774). - -=item cupt::worker::download-only - -boolean, see L<--download-only|/--download-only,-d> - -=item cupt::worker::log - -boolean, whether to log performed actions or not. True by default. - -=item cupt::worker::log::levels::metadata - -non-negative integer, the log level for the metadata updates. 1 by default. - -=item cupt::worker::log::levels::packages - -non-negative integer, the log level for the package changes -(install/upgrade/remove etc.). 2 by default. - -=item cupt::worker::log::levels::snapshots - -non-negative integer, the log level for the snapshot actions. 1 by default. - -=item cupt::worker::purge - -boolean, specifies whether purge packages in addition to removing or not. -False by default. - -=item cupt::worker::simulate - -boolean, see L<--simulate|/--simulate,-s> - -=item cupt::worker::use-locks - -boolean, specifies whether Cupt protects simultaneous runs of itself against -the misuse of the common resources. True by default. - -B<Warning! Setting this option to false will allow several non-simulating Cupt -instances to break the system when misused.> - -=item debug::resolver - -boolean, if true, resolver will print a lot of debug information to the -standard error. False by default. - -=item debug::worker - -boolean, if true, worker will print some debug information to the -standard error. False by default. - -=item debug::gpgv - -boolean, if true, cache will print some debug information while verifying -signatures to the standard error. False by default. - -=item debug::downloader - -boolean, if true, the downloader manager will print some debug messages. False -by default. - -=item debug::logger - -boolean, if true, the logger will print some debug messages. False by default. +See L<cupt.conf(5)>. =back @@ -1256,7 +863,7 @@ The discussion channel about Cupt is irc://irc.debian.org#cupt. =head1 SEE ALSO -L<cupt_vs_apt(5)>, L<cupt_tutorial(7)> +L<cupt_vs_apt(5)>, L<cupt_tutorial(7)>, L<cupt.conf(5)> =head1 AUTHOR diff --git a/doc/cupt.conf.5.pod b/doc/cupt.conf.5.pod new file mode 100644 index 00000000..d3642a61 --- /dev/null +++ b/doc/cupt.conf.5.pod @@ -0,0 +1,421 @@ +=pod + +=encoding utf8 + +=head1 NAME + +cupt.conf - configuration file for Cupt + +=head1 SYNOPSIS + +$APT_CONFIG, /etc/apt/apt.conf, /etc/apt/apt.conf.d/*, +/etc/cupt/cupt.conf, /etc/cupt/cupt.conf.d/* + +=head1 DESCRIPTION + +Cupt uses the same configuration syntax as L<apt.conf(5)>, which see. + +=head1 CONFIGURATION VARIABLES + +Firstly, Cupt uses following APT configuration variables: + +acquire::*::timeout, acquire::*::proxy, acquire::http::allowredirect, +acquire::retries, apt::acquire::translation, 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::state, +dir::state::extendedstates, dir::state::status, dpkg::options, +dpkg::pre-invoke, dpkg::post-invoke, dpkg::pre-install-pkgs, +gpgv::trustedkeyring, quiet + +See L<apt.conf(5)> for their meanings. + +Secondly, Cupt recognizes (but doesn't use) following configuration variables: + +apt::archives::*, acquire::pdiffs, apt::cache-limit, apt::periodic::*, +dir::state::lists, unattended-upgrade::*, acquire::compressiontypes, +apt::get::show-upgraded, apt::get::build-dep-automatic, rpm::pre-invoke, +rpm::post-invoke + +Thirdly, Cupt introduces cupt-specific configuration variables. + +=head2 variable types + +=over + +=item boolean + +false may be specified as "0" or "false" or "no", everything else interpretes as true + +if undefined, interpretes as false + +=item integer + +signed 32-bit integer on 32-bit systems, signed 64-bit integer on 64-bit systems + +if undefined, interpretes as 0 + +=item string + +interpreted as is + +if undefined, interpretes as empty string + +=item list + +list of strings + +if undefined, intepretes as empty list + +=back + +=head2 variables + +=over + +=item cupt::cache::pin::addendums::downgrade + +integer, specifies priority change for versions that are smaller than currently +installed. Defaults to -10000. + +=item cupt::cache::pin::addendums::hold + +integer, specifies 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 very large query; +when you have a manually crafted pin priorities system with very large pin +values. + +=item cupt::cache::pin::addendums::not-automatic + +integer, specifies priority increase for versions that come only from 'not +automatic' sources. Defaults to -4000. + +=item 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. + +B<Warning! Setting this option to true will make the system vulnerable to a replay attack on package manager indexes.> + +=item cupt::console::allow-untrusted + +boolean, don't treat using untrusted packages as dangerous action + +=item cupt::console::assume-yes + +boolean, see L<cupt(1)> L<--assume-yes|/--assume-yes> + +=item cupt::directory + +string, base directory for all cupt::directory::* options + +=item cupt::directory::configuration + +string, base directory for Cupt-specific configuration files + +=item cupt::directory::configuration::main + +string, relative file path for the Cupt main configuration file (same format as +L<apt.conf(5)>) + +=item cupt::directory::configuration::main-parts + +string, relative directory path for additional Cupt configuration files (same +format as L<apt.conf(5)>) + +=item cupt::directory::log + +string, relative file path for the log file + +=item cupt::directory::state + +string, directory which contains Cupt state info + +=item cupt::directory::state::lists + +string, directory for repository indexes + +=item cupt::downloader::max-simultaneous-downloads + +integer, positive, specifies maximum number of simultaneous downloads. Defaults to 2. + +=item cupt::downloader::protocols::I<protocol>::priority + +integer, positive, defines the priority of download protocol I<protocol>, determines an order in which +different URIs for the same file will be tried. Defaults to 100. + +=item cupt::downloader::protocols::I<protocol>::methods::I<method>::priority + +positive number, defines the priority of download method I<method>, the method +with maximum priority will be used for downloading the URI of protocol +I<protocol>. +Defaults to 100. + +=item cupt::downloader::protocols::I<protocol>::methods + +list, names of the methods available to download protocol I<protocol> + +=item cupt::update::check-release-files + +boolean, if set, Release files will be checked for the validity (including the +expiration check and a signature if present) at the download stage. True by default. + +=item cupt::update::compression-types::*::priority + +integer, defines preference to download compressed files with higher priority first. 100 by default. + +'*' can be 'gz', 'bz2', 'lzma', 'xz', and 'uncompressed'. + +Set some option to <100 value to make it low-precedence than default, and >100 +to make it high-precedence than default. + +If some methods have the equal priority (which is the default setting), then +files with smaller size with be chosen over the files with bigger size. + +Example: + +You have a low-speed CPU but rather high-speed internet connection and want to +prefer gzip over lzma and lzma over bzip2. Then you have to set options like: + + cupt::update::compression-types + { + gz::priority "200"; + lzma::priority "150"; + } + +Also, if you have a local mirror, which may store uncompressed indexes too +(an official Debian archive doesn't store them), you may set also + +cupt::update::compression-types::uncompressed::priority "300"; + +=item cupt::update::keep-bad-signatures + +boolean, specifies whether to keep signature files that failed GPG check +when doing update. True by default. Setting this option to false will not have +an effect if the option L<cupt::update::check-release-files> is set to false. + +=item 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. + +When turned on, this option saves bandwidth but increases CPU and disk usage +while updating. On the fast unlimited connections (say, >= 2 Mbit/s, but +heavily depends on many other factors) you would likely want to turn off this +option. + +=item cupt::resolver::keep-recommends + +boolean, specifies whether should resolver try to keep already installed +recommended packages or not. True by default. + +=item cupt::resolver::keep-suggests + +boolean, specifies whether should resolver try to keep already installed +suggested packages or not. False by default. + +=item cupt::resolver::auto-remove + +boolean, see L<--no-auto-remove/|--no-auto-remove> + +=item cupt::resolver::max-solution-count + +integer, positive, see L<--max-solution-count|/--max-solution-count> + +=item cupt::resolver::external-command + +string, a preview-only, experimental option to use external resolver using CUDF +protocol. Don't use it unless you know what you are doing. + +Example: C<< cupt -s safe-upgrade -o "cupt::resolver::external-command=cat > cudfout.txt" >> + +=item cupt::resolver::no-remove + +boolean, see L<--no-remove|/--no-remove> + +=item 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 have not a corresponding source version in +the repository. + +Possible values: + +=over + +=item none + +Don't attempt to synchronize. This is the default value. + +=item soft + +Don't forbid any modifications to the packages and attempt to synchronize +related binary packages when possible upon the modifications of certain binary +package. + +=item hard + +Forbid any modifications to the packages when at least one related binary +package cannot be synchronized with the modified one. + +=back + +=item cupt::resolver::track-reasons + +boolean, see L<--show-reasons|/--show-reasons,--show-deps,-D> + +=item cupt::resolver::type + +string, see L<--resolver|/--resolver> + +=item cupt::resolver::score::<part> + +The group of integer options which control internal resolver's score +calculation. Values are absolute. + +<part> can be one of: + +=over + +=item new + +installing a new package + +=item removal + +removal of an existing package + +=item removal-of-essential + +removal of an existing essential package (a general B<removal> option is applied as well) + +=item upgrade + +installing a higher version of an existing package + +=item downgrade + +installing a lower version of an existing package + +=item position-penalty + +when several actions may be performed to resolve a problem, apply N penalties +to N-th action (counting from 0) + +=item quality-adjustment + +the value will be added to each action's score + +=item unsatisfied-recommends + +some 'recommends' dependency is not satisfied (when requested) + +=item unsatisfied-suggests + +some 'suggests' dependency is not satisfied (when requested) + +=item failed-synchronization + +some source version synchronization cannot be performed (when +L<cupt::resolver::synchronize-source-versions|/cupt::resolver::synchronize-source-versions> +is 'soft') + +=back + +=item cupt::worker::archives-space-limit + +integer, bytes, positive, if set, limits the worker to not download more than specified +amount of archives, and use download-install-clean algorithm (download +archives, install packages, clean just downloaded archives). Worker will try +to split all actions into unrelated changesets so each changeset require only +limited download space. Any system changes will be started only if changesets +are generated successfully. + +=item cupt::worker::defer-triggers + +boolean, specifies whether should worker defer dpkg trigger processing to +the end of the whole operation or not. Being set to true, speeds up +large-amount actions, but if the operation will somewhy be interrupted, leaves +system in the interim trigger state, which can be fixed by manual run of 'dpkg +--triggers-only --pending' command. False by default due to tiresome dpkg bug +(Debian BTS #526774). + +=item cupt::worker::download-only + +boolean, see L<cupt(1)> L<--download-only|/--download-only,-d> + +=item cupt::worker::log + +boolean, whether to log performed actions or not. True by default. + +=item cupt::worker::log::levels::metadata + +non-negative integer, the log level for the metadata updates. 1 by default. + +=item cupt::worker::log::levels::packages + +non-negative integer, the log level for the package changes +(install/upgrade/remove etc.). 2 by default. + +=item cupt::worker::log::levels::snapshots + +non-negative integer, the log level for the snapshot actions. 1 by default. + +=item cupt::worker::purge + +boolean, specifies whether purge packages in addition to removing or not. +False by default. + +=item cupt::worker::simulate + +boolean, see L<cupt(1)> L<--simulate|/--simulate,-s> + +=item cupt::worker::use-locks + +boolean, specifies whether Cupt protects simultaneous runs of itself against +the misuse of the common resources. True by default. + +B<Warning! Setting this option to false will allow several non-simulating Cupt +instances to break the system when misused.> + +=item debug::resolver + +boolean, if true, resolver will print a lot of debug information to the +standard error. False by default. + +=item debug::worker + +boolean, if true, worker will print some debug information to the +standard error. False by default. + +=item debug::gpgv + +boolean, if true, cache will print some debug information while verifying +signatures to the standard error. False by default. + +=item debug::downloader + +boolean, if true, the downloader manager will print some debug messages. False +by default. + +=item debug::logger + +boolean, if true, the logger will print some debug messages. False by default. + +=back + +=head1 SEE ALSO + +L<cupt(1)>, L<apt.conf(5)> + +=cut -- 1.7.8.rc1 -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org