Metadata-Version: 2.4
Name: urpm
Version: 0.9.11
Summary: Modern package manager for Mageia Linux
Author: Mageia Community
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://mageia.org
Project-URL: Repository, https://github.com/mageia/urpm-ng
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# urpm-ng

A modern package manager for Mageia Linux, written in Python.

urpm-ng is a complete rewrite of the classic urpmi toolset, providing faster performance, better dependency resolution, and modern features like P2P package sharing.

## Prerequisites

### Distribution

At the moment you need Mageia 9 or Mageia 10.

### Firewall ports (for P2P sharing)

The `urpm-ng-daemon` package ships `/etc/shorewall/rules.urpm-ng` as
an include file, and its `%post` hooks it into `/etc/shorewall/rules`
automatically. On a Shorewall-managed box (the Mageia default) the
following ports are therefore open right after install, no action
needed:

- **TCP 9876** (production) or **TCP 9877** (dev mode) -- urpmd HTTP API
- **UDP 9878** (production) or **UDP 9879** (dev mode) -- Peer discovery broadcasts

If Shorewall is not in use (bare `iptables` / `nftables`), open the
ports by hand — the file `/etc/shorewall/rules.urpm-ng` in the source
tree is a good template.

## Installation

### Packages

urpm-ng is split into several packages for flexibility:

| Package | Description |
|---------|-------------|
| `urpm-ng-core` | Minimal: CLI, resolver, database |
| `urpm-ng-daemon` | Background daemon + P2P sharing |
| `urpm-ng` | Meta: pulls `-core` + `-daemon` (standard install) |
| `urpm-ng-appstream` | AppStream metadata configuration (Mageia OS metainfo, distro config) |
| `urpm-ng-packagekit-backend` | PackageKit backend (Discover, GNOME Software) + D-Bus service |
| `urpm-ng-desktop` | Meta: pulls `-core` + `-daemon` + `-appstream` + `-packagekit-backend` |
| `urpm-ng-build` | Meta: pulls `-core` (for `urpm image` / `urpm build` — commands live in `-core`) |
| `urpm-ng-genmedia` | Server-side media metadata generation (`urpm genmedia`, for mirror maintainers) |
| `urpm-ng-all` | Meta: pulls everything above |

**Choose the right package:**
- **Minimal / container install**: `urpm-ng-core`
- **Standard CLI usage**: `urpm-ng`
- **Desktop with GUI software centers**: `urpm-ng-desktop`
- **Package builders (bm / mkimage users)**: `urpm-ng-build`
- **Mirror maintainers publishing repositories**: `urpm-ng-genmedia`

### Quick install / upgrade (`geturpm.sh`)

`geturpm.sh` is the recommended way to install urpm-ng on a fresh Mageia
system, and it can also upgrade an existing install. It auto-detects the
Mageia release and architecture, pulls the latest urpm-ng from the channel
you pick, and does the right thing whether urpm-ng is already installed or
not (fresh boxes bootstrap with `urpmi`; further upgrades use urpm-ng itself).

**Quick — piped, no local inspection**

```bash
curl -fsSL https://raw.githubusercontent.com/pvi-github/urpm-ng/main/geturpm.sh | bash
```

Prompts (channel choice, "Proceed?", the root password for `su`) are
read from `/dev/tty`, so the piped form is fully interactive — same
experience as running the script from a file.

**Verified — download, read, then run** (recommended if you don't
already trust the source):

```bash
curl -fsSLO https://raw.githubusercontent.com/pvi-github/urpm-ng/main/geturpm.sh
less geturpm.sh                  # inspect before running
bash geturpm.sh                  # interactive: asks channel + confirmation
```

**Channel selection** (`--channel=CHAN`):

- `mgabiz` — fetches from the Mageia.biz project repo (default when
  no terminal is available). Uses `urpm media discover` on the mgabiz
  mirror, so future updates go through the standard `urpm media
  update` flow.
- `github` — fetches release RPMs straight from the GitHub releases
  page. Useful for testing a specific tag, or when the mgabiz
  publication lags a release.

**Unattended runs** — add `-y` (skip the "Proceed?" confirmation) and
`--channel=CHAN` (skip the channel prompt) via `bash -s --`:

```bash
curl -fsSL <url>/geturpm.sh | bash -s -- -y --channel=mgabiz
```

Note: on the first install, urpm-ng imports its configuration from
existing `urpmi.cfg` and `urpmi/skip.list` files automatically.

## First-run setup

urpm works out of the box. Advanced options (blacklist, redlist, kernel-keep) are documented under **Configuration** further down.

When installed system-wide (in `/usr/bin/`), urpm uses:
- Database: `/var/lib/urpm/packages.db`
- Daemon port: 9876
- PID file: `/run/urpmd.pid`

### Media sources

On an install performed via the RPM path (or `geturpm.sh`), the standard
Mageia media and the servers to fetch them from are set up automatically:
`urpm-ng` imports the existing `urpmi.cfg` at first run and
`urpm server autoconfig` fills the mirror pool from the Mageia mirror
API. Nothing else is required to install packages.

On a machine with no prior `urpmi.cfg` (fresh chroot, image build, or a
system that never had urpmi), the same bootstrap is one manual pass:

```bash
urpm media list                       # Nothing yet? bootstrap:
urpm media import                     # Reads /etc/urpmi/urpmi.cfg by default; no-op if absent
urpm server autoconfig                # Pull mirrors from the Mageia API
urpm media update                     # First metadata sync
```

To add a **community repository** (MageiaLinux-Online, mageia.biz,
blogdrake, an in-house mirror, ...), use `urpm media discover` — it
reads the repository's `media.cfg` and adds every media it advertises
in one call:

```bash
urpm media discover https://www.mageia.biz/repo/Mageia/mgabiz/10/x86_64/media/
urpm media discover --dry-run https://download.mageialinux-online.org/...   # Preview
```

`urpm media add` is reserved for a single, non-discover-compliant
custom media — that is, one you know is not published through a
`media.cfg`. See the **Media Management** section further down for
the syntax.

---

# urpm - Command Line Interface

## Global Options

These options apply to most commands and are placed before the subcommand:

```bash
-V, --version              # Show urpm version
-v, --verbose              # Verbose output
-q, --quiet                # Quiet output
--nocolor                  # Disable colored output
--root DIR                 # Use DIR as root for RPM install (chroot, urpm config from host)
--urpm-root DIR            # Use DIR as root for both urpm config and RPM install
```

The following parents are inherited by transactional and query commands
(`install`, `upgrade`, `erase`, `download`, `depends`, ...):

```bash
--arch ARCH                # Target architecture (default: current system)
--debug COMPONENT          # Enable debug output: solver, tsrun, orphans, download, timing, all
--watched PACKAGES         # Comma-separated package names to watch during resolution
```

Note: `--arch` (parent option, sets the target architecture for the
operation) is distinct from `--allow-arch` (per-call option on
install/upgrade/download, allows additional architectures alongside the
system arch — typically `i686` for wine/steam on x86_64).

## Display Options

Most commands support these output options:

```bash
--show-all            # Show all items without truncation
--flat                # One item per line (parsable by scripts)
--json                # JSON output (for programmatic use)
```

By default, long lists are displayed in multi-column format and truncated to 10 lines with "... and N more". Use `--show-all` to see everything.

Examples:
```bash
urpm list installed --flat          # One package per line
urpm search firefox --json          # JSON output
urpm i task-plasma --show-all       # Show all dependencies
```

## Atomic vs best-effort transactions

Since 0.7.9, `urpm upgrade` runs in **best-effort** mode by default:
packages whose dependencies cannot be satisfied are dropped from the
transaction and reported at the end with their reason (missing
dependency, version mismatch, SRPM sibling cascade, ...). The transaction
is committed for everything else. Pass `--atomic` to switch to strict
mode (recommended on servers): any unsolvable package aborts the whole
transaction.

`urpm install`, by contrast, is **atomic by default**: if any requested
package cannot be installed, the entire transaction is rolled back. Pass
`--no-atomic` to opt into best-effort mode for the install path.

## Exit codes

| Code | Meaning |
|------|---------|
| 0    | Transaction completed successfully, no package skipped |
| 1    | Hard failure: transaction aborted (atomic mode, network, permission, ...) |
| 2    | Partial transaction: succeeded but at least one package was dropped (skipped packages listed on stderr with their reason) |

Scriptable check for the partial case:

```bash
urpm upgrade --auto || [ $? -eq 2 ] && echo "ok or partial"
```

## Package Management

### Install packages

```bash
urpm install <package>        # Install a package
urpm i <package>              # Short alias

# Options
--auto, -y                    # Non-interactive mode
--test                        # Dry run (simulation)
--without-recommends          # Skip recommended packages
--with-suggests               # Also install suggested packages
--force                       # Force despite dependency problems
--reinstall                   # Reinstall already installed packages (repair)
--nosignature                 # Skip GPG verification (not recommended)
--noscripts                   # Skip pre/post install scripts (chroot/container builds)
--no-peers                    # Disable P2P download from LAN peers
--only-peers                  # Only download from LAN peers, no upstream mirrors
--no-atomic                   # Best-effort mode (default is atomic for install)
--download-only               # Download to cache, do not install
--nodeps                      # Skip dependency resolution (with --download-only)
--all                         # Install for all matching families (e.g., php8.4 + php8.5)
--install-src                 # Install source RPM (extract spec/sources to ~/rpmbuild/)
--config-policy {keep,replace,ask}  # Config file conflict policy (default: keep)
--prefer=<prefs>              # Guide alternative choices (see below)
--allow-arch <arch>           # Allow additional architectures (e.g., i686 for wine/steam)
--sync                        # Wait for full completion (post-install triggers)
```

#### Preference-guided installation

When installing packages with alternatives (e.g., phpmyadmin that can use different PHP versions and web servers), use `--prefer` to guide choices:

```bash
# Prefer PHP 8.4 with Apache and php-fpm, exclude mod_php
urpm i phpmyadmin --prefer=php:8.4,apache,php-fpm,-apache-mod_php

# Prefer nginx instead of apache
urpm i phpmyadmin --prefer=php:8.4,nginx,php-fpm
```

Preference syntax:
- `capability:version` - Version constraint (e.g., `php:8.4`)
- `pattern` - Prefer packages providing this capability (e.g., `apache`, `php-fpm`)
- `-pattern` - Disfavor packages matching this (e.g., `-apache-mod_php`)

Preferences work by checking package REQUIRES and PROVIDES, not package names.

#### Architecture filtering

By default, urpm only considers packages matching your system architecture and `noarch`. This prevents accidental installation of i686 packages on x86_64 systems when 32-bit media are enabled.

To install 32-bit packages (wine, steam, multilib):

```bash
urpm install wine --allow-arch i686
urpm install steam --allow-arch i686

# Multiple architectures
urpm install mypackage --allow-arch i686 --allow-arch armv7hl
```

### Remove packages

```bash
urpm erase <package>          # Remove a package
urpm e <package>              # Short alias

# Options
--auto, -y                    # Non-interactive mode
--test                        # Dry run (simulation)
--auto-orphans                # Also remove orphan dependencies (implied by -y unless --keep-orphans)
--keep-orphans                # Do not remove orphan dependencies
--erase-recommends            # Also remove packages only recommended (not required)
--keep-suggests               # Keep packages that are suggested by remaining packages
--force                       # Force despite dependency problems
--debug {solver,tsrun,all}    # Enable debug output for the resolver/transaction
--sync                        # Wait for full completion (post-uninstall triggers)
```

### Update metadata (apt-style)

```bash
urpm update                   # Update all media metadata
urpm update "Core Release"    # Update specific media
```

Since 0.7.x, `files.xml.lzma` is fetched alongside `synthesis.hdlist.cz` whenever the media publishes it — no opt-in flag needed.

### Download packages (without installing)

```bash
urpm download <package>       # Download a package to cache
urpm dl <package>             # Short alias
urpm download --only-peers pkg  # Download only from LAN peers

# Options
--release, -r <version>       # Target release for cross-release downloads (e.g., cauldron)
--buildrequires, --br [SPEC]  # Download build dependencies (auto-detect or from .spec/.src.rpm)
--without-recommends          # Skip recommended packages
--nodeps                      # Download only the listed packages, no dependencies
--no-peers / --only-peers     # Same as install (peer policy)
--allow-arch <arch>           # Allow additional architectures
--arch <arch>                 # Inherited: target architecture
--show-all                    # Print the full list of resolved packages
                              # (default truncates to 20 with "... and N more")
```

### Upgrade packages

```bash
urpm upgrade                  # Upgrade all packages
urpm u                        # Short alias
urpm upgrade <package>        # Upgrade specific packages

# Options
--auto, -y                    # Non-interactive mode
--test                        # Dry run (simulation)
--atomic                      # Strict mode: abort the whole transaction on any unsolvable package.
                              # Default is best-effort (see "Atomic vs best-effort transactions" above).
--with-recommends             # Install recommended packages
--with-suggests               # Also install suggested packages
--noerase-orphans             # Keep orphan dependencies (do not remove them)
--download-only               # Download to cache without applying the upgrade
--nosignature                 # Skip GPG verification (not recommended)
--no-peers / --only-peers     # Disable / restrict to LAN peers
--force                       # Force upgrade despite dependency problems
--config-policy {keep,replace,ask}  # Config file conflict policy (default: keep)
--allow-arch <arch>           # Allow additional architectures (e.g., i686)
--sync                        # Wait for full completion (post-install triggers)
```

### Auto-remove orphans

```bash
urpm autoremove               # Remove unused dependencies (default: --orphans)
urpm ar                       # Short alias

# Selectors
--orphans, -o                 # Orphaned packages (default)
--kernels, -k                 # Old kernels
--faildeps, -f                # Deps from interrupted transactions
--buildrequires, -b           # Build dependencies (--builddeps, --br)
--all, -a                     # All of the above

# Options
--auto, -y                    # Non-interactive mode
```

### Distribution upgrade (mga N → N+1)

```bash
urpm distupgrade                        # Auto-detect target = current + 1
urpm distupgrade --to 11                # Explicit target release
urpm distupgrade --to cauldron          # Target Cauldron (rolling)
urpm distupgrade --to cauldron:12       # Cauldron pointing at 12 (during freeze)

# Options
--to <version>                # Explicit target ; auto = current + 1
--yes / -y / --auto           # Skip confirmation prompts, auto-drop old
                              # media at Stage 4
--dry-run                     # Stage 0 checks + metadata refresh only
--export-plan <file>          # Solve, write NEVRAs to <file>, restore DB
                              # (no download, no install) — pair with
                              # `urpm download --from-file` on a neighbour
                              # peer to preload cache before the real run
--resume                      # Resume a previously interrupted distupgrade
--abort                       # Abandon a running or interrupted distupgrade

# Post-upgrade cleanup
urpm media remove --distupgraded   # Drop the mga N repositories replaced
                                    # by their mga N+1 counterpart
```

Runs in stages : preliminary checks (release detection, target maturity,
multi-version-jump prompt) → repository switchover → target-release solve
+ confirmation prompt → download → install of critical system components
(rpm / python / glibc) first, then the rest → post-transaction report
(`.rpmnew` files, residual mga N packages, orphan third-party media). Reboot
so post-boot adjustments run at next startup.

Before anything is downloaded, the plan is measured against every filesystem that has to hold part of it, and the figures are printed next to the confirmation prompt. Nothing is refused: the estimate is calibrated against a single measured migration, and a wrong refusal would abort an upgrade that had every chance of working — after the repositories have already been switched over, since the plan cannot exist before that.

The filesystem carrying `/usr` is charged what the incoming packages occupy minus what the departing ones give back, plus one batch caught between its writes and its commit, plus the packages still in use whose space only comes back with the last batches. The one carrying the download cache is charged the RPMs still to fetch. Where `/var` is a separate partition the two get separate verdicts; on a single filesystem they still are not added, because each batch's RPMs are deleted as soon as it installs, so the cache drains as the new files arrive and the peak is the larger of the two.

Beside that estimate — never inside it — sits a recommended headroom of 10% of the installed footprint, for what no package declares: the regenerated initramfs, the font and icon caches. Folding it into the requirement turned a measurement into a verdict. Blocks a filesystem reserves for root are not counted as available. If the margin is thin or the filesystem plainly too small, you get the figures and the commands that free space where it is actually missing, and you decide.

## Search and Query

### Search packages

```bash
urpm search <pattern>         # Search by name/summary
urpm s <pattern>              # Short alias
urpm q <pattern>              # Query alias (urpmq compatibility)

# Options
--installed                   # Search only installed packages
--unavailable                 # List installed packages not in any media
```

#### Find unavailable packages

List packages that are installed but no longer available in any configured media (like `urpmq --unavailable`):

```bash
urpm q --unavailable          # List all unavailable packages
urpm q --unavailable php      # Filter by pattern
```

### Show package info

```bash
urpm show <package>              # Show package details
urpm info <package>              # Alias
urpm show --files <package>      # Also print the package's file list
                                 # (rpm -ql if installed, files.xml.lzma otherwise)
urpm show --changelog <package>  # Also print the package's changelog
                                 # (rpm -q --changelog; installed packages only)
```

### List packages

```bash
urpm list installed           # List installed packages
urpm list available           # List available packages
urpm list updates             # List available updates
urpm list upgradable          # Alias for updates
```

### Dependencies

```bash
urpm depends <package>        # Show what a package requires
urpm rdepends <package>       # Show what requires a package (reverse deps)
urpm why <package>            # Explain why a package is installed

# Options for depends
--tree                        # Show dependency tree
--prefer=<prefs>              # Filter by preferences (same syntax as install)
--legend                      # Show symbol legend after tree display

# Options for rdepends
--tree                        # Show reverse dependency tree
--all                         # Show all recursive reverse dependencies (flat)
--depth=N                     # Maximum tree depth (default: 3)
--hide-uninstalled            # Only show paths leading to installed packages
--legend                      # Show symbol legend after tree display
```

Example with preferences:
```bash
# Show phpmyadmin dependencies preferring PHP 8.4
urpm depends phpmyadmin --prefer=php:8.4
```

Example with rdepends:
```bash
# Show reverse dependency tree for rtkit, depth 10, only installed paths
urpm rdepends --tree --hide-uninstalled --depth=10 rtkit
```

### Weak dependencies

```bash
urpm recommends <package>     # Show packages recommended by a package
urpm whatrecommends <package> # Show packages that recommend a package
urpm suggests <package>       # Show packages suggested by a package
urpm whatsuggests <package>   # Show packages that suggest a package
```

### File queries

```bash
urpm provides <package>       # List files provided by a package
urpm whatprovides <file>      # Find which package provides a file
urpm find <pattern>           # Search files in packages (installed + available)
urpm find -i <pattern>        # Search only in installed packages
urpm find -a <pattern>        # Search only in available packages
urpm find <pattern> --all-versions  # Include every EVR that ships the match
urpm find <pattern> --limit 500     # Raise the default 100-hit cap
```

`urpm find` searches both installed and available packages by default. `files.xml.lzma` is fetched automatically as part of every `urpm media update` (conditional on the media advertising it in `MD5SUM`), so no opt-in is required — the `--sync-files` toggle was removed in 0.7.x.

## Package Marking

```bash
urpm mark manual <package>    # Mark as manually installed
urpm mark auto <package>      # Mark as auto-installed (dependency)
urpm mark show <package>      # Show install reason
```

## Package Holds

Hold packages to prevent upgrades and replacement by obsoletes:

```bash
urpm hold <package>           # Hold a package
urpm hold <package> -r "reason"  # Hold with a reason
urpm hold                     # List held packages
urpm unhold <package>         # Remove hold
```

Held packages are protected from:
- Version upgrades during `urpm upgrade`
- Being replaced by packages that obsolete them

Example:
```bash
# dhcpcd obsoletes dhcp-client, but you want to keep dhcp-client
urpm hold dhcp-client -r "Prefer dhcp-client over dhcpcd"

# Now urpm upgrade will skip dhcp-client and warn:
#   Held packages (1) skipped:
#     dhcp-client (would be obsoleted by dhcpcd)

# To allow the replacement later:
urpm unhold dhcp-client
```

## History and Undo

```bash
urpm history                  # Show transaction history (last 20)
urpm history -i               # Filter: install transactions only
urpm history -r               # Filter: remove transactions only
urpm history -d <id>          # Show details of transaction <id>
urpm history --delete <id>... # Delete transactions from the history log

urpm undo [id]                # Undo a transaction (default: last). Records a clean
                              # history entry. Use --auto/-y to skip the prompt.

urpm rollback <n>             # Rollback last n transactions
urpm rollback to <id>         # Rollback to a specific transaction
urpm rollback to <date>       # Rollback to a date (YYYY-MM-DD or DD/MM/YYYY)
```

## Background transactions

When a transaction is detached (e.g. via the daemon or PackageKit), follow
its progress with:

```bash
urpm progress                 # Show current transaction progress and exit
urpm progress --watch         # Continuously watch until completion
```

## Distribution identity (`distro-switch`)

A machine has one release identity at a time — either a numeric stable
(`10`, `11`, …) or `cauldron`.  That identity anchors which media the
resolver considers when it composes an install or upgrade transaction;
media whose `mageia_version` doesn't match are left out of the pool even
if they're still enabled in the DB.

Switching identity is a deliberate act (a dist-upgrade in filigree), so
it lives in its own verb rather than in `urpm config`.

```bash
urpm distro-switch cauldron     # move this machine onto cauldron
urpm distro-switch 11           # move it to the numeric mga11 tree
urpm distro-switch cauldron:12  # cauldron with an explicit numeric target
```

Before applying the switch, the command:

- Verifies at least one enabled media already carries the target identity
  (otherwise you'd end up with an empty candidate pool).  Diagnostic hints
  at `urpm media autoconfig -r <target>` when the check fails.
- Warns about media of the old identity that stay enabled — they will drop
  out of the resolver's view until re-aligned or disabled.
- Best-effort refresh of `system-numeric` (the effective numeric used to
  render `.mgaN` release tags and seed `/etc/mageia-release` inside build
  containers): explicit override wins first, identity itself if numeric,
  else a probe of an enabled server's `media.cfg`.

After the switch, run `urpm media update` to fetch the new identity's
metadata.

## Media Management

```bash
urpm media list               # List configured media
urpm media add <url>          # Add official Mageia media (auto-parsed)
urpm media add --custom "Name" shortname <url>  # Add custom/third-party media
urpm media remove <name>...   # Remove one or more media sources
urpm media remove --all       # Remove EVERY configured media (asks for
                              # confirmation; add -y/--auto to skip it).
                              # Orphan servers (no media left) are
                              # dropped in the same pass.
urpm media enable <name>      # Enable a media
urpm media disable <name>     # Disable a media
urpm media update [name]      # Update media metadata
urpm media import <file>      # Import from urpmi.cfg
urpm media link <name> +srv -srv  # Link/unlink servers to a media
urpm media set <name> [opts]  # Modify media settings (sharing, replication, quota...)
urpm media seed-info <name>   # Show seed set info (sections, package count, size estimate)
urpm media autoconfig -r 10   # Auto-add official Mageia media for release 10
urpm media discover <url>     # Discover media from a repo's media.cfg
```

Useful flags for `urpm media add`:

```bash
--import-key                  # Import the GPG key advertised by the media
--allow-unsigned              # Allow unsigned packages (custom media only)
--version <ver>               # Target Mageia version (custom media only: 9, 10, cauldron...)
--update                      # Mark as an update media
--disabled                    # Add but leave disabled
-y, --auto                    # Non-interactive: accept the auto-detected name/short_name
```

### Import media from a legacy urpmi.cfg

Migrate an existing Mageia box from `urpmi` to urpm-ng without hand-adding
each media source. Both URL-based entries and `MIRRORLIST=` entries are
imported — the latter as pending media that `urpm server autoconfig`
attaches servers to on the next run.

```bash
urpm media import /etc/urpmi/urpmi.cfg    # Default source path
urpm media import                          # Same (path defaults to /etc/urpmi/urpmi.cfg)

# Options
--replace                     # Overwrite media entries that already exist by short_name
-r, --release <version>       # Target Mageia release (default: /etc/mageia-release value)
--arch <arch>                 # Target architecture (default: `uname -m`)
-y, --auto                    # Non-interactive: skip the confirmation prompt
```

### Discover media from a repository

Discover all available media from any Mageia-compatible repository
(official mirrors, community repos like MLO, corporate mirrors):

```bash
urpm media discover https://repo.example.org/9/x86_64/media/       # Add all media
urpm media discover --dry-run https://repo.example.org/9/x86_64/media/  # Preview only
urpm media discover --sources --debug https://...                   # Include SRPMS and debug

# Force-enable / force-disable categories (nonfree, tainted, 32bit, all)
urpm media discover --with nonfree,tainted https://...
urpm media discover --without nonfree https://...
urpm media discover --with all https://...
```

The command fetches `media.cfg` from the repository, discovers all media,
and links existing servers that host the same content (verified by MD5
checksum of `synthesis.hdlist.cz`).

### Server-Media linking

Link or unlink servers to specific media sources:

```bash
urpm media link "Core Release" +mirror1 +mirror2   # Add servers
urpm media link "Core Updates" -oldserver          # Remove server
urpm media link "Core Release" +all                # Add all available servers
urpm media link "Core Release" -all +preferred     # Reset and add one
```

Note: When adding servers, urpm verifies the media content matches by comparing MD5 checksums of `synthesis.hdlist.cz` with existing reference servers.

### Auto-configure media

Automatically add official Mageia media for a release:

```bash
urpm media autoconfig --release 10              # Add all official media for Mageia 10
urpm media autoconfig -r cauldron               # Add media for Cauldron
urpm media autoconfig -r 10 --no-nonfree        # Skip nonfree media
urpm media autoconfig -r 10 --no-tainted        # Skip tainted media
urpm media autoconfig -r 10 -n                  # Dry-run: show what would be added
```

### Media settings

Configure media sharing and replication:

```bash
urpm media set "Core Release" --shared=yes           # Share with P2P peers
urpm media set "Core Release" --replication=seed     # Full replication (DVD-like)
urpm media set "Core Release" --replication=on_demand  # Cache downloaded packages
urpm media set "Core Release" --quota=5G             # Limit cache size
urpm media set "Core Release" --retention=30         # Keep packages 30 days
urpm media set "Core Release" --priority=10          # Higher priority
urpm media set "Core Release" --seeds=INSTALL,CAT_PLASMA5  # Seed sections
```

Examples:
```bash
# Add official Mageia media (server and media auto-detected)
urpm media add https://ftp.belnet.be/mageia/distrib/9/x86_64/media/core/release/

# Add custom third-party media
urpm media add --custom "RPM Fusion" rpmfusion https://download1.rpmfusion.org/free/fedora/40/x86_64/os/
```

## Server Management

Servers are mirror sources that can serve multiple media. urpm supports multiple servers per media for load balancing and failover.

```bash
urpm server list              # List configured servers (with country)
urpm server add <name> <url>  # Add a server (tests IP and scans media)
urpm server remove <name> ... # Remove one or more servers
urpm server enable <name>     # Enable a server
urpm server disable <name>    # Disable a server
urpm server priority <name> <n>  # Set server priority (higher = preferred)
urpm server test [name]       # Test connectivity and detect IP mode
urpm server ip-mode <name> <mode>  # Set IP mode (auto/ipv4/ipv6/dual)
urpm server autoconfig        # Auto-add servers from Mageia mirror API
urpm server stats [name]      # Show performance statistics for a server
urpm server status            # Show blacklisted / low-reputation servers
urpm server unblacklist <name>   # Clear a server's blacklist (after review)
urpm server ack-blacklist <name>  # Acknowledge a blacklist (silences the banner)
```

### Server list

Options for urpm server list:
```bash
--all                 # Show all servers including those disabled
```

### IP Mode

Each server has an IP mode to handle IPv4/IPv6 connectivity:
- `auto` - Let system decide (may cause 30s timeout if IPv6 fails)
- `ipv4` - Force IPv4 only
- `ipv6` - Force IPv6 only
- `dual` - Both work, prefer IPv4 (recommended for dual-stack servers)

IP mode is auto-detected when adding a server. Use `server test` to re-detect or `server ip-mode` to set manually.

### Bandwidth tracking and automatic failover

urpm tracks download performance for each server automatically. After each download
or metadata sync, the measured speed is recorded using an EWMA (Exponentially
Weighted Moving Average, α=0.3), giving inertia so a single slow transfer doesn't
unfairly penalise a good server.

Servers are tried in order of `priority DESC, bandwidth_kbps DESC`: if a server
fails during a download or metadata sync, the next best server is tried automatically
without user intervention. Within a session, per-server speed estimates are also
kept in memory so the ordering adapts in real time without waiting for the next run.

`urpm server autoconfig` measures latency to all mirror candidates and persists
the results, so server ordering is meaningful from the very first download.

### Blacklist and reputation

A server that serves a corrupt or unsigned RPM is **auto-blacklisted**: it is
excluded from further downloads until you review and clear it. Signature
failures are treated as active tampering signals — no time-based auto-unblock.

Alongside the blacklist, urpm maintains a sliding 24 h **reputation score**
(baseline 100) that drains on corrupt bodies, HTTP 4xx/5xx, network errors
and slow transfers. The score reorders the pool without excluding servers
outright.

```bash
urpm server status               # List blacklisted and low-reputation servers
urpm server unblacklist <name>   # Clear the blacklist after human review
urpm server ack-blacklist <name> # Acknowledge (silences the banner without unblocking)
```

At `install` / `upgrade` / `media update` time, a persistent red banner lists
every unacknowledged blacklist with reactivation instructions — the banner
does not go away on its own, only `unblacklist` or `ack-blacklist` silences it.

`urpm server list` flags blacklisted rows in red so a glance at the pool
tells you immediately who is out.

### Geographic filtering

Servers discovered from the Mageia mirror API carry country and continent
metadata.  The `[server]` configuration section (see below) lets you
restrict which mirrors are accepted:

```ini
# /etc/urpm/conf.d/10-server.cfg
[server]
country_blacklist = UA, RU        # Exclude specific countries
continent_whitelist = EU          # Only European mirrors
```

Filtering is applied when mirrors are added (`urpm init`, `urpm media
autoconfig`, `urpm server autoconfig`, and background pool expansion).
Servers already in the database are backfilled with their country on
first run; those that fail the filter are disabled automatically.

Set `auto_add = false` to prevent all automatic mirror addition.

Use `urpm server stats [name]` to inspect the collected metrics:

```
$ urpm server stats mirror1
mirror1  https://mirror.example.com/mageia/
  Status        : enabled
  Priority      : 50
  IP mode       : dual
  Bandwidth     : 12 400 KB/s
  Latency       : 18 ms
  Success rate  : 98% (245/250)
  Last check    : 3m ago
  Media         : Core Release, Core Updates, Nonfree Release
```

## Peer Management

When urpmd is running on multiple machines on the same LAN, they discover each other and share cached packages (P2P).

```bash
urpm peer list                # List discovered peers
urpm peer downloads [host]    # Show packages downloaded from peers (filter by host)
urpm peer blacklist <host>    # Block a peer (e.g., if providing bad packages)
urpm peer unblacklist <host>  # Unblock a peer
urpm peer clean <host>        # Delete RPMs downloaded from a specific peer
                              # (use after blacklisting; <host> is required)
```

### Local-only mode

Use `--only-peers` to download exclusively from LAN peers without falling back to upstream mirrors:

```bash
urpm i --only-peers firefox   # Install only if available from peers
urpm u --only-peers           # Upgrade only with packages from peers
urpm download --only-peers pkg  # Download only from peers
```

This is useful for air-gapped networks or when you want to ensure all packages come from trusted local sources.

## Cache Management

```bash
urpm cache info               # Show cache information
urpm cache clean              # Remove orphan RPMs from cache
urpm cache rebuild            # Rebuild package database from synthesis files
urpm cache rebuild-fts        # Rebuild the FTS index for fast file search
urpm cache stats              # Detailed statistics
```

`urpm cache clean` accepts `--dry-run/-n` (preview), `--auto/-y`
(no confirmation) and `--verbose/-v` (list every orphan file).

## Mirror / Replication

urpm-ng can replicate a subset of packages locally (similar to a DVD
installation set) and expose them to LAN peers. Useful for install
parties, offline installations, and building an in-house mirror.

Two moving parts:

- **Per-media policy** — `urpm media set <name> --replication=...`
  controls how each media is replicated (metadata only, on-demand
  caching, or full seed).
- **Top-level `urpm mirror`** — daemon-side global state (quotas,
  served versions, outbound rate limit) and explicit maintenance
  triggers.

### Top-level mirror control

```bash
urpm mirror status            # Show mirror status, quotas and served versions
urpm mirror enable            # Start serving cached packages to peers
urpm mirror disable           # Stop serving packages
urpm mirror quota [SIZE]      # Show or set the global cache quota (e.g., 10G, 500M)
urpm mirror enable-version 10,cauldron   # Resume serving these versions
urpm mirror disable-version 8,9          # Stop serving these versions
urpm mirror clean [-n]        # Enforce quotas and retention policies (--dry-run preview)
urpm mirror sync [media]      # Force replication sync for `seed`-policy media
urpm mirror sync --latest-only           # Smaller, DVD-like sync
urpm mirror rate-limit [on|off|N/min]    # Configure outbound rate limit
```

### Seed-based replication

Replication uses the `rpmsrate-raw` file from Mageia to determine which packages to mirror (same logic as DVD content).

```bash
# Enable seed-based replication on a media
urpm media set "Core Release" --replication=seed
urpm media set "Core Updates" --replication=seed

# View the computed seed set
urpm media seed-info "Core Release"
# Output:
#   Sections: INSTALL, CAT_PLASMA5, CAT_GNOME, ...
#   Seed packages from rpmsrate: 437
#   Locale patterns: 3
#   Expanded locale packages: +237
#   With dependencies: 2300 packages
#   Estimated size: ~3.5 GB

# Force sync (download missing packages)
urpm mirror sync

# Sync only latest version of each package (smaller, DVD-like)
urpm mirror sync --latest-only
```

### How it works

1. Parses `/usr/share/meta-task/rpmsrate-raw` (from meta-task package)
2. Extracts packages from sections: INSTALL, CAT_PLASMA5, CAT_GNOME, CAT_XFCE, etc.
3. Expands locale patterns (e.g., `libreoffice-langpack-ar` → all langpacks)
4. Resolves dependencies (Requires + Recommends)
5. Downloads missing packages in parallel

The default seed sections cover all major desktop environments and applications, resulting in ~5 GB of packages (comparable to a Mageia DVD).

### Replication policies

```bash
urpm media set <name> --replication=none       # Metadata only, no packages
urpm media set <name> --replication=on_demand  # Cache what's downloaded (default)
urpm media set <name> --replication=seed       # DVD-like content from rpmsrate
```

## Configuration

### Blacklist (never install/upgrade)

```bash
urpm config blacklist list    # Show blacklisted packages
urpm config blacklist add <pkg>
urpm config blacklist remove <pkg>
```

### Redlist (warn before auto-remove)

```bash
urpm config redlist list      # Show redlisted packages
urpm config redlist add <pkg>
urpm config redlist remove <pkg>
```

### Kernel management

```bash
urpm config kernel-keep       # Show how many kernels to keep
urpm config kernel-keep <n>   # Set number of kernels to keep
```

### Version mode (system vs cauldron)

When both system and cauldron media are configured, `version-mode` picks
which one wins for upgrades:

```bash
urpm config version-mode              # Show current mode
urpm config version-mode system       # Stick to the installed system version
urpm config version-mode cauldron     # Roll with cauldron
urpm config version-mode auto         # Remove the explicit preference
```

### Auto-upgrade hooks for software centers

Control whether GNOME Software, KDE Discover or the PackageKit offline
update path may install upgrades on their own:

```bash
urpm config gnome-auto-upgrades [yes|no]      # GNOME Software
urpm config discover-auto-upgrades [yes|no]   # KDE Discover
urpm config packagekit-auto-upgrades [yes|no] # PackageKit offline updates
```

Without an argument, each subcommand prints the current setting. These
hooks toggle the desktop-side dconf/PolicyKit settings; the system policy
is enforced separately by the `urpm-ng-desktop` package.

### Inspect or edit configuration

```bash
urpm config show              # Show effective configuration from all *.cfg files
urpm config edit              # Open urpm.cfg in $EDITOR
urpm config edit 00-urpmi-compat   # Open a specific drop-in
```

### Server selection

The `[server]` section in `/etc/urpm/conf.d/10-server.cfg` controls
automatic mirror selection:

| Key | Default | Description |
|-----|---------|-------------|
| `auto_add` | `true` | Allow automatic addition of mirrors |
| `country_blacklist` | *(empty)* | Comma-separated ISO 3166 codes to exclude (e.g. `UA, RU`) |
| `country_whitelist` | *(empty)* | Only accept these countries (overrides blacklist) |
| `continent_blacklist` | *(empty)* | Continent codes to exclude (`EU`, `NA`, `SA`, `AS`, `AF`, `OC`) |
| `continent_whitelist` | *(empty)* | Only accept these continents (overrides blacklist) |

A mirror must pass **both** the continent and country filter.  Whitelist
wins over blacklist at each level.  Use `urpm config show` to see the
effective settings.

## GPG Keys

```bash
urpm key list                 # List installed GPG keys
urpm key import <file|url>    # Import a GPG key
urpm key remove <keyid>       # Remove a GPG key
```

## Build Dependencies

Install build dependencies for RPM building:

```bash
urpm install --buildrequires foo.spec    # From spec file
urpm install --buildrequires foo.src.rpm # From source RPM
urpm i -b                                # Auto-detect in RPM build tree
urpm i --br                              # Short alias

# Options
--sync                        # Wait for all scriptlets to complete
```

Installed build dependencies are tracked in `/var/lib/rpm/installed-through-builddeps.list`
and excluded from regular orphan removal. To clean them up:

```bash
urpm autoremove --buildrequires          # Remove all tracked build deps
urpm ar -b                               # Short form
```

## Container Build System

urpm provides a complete container-based build system for RPM packages using Docker or Podman.

### Image management

```bash
# List available build images
urpm image list

# Update an existing image (re-sync media + packages)
urpm image update mageia:10-build

# Delete one or more images
urpm image delete mageia:10-build mageia:10-ci
```

### Create build image

```bash
urpm image make --release 10 --tag mageia:10-build
urpm image make --release 10 --tag mageia:10-ci --profile ci

# Build image for a .spec or .src.rpm (auto-installs BuildRequires)
urpm image make --release 10 --tag mga:10-foo --buildrequires SPECS/foo.spec

# Options
-r, --release <version>       # Mageia version (e.g., 10, cauldron)
-t, --tag <tag>               # Image tag (e.g., mageia:10-build)
--profile <name>              # Package profile (default: build)
--arch <arch>                 # Target architecture (default: host)
-p, --packages <list>         # Additional packages (comma-separated)
--buildrequires <spec|srpm>   # Install BuildRequires from a .spec or .src.rpm
--addmedia <NAME> <URL>       # Add an extra media inside the image (repeatable) --
                              # e.g. a third-party or in-house mirror
--import-key <URL>            # Import a GPG public key inside the image (repeatable) --
                              # pairs with --addmedia for signed third-party media
--runtime docker|podman       # Container runtime (default: auto-detect)
--keep-chroot                 # Keep temporary chroot after image creation
-w, --workdir <path>          # Working directory for chroot (default: ~/.cache/urpm/mkimage).
                              # Also used as TMPDIR for the podman commit stage so
                              # image blobs don't spill onto a small /tmp.
--exclude PKG                 # Remove PKG from the finished image via
                              # `urpm erase --force --keep-orphans --sync` (repeatable).
                              # Canonical use: `--exclude python3-zstandard` so firefox's
                              # mach doesn't trip on its own version pin.
--urpm-ng-source auto|local|media|github
                              # Where urpm-ng-core comes from (default: auto waterfall)
--urpm-ng-core <path>         # Install urpm-ng-core from this specific RPM
--allow-disttag-mismatch      # Accept a local RPM whose disttag lies outside the
                              # target's window (default: only .mgaN. for numeric;
                              # .mgaN. and .mga{N-1}. for cauldron/N — the packager
                              # rebuilding on their stable host is covered without this).
```

**Release identity in `--release`.** The argument accepts three forms:

- `--release 10` — pin the machine's identity to a numeric stable release.
- `--release cauldron` — pin to the moving development tree.  The image's
  effective numeric (used for `.mgaN` release tags and the `%mgaversion`
  macro inside build containers) is best-effort probed from the mirror's
  `media.cfg` at init time.  Offline or when the probe fails, it stays
  unset and consumers fall back to `/etc/mageia-release`.
- `--release cauldron:11` — cauldron with an explicit numeric target.
  Wins over the probe, works offline, and overrides the mirror when the
  server-side `media.cfg` lags behind during a flip window.

> **Backward compatibility:** `urpm mkimage` is kept as an alias for `urpm image make`.

### Profiles

Profiles define which packages are installed in the image:

| Profile | Description |
|---------|-------------|
| `build` | RPM build environment (default): rpm-build, gcc, make, etc. |
| `ci` | CI/testing: python3-pytest, git, python3-solv, etc. |
| `minimal` | Minimal usable system with urpm |

Profiles are loaded from:
- `/usr/share/urpm/profiles/*.yaml` (system, from package)
- `/etc/urpm/profiles/*.yaml` (local additions)

### Build packages

By default, `urpm build` auto-updates media and packages inside the container
before building, so that builds always run against the latest repository state.
Use `--no-update` to skip this step when working offline or to speed up
repeated builds.

When you pass multiple sources at once, the specs are compiled in a single
shared container: the shared setup (`urpm upgrade`, `rpm-build` install) runs
once, each spec builds in its own `/root/<name>` topdir, and the RPMs
produced by an earlier spec are automatically visible to later specs as a
local media (useful when the second spec's BuildRequires include the first
one's output). Use `--parallel N` to switch to the isolated path (one
container per spec, N in flight) when you want each build to be sealed off
from the others.

```bash
# Build from source RPM (output to ./build-output/)
urpm build -i mageia:10-build foo-1.0-1.mga10.src.rpm

# Build from spec file (output to workspace/RPMS/ and SRPMS/)
urpm build -i mageia:10-build SPECS/foo.spec

# Build without auto-updating media/packages first
urpm build -i mga10-build --no-update SPECS/foo.spec

# Build with local dependencies (e.g., libfoo built previously)
urpm build -i mageia:10-build SPECS/bar.spec -w 'RPMS/x86_64/libfoo*.rpm'

# Multiple local dependencies
urpm build -i mageia:10-build SPECS/app.spec \
    -w 'RPMS/x86_64/libfoo*.rpm' -w 'RPMS/x86_64/libbar*.rpm'

# Multiple builds in parallel
urpm build -i mageia:10-build *.src.rpm --parallel 4

# Chain multiple specs in a single shared container (default when
# passing several sources): setup happens once, artefacts of the
# first spec are visible to the second one.
urpm build -i mageia:10-build libfoo.spec app-using-libfoo.spec

# Same as above, but stop at the first failure and roll back each
# spec's BuildRequires so every spec starts from the shared baseline.
urpm build -i mageia:10-build --stop-on-fail --rbb *.spec

# Third-party builder: tag output as foo-1.0-1.mlo.mga10.x86_64.rpm
urpm build -i mageia:10-build --subrel mlo SPECS/foo.spec

# Override packager/vendor/dist without touching the spec
urpm build -i mageia:10-build --rpmmacros ./my-macros SPECS/foo.spec

# Options
-i, --image <tag>             # Docker/Podman image to use
-o, --output <dir>            # Output directory for SRPM builds (default: ./build-output)
-w, --with-rpms <pattern>     # Pre-install local RPMs before build (glob, repeatable)
--no-update                   # Skip auto-update of media and packages before build
--runtime docker|podman       # Container runtime (default: auto-detect)
-j, --parallel <N>            # Isolated multi-container builds (default: 1, chain in a shared container)
--keep-container              # Keep container after build (for debugging)
--stop-on-fail                # Abort the chain at the first failing spec (default: continue)
--rollback-between-builds     # Rewind per-spec BuildRequires between specs (alias: --rbb)
--subrel <tag>                # Inject %subrel TAG so output RPMs become NAME-VERSION-RELEASE.TAG.DIST.ARCH.rpm
--rpmmacros <file>            # Inject FILE as /root/.rpmmacros in the build container (combinable with --subrel)
--build-cpus N                # Cap parallel build jobs at N threads (rpmbuild %_smp_mflags = -jN
                              # + podman --cpus).  Default: max(1, nproc - 2), so the host keeps
                              # two cores free for interactive work.
--build-memory SIZE           # Container RAM ceiling (e.g. 8G, 12000M, 16GB).  Enforced as
                              # podman --memory.  Default: max(2G, MemTotal - 2G).
--full-throttle               # Shortcut: no CPU cap, no memory cap.  Overrides --build-cpus
                              # and --build-memory.
--strict-memory               # Tie --memory-swap to --build-memory (podman kills the process on
                              # reaching the RAM ceiling).  Default: swap unlimited, matches
                              # mock/systemd-nspawn.  Use in CI where quiet swapping would
                              # masquerade as a timeout.
--with FEATURE                # Pass `--with FEATURE` to rpmbuild (spec %bcond).  Repeatable.
--without FEATURE             # Pass `--without FEATURE` to rpmbuild (spec %bcond).  Repeatable.
```

#### Build resource caps and mock parity

The `--build-cpus` / `--build-memory` / `--strict-memory` trio is the primary
lever for building heavy specs (firefox, thunderbird, chromium) on machines
that don't have 32+ GB of spare RAM.  Defaults leave two CPUs and two GB of
RAM to the host so it stays usable, and, importantly, **swap is left
unbounded by default** — the container can spill cold pages onto host swap
the way mock's systemd-nspawn wrapper does.  Without that, firefox's rustc
runs into `SIGKILL` well before the actual RAM ceiling on <16 GB hosts.
`--strict-memory` re-ties `--memory-swap` for CI where quiet swapping would
be indistinguishable from a hang.

#### rpmbuild bcond passthrough

`--with FEATURE` and `--without FEATURE` are forwarded verbatim to rpmbuild
so specs using `%bcond_with` / `%bcond_without` can be flipped without
shelling out to rpmbuild.  Example: a firefox spec that declares
`%bcond_without unified_build` (unified translation units on by default) can
be built without them for a memory-constrained test run via
`urpm build --without unified_build ./SPECS/firefox.spec`.

### Workspace layout

For spec file builds, urpm supports the standard RPM workspace layout:

```
workspace/
├── SPECS/
│   └── foo.spec
└── SOURCES/
    ├── foo-1.0.tar.gz
    └── patches/
```

Results are placed in:
```
workspace/
├── RPMS/
│   └── x86_64/
│       └── foo-1.0-1.mga10.x86_64.rpm
└── SRPMS/
    └── foo-1.0-1.mga10.src.rpm
```

### Example workflow

```bash
# 1. Create build image (once)
urpm image make --release 10 --tag mga:10-build

# 2. Build a package
urpm build --image mga:10-build ./mypackage.src.rpm

# 3. Later, update the image to pick up new repo packages
urpm image update mga:10-build

# 4. Check results
ls ./build-output/
```

### Manual bootstrap (advanced)

Under the hood, `urpm image make` calls `urpm init` inside a fresh chroot to
populate the media catalogue. `urpm init` is exposed directly for callers
that need to bootstrap a rootfs outside the containerised path — installer
scripts, VM disk builds, or preseeded test roots. Mirrors are picked from
the Mageia mirror API and filtered by the `[server]` section of
`/etc/urpm/conf.d/10-server.cfg`.

```bash
# Bootstrap a chroot rootfs for Mageia 10
urpm --urpm-root /tmp/rootfs init --release 10 --arch x86_64

# Use a custom mirror list
urpm init --mirrorlist 'https://mirrors.mageia.org/api/mageia.10.x86_64.list'

# Options
--release, -r <version>     # Target Mageia version (10, cauldron, ...)
--mirrorlist <url>          # Override the auto-generated mirror list URL
--arch <arch>               # Target architecture (default: host)
--auto, -y                  # Non-interactive mode
--no-sync                   # Configure media but skip the initial metadata sync
```

After working inside an `--urpm-root` chroot, unmount `/dev` and `/proc`
mounted by `urpm init`:

```bash
urpm --urpm-root /tmp/rootfs cleanup
```

## Repository maintainer tools

The two commands below are aimed at people **publishing** a Mageia-compatible
repository, not consuming one. They are documented together so it stays
obvious which ships client metadata and which produces it.

- **`urpm appstream`** (client side) — refreshes the AppStream catalog on
  the current box so software centres see up-to-date descriptions.
  Ships in `urpm-ng-appstream`.
- **`urpm genmedia`** (server side) — produces the full set of media
  metadata a mirror serves to clients. Ships in `urpm-ng-genmedia`
  as a separate sub-package so the base client install stays lean.

### AppStream metadata (`urpm appstream`)

urpm can produce and refresh the AppStream catalogs consumed by KDE
Discover and GNOME Software:

```bash
urpm appstream generate              # Generate catalog from the package database
urpm appstream generate -m core/release    # Limit to a specific media
urpm appstream generate --no-compress       # Plain XML instead of gzip
urpm appstream status                # Show catalog status per media
urpm appstream merge                 # Merge per-media files into the unified catalog
urpm appstream merge --refresh       # Also refresh the system AppStream cache
urpm appstream init-distro           # Create the OS metainfo file (needed by Discover/GS)
urpm appstream init-distro --force   # Overwrite an existing metainfo
```

### Media generation (`urpm genmedia`)

`urpm genmedia` is the server-side companion of `urpm appstream`: where
`appstream` consumes catalogs to populate client databases, `genmedia`
**produces** the full set of media metadata that a Mageia mirror serves
to its clients.  It is a Python rewrite of the historical
`genhdlist3`, integrated into urpm-ng and packaged separately as
`urpm-ng-genmedia` so the dependency footprint stays out of the base
client install.

From a directory of RPM files:

```bash
urpm genmedia /path/to/rpms          # Default: full generation
urpm genmedia /path/to/rpms --incremental   # Skip RPMs whose SHA-256 has not changed
urpm genmedia /path/to/rpms --no-hdlist     # Skip the hdlist.cz output
urpm genmedia /path/to/rpms --xml-info      # Force regeneration of XML info files
urpm genmedia /path/to/rpms --appstream-info  # Generate AppStream catalog
urpm genmedia /path/to/rpms --no-md5sum     # Skip MD5SUM (faster for tests)
urpm genmedia /path/to/rpms --allow-empty-media  # Tolerate an empty input dir
```

The command produces the canonical layout expected by every urpm-ng
or urpmi client:

```
media_info/
  hdlist.cz                # Compressed binary package headers
  synthesis.hdlist.cz      # Lightweight dependency synthesis
  files.xml.lzma           # Per-package file lists
  info.xml.lzma            # URL, sourcerpm, licence, description
  changelog.xml.lzma       # Per-package changelogs
  appstream.xml.gz         # When --appstream-info is set
  MD5SUM                   # Checksums of the above
```

The AppStream pass extracts the embedded `*.metainfo.xml` files
shipped by upstream applications (KDE, GNOME, etc.) and generates a
minimal component from RPM header fields for packages that need one
but ship none.  Packages whose content is entirely non-user-facing
(devel headers, debug symbols, static archives, pure runtime
libraries) are **filtered out** rather than emitted with a fallback
``System`` category — they would clutter Discover and GNOME Software
without ever being installable through an app store.

The `media_info/` directory is locked while a generation runs, so
clients reading concurrently always see a consistent snapshot.

## Package README messages

`urpm readme` shows package README messages displayed to the user during
a transaction (Mageia keeps them as `README.urpmi` / `README.upgrade`):

```bash
urpm readme                          # README from the most recent transaction
urpm readme --transaction <id>       # README from a specific transaction
urpm readme --list                   # List transactions that have README messages
```

## Orphan Cleanup

```bash
urpm cleandeps                # Alias for `urpm autoremove --faildeps`:
                              # remove orphan dependencies left behind by
                              # interrupted transactions.
```

---

# urpmd - Background Daemon

urpmd is a background service providing:
- HTTP API for package operations
- Scheduled background tasks
- P2P peer discovery for LAN package sharing



## API Endpoints

### GET endpoints

| Endpoint | Description |
|----------|-------------|
| `/` | Service info |
| `/api/ping` | Health check |
| `/api/status` | Daemon status |
| `/api/media` | List configured media |
| `/api/available` | List available packages |
| `/api/updates` | List available updates |
| `/api/peers` | List discovered LAN peers |

### POST endpoints

| Endpoint | Description |
|----------|-------------|
| `/api/refresh` | Refresh media metadata |
| `/api/available` | Query available packages |
| `/api/announce` | Announce packages to peers |
| `/api/have` | Query if peer has specific packages |

## Scheduled Tasks

The daemon automatically performs:
- Media metadata sync
- Cache cleanup
- Updates availability check
- Peer discovery (UDP broadcast)

## P2P Package Sharing

When multiple machines on the same LAN run urpmd, they automatically discover each other and can share cached RPM packages, reducing bandwidth usage.

---

# GUI Integration (Discover / GNOME Software)

urpm-ng provides a PackageKit backend allowing graphical software centers to manage packages.

## Installation

```bash
urpm install urpm-ng-desktop
```

Or install the backend directly:
```bash
urpm install urpm-ng-packagekit-backend
```

This installs:
- `libpk_backend_urpm.so` - PackageKit backend
- D-Bus service `org.mageia.Urpm.v1` - Privileged operations
- PolicyKit policies - Authorization prompts
- AppStream configuration - Software catalog metadata

## Supported Applications

- **KDE Discover** - Full support (search, install, remove, updates)
- **GNOME Software** - Full support (search, install, remove, updates)

## How It Works

```
┌─────────────────┐
│  Discover /     │
│  GNOME Software │
└────────┬────────┘
         │
┌────────▼────────┐
│   PackageKit    │
│ (libpk_backend_ │
│    urpm.so)     │
└────────┬────────┘
         │
┌────────▼────────┐
│  D-Bus Service  │
│  + PolicyKit    │
│ (org.mageia.    │
│   Urpm.v1)      │
└────────┬────────┘
         │
┌────────▼────────┐
│  urpm-ng core   │
│  (Python)       │
└─────────────────┘
```

### rpmdrake-ng (Qt6)

A dedicated Qt6 GUI for package management is under development. See
`rpmdrake/README.md` for details.

## Troubleshooting

```bash
# Check if D-Bus service is running
systemctl status urpm-dbus.service

# Check PackageKit backend
pkcon backend-details

# Restart services after update
systemctl restart packagekit.service
systemctl restart urpm-dbus.service

# Check D-Bus interface
gdbus introspect --system --dest org.mageia.Urpm.v1 \
  --object-path /org/mageia/Urpm/v1
```

---

# Development & contributing

## Prerequisites

### Firewall ports

See Prerequisites section for network ports to open for P2P sharing.

### Setting up your environment

Clone the repository :

```bash
git clone https://github.com/pvi-github/urpm-ng.git
cd urpm-ng

```


### Dev mode configuration

Create a `.urpm.local` file in the project root to customize dev mode:

```bash
cd /where/is/urpm-ng

# Dev mode (port 9877, user data in ~/var/lib/urpm-dev/)
# Switch to dev mode
touch .urpm.local
```

Nota, you can change where urpm & uprmd put their data by editing .urpm.local file :
```ini
# Custom base directory (optional)
base_dir=/path/lib/urpm-dev
```

In dev mode, by default, data is stored in `/var/lib/urpm-dev/` and the daemon uses port 9877.

**Note that in dev mode urpmd will only interact with other urpmd in dev mode.**

## Running the daemon

```bash
# Run daemon (as root, without background mode)

cd /where/is/urpm-ng

./bin/urpmd --dev

```

## Running urpm

```bash
# Run urpm (as root in a specific console)

cd /where/is/urpm-ng

./bin/urpm --help

```

## Coding, testing, contributing...

Contributions of all kinds are welcome: code, testing, translating, giving feedback... no contribution is too small.

See `CLAUDE.md` for development guidelines and `doc/ARCHITECTURE.md` for technical architecture.

---

# Known Issues / TODO

- **`urpm find` performance** - Search in files.xml is slower than urpmf (2.5s vs 0.6s). Needs optimization.

---

# License

GPL-3.0 - See LICENSE file for details.

# Authors

- Maât (Pascal Vilarem)
- Papoteur (Mageia Contributor)
- Claude (AI assistant)
