Incus Documentation

The usbid package is a specialized Go variant of the usbid implementation found in google/gousb. It is designed for environments where minimal footprint and high portability are required, such as cross-built static binaries.

Key characteristics of this variant include:

• Reduced Memory Footprint: It does not load on import.
• System Consistency: It uses the system-local USB database to ensure results match the output of the lsusb command.
• Zero External Dependencies: It does not import any packages outside of the Go built-in standard library.
• CGO-free: It does not use or indirectly rely on CGO, making it suitable for static builds.

Incus is a modern, secure, and powerful system container and virtual machine manager. It provides a unified experience for running and managing full Linux systems inside containers or virtual machines.

Key features include:

• Support for a wide range of Linux distributions via official Ubuntu images and community-provided images.
• A powerful and simple REST API.
• Scalability ranging from a single instance on one machine to a full data center cluster.
• Ability to set up a private cloud-like environment for cost-effective infrastructure management.

Incus operates using an image-based workflow where every instance is derived from an image. An image contains a basic operating system (e.g., a Linux distribution) and Incus-specific metadata.

Key concepts:

• Remote Image Stores: Sources for downloading images.
• Custom Images: You can create images based on existing instances or rootfs images.
• Identification: Images are identified by a SHA256 fingerprint, but you can define aliases to make management easier.
• Portability: You can copy images between local stores and remote servers, or use local images to create remote instances.

The Incus btrfs driver manages entities by creating a Btrfs subvolume for every instance, image, and snapshot. When a new entity is launched, Incus automatically creates a Btrfs snapshot.

Important considerations:

• VMs: Btrfs does not natively support block devices. For Virtual Machines, Incus stores the VM as a large file on disk. This is inefficient and can cause issues during snapshot creation.
• Nested Incus: You can use Btrfs as a storage backend inside a container in a nested Incus environment, provided the parent container also uses Btrfs. However, nested setups do not inherit Btrfs quotas from the parent.

All communication between Incus and its clients occurs via a RESTful API over HTTP.

• Local operations: Use a Unix socket.
• Remote operations: Use TLS.

To inspect API calls and return values while using the Incus CLI, run any command with the --debug flag. For quick API queries, use the incus query command.

External networks in Incus utilize network interfaces that already exist on the host system. Because Incus does not own these interfaces, it has limited control over them.

Important Limitations:

• Network ACLs (Access Control Lists) are not supported.
• Network forwards are not supported.
• Network zones are not supported.

The primary use case for external networks is to provide an uplink network through a parent interface. When configuring an external network, you specify presets that determine how instances or other networks connect to that parent interface.

The generate-config CLI parses comments from a Golang codebase's Abstract Syntax Tree (AST) to extract documentation for configuration variables. It is designed to bundle metadata key-value pairs with documentation to build hierarchical structures (like YAML trees or Markdown documents).

Disclaimer: This tool is intended for internal use within the Incus codebase. There are no guarantees regarding backwards compatibility, API stability, or long-term availability.

Incus collects metrics for CPU, memory, network, disk, and process usage for all running instances and internal processes. These metrics are designed for consumption by Prometheus and visualization in Grafana.

Important considerations:

• Clusters: In a cluster environment, each Incus server only returns metrics for instances running on that specific server. You must scrape each cluster member separately.
• Performance: Fetching metrics is a relatively expensive operation. Metrics are cached for 8 seconds to handle multiple scrapers. If performance impact is too high, increase your scraping interval.

Incus uses a distributed database to store server configuration and state. This architecture enables efficient querying across all instances (e.g., finding all instances using a specific network bridge) without needing to iterate through individual instance directories.

In a cluster environment, Incus uses Cowsql, a distributed version of SQLite that provides replication, fault-tolerance, and automatic failover. When running Incus on a single machine (non-clustered), Cowsql behaves like a standard SQLite database.