# 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 example:

    mini-buildd-api pub_key http://foo.bar.org:8066 >/etc/apt/trusted.gpg.d/foo.asc
    # OR
    wget http://foo.bar.org:8066/mini_buildd/api/pub_key/?output=plain --output-document /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:

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