Archmox Documentation Hub

Comprehensive guide for porting the Proxmox Virtual Environment stack (~50 packages) from Debian to Arch Linux PKGBUILDs.

Covers:

• Package inventory of all 51 PVE components across 4 dependency tiers
• PKGBUILD template with build(), check(), and package() functions
• Perl module path mapping from Debian to Arch vendor directories
• Systemd service files for all daemons (pveproxy, pvedaemon, pve-cluster, etc.)
• pmxcfs configuration layout under /etc/pve/
• Web UI asset pipeline (ExtJS, Sencha CMD, widget toolkit)
• Dependency resolution order for core, PVE, and infra packages
• Common pitfalls: Debian-specific build deps, AUR Perl module availability, kernel module deps
• Verification checklist after completing the port

Detailed guide for porting Proxmox Backup Server — a Rust-based backup solution with content-addressable storage.

Covers:

• Package architecture: proxmox-rs (workspace of 13 sub-crates), pxar, proxmox-fuse-rs, proxmox-backup, proxmox-backup-qemu
• Rust build pipeline with cargo workspaces and frozen dependency resolution
• pxar archive format: sparse files, extended attributes, chunking, FUSE mounting
• PostgreSQL integration: schema migration, user/database setup
• FUSE snapshot mounting for file-level restore
• Web UI build (ExtJS with Rust HTTP server, no nginx needed)
• Backup datastore directory structure (chunks, indices, catalogs)
• Verification: start daemon, create datastore, run backup/restore cycle

Complete guide for porting Proxmox Mail Gateway — an SMTP proxy with spam filtering, virus scanning, and policy routing.

Covers:

• PMG package architecture: pmg-api (Perl), pmg-gui (ExtJS), pmg-docs
• Dependency chain through PVE common libraries plus mail infrastructure
• SMTP proxy architecture: pmg-smtp-filter, pmg-smtp-forward, pmg-policy
• Postfix integration: master.cf configuration, content_filter directives
• Content filtering pipeline: SpamAssassin, ClamAV, custom rules engine
• Quarantine system: storage format, daily digest, web management
• DKIM signing and verification workflow
• File system layout for PMG binaries, configuration, and quarantine data
• Verification procedure: configure Postfix, start filter, test mail flow

High-level architecture of the complete Archmox stack, from the Hyperbola/LTS kernel up through the web UI layer.

Covers:

• Five-layer architecture model: OS, Infrastructure, Service, API, Web UI
• Kernel patches for ZFS, Corosync, QEMU, LXC, OVS, and nftables
• Service layer details: pmxcfs, pve-ha-manager (CRM/LRM), pve-firewall, pve-container, qemu-server, pve-storage, pve-access-control, pve-network
• API layer: pveproxy (nginx reverse proxy), pvedaemon (Perl API), pmg-api, proxmox-backup (Rust HTTP)
• IPC mechanisms: REST API, Unix sockets, shared memory, D-Bus, WebSocket, TCP
• Security model: PAM, LDAP, AD realms, TOTP 2FA, RBAC path-based permissions
• Package management: archmox- prefix, pacman repository configuration

In-depth coverage of cluster communication via Corosync, the pmxcfs distributed filesystem, and the HA resource management system.

Covers:

• Cluster stack: Corosync (knet transport, totem protocol, AES-256-GCM encryption)
• Corosync configuration: nodelist, ring0/ring1 redundancy, quorum settings
• pmxcfs internals: FUSE implementation, SQLite + corosync CPG replication, strong consistency model
• Write path: SQLite transaction, broadcast via CPG, lock manager, crash recovery
• Cluster formation: create cluster, node joining, membership negotiation
• Quorum math: requirement, two-node mode, split-brain prevention
• HA system: CRM leader election, LRM watchdog integration, resource state machine
• Fencing: watchdog-based, STONITH (IPMI, iLO, DRAC, APC)
• Service recovery policies: max_restart, max_relocate, HA groups
• Live migration: pre-copy and post-copy strategies, storage migration scenarios

Comprehensive guide to the pve-storage plugin system and all supported storage backends: ZFS, Ceph, LVM, NFS, iSCSI, and more.

Covers:

• Storage plugin API contract: create, remove, resize, snapshot, clone, template operations
• ZFS: ARC tuning, SLOG/L2ARC, recordsize optimization, zvol vs subvolume, ZFS replication via pve-zsync
• Ceph: MON/OSD/MGR architecture, CRUSH map, RBD pool configuration, BlueStore tuning, cephx authentication
• LVM thin provisioning: pool creation, LV lifecycle, monitoring and overcommit risks
• Directory, NFS, iSCSI, and SMB/CIFS storage configuration
• Storage replication: ZFS send/recv, Ceph native replication, cross-cluster DR
• Storage selection guide for small, medium, and large deployments

Complete installation guide covering all three methods: binary repository, source build, and ISO installer.

Covers:

• Hardware requirements: CPU, RAM, storage, network minimums and recommendations
• Method 1: Binary repository setup via pacman, installing from archmox repo
• Method 2: Source build from PKGBUILDs, cloning repo, running build-all.sh
• Method 3: ISO installation (coming soon) with archiso-based guided installer
• Post-installation: network bridge configuration, ZFS pool creation, Ceph bootstrap
• Web interface access at ports 8006 (PVE/PMG) and 8007 (PBS)
• TLS certificate replacement for production
• Firewall configuration at cluster and node level
• Cluster setup: create cluster, add nodes, verify with pvecm
• Post-installation checklist for production readiness
• Troubleshooting: pve-cluster failures, web UI accessibility, ZFS pool import

Detailed reference for configuring all Archmox components through configuration files, CLI tools, and APIs.

Covers:

• Configuration hierarchy: cluster-level pmxcfs files, node-level /etc files
• Datacenter.cfg: keyboard, console, migration, email, proxy, timeout settings
• Storage.cfg: all backend types with example configurations (dir, zfspool, rbd, lvmthin, nfs, pbs)
• Content types per storage: images, rootdir, iso, vztmpl, backup, snippets, import
• User realms: Linux PAM, PVE, LDAP with pveum command reference
• ACL structure: path-based permissions, groups, TOTP two-factor auth
• VM configuration options: boot order, CPU, memory, network, PCI passthrough, UEFI, TPM
• Container configuration: unprivileged mode, cgroup limits, mount points
• PMG configuration: mydomain, relayhost, spam thresholds, DKIM, quarantine
• PBS configuration: server identity, TLS, datastores, GC, verify, remote sync
• Network configuration: Linux bridges, SDN zones (VXLAN, VLAN), VNets
• Service overrides via systemd drop-in files
• Backup job configuration for PBS and legacy VZDump

Day-to-day operations guide covering updates, health monitoring, backup/restore, capacity planning, and disaster recovery.

Covers:

• Update procedures: pacman updates, kernel updates, ZFS DKMS rebuilds
• Clustered update sequence: migrate VMs, stop services, update, reboot, rejoin
• Rolling back problematic updates from pacman cache or source rebuild
• Health monitoring: systemctl, journalctl, pvecm, corosync-cfgtool, zpool status
• Performance monitoring: pvesh rrddata, VM and container metrics
• Backup procedures: PBS datastore verification, configuration backup, PostgreSQL dump
• Full node restore: reinstall, copy cluster keys, rejoin, re-add storage
• Certificate management: check expiry, regenerate, Let's Encrypt via ACME
• Capacity planning: ZFS pool usage, datastore monitoring, adding storage
• Disaster recovery: node failure, storage failure, backup restore
• Routine maintenance: daily, weekly, monthly, quarterly checklists
• Troubleshooting: high CPU, corosync failures, ZFS degradation

Complete reference for the Proxmox VE REST API — managing VMs, containers, storage, cluster, users, and firewall.

Covers:

• API structure at /api2/json/ with hierarchical path organization
• HTTP methods: GET (list), POST (create/action), PUT (update), DELETE (remove)
• Authentication: API tokens for automation, ticket-based for interactive use
• All endpoint categories with curl examples
• Node management: status, RRD data, reboot, command execution
• QEMU VM management: create, start/stop, snapshots, live migration, resize, console proxy
• LXC container management: create, lifecycle, console, exec commands
• Storage management: list, upload ISO, upload VZTMPL, delete volumes
• Cluster management: status, resource map, logs, join info
• Firewall management: cluster and per-VM rules with IPSets
• User management: users, roles, ACLs, realms, TOTP enrollment
• HA management: resources, status, groups
• Task management: list, log streaming, cancellation
• Error handling: response format, HTTP status codes, rate limiting

Reference for the Proxmox Backup Server REST API — datastores, backup jobs, verification, prune, garbage collection, and remote sync.

Covers:

• API structure at /api2/json/ (Rust-based using proxmox-router)
• Authentication: API tokens and ticket-based with PBSAuthCookie
• Datastore management: status, statistics, backup groups, snapshots
• Backup operations: start backup, upload chunks, close, restore, list files
• Job management: backup, verify, prune, garbage collection, sync
• Remote sync: configure remotes, create sync jobs, run manually
• Tape management: drives, media pools, backup-to-tape, restore-from-tape
• User and access management: users, API tokens, ACL permissions
• Chunk and catalog operations: chunk info, catalog download
• Streaming endpoints for large data transfers
• Best practices: API tokens, chunk sizing, verify schedules, DR planning

Reference for the Proxmox Mail Gateway REST API — content filtering rules, quarantine, SpamAssassin, ClamAV, DKIM, and statistics.

Covers:

• API structure at /api2/json/, shares PVE auth system
• Rule management: who/what/action objects, priority, reordering
• Spam configuration: SpamAssassin thresholds, auto-learning, sa-update
• Virus configuration: ClamAV enable/disable, action, max_size, freshclam
• Quarantine management: list, release, delete, whitelist/blacklist, digest config
• Mail proxy configuration: default relay, max connections, greylisting
• Transport rules: domain-based relay routing
• DKIM configuration: domain, selector, key generation, public key retrieval
• TLS configuration: certificate upload, enable/disable
• LDAP server configuration: add, test connection
• Statistics: mail flow, spam, virus, top senders/recipients
• Node management: service control, system logs
• Configuration backup and restore

The build script at scripts/ci/build-all.sh enforces this dependency order:

Core (6): proxmox-rs, pve-common, proxmox-widget-toolkit, proxmox-i18n, pve-eslint, pve-jslint

PVE (22): pve-access-control, pve-cluster, pve-storage, pve-firewall, pve-guest-common, pve-ha-manager, pve-network, pve-http-server, pve-container, qemu-server, pve-edk2-firmware, pve-xtermjs, pve-zsync, pve-lxc-syscalld, pve-sheepdog, proxmox-yew-comp, proxmox-datacenter-manager, pve-docs, pve-installer, pve-manager, proxmox-ve

PBS (4): pxar, proxmox-fuse-rs, proxmox-backup, proxmox-backup-qemu

PMG (3): pmg-api, pmg-gui, pmg-docs

Infra (23): libiscsi, lvm, lxc, zfs, ksm-control-daemon, pve-libspice-server, pve-firmware, vncterm, spiceterm, corosync-pve, corosync-qdevice, openvswitch, redhat-cluster-pve, gfs2-utils, fence-agents-pve, resource-agents-pve, ceph, qemu, dab, dab-pve-appliances, libgtk3-webkit-perl, proxmox-firewall

API Health: GET /api/health on any subdomain returns fleet status, version, and service availability.

Worker performs reverse proxy for Pages (pmg, cdn, pbs subdomains), serves CDN via R2 buckets, handles contact/newsletter/security report endpoints.

Archmox is community-driven. Key contribution areas:

• Porting Perl modules from Debian paths to Arch vendor paths
• Converting debian/rules to PKGBUILDs
• Adapting pve-installer for archiso
• Testing on bare metal
• Writing documentation