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 ``~+0`` ``~test11+0`` No auto *Use at will* Developer. snapshot U E 12R ``~+0`` ``~test11+0`` No auto, but upgrades *Continuous integration* Developer, beta tester. ``unstable`` U M 9R ``~+[1-9]`` ``~test11+3`` No auto, but upgrades *Proposed for live* Developer, beta tester. ``testing`` M 3R ``~+[1-9]`` ``~test11+2`` No auto, but upgrades *QA testing* Quality Assurance. ``hotfix`` U M 4R ``~+[1-9]`` ``~test11+2+hotfix1`` No auto, but upgrades *Hotfix proposed for live* Quality Assurance. ``stable`` 6R ``~+[1-9]`` ``~test11+1`` No auto, but upgrades *Live* End customer. ==================== ========= =================== ========================== ========================= ============================ ======================= ``U``: Uploadable ``M``: Migrates ``E``: Experimental ``NR``: keeps N Rollback versions ````: Repository Identity ````: 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: .. code:: bash :class: root-code 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: .. code:: bash :class: root-code mini-buildd-bootstrap-apt 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 :apicall:`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 :mbdpage:`repositories-dir`, 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: .. code:: bash :class: root-code apt --allow-insecure-repositories update apt --allow-unauthenticated install -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 :apicall:`pub_key`, then install it under ``/etc/apt/trusted.gpg.d/foo.asc``. For example: .. code:: bash :class: root-code 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 :apicall:`sources_list`. Here is an example on how to do it on the shell (requires :debpkg:`mini-buildd-utils`): .. code:: bash mini-buildd-api sources_list --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: .. code:: bash :class: root-code cd /etc/apt/sources.list.d ln -s /usr/share/-archive-keyring/sources.list.d//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 (:debbug:`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 (:debbug:`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: .. code-block:: :caption: /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 :mbdpage:`api` (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 :mbdpage:`events`. Access via Shell ---------------- Access from the shell via :mbdcommand:`mini-buildd-api` or :mbdcommand:`mini-buildd-events`, respectively. To get started, try: .. code:: bash mini-buildd-api --help mini-buildd-events --help .. tip:: How to save credentials when working from the shell? Credentials are handled via :debpkg:`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**): .. literalinclude:: ../examples/mini-buildd-utils/keyringrc.cfg :caption: /usr/share/doc/mini-buildd-utils/examples/keyringrc.cfg .. seealso:: 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: .. literalinclude:: ../examples/mini-buildd-utils/python-client :caption: /usr/share/doc/mini-buildd-utils/examples/python-client ``python`` code might be more suitable for elaborated scripts; for simple tasks, rather use :mbdcommand:`mini-buildd-api`.