Clan Core

Mycelium is an end-to-end encrypted IPv6 overlay network designed for planetary-scale scalability. It provides locality-aware routing to find the shortest paths between nodes and automatically reroutes traffic if physical links fail.

Key capabilities include:

• End-to-end encryption: All traffic is encrypted.
• Flexible Transport: Supports multiple transports like QUIC and TCP (with QUIC hole punching in progress for NAT traversal).
• Identity-based Addressing: IPv6 addresses are derived from private keys.
• Dual-mode usage: Can be used as a full network interface (via TUN device) or solely as a reliable message bus without a TUN device.

ClanLib is a collection of clan-specific Nix functions designed to provide high-level abstractions for the ecosystem. It is structured as a recursive attribute set in a fixed-point, similar to nixpkgs/lib, allowing functions within the library to depend on one another to build complex abstractions.

Key functional areas include:

• clan functions
• select functions
• inventory functions
• json-schema-converter

The installer service configures a machine to function as an installation ISO for physical hardware installations. It is designed to work with nixos-anywhere and Clan's hardware-config workflow.

Key features include:

• Profiles: Imports the nixpkgs installation-device profile.
• Kernel: Pins the latest ZFS-compatible kernel.
• Console: Configures kmscon with root autologin via agetty. It enables both serial and VGA consoles, setting VGA as the primary /dev/console.
• Included Tools: The image contains nixos-install-tools, disko, nixos-facter, and rsync.

The dm-dns service provides distributed DNS zone propagation for clan networks. It enables clan-internal service discovery by collecting endpoints exports from all services, generating CNAME zone entries, and distributing them via data-mesher.

When enabled, a service hosted at https://myservice.<clan domain> becomes reachable from any machine in your clan.

Key Requirements:

• data-mesher: Must be configured and running on all machines.
• endpoints exports: Other services must export endpoints.hosts for DNS entries to be generated.
• SSL/TLS: It is recommended to combine this with the pki service to secure internal services with SSL.

data-mesher is an experimental file synchronization daemon that uses a gossip protocol to replicate files across a cluster of nodes.

In v2, the architecture follows a file-based approach where:

• Files are defined by a list of authorized ED25519 public keys.
• Only files explicitly listed in the configuration can be uploaded or synced.
• Files must be signed by one of the configured public keys to be valid.

The sshd service in clan-core manages SSH host security through two primary mechanisms:

1. Host Key Management: Generates and persists SSH host keys using vars.
2. Certificate Authority (CA) Signing: Issues CA-signed host certificates for servers and installs the CA public key into clients' known_hosts to enable TOFU-less (Trust On First Use) verification.

This allows for zero-TOFU SSH connections, meaning clients can connect to dynamic fleets (like frequently rebuilt hosts) without manual fingerprint verification or known_hosts churn.

The localbackup service is designed for robust incremental backups with the following capabilities:

• Incremental Snapshots: Uses rsnapshot to minimize storage usage.
• Multiple Targets: Supports configuring several different backup destinations.
• Hooks: Provides mount/unmount hooks for external storage and pre/post backup hooks for executing custom scripts.
• Retention: Configurable snapshot retention policies.
• Auto-detection: Automatically detects state folders.

Clan provides a suite of tools for system management and security, including:

• Full-Stack System Deployment: Build and manage systems using Clan's toolkit and Nix.
• Overlay Networks: Establish secure, private communication channels between devices.
• Virtual Machine Integration: Run VM applications seamlessly within the main operating system.
• Robust Backup Management: Long-term, self-hosted data preservation.
• Intuitive Secret Management: Simplified encryption and password management processes.

The hello-world service is an experimental reference implementation designed to demonstrate how to build and register a Clan-compatible service. It serves as a blueprint for:

• Defining a basic Clan-compatible service.
• Structuring services for discovery and configuration.
• Managing interactions between Clan services and NixOS.

Warning: This service is for demonstration purposes only and its API/structure may change.

The Clan Framework provides several interfaces for interaction:

• Clan CLI: Command-line interface for managing Clan operations.
• Services: A collection of available services provided by the framework.
• NixOS Configuration: Specialized configuration options for users running Clan on a NixOS machine.

Tor Networking provides every machine with a .onion address—a stable, cryptographically unique identifier. This allows machines to be reachable via the Tor network without public IP addresses, open firewall ports, or DNS configuration.

Key Characteristics:

• Low Priority: Tor has the lowest priority (10) of all Clan networking services. Clan only uses it as a last-resort fallback after all other configured services (like direct SSH or VPN) have failed.
• Use Cases: Use Tor for machines behind NAT with no public address, in environments with restrictive firewalls, or as a guaranteed fallback for machines that might be temporarily unreachable via primary methods.

:::admonition[Experimental]{type=danger} This service is experimental and will change in the future. :::