postmarketOS

https://docs.postmarketos.org
Admin
postmarketOS is a touch-optimized, pre-installed Linux-based operating system designed to replace...
Tokens:157,924
Snippets:1,039
Trust Score:9.7
Update:7 months ago
Show doc for...
Tokens:
Raw
### pmb.install._install.install_system_image

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Installs the system image onto a device, with options for partition labels, splitting, and single partition setup.

```APIDOC
## pmb.install._install.install_system_image

### Description
Installs the system image onto the device.

### Method
POST

### Endpoint
/pmb/install/_install/install_system_image

### Parameters
#### Request Body
- **args** (PmbArgs) - Required - pmbootstrap arguments.
- **size_reserve** (int) - Optional - empty partition between root and boot in MiB (pma#463).
- **chroot** (Chroot) - Required - The chroot object.
- **step** (int) - Required - current installation step.
- **steps** (int) - Required - total installation steps.
- **boot_label** (str) - Optional - label of the boot partition (e.g. “pmOS_boot”). Defaults to 'pmOS_boot'.
- **root_label** (str) - Optional - label of the root partition (e.g. “pmOS_root”). Defaults to 'pmOS_root'.
- **split** (bool) - Optional - create separate images for boot and root partitions. Defaults to False.
- **single_partition** (bool) - Optional - create a single partition for boot and root. Defaults to False.
- **disk** (Path | None) - Optional - path to disk block device (e.g. /dev/mmcblk0) or None.
```

--------------------------------

### Generate and Test Boot Artifacts for qemu-amd64

Source: https://docs.postmarketos.org/hardware-ci/gitlab-ci.html

This example demonstrates how to generate boot artifacts and then test them for the qemu-amd64 device using GitLab CI. The 'prepare-qemu-amd64' job extends '.pmos-ci-tron-build-boot-artifacts' to build the kernel and initramfs, specifying device name, kernel variant, and installation packages. The 'test-qemu-amd64' job extends '.pmos-ci-tron-initramfs-test' to boot these artifacts, configuring necessary tags and artifact URLs.

```yaml
prepare-qemu-amd64:
  stage: hardware tests
  extends:
    - .pmos-ci-tron-build-boot-artifacts
  variables:
    DEVICE_NAME: qemu-amd64
    KERNEL_VARIANT: lts
    INSTALL_PACKAGES: device-${DEVICE_NAME} device-${DEVICE_NAME}-kernel-${KERNEL_VARIANT} postmarketos-mkinitfs-hook-ci

test-qemu-amd64:
  stage: hardware tests
  extends:
    - .pmos-ci-tron-initramfs-test

  # List of tags the device/runner should have to be picked by GitLab for testing.
  # Alternatively you can use .pmos-ci-tron-runner-qemu-amd64 from common.yml
  tags:
    -   cpu:arch:x86_64
    -   virtio:codename:VIRTIO

  # Wait for the preapre-qemu-amd64 job to be over before executing this job
  dependencies: []
  needs:
    -   job: 'prepare-qemu-amd64'
      artifacts: false

  # Specify how to get the kernel and initramfs to use for testing
  variables:
    CI_TRON_KERNEL__URL: "glartifact://build-qemu-amd64/${CI_TRON__PMB_EXPORT_PATH}/vmlinuz-${KERNEL_VARIANT}"
    CI_TRON_INITRAMFS__INITRAMFS__URL: "glartifact://build-qemu-amd64/${CI_TRON__PMB_EXPORT_PATH}/initramfs"
```

--------------------------------

### Partition Disk for Installation (pmb.install.partition)

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Partitions a disk for installation, creating boot, root, and optional reserved partitions. It takes the partition layout, boot partition size, and a reserve size as input. This function is used for standard GPT devices.

```python
pmb.install.partition.partition(_layout : PartitionLayout_, _size_boot : int_, _size_reserve : int_) → None
```

--------------------------------

### Install pmbootstrap from Git

Source: https://docs.postmarketos.org/pmbootstrap/main/installation.html

Clones the pmbootstrap repository from git and creates a symbolic link for execution. This method is useful for obtaining the latest version or for development. It requires git to be installed on the system.

```shell
$ git clone --depth=1 https://gitlab.postmarketos.org/postmarketOS/pmbootstrap.git
$ mkdir -p ~/.local/bin
$ ln -s "$PWD/pmbootstrap/pmbootstrap.py" ~/.local/bin/pmbootstrap
$ pmbootstrap --version
2.1.0

```

--------------------------------

### pmb.install._install.setup_appstream

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Executes alpine-appstream-downloader to update AppStream data on new installations if the downloader has been downloaded.

```APIDOC
## pmb.install._install.setup_appstream

### Description
If alpine-appstream-downloader has been downloaded, execute it to have update AppStream data on new installs

### Method
POST

### Endpoint
/pmb/install/_install/setup_appstream

### Parameters
#### Request Body
- **offline** (bool) - Required - Whether to run in offline mode.
- **chroot** (Chroot) - Required - The chroot object.
```

--------------------------------

### pmb.install.blockdevice API

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Functions for creating, mounting, and checking block devices for installation.

```APIDOC
## POST /pmb.install.blockdevice/create

### Description
Creates the install block device, /dev/install, with specified partition sizes and options.

### Method
POST

### Endpoint
/pmb.install.blockdevice/create

### Parameters
#### Query Parameters
- **_sector_size** (int) - Optional - Sector size for the block device.
- **_size_boot** (int) - Required - Size of the boot partition in MiB.
- **_size_root** (int) - Required - Size of the root partition in MiB.
- **_size_reserve** (int) - Required - Size of the empty partition between root and boot in MiB.
- **_split** (bool) - Required - Whether to create separate images for boot and root partitions.
- **_disk** (Path) - Optional - Path to the disk block device (e.g., /dev/mmcblk0).

### Request Example
```json
{
  "_sector_size": null,
  "_size_boot": 512,
  "_size_root": 4096,
  "_size_reserve": 128,
  "_split": true,
  "_disk": "/dev/mmcblk0"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```

## POST /pmb.install.blockdevice/create_and_mount_image

### Description
Creates a new image file and mounts it as /dev/install.

### Method
POST

### Endpoint
/pmb.install.blockdevice/create_and_mount_image

### Parameters
#### Query Parameters
- **_sector_size** (int) - Optional - Sector size for the image file.
- **_size_boot** (int) - Required - Size of the boot partition in MiB.
- **_size_root** (int) - Required - Size of the root partition in MiB.
- **_size_reserve** (int) - Required - Size of the empty partition between root and boot in MiB.
- **_split** (bool) - Optional, defaults to False - Whether to create separate images for boot and root partitions.

### Request Example
```json
{
  "_sector_size": null,
  "_size_boot": 512,
  "_size_root": 4096,
  "_size_reserve": 128,
  "_split": false
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```

## POST /pmb.install.blockdevice/mount_disk

### Description
Mounts a specified disk block device.

### Method
POST

### Endpoint
/pmb.install.blockdevice/mount_disk

### Parameters
#### Query Parameters
- **_path** (Path) - Required - Path to the disk block device (e.g., /dev/mmcblk0).

### Request Example
```json
{
  "_path": "/dev/mmcblk0"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```

## POST /pmb.install.blockdevice/previous_install

### Description
Searches the disk for a previous installation of pmOS.

### Method
POST

### Endpoint
/pmb.install.blockdevice/previous_install

### Parameters
#### Query Parameters
- **_path** (Path) - Required - Path to the disk block device (e.g., /dev/mmcblk0).

### Request Example
```json
{
  "_path": "/dev/mmcblk0"
}
```

### Response
#### Success Response (200)
- **exists** (bool) - True if a previous installation is found, False otherwise.

#### Response Example
```json
{
  "exists": true
}
```
```

--------------------------------

### pmb.install._install.create_device_rootfs

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Handles the creation of the device's root filesystem. This function is involved in the core installation process and takes various options related to package installation and system security.

```APIDOC
## pmb.install._install.create_device_rootfs

### Description
Creates the device root filesystem.

### Method
None (Function)

### Endpoint
None (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **_step** (int) - Current step in the installation process.
* **_steps** (int) - Total number of installation steps.
* **_add** (str) - Additional packages to install.
* **_password** (str) - Password for the root user.
* **_install_base** (bool) - Whether to install the base system.
* **_install_recommends** (bool) - Whether to install recommended packages.
* **_full_disk_encryption** (bool) - Whether to enable full disk encryption.
* **_on_device_installer** (bool) - Whether to use the on-device installer.
* **_no_sshd** (bool) - Whether to disable SSH daemon.
* **_no_firewall** (bool) - Whether to disable the firewall.

### Request Example
None (Function call)

### Response
#### Success Response (None)
None

#### Response Example
None
```

--------------------------------

### pmb.install._install.set_user

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Creates a user with UID 10000 if it does not exist, avoiding conflicts with existing installations.

```APIDOC
## pmb.install._install.set_user

### Description
Create user with UID 10000 if it doesn’t exist. Usually the ID for the first user created is 1000, but higher ID is chosen here to not cause issues with existing installations. Historically, this was done to avoid conflict with Android UIDs/GIDs, but pmOS has since dropped support for hybris/Halium.

### Method
POST

### Endpoint
/pmb/install/_install/set_user

### Parameters
#### Request Body
- **config** (Config) - Required - The configuration object.
```

--------------------------------

### Install QEMU Dependencies

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.qemu.html

Installs any required QEMU dependencies within the native chroot environment. This function ensures that the necessary packages are present for QEMU to operate correctly with the specified architecture.

```python
def install_depends(_arch : Arch_) → None
```

--------------------------------

### Install Dependencies

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.flasher.html

The install_depends function, found in the pmb.flasher.init module, is responsible for installing necessary dependencies. It takes the method as a string argument.

```python
pmb.flasher.init.install_depends(_method : str_) → None
```

--------------------------------

### pmb.chroot.apk.install

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.chroot.html

Installs packages into the chroot, handling dependencies and building missing packages if necessary.

```APIDOC
## POST /pmb.chroot.apk.install

### Description
Installs packages from pmbootstrap’s local package index or the pmOS/Alpine binary package mirrors. Iterates over all dependencies recursively, and builds missing packages as necessary.

### Method
POST

### Endpoint
/pmb.chroot.apk.install

### Parameters
#### Query Parameters
- **packages** (Collection[str]) - Required - List of package names to be installed.
- **chroot** (Chroot) - Required - The chroot object representing the target environment.
- **build** (bool) - Optional - Defaults to True. Automatically build the package if it does not exist or needs updating within pmaports. Set to False for performance if all packages are expected in Alpine's repositories.
- **quiet** (bool) - Optional - Defaults to False. Suppresses output.

### Request Body
```json
{
  "packages": ["package1", "package2"],
  "chroot": "<chroot_object>",
  "build": true,
  "quiet": false
}
```

### Response
#### Success Response (200)
- **None** - Indicates successful installation.

#### Response Example
```json
null
```
```

--------------------------------

### Minimal postmarketOS Deviceinfo Example

Source: https://docs.postmarketos.org/pmaports/main/deviceinfo-reference.html

A basic example of a deviceinfo file for postmarketOS. It includes essential variables like format version, device name, manufacturer, codename, year, DTB, architecture, chassis, external storage, and flash method. This file can be sourced in shell scripts and uses double quotes for all values.

```shell
# https://postmarketos.org/deviceinfo
# Please use double quotes only. You can source this file in shell scripts.
deviceinfo_format_version="0"
deviceinfo_name="Manufacturer Official Name"
deviceinfo_manufacturer="Manufacturer"
deviceinfo_codename="vendor-codename"
deviceinfo_year="2026"
deviceinfo_dtb="qcom/qcm6490-fairphone-fp5"
deviceinfo_arch="aarch64"

# Device related
deviceinfo_chassis="handset"
deviceinfo_external_storage="false"

# Bootloader related
deviceinfo_flash_method="none"

```

--------------------------------

### pmb.commands.netboot.start_nbd_server

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.commands.html

Starts an NBD server in chroot_native with pmOS rootfs.

```APIDOC
## POST /pmb/commands/netboot/start-nbd-server

### Description
Starts an NBD server in chroot_native with pmOS rootfs. This allows network booting from the host.

### Method
POST

### Endpoint
/pmb/commands/netboot/start-nbd-server

### Parameters
#### Query Parameters
- **_device** (str) - Required - The device to serve via NBD.
- **_replace** (bool) - Optional - Whether to replace existing NBD server configurations.
- **_ip** (str) - Optional - IP address to serve NBD server for (default: '172.16.42.2').
- **_port** (int) - Optional - Port of the NBD server (default: 9999).

### Request Example
```json
{
  "_device": "sda1",
  "_replace": false,
  "_ip": "172.16.42.2",
  "_port": 9999
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of starting the NBD server.

#### Response Example
```json
{
  "status": "NBD server started successfully"
}
```
```

--------------------------------

### pmb.install._install.get_ondev_pkgver

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Retrieves the package version for the on-device installer.

```APIDOC
## pmb.install._install.get_ondev_pkgver

### Description
Retrieves the package version for the on-device installer.

### Method
None (Function)

### Endpoint
None (Internal function)

### Parameters
None

### Request Example
None (Function call)

### Response
#### Success Response (str)
- **str** - The package version string.

#### Response Example
None
```

--------------------------------

### pmb.install._install.copy_files_from_chroot

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Copies all files from the rootfs chroot to /mnt/install, excluding the home folder. This is essential for transferring the system to the installation target.

```APIDOC
## pmb.install._install.copy_files_from_chroot

### Description
Copy all files from the rootfs chroot to /mnt/install, except for the home folder (because /home will contain some mountpoint folders).

### Method
None (Function)

### Endpoint
None (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **_chroot** (Chroot) - The chroot object representing the source root filesystem.
* **_rsync** (bool) - Whether to use rsync for copying files.
* **_verbose** (bool) - Whether to enable verbose output during the copy process.

### Request Example
None (Function call)

### Response
#### Success Response (None)
None

#### Response Example
None
```

--------------------------------

### Initialize BPO Components

Source: https://docs.postmarketos.org/build.postmarketos.org/main/api/bpo.html

Initializes the necessary components for the BPO server. This function is typically called at the start of the BPO service.

```python
bpo.init_components()
```

--------------------------------

### pmb.build.envkernel Module Functions

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.build.html

Documentation for functions within the pmb.build.envkernel module, related to kernel build environment setup and packaging.

```APIDOC
## pmb.build.envkernel Module

### find_kbuild_output_dir

**Description**: Guesses the kernel build output directory by parsing function lines.

**Parameters**:
- `_function_body` (list[str]) - Contents of a function from the kernel APKBUILD.

**Returns**:
- `str` - The kbuild output directory, or None if not found.

### match_kbuild_out

**Description**: Looks for kernel build output paths in specific formats within a given word.

**Parameters**:
- `_word` (str) - A string segment from an APKBUILD function line.

**Returns**:
- `str | None` - The kernel build output directory, an empty string if a separate build output directory isn't used, or None if no output directory is found.

### modify_apkbuild

**Description**: Modifies a kernel APKBUILD to package build output from envkernel.sh.

**Parameters**:
- `_pkgname` (str) - Package name of a linux kernel aport.
- `_aport` (Path) - Path to the aport.

### overmount_makefile

**Description**: Overmounts the makefile for the kernel build environment.

**Parameters**:
- `_context` (Context) - The build context.
- `_kbuild_out` (str) - The kernel build output directory.

### package_kernel

**Description**: Frontend for ‘pmbootstrap build –envkernel’: creates a package from envkernel output.

**Parameters**:
- `_packages` (list[str]) - List of packages to create.

### run_abuild

**Description**: Prepares the build environment and runs abuild for kernel packaging.

**Parameters**:
- `_context` (Context) - The build context.
- `_pkgname` (str) - Package name of a linux kernel aport.
- `_arch` (Arch) - Architecture for the kernel.
- `_pmaports_path` (Path) - Path to the aports directory.
- `_apkbuild_path` (Path) - Path to the APKBUILD file.
- `_kbuild_out` (str) - Kernel build system output sub-directory.
```

--------------------------------

### Get All Installed Packages and Versions

Source: https://docs.postmarketos.org/mrhlpr/main/mrtest/mrtest.html

Returns a dictionary mapping all installed package names to their versions. For virtual packages, the version will be None. This function provides a comprehensive overview of the system's installed packages.

```python
import mrtest.apk_installed

# Example usage:
# installed_packages = mrtest.apk_installed.get_installed_all()
```

--------------------------------

### pmb.install._install.setup_keymap

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Sets the keymap using the setup-keymap utility if required by the device.

```APIDOC
## pmb.install._install.setup_keymap

### Description
Set the keymap with the setup-keymap utility if the device requires it

### Method
POST

### Endpoint
/pmb/install/_install/setup_keymap

### Parameters
#### Request Body
- **config** (Config) - Required - The configuration object.
```

--------------------------------

### pmb.install._install.setup_login

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Sets the user password and disables root login, looping until successful.

```APIDOC
## pmb.install._install.setup_login

### Description
Loop until the password for user has been set successfully, and disable root login.

### Method
POST

### Endpoint
/pmb/install/_install/setup_login

### Parameters
#### Request Body
- **config** (Config) - Required - The configuration object.
- **chroot** (Chroot) - Required - The chroot object.
- **password** (str) - Required - The user's password.
- **on_device_installer** (bool) - Required - Whether this is running on the device installer.
- **suffix** (str) - Required - of the chroot, where passwd will be execute (either the rootfs_{args.device} or installer_{args.device}).
```

--------------------------------

### Run Local Webserver for Documentation

Source: https://docs.postmarketos.org/dpo/index.html

Starts a local HTTP server to preview the built documentation. The command uses Python's http.server module to serve files from the '_out' directory on a specified host and port.

```shell
$ make run
python3 -m http.server -b 127.0.0.1 8080 -d _out
Serving HTTP on 127.0.0.1 port 8080 (http://127.0.0.1:8080/) ...
```

--------------------------------

### Get Installed Package Version using APK

Source: https://docs.postmarketos.org/mrhlpr/main/mrtest/mrtest.html

Retrieves the version of an installed package by providing the path to its APK file. Returns the version string or None if the package is virtual or not found. This interacts with Alpine's package manager.

```python
import mrtest.apk_installed

# Example usage:
# version = mrtest.apk_installed.get_installed("path/to/package.apk")
```

--------------------------------

### Get Package Repository Name from Subdirectory

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.core.html

Determines the package repository name from a given subdirectory path. For example, it returns 'pmaports' for a path like '$WORKDIR/pmaports/main/foobar'.

```python
from pathlib import Path

def pkgrepo_name_from_subdir(_subdir: Path) -> str:
    """Return the name of the package repository for the given directory. e.g. “pmaports” for “$WORKDIR/pmaports/main/foobar”"""
    # Implementation details would go here
    pass
```

--------------------------------

### Prepare PReP Partition (pmb.install.partition.partition_prep)

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Prepares a disk with PReP boot and root partitions. This function takes the partition layout as input and is specific to PReP boot environments.

```python
pmb.install.partition.partition_prep(_layout : PartitionLayout_) → None
```

--------------------------------

### Interactive Package Selection Dialog

Source: https://docs.postmarketos.org/mrhlpr/main/mrtest/mrtest.html

Presents an interactive dialog to the user for selecting packages to install or upgrade from a zip archive. It guides the user through the selection process and returns the chosen packages.

```python
from pathlib import Path
import mrtest.select_package

# Example usage:
# selected = mrtest.select_package.ask(Path("path/to/artifacts.zip"))
```

--------------------------------

### pmb.install._install.setup_hostname

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Sets the system hostname and updates the localhost address in /etc/hosts.

```APIDOC
## pmb.install._install.setup_hostname

### Description
Set the hostname and update localhost address in /etc/hosts

### Method
POST

### Endpoint
/pmb/install/_install/setup_hostname

### Parameters
#### Request Body
- **device** (str) - Required - The device name.
- **hostname** (str | None) - Optional - The desired hostname.
```

--------------------------------

### pmb.install._install.setup_locale

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Configures locale-related settings, including $LANG and keyboard layout.

```APIDOC
## pmb.install._install.setup_locale

### Description
Set locale-related settings such as $LANG and keyboard layout

### Method
POST

### Endpoint
/pmb/install/_install/setup_locale

### Parameters
#### Request Body
- **chroot** (Chroot) - Required - The chroot object.
- **locale** (str) - Required - The locale string to set.
```

--------------------------------

### Build Image Functions - bpo.jobs.build_image

Source: https://docs.postmarketos.org/build.postmarketos.org/main/api/bpo.jobs.html

Provides functions to manage image building processes. Includes getting image prefixes, pmbootstrap install commands, task names, and running the build job. These functions are crucial for automating the creation of postmarketOS images.

```python
bpo.jobs.build_image.get_arg_img_prefix(_kernel_)

bpo.jobs.build_image.get_pmbootstrap_install_cmd(_branch_)
    
pmbootstrap install command for image building. This is a separate function, so we can override it with a stub in a test. 

bpo.jobs.build_image.get_task_name(_prefix_ , _kernel_)
    
bpo.jobs.build_image.run(_device_ , _branch_ , _ui_)
    
Start a single image build job.
```

--------------------------------

### pmb.install._install.create_home_from_skel

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Creates the user's home directory (/home/{user}) by copying contents from the /etc/skel directory. This provides default user configurations and files.

```APIDOC
## pmb.install._install.create_home_from_skel

### Description
Create /home/{user} from /etc/skel.

### Method
None (Function)

### Endpoint
None (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **_filesystem** (str) - The filesystem type.
* **_user** (str) - The username for whom the home directory is created.

### Request Example
None (Function call)

### Response
#### Success Response (None)
None

#### Response Example
None
```

--------------------------------

### pmb.chroot.init.copy_resolv_conf

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.chroot.html

Copies the host's /etc/resolv.conf file to the chroot if it differs, or creates an empty one.

```APIDOC
## POST /pmb.chroot.init.copy_resolv_conf

### Description
Copies the /etc/resolv.conf file from the host system into the chroot. It uses Python's file comparison to check for differences and creates an empty file if it doesn't exist on the host.

### Method
POST

### Endpoint
/pmb.chroot.init.copy_resolv_conf

### Parameters
#### Query Parameters
- **chroot** (Chroot) - Required - The chroot object representing the target environment.

### Request Body
```json
{
  "chroot": "<chroot_object>"
}
```

### Response
#### Success Response (200)
- **None** - Indicates the file was copied or created successfully.

#### Response Example
```json
null
```
```

--------------------------------

### Install pmbootstrap via Package Manager on Linux

Source: https://docs.postmarketos.org/pmbootstrap/main/installation.html

Installs pmbootstrap using the native package manager for various Linux distributions. Ensure you have the necessary administrative privileges to run these commands. This method is distribution-specific.

```shell
# Alpine Linux, postmarketOS:
# apk add pmbootstrap

# Arch Linux:
# pacman -S pmbootstrap

# Debian:
# apt install pmbootstrap

# Fedora:
# dnf install pmbootstrap

# Void Linux:
# xbps-install -S pmbootstrap

# Gentoo:
# emerge -va app-eselect/eselect-repository
# eselect repository enable guru
# emaint -r guru sync
# emerge -va dev-util/pmbootstrap

# Nix/NixOS
# nix run nixpkgs#pmbootstrap

```

--------------------------------

### pmb.chroot.apk.install_run_apk

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.chroot.html

Executes apk commands to install, remove, or update packages within the chroot, ensuring precise control over installed packages.

```APIDOC
## POST /pmb.chroot.apk.install_run_apk

### Description
Runs apk to add packages, and ensures only the desired packages get explicitly marked as installed. Handles package additions, local package installations, and deletions due to conflicts.

### Method
POST

### Endpoint
/pmb.chroot.apk.install_run_apk

### Parameters
#### Query Parameters
- **to_add** (Collection[str]) - Required - List of package names to install, without their dependencies.
- **to_add_local** (Collection[Path]) - Required - List of paths to locally built packages to install.
- **to_del** (Collection[str]) - Required - List of package names to be deleted (e.g., conflicting dependencies).
- **chroot** (Chroot) - Required - The chroot object representing the target environment.

### Request Body
```json
{
  "to_add": ["package1"],
  "to_add_local": ["/path/to/local.apk"],
  "to_del": ["conflicting-package"],
  "chroot": "<chroot_object>"
}
```

### Response
#### Success Response (200)
- **None** - Indicates successful execution of apk commands.

#### Response Example
```json
null
```
```

--------------------------------

### Database Initialization and Session Management

Source: https://docs.postmarketos.org/build.postmarketos.org/main/api/bpo.db.html

Demonstrates how to initialize the database connection and obtain a session for performing database operations. This is a fundamental step before interacting with the database.

```python
import bpo.db

# Initialize the database
bpo.db.init()
bpo.db.init_relationships()

# Get a database session
session = bpo.db.session()

# Example usage: logging an action
log_entry = bpo.db.Log(action="db_init", details="hello world")
session.add(log_entry)
session.commit()
```

--------------------------------

### Install Packages from Merge Request (postmarketOS)

Source: https://docs.postmarketos.org/mrhlpr/main/usage.html

This command installs packages from a specified merge request ID on postmarketOS. It fetches artifacts from CI runs, identifies suitable packages, and prompts the user for interactive selection and installation. Ensure you understand the MR's changes before proceeding.

```bash
$ mrtest add MR_ID.

```

--------------------------------

### pmb.install._install.get_recommends

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Recursively collects recommended packages for a given list of packages. It checks for packages listed under '_pmb_recommends' within other packages, but only considers packages found in pmaports. If 'pmbootstrap install --no-recommends' is used, it returns an empty list.

```APIDOC
## pmb.install._install.get_recommends

### Description
Look through the specified packages and collect additional packages specified under _pmb_recommends in them. This is recursive, so it will dive into packages that are listed under recommends to collect any packages they might also have listed under their own _pmb_recommends. Recursion is only done into packages found in pmaports. If running with pmbootstrap install –no-recommends, this function returns an empty list.

### Method
None (Function)

### Endpoint
None (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **_packages** (list[str]) - The list of packages to check for recommendations.
* **_install_recommends** (bool) - Whether to install recommended packages.

### Request Example
None (Function call)

### Response
#### Success Response (Sequence[str])
- **Sequence[str]** - A sequence of recommended package names.

#### Response Example
None
```

--------------------------------

### Toggle Already Installed Packages in Selection

Source: https://docs.postmarketos.org/mrhlpr/main/mrtest/mrtest.html

Updates the selection list by toggling the status of packages that are already installed on the system. This helps in managing upgrades or re-installs.

```python
import mrtest.select_package

# Example usage:
# all_apks = ["pkg1.apk", "pkg2.apk"]
# current_selection = ["pkg1.apk"]
# updated_selection = mrtest.select_package.toggle_installed(all_apks, current_selection)
```

--------------------------------

### Get Device Category by Name

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.helpers.html

Determines the device category from the device's name, typically in the format 'vendor-codename'. This function provides a straightforward way to get the category when the device name is known.

```python
def pmb.helpers.devices.get_device_category_by_name(_device_name : str_) -> DeviceCategory:
    """
    Get the category of a device based on its name. 

    Device_name:
        Name of a particular device to determine the category of. Format should be “vendor-codename”. 

    Returns:
        The device category of the provided device name.
    """
    pass
```

--------------------------------

### Build Documentation Locally with Make

Source: https://docs.postmarketos.org/dpo/index.html

Clones a git repository and uses the 'make' command to build the documentation. This is a common process for both the main documentation repository and other related projects like pmbootstrap.

```shell
git clone https://gitlab.postmarketos.org/postmarketOS/docs.postmarketos.org.git
cd docs.postmarketos.org
make
```

```shell
git clone https://gitlab.postmarketos.org/postmarketOS/pmbootstrap.git
cd pmbootstrap/docs
make
```

--------------------------------

### Create Android Recovery Zip (pmb.install.recovery.create_zip)

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.install.html

Creates an installer zip file compatible with Android recovery systems. This function takes arguments related to the postmarketOS installation, a chroot environment, and the target device.

```python
pmb.install.recovery.create_zip(_args : PmbArgs_, _chroot : Chroot_, _device : str_) → None
```

--------------------------------

### pmb.chroot.init.init_keys

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.chroot.html

Copies Alpine and postmarketOS repository keys into the chroot's apk configuration.

```APIDOC
## POST /pmb.chroot.init.init_keys

### Description
Copies all Alpine and postmarketOS repository keys into the chroot's `/etc/apk/keys` directory. This ensures that apk can verify APKINDEX files from binary repositories even before the `alpine-keys` or `postmarketos-keys` packages are installed.

### Method
POST

### Endpoint
/pmb.chroot.init.init_keys

### Parameters
None

### Request Body
None

### Response
#### Success Response (200)
- **None** - Indicates the keys were successfully copied.

#### Response Example
```json
null
```
```

--------------------------------

### pmb.config.init Module

Source: https://docs.postmarketos.org/pmbootstrap/main/api/pmb.config.html

Functions for initializing configuration through interactive prompts.

```APIDOC
## pmb.config.init Module

### Description
Functions for initializing configuration through interactive prompts.

### Endpoints

#### `pmb.config.init.ask_build_pkgs_on_install(_default: bool_) -> bool`

##### Description
Prompts the user to confirm building packages on install.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_build_pkgs_on_install`

##### Parameters

###### Query Parameters
- **_default** (bool) - Required - The default value for the prompt.

###### Response

##### Success Response (200)
- **bool** - User's choice (True/False).

#### `pmb.config.init.ask_for_additional_options(_config: Config_) -> None`

##### Description
Prompts the user for additional configuration options.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_additional_options`

##### Parameters

###### Query Parameters
- **_config** (Config) - Required - The current configuration object.

###### Response

##### Success Response (200)
- **None** - Indicates completion of the prompt.

#### `pmb.config.init.ask_for_channel(_config: Config_) -> str`

##### Description
Asks for the postmarketOS release channel. The channel dictates which pmaports branch pmbootstrap will check out, and which repository URLs will be used when initializing chroots.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_channel`

##### Parameters

###### Query Parameters
- **_config** (Config) - Required - The current configuration object.

###### Response

##### Success Response (200)
- **str** - The selected channel name (e.g., “edge”, “v21.03”).

#### `pmb.config.init.ask_for_device(_context: Context_, _channel: str_) -> tuple[str, bool, str]`

##### Description
Prompts for the device vendor, model, and kernel.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_device`

##### Parameters

###### Query Parameters
- **_context** (Context) - Required - The current context.
- **_channel** (str) - Required - The selected postmarketOS channel.

###### Response

##### Success Response (200)
- **tuple[str, bool, str]** - A tuple containing: (device, device_exists, kernel)
  - device: "<vendor>-<codename>" string for the device.
  - device_exists: Boolean indicating if the device port exists in the repository.
  - kernel: Type of kernel (downstream, etc.).

#### `pmb.config.init.ask_for_device_kernel(_config: Config_, _device: str_) -> str`

##### Description
Asks for the kernel that should be used with the device.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_device_kernel`

##### Parameters

###### Query Parameters
- **_config** (Config) - Required - The current configuration object.
- **_device** (str) - Required - The device codename (e.g., “lg-mako”).

###### Response

##### Success Response (200)
- **str** - The kernel type ("downstream", "stable", "mainline", …). Returns None if the kernel is hardcoded in depends without subpackages.

#### `pmb.config.init.ask_for_hostname(_default: str | None_, _device: str_) -> str`

##### Description
Prompts the user for the desired hostname.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_hostname`

##### Parameters

###### Query Parameters
- **_default** (str | None) - Optional - The default hostname.
- **_device** (str) - Required - The device codename.

###### Response

##### Success Response (200)
- **str** - The entered hostname.

#### `pmb.config.init.ask_for_keymaps(_config: Config_, _deviceinfo: Deviceinfo_) -> str`

##### Description
Prompts the user for keymap selection.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_keymaps`

##### Parameters

###### Query Parameters
- **_config** (Config) - Required - The current configuration object.
- **_deviceinfo** (Deviceinfo) - Required - Device information.

###### Response

##### Success Response (200)
- **str** - The selected keymap.

#### `pmb.config.init.ask_for_locale(_current_locale: str_) -> str`

##### Description
Prompts the user for locale selection.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_locale`

##### Parameters

###### Query Parameters
- **_current_locale** (str) - Required - The current locale.

###### Response

##### Success Response (200)
- **str** - The selected locale.

#### `pmb.config.init.ask_for_mainline_downstream() -> DeviceCategory`

##### Description
Asks the user to choose between mainline and downstream kernels.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_mainline_downstream`

##### Parameters

None

###### Response

##### Success Response (200)
- **DeviceCategory** - The user's choice.

#### `pmb.config.init.ask_for_mirror() -> str`

##### Description
Prompts the user to select a mirror.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_mirror`

##### Parameters

None

###### Response

##### Success Response (200)
- **str** - The selected mirror URL.

#### `pmb.config.init.ask_for_pmaports_path(_default: Path_) -> Path`

##### Description
Asks for a path for pmaports, until it can either be created or already exists.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_pmaports_path`

##### Parameters

###### Query Parameters
- **_default** (Path) - Required - The default path for pmaports.

###### Response

##### Success Response (200)
- **Path** - The full path to the pmaports directory, with a leading ~ expanded.

#### `pmb.config.init.ask_for_provider_select(_apkbuild: dict[str, Any]_, _providers_cfg: dict[str, str]_) -> None`

##### Description
Asks for selectable providers that are specified using “_pmb_select” in a APKBUILD.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_provider_select`

##### Parameters

###### Query Parameters
- **_apkbuild** (dict[str, Any]) - Required - The APKBUILD with the _pmb_select.
- **_providers_cfg** (dict[str, str]) - Required - The configuration section with previously selected providers. Updated with new providers after selection.

###### Response

##### Success Response (200)
- **None** - Indicates completion of the prompt.

#### `pmb.config.init.ask_for_provider_select_pkg(_pkgname: str_, _providers_cfg: dict[str, str]_) -> None`

##### Description
Looks up the APKBUILD for the specified pkgname and asks for selectable providers that are specified using “_pmb_select”.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_provider_select_pkg`

##### Parameters

###### Query Parameters
- **_pkgname** (str) - Required - Name of the package to search APKBUILD for.
- **_providers_cfg** (dict[str, str]) - Required - The configuration section with previously selected providers. Updated with new providers after selection.

###### Response

##### Success Response (200)
- **None** - Indicates completion of the prompt.

#### `pmb.config.init.ask_for_ssh_keys(_ssh_key_glob: str_, _default: bool_) -> bool`

##### Description
Prompts the user about SSH key usage.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_ssh_keys`

##### Parameters

###### Query Parameters
- **_ssh_key_glob** (str) - Required - Glob pattern for SSH keys.
- **_default** (bool) - Required - Default value for the prompt.

###### Response

##### Success Response (200)
- **bool** - User's choice regarding SSH keys.

#### `pmb.config.init.ask_for_systemd(_config: Config_, _ui: str_) -> SystemdConfig`

##### Description
Prompts the user for systemd configuration.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_systemd`

##### Parameters

###### Query Parameters
- **_config** (Config) - Required - The current configuration object.
- **_ui** (str) - Required - The user interface type.

###### Response

##### Success Response (200)
- **SystemdConfig** (SystemdConfig) - The systemd configuration.

#### `pmb.config.init.ask_for_timezone() -> str`

##### Description
Prompts the user for timezone selection.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_timezone`

##### Parameters

None

###### Response

##### Success Response (200)
- **str** - The selected timezone.

#### `pmb.config.init.ask_for_ui(_deviceinfo: Deviceinfo_) -> str`

##### Description
Prompts the user for the user interface selection.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_ui`

##### Parameters

###### Query Parameters
- **_deviceinfo** (Deviceinfo) - Required - Device information.

###### Response

##### Success Response (200)
- **str** - The selected user interface.

#### `pmb.config.init.ask_for_ui_extras(_config: Config_, _ui: str_) -> bool`

##### Description
Prompts the user for additional user interface options.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_ui_extras`

##### Parameters

###### Query Parameters
- **_config** (Config) - Required - The current configuration object.
- **_ui** (str) - Required - The selected user interface.

###### Response

##### Success Response (200)
- **bool** - User's choice for extra UI options.

#### `pmb.config.init.ask_for_username(_default_user: str_) -> str`

##### Description
Asks for a reasonable username for the non-root user.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_username`

##### Parameters

###### Query Parameters
- **_default_user** (str) - Required - The default username.

###### Response

##### Success Response (200)
- **str** - The entered username.

#### `pmb.config.init.ask_for_work_path(_default: Path | None_) -> tuple[Path, bool]`

##### Description
Asks for the work path, until we can create it (when it does not exist) and write into it.

##### Method
GET

##### Endpoint
`/pmb.config.init.ask_for_work_path`

##### Parameters

###### Query Parameters
- **_default** (Path | None) - Optional - The default work path.

###### Response

##### Success Response (200)
- **tuple[Path, bool]** - A tuple containing:
  - path: The full path, with expanded ~ sign.
  - exists: Boolean indicating if the folder existed before testing writability.

#### `pmb.config.init.frontend(_args: PmbArgs_) -> None`

##### Description
Handles the initialization frontend based on provided arguments.

##### Method
POST

##### Endpoint
`/pmb.config.init.frontend`

##### Parameters

###### Request Body
- **_args** (PmbArgs) - Required - The arguments for the frontend.

###### Response

##### Success Response (200)
- **None** - Indicates completion.

#### `pmb.config.init.get_locales() -> list[str]`

##### Description
Retrieves a list of available locales.

##### Method
GET

##### Endpoint
`/pmb.config.init.get_locales`

##### Parameters

None

###### Response

##### Success Response (200)
- **list[str]** - A list of available locale strings.

#### `pmb.config.init.print_systemd_warning(_device_exists: bool_, _apkbuild: dict[str, Any]_, _kernel: str_) -> None`

##### Description
Prints a warning message related to systemd configuration.

##### Method
GET

##### Endpoint
`/pmb.config.init.print_systemd_warning`

##### Parameters

###### Query Parameters
- **_device_exists** (bool) - Required - Whether the device exists.
- **_apkbuild** (dict[str, Any]) - Required - The APKBUILD data.
- **_kernel** (str) - Required - The kernel type.

###### Response

##### Success Response (200)
- **None** - Indicates the warning was printed.

#### `pmb.config.init.require_programs() -> None`

##### Description
Ensures all required programs for pmbootstrap are installed.

##### Method
GET

##### Endpoint
`/pmb.config.init.require_programs`

##### Parameters

None

###### Response

##### Success Response (200)
- **None** - Indicates all programs are present or have been installed.

#### `pmb.config.init.switch_channel(_config: Config_, _channel: str_) -> None`

##### Description
Wrapper around pmb.config.pmaports.switch_to_channel_branch(channel) that also handles installing git hooks if master is selected.

##### Method
POST

##### Endpoint
`/pmb.config.init.switch_channel`

##### Parameters

###### Request Body
- **_config** (Config) - Required - The current configuration object.
- **_channel** (str) - Required - The target channel to switch to.

###### Response

##### Success Response (200)
- **None** - Indicates the channel switch was successful.
```
Tokens:
Raw