Qubes OS Documentation

The Qubes Admin API is the intended management interface for Qubes OS, designed to allow users to manage domains without requiring direct access to dom0. It enables remote management, the creation of multi-user systems with overlapping domain sets, and the use of custom management tools.

Common use cases include:

• Qubes OS Manager (or replacement tools)
• CLI tools running from other VMs
• Remote management tools
• Custom automation tools

qvm-template is a template manager application for Qubes OS designed to provide a unified tool for template management and a better mechanism for template distribution. It replaces the previous method of managing templates via standard RPM packages and yum/dnf, which caused issues with dynamic VM images and accidental updates.

Key capabilities include:

• Installing, reinstalling, downgrading, and upgrading templates from local packages or remote repositories.
• Supporting alternative installation pools.
• Listing, searching, and removing templates.
• Removing templates with an option to "disassociate" dependent VMs (changing their template to a "dummy" one).
• Working in both dom0 and management VMs via the Admin API.
• Providing both a Command-line interface (with DNF-like usage) and a graphical interface.

The Qubes security pack (qubes-secpack) is a Git repository used to distribute critical security assets for the Qubes OS project. It serves as a central, verifiable source for:

• Qubes security bulletins (QSBs)
• Qubes canaries (Warrant Canaries)
• Qubes ISO cryptographic hash values (located in the digests directory)
• Qubes fund information (located in the fund directory)
• Qubes PGP keys
• Security-related announcements and key revocations

The official repository is located at: https://github.com/QubesOS/qubes-secpack

The Qubes architecture is defined by several core security and usability features:

• Hypervisor: Based on the secure bare-metal Xen hypervisor.
• Network Isolation: Networking code is sandboxed in an unprivileged VM using IOMMU/VT-d; no networking code resides in the privileged domain (dom0).
• USB Isolation: USB stacks and drivers are sandboxed in an unprivileged VM (experimental).
• App Isolation: All user applications run in "app qubes," which are lightweight Linux-based VMs.
• Template-based Updates: App qubes use centralized updates based on shared templates.
• GUI Virtualization: Provides a seamless experience where applications appear to run locally while maintaining isolation between apps sharing the same desktop.
• Secure Boot: Supports optional secure system boot.

Qubes OS defaults to the XFCE desktop environment. The top bar contains several key areas:

• App Menu: Access applications, the dom0 terminal, and administrative tools like the Qube Manager.
• Task Bar: Shows buttons for open and hidden windows.
• Spaces: Virtual desktops for organization (does not provide security isolation).
• Tray: Contains specialized Qubes widgets:
  • Whonix SDWDate: Controls Tor connections in sys-whonix.
  • Qubes Clipboard: Manages text copying between qubes and dom0.
  • Qubes Devices: Attaches/detaches USB drives and cameras.
  • Qubes Disk Space: Monitors storage usage.
  • Qubes Domains: Manages qube states (on/off) and monitors RAM/CPU.
  • Qubes Updater: Notifies of and assists with system updates.

The Qubes OS documentation is organized into several primary categories to serve different user needs:

• Introduction: General information including getting started, FAQs, support, and contributing guidelines.
• User Documentation: Core guides for operating Qubes OS, covering hardware selection, installation, how-to guides (e.g., managing files, software, and devices), templates, troubleshooting, security practices, and advanced topics.
• Developer Documentation: Technical documentation for developers and advanced users, covering general development workflows, source code, system architecture, core services (like qrexec and admin-api), debugging, and building the Qubes OS stack.
• Project Security: Information regarding project-wide security, security packs, and signature verification.

The Dasharo FidelisGuard Z690 is an officially certified hardware platform for Qubes OS Release 4. It is a full desktop PC build utilizing the Dasharo open-source firmware distribution on an MSI PRO Z690-A DDR4 motherboard.

Hardware Configuration:

• CPU: Intel Core i5-12600K, 3.7GHz
• Cooling: Noctua CPU NH-U12S Redux
• RAM: Kingston Fury Beast, DDR4, 4x8GB (32 GB Total), 3600 MHz, CL17
• Power Supply: Seasonic Focus PX 750W 80 Plus Platinum
• Storage: SSD Intel 670p 512 GB M.2 2280 PCI-E x4 Gen3 NVMe
• Enclosure: SilentiumPC Armis AR1

The NitroPad X230 is officially certified for Qubes OS Release 4. It is designed for high-security use cases with the following features:

• Tamper Detection: Supports measured boot using coreboot and Heads, alongside Nitrokey USB hardware, enabling Anti Evil Maid (AEM) protection.
• Intel Management Engine (ME): The Intel ME is deactivated.
• Cryptographic Control: Supports user-replaceable cryptographic keys and includes a Nitrokey USB key.
• Hardware Base: Built on professional ThinkPad X230 hardware.
• Secure Logistics: Uses security-conscious shipping to mitigate third-party interdiction.

Qubes OS provides several security-focused features to isolate and protect digital activities:

• Strong isolation: Uses advanced virtualization to isolate software as if it were on separate physical machines.
• Template system: Uses app qubes to share a root file system securely via the Template system.
• Multiple operating systems: Run Fedora, Debian, and Windows simultaneously.
• Disposables: Create temporary VMs that self-destruct upon shutdown.
• Whonix integration: Securely run Tor system-wide.
• Device isolation: Isolate network cards and USB controllers.
• Split GPG: Keep private keys safe by splitting GPG operations.
• CTAP proxy: Use two-factor authentication devices without exposing the web browser to the full USB stack.

Qubes OS is a security-oriented, open-source operating system for single-user desktop computing. It uses Xen-based virtualization to create and manage isolated compartments called qubes.

Each qube is a virtual machine (VM) that can be configured with specific:

• Purposes: Predefined sets of isolated applications (e.g., managing a network stack, a firewall, or specific professional projects).
• Natures: Can be full-fledged virtual machines or stripped-down VMs based on operating systems like Fedora, Debian, or Windows.
• Levels of trust: Ranging from complete to non-existent. To help users identify security levels, Qubes uses unforgeable colored window borders in a unified desktop environment.

Split GPG is a security architecture that mimics the behavior of a hardware smart card by delegating cryptographic operations (encryption, decryption, and signing) from a potentially untrusted domain (e.g., a domain running Thunderbird) to a dedicated, more trusted, and network-isolated GPG backend domain.

Unlike a traditional smart card, which might blindly perform decryption requests from a compromised host, Split GPG requires explicit user consent for each key usage. The user is notified via a tray notification from the backend domain and must approve the request within a definable timeout period (defaulting to 5 minutes). This helps prevent an attacker from silently decrypting files even if they have compromised the client application domain.