Consumer’s Manual¶

Introduction¶

This manual should be sufficient for people merely consuming the APT repositories, plus maybe some repository maintenance like migration – i.e., everything but actually developing Debian packages.

For example: system administrators, quality assurance personnel.

Default Layout¶

The Default Layout’s Suites and Semantics Overview
Suite	Flags	Version restriction	Example(`test/bullseye`)	Repository	Semantic	Consumer
experimental	U E 6R	`~<R><C>+0`	`~test11+0`	No auto	Use at will	Developer.
snapshot	U E 12R	`~<R><C>+0`	`~test11+0`	No auto, but upgrades	Continuous integration	Developer, beta tester.
`unstable`	U M 9R	`~<R><C>+[1-9]`	`~test11+3`	No auto, but upgrades	Proposed for live	Developer, beta tester.
`testing`	M 3R	`~<R><C>+[1-9]`	`~test11+2`	No auto, but upgrades	QA testing	Quality Assurance.
`hotfix`	U M 4R	`~<R><C>+[1-9]`	`~test11+2+hotfix1`	No auto, but upgrades	Hotfix proposed for live	Quality Assurance.
`stable`	6R	`~<R><C>+[1-9]`	`~test11+1`	No auto, but upgrades	Live	End customer.

U: Uploadable M: Migrates E: Experimental NR: keeps N Rollback versions <R>: Repository Identity <C>: Codename version.

Tip

What’s the hotfix suite good for?

The hotfix suite fills the kludge in a situation when a new version is in unstable/testing (but no yet ready for stable), but you need but to do important bug fixes to what is in stable immediately (it does migrate to stable directly).

Release2PinPrio Map¶

NotAutomatic	ButAutomaticUpgrades	APT Pin Prio
no	no	500
yes	no	1
no	yes	n/a
yes	yes	100

Installation¶

No custom package installations are required; just access the provided service via some web browser, and standard Debian tools should be enough.

However, it’s still recommended to install the mini-buildd-utils package:

apt install mini-buildd-utils

This toolbox will (among other things) allow you to access the API and events system from the command line. Also, this manual might just silently assume it’s installed.

Setup¶

Tip

firefox: How can I reset (table) searches (like in webkit browsers)?

firefox still (2022) does not support this ootb. However, you can enable layout.forms.input-type-search.enabled preference as (seemingly still experimental) feature via about:config in your browser’s preferences.

See: https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Experimental_features#html

APT Bootstrap¶

To use mini-buildd’s repository (or any, really), its APT key must be known/trusted by your system. mini-buildd conveniently provides that key in a Debian package – but in that very not-yet-trusted repository.

To “TOFU bootstrap” your system’s APT, you may just run:

mini-buildd-bootstrap-apt <URL>

That tool finds the current codename and the archive ID automatically, and also has some bells and whistles built-in to work for older releases.

Tip

How do I verify mini-buildd’s APT key?

You may compare the key’s fingerprint (apt-key finger) with mini-buildd’s (see API call ‘pub_key’). There might also be other means set up by the local administrator to cross-verify the key.

Alternative: Download archive-keyring.deb and install via dpkg¶

Find and download the correct deb via mini-buildd’s ‘repositories-dir’ page, then install it via dpkg -i.

For jessie or older, you will need an extra apt-key add /etc/apt/trusted.gpg.d/mini-buildd-foo.asc call.

Will yield the same end result (i.e., keyring package installed) as the recommended method.

Alternative: Doing ‘insecure’ apt update and install¶

Let’s say you have your sources list configured manually, but mini-buildd’s key is not yet trusted.

For anything stretch or newer, you can run:

apt --allow-insecure-repositories update
apt --allow-unauthenticated install <ARCHIVE>-archive-keyring
apt update

For jessie or older, this should still work just omitting any --allow* options apt may not yet know about.

Will yield the same end result (i.e., keyring package installed) as the recommended method.

Alternative: Manually install the APT key file¶

Download the key via API call ‘pub_key’, then install it under /etc/apt/trusted.gpg.d/foo.asc.

For jessie or older, you will need an extra apt-key add foo.asc call.

Different end result than the recommended method – you now have an extra local configuration file to maintain.

Sources Lists¶

You can retrieve any apt line(s) via the API call ‘sources_list’.

Here is an example on how to do it on the shell (requires Debian package ‘mini-buildd-utils’):

mini-buildd-api sources_list <ENDPOINT> --codenames sid --suites stable

Just add lines to /etc/apt/sources.list or individual files in /etc/apt/sources.list.d/.

Symlinks to keyring package¶

The resp. archive’s keyring package also provides a library of predefined sources list files you can just symlink to:

cd /etc/apt/sources.list.d
ln -s /usr/share/<ARCHIVE>-archive-keyring/sources.list.d/<CODENAME>/foo.list .
apt-get update

User¶

To be able to use advanced functionality (for example, create package subscriptions, access restricted API calls, or upload your GnuPG public key, migrate packages), create a user account:

Register a user account.
Setup your profile (package subscriptions, GnuPG key upload).

Aptitude¶

In case you use aptitude: By default, it does not show distribution or origin of packages – but this might be very helpful.

To show the distribution of packages, just add %t to the package display format (Debian Bug #484011). For example, I do prefer this setting for the Package-Display-Format:

aptitude::UI::Package-Display-Format "%c%a%M%S %p %t %i %Z %v# %V#";

The origin cannot be shown in the package display format (Debian Bug #248561). However, you may change the grouping to categorize with “origin”. For example, I do prefer this setting for the Default-Grouping:

aptitude::UI::Default-Grouping "task,status,pattern(~S~i~O, ?true ||),pattern(~S~i~A, ?true ||),section(subdirs,passthrough),section(topdir)";

This will group installed packages into an Origin->Archive hierarchy.

Additionally to aptitude’s default “Obsolete and locally installed” top level category (which only shows packages not in any apt archive), this grouping also more conveniently shows installed package _versions_ which are not currently in any repository (check “Installed Packages/now”).

Workflows¶

Tip

How can I upgrade after Debian main release version fix?

Since Debian wheezy, Debian uses only one number as main release version. I.e., squeeze main version was 6.0, while wheezy’s main version is just 7.

(Assuming repo test for the following, replace as needed.)

So, the new default version appendix in mini-buildd is now just something like ~test7 (wheezy) or ~test11 (bullseye), analogous to what Debian does with bpo.

On a production system, the admin may/should decide at some point (i.e., when a new codename is introduced) to switch to the new scheme.

Let’s say the admin decided to do the change with the introduction of buster. Then ~test90 (stretch, oldstyle) would be bigger than ~test10 (buster, new style). To be able to upgrade the packages, use an apt preference like this:

/etc/apt/preferences.d/mbd-buster-upgrade.pref¶

        Package: *
        Pin: release a=buster-test-*
        Pin-Priority: 1001

API and Events¶

Documentation of all API calls is in-code only; on mini-buildd’s web interface, you find a summary on mini-buildd’s ‘api’ page (there is also a convenience menu in this manual in the left sidebar).

On the web interface, API calls are embedded where appropriate; events are shown on mini-buildd’s ‘events’ page.

Access via Shell¶

Access from the shell via command ‘mini-buildd-api’ or command ‘mini-buildd-events’, respectively.

To get started, try:

mini-buildd-api --help
mini-buildd-events --help

Tip

How to save credentials when working from the shell?

Credentials are handled via Debian package ‘python3-keyring’, which should just work – i.e., choose a working && secure backend for you automatically.

If you want to do unnattended authorized task, see this example (forcing to save passwords as plain text file):

/usr/share/doc/mini-buildd-utils/examples/keyringrc.cfg¶

# Example python-keyring config (used by mini-buildd utils)
#
# This sample forces to always use the PLAINTEXT keyring from
# :debpkg:`python3-keyrings.alt`. While this is generally frowned
# upon, it might be suitable on a server to run unattended API calls
# (w/o any further dependencies).
#
# This file resides in:                       ``~/.config/python_keyring/``.
# Password IN PLAIN will then be be saved in: ``~/.local/share/python_keyring/keyring_pass.cfg``
#
# For version < 21.3.0 (<= buster), the config file was also placed in ``~/.local/share/python_keyring/``.
[backend]
default-keyring=keyrings.alt.file.PlaintextKeyring

Access via Python¶

Python documentation is here (or maybe that is still just where it should be eventually ;). At least you get the definitions, and you still have the source…)

To get started, look at:

/usr/share/doc/mini-buildd-utils/examples/python-client¶

#!/usr/bin/python3
from mini_buildd import api, client, events

if __name__ == "__main__":
    CLIENT = client.Client("http://localhost:8066")

    print("\n=> status:")
    print(CLIENT.api(api.Status()))

    print("\n=>ls mbd-test-cpp:")
    print(CLIENT.api(api.Ls(source="mbd-test-cpp")))

    print("\n=>Waiting for next MIGRATED event:")
    print(CLIENT.event(types=[events.Type.MIGRATED]))

python code might be more suitable for elaborated scripts; for simple tasks, rather use command ‘mini-buildd-api’.