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

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/.

User

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

  1. Register a user account.

  2. 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 to 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

See also

py3-keyring bugs that may catch you as well: 391, 514

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 client, api, 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’.