Making Self-Signed Certificates Persistent in NixOS VMs: A Comprehensive Guide

Welcome to revWhiteShadow, your personal blog for diving deep into the intricacies of NixOS and system administration. Today, we’re tackling a common challenge faced by developers and system administrators working with NixOS virtual machines: how to ensure that a self-signed SSL certificate remains reliably available and recognized even after subsequent nixos-rebuild operations within the VM. This is a crucial step for establishing trust and security in internal services or development environments where official certificates aren’t practical or necessary. We understand the frustration of having a perfectly functioning setup that falters after a simple reconfiguration. This article will provide a detailed, in-depth exploration of effective strategies to make your self-signed certificate persist in NixOS VMs, aiming to outrank existing content by offering unparalleled clarity, comprehensiveness, and practical solutions.

When you initially build a NixOS virtual machine using a Nix expression, incorporating a self-signed certificate is typically straightforward. You might define your certificate like this:

certfile = builtins.readFile ./certificate.crt;
security.pki.certificates = [ certfile ];

This method works flawlessly for the initial build, ensuring that the certificate is correctly integrated into the VM’s trust store. The problem, however, arises when you need to perform a nixos-rebuild within the VM itself. If you no longer have direct access to the original certificate.crt file on the build host, or if the VM’s filesystem doesn’t retain it in a readily accessible location for the rebuild process, you’re faced with a dilemma. How do you re-inject this crucial certificate into the NixOS configuration without losing it on subsequent rebuilds? We’ve explored several avenues to address this, and this guide will meticulously detail the most robust and reliable methods.

Understanding the NixOS PKI and Certificate Management

Before we delve into the solutions, it’s essential to grasp how NixOS handles public key infrastructure (PKI) and certificates. NixOS treats system configuration as code, and this extends to its security mechanisms. The security.pki.certificates option in your configuration.nix is designed to ingest trusted certificates. When you provide a path to a certificate file, NixOS copies that file into its managed store and establishes the necessary symlinks and configurations to make it a trusted root authority or intermediate certificate.

The challenge with your scenario is that nixos-rebuild operates within the context of the VM’s current state. If the original certificate file is only accessible during the initial VM image generation and not made a permanent fixture within the VM’s root filesystem in a way that NixOS’s build process can readily consume during a subsequent rebuild, it will effectively disappear from Nix’s perspective. This is where careful consideration of how the certificate is made available to the rebuild process becomes paramount.

Strategy 1: Preserving the Certificate within the VM’s Root Filesystem

One of the most direct approaches is to ensure that a copy of your self-signed certificate is reliably placed within the VM’s root filesystem during the initial build, in a location that can be easily referenced by subsequent nixos-rebuild commands. This leverages the fact that once a file is present on the VM’s disk, it can be referenced as a static path.

Method 1.1: Placing the Certificate in `/root` During Initial Build

Your initial idea of placing an extra copy of the certificate under /root is a sound one. This approach involves modifying your VM’s build process to include a step that copies the certificate.crt file to a persistent location within the VM’s filesystem.

Detailed Implementation:

Within your Nix expression that builds the VirtualBox VM, you can utilize the users.users.<name>.extraGroups or system.extraSystemdUnits to execute commands during the initial boot or system setup phase. However, a more idiomatic NixOS way is to directly inject files into the Nix store that will then be copied to the target filesystem.

Let’s refine your concept by directly integrating the certificate into a Nix-managed location, ensuring it’s part of the Nix store and thus reliably available.

Make the Certificate a Nix Store Path: Instead of just reading the file, let’s ensure the certificate itself becomes a Nix store path that is then copied to a specific location within the VM’s filesystem during the initial build.

# In your VM build expression, e.g., configuration.nix or a separate module
let
  myCert = builtins.readFile ./certificate.crt;
  # Create a derivation for the certificate file, ensuring it's in the Nix store
  certFileDerivation = pkgs.runCommand "my-self-signed-cert.crt" { } ''
    mkdir -p $out/etc/ssl/certs
    echo "${myCert}" > $out/etc/ssl/certs/my-self-signed-cert.crt
    ln -s $out/etc/ssl/certs/my-self-signed-cert.crt $out/cert.pem # Optional: provide an alternative symlink
  '';
in
{
  security.pki.certificates = [
    certFileDerivation + "/cert.pem" # Reference the certificate file within the derivation's output
  ];

  # Now, ensure this certificate is also copied to a fixed, known location
  # This is where we make it accessible for future rebuilds via a static path
  system.copySystemConfiguration = {
    # Add the specific certificate path to be copied
    paths = [ certFileDerivation ];
    # Define the destination directory within the VM's filesystem
    targetDirectory = "/etc/nixos/certificates"; # A dedicated directory for certs
  };

  # Then, in your VM's configuration.nix, you can reference it like this:
  # security.pki.certificates = [ "/etc/nixos/certificates/my-self-signed-cert.crt" ];
  # Or even more robustly, by making it available as a Nix store path directly:
  # This requires a slight adjustment: the Nix store path IS the persisted file.
  # If certFileDerivation produces a path like /nix/store/..., then
  # security.pki.certificates = [ "/nix/store/..." ];
  # However, the requirement is for a *rebuild* within the VM.
  # The `system.copySystemConfiguration` ensures it's on disk.

  # The key insight: NixOS rebuilds *are* code execution. If the certificate is a file
  # on disk at a known path, and that path is added to `security.pki.certificates`,
  # Nix will fetch it from that path.
  # The most direct way to satisfy your prompt is to ensure it's part of the NixOS
  # configuration *itself* and then copied.

  # Let's rethink the `security.pki.certificates` usage during rebuild.
  # If we want to *re-add* it during a rebuild using a static path,
  # that static path must exist.
  # The `system.copySystemConfiguration` approach is good for making it
  # available. Now, how to reference it during rebuild?

  # The ideal solution is to make the certificate a Nix attribute that
  # you reference, and ensure that attribute's source is persistent.

  # Let's simplify the approach for clarity and effectiveness for rebuilds.
  # Instead of copying to `/etc/nixos/certificates`, let's place it
  # where `nixos-rebuild` can easily find it as a Nix-managed file.

  # Revised approach using `environment.etc` for direct inclusion
  environment.etc."my-self-signed-cert.crt" = {
    source = ./certificate.crt;
    mode = "0444"; # Read-only for security
  };

  # Then, in your configuration.nix within the VM:
  # security.pki.certificates = [ "/etc/my-self-signed-cert.crt" ];

  # This ensures that on the initial build, the certificate is placed at /etc/my-self-signed-cert.crt
  # managed by Nix. For subsequent rebuilds, this file will still be present.
  # When `nixos-rebuild` processes `security.pki.certificates = [ "/etc/my-self-signed-cert.crt" ];`,
  # it will find this file. If the file is managed by Nix (via environment.etc),
  # it remains in its store path, and the symlink /etc/my-self-signed-cert.crt is maintained.
  # If you are rebuilding *from within the VM*, the path `/etc/my-self-signed-cert.crt`
  # is a stable symlink to a Nix store path. As long as the Nix store is not cleaned
  # in a way that removes this specific derivation, the certificate will persist.
};

This refined method uses environment.etc to place the certificate in a well-known location (/etc/my-self-signed-cert.crt) managed by Nix. When you perform nixos-rebuild within the VM, the configuration directive security.pki.certificates = [ "/etc/my-self-signed-cert.crt" ]; will correctly reference this file. Since environment.etc creates a symlink from /etc/my-self-signed-cert.crt to its corresponding path in the Nix store, and the Nix store is typically preserved across rebuilds (unless explicitly garbage collected aggressively), the certificate remains available.

Key Benefits of `environment.etc`:

Nix-Managed: The certificate is integrated into the Nix store, providing a robust and declarative way to manage its lifecycle.
Stable Path: /etc/my-self-signed-cert.crt becomes a consistent and reliable reference point.
Declarative: Directly fits within the NixOS configuration paradigm.
Read-Only: Setting the mode to 0444 enhances security by preventing accidental modification.

Strategy 2: Leveraging `fetchUrl` for Dynamic Certificate Retrieval

Your second idea, using fetchUrl to download the certificate from an internal server during nixos-rebuild, is a viable strategy, particularly if you want to externalize the certificate management completely from the VM’s build definition.

Method 2.1: Fetching the Certificate Declaratively

This approach treats the certificate as an external resource that Nix can fetch.

Detailed Implementation:

You would first need to ensure your internal HTTP server is running and accessible from within the VM. The certificate file should be served at a stable URL.

# In your VM's configuration.nix
{ pkgs, ... }:

let
  # Define the URL where your certificate is hosted internally
  certificateUrl = "http://internal-server.example.com/certs/my-self-signed-cert.crt";

  # Use fetchurl to download the certificate.
  # We use sha256 to ensure integrity and cache the fetched file.
  # If the certificate is updated, you'll need to update the sha256 hash.
  # A tool like `nix-prefetch-url --unpack <url>` can help you get the hash.
  myFetchedCert = pkgs.fetchurl {
    url = certificateUrl;
    sha256 = "YOUR_SHA256_HASH_HERE"; # Replace with the actual SHA256 hash of your certificate
  };
in
{
  security.pki.certificates = [
    myFetchedCert # Nix will treat this derivation output as the certificate file
  ];

  # Optional: If your internal server itself uses this certificate,
  # you might need to manage its trust store as well.
  # For example, if your internal server is served by nginx:
  # services.nginx.enable = true;
  # services.nginx.virtualHosts."internal-server.example.com".sslCert = "/path/to/your/server.crt";
  # services.nginx.virtualHosts."internal-server.example.com".sslKey = "/path/to/your/server.key";
}

Considerations for fetchUrl:

sha256 Hash Management: The primary challenge with fetchUrl is managing the sha256 hash. Every time you update the certificate on your internal server, you must update the sha256 hash in your Nix expression. Failure to do so will result in nixos-rebuild failing because the fetched content will not match the expected hash.
External Dependency: This method introduces a dependency on your internal HTTP server being available and serving the certificate correctly during the nixos-rebuild process. If the server is down or the URL changes, the rebuild will fail.
Network Accessibility: The VM must have network access to the internal server during the rebuild.

Advanced `fetchUrl` Scenarios:

Using Nix for Hash Updates: You can automate the sha256 hash update process. Before committing changes, run nix-prefetch-url <certificateUrl> and copy the output hash into your configuration. This can be part of your CI/CD pipeline.
Internal CA for Fetching: If you’re fetching from an internal server that uses its own self-signed certificate, you might need to pre-configure trust for that server’s certificate as well, creating a potential bootstrapping problem. However, typically, fetching over HTTP does not require the client to trust the server’s certificate in the same way as fetching over HTTPS with a custom CA.

Strategy 3: Extracting the Certificate from System-Wide CA Store

Your third idea, extracting the certificate from /etc/ssl/ca-certificates.crt (or its NixOS equivalent) during the rebuild process, is technically feasible but generally not recommended for self-signed certificates managed this way.

Method 3.1: Parsing `ca-certificates.crt` (Discouraged)

The ca-certificates.crt file on most Linux systems aggregates various trusted certificates. It’s usually a concatenation of PEM-encoded certificates.

Why this is generally not a good idea for your use case:

NixOS Integration: In NixOS, system-wide CA certificates are managed differently. While /etc/ssl/ca-certificates.crt might exist, it’s often a symlink to a Nix store path. Directly parsing this file assumes a specific file format and structure that might not be guaranteed or might change across NixOS versions or configurations.
Complexity: Extracting a specific self-signed certificate from a large concatenated file requires robust parsing logic. You would need to reliably identify the start and end of your specific certificate, which can be brittle if the format of the aggregated file changes.
Nix Expression Limitations: Nix expressions are primarily for defining derivations and system configurations, not for general-purpose scripting or parsing complex file formats within the build process. While you could write a custom derivation to do this, it would be significantly more complex and less declarative than other methods.
Rebuild Triggering: If the certificate is already in the trust store via security.pki.certificates, and you’re trying to extract it from the system’s CA bundle to re-add it, you’re creating a circular dependency or an unnecessary step. The goal is to make it available for the security.pki.certificates option during rebuild.

If you were absolutely forced to consider this (which we strongly advise against for this specific problem), you might explore using pkgs.coreutils for grep and sed within a custom derivation to extract the certificate. However, this would involve a custom Nix expression that:

Reads the aggregated CA certificate file.
Uses tools to find and extract your specific certificate based on its content or distinguished name.
Creates a new derivation output containing only your extracted certificate.
References this new derivation output in security.pki.certificates.

This approach is unnecessarily complicated and prone to breaking. It’s far more efficient and robust to ensure the certificate is directly managed or fetched.

Best Practices and Recommended Approach

Based on our analysis, the recommended and most robust approach for making your self-signed certificate persist in NixOS VMs across nixos-rebuild operations is Strategy 1: Preserving the Certificate within the VM’s Root Filesystem using environment.etc.

This method offers the best balance of:

Declarative Management: Fits perfectly within the NixOS philosophy.
Reliability: The certificate is placed in a known, Nix-managed location.
Simplicity: The configuration is straightforward to implement and understand.
Maintainability: No external dependencies to manage (like fetchUrl’s hash) or complex parsing logic.

Refining the Recommended Method for Maximum Resilience

Let’s recap the most robust implementation of Strategy 1:

1. Modify your initial VM build configuration (or a dedicated module) to include the certificate using environment.etc:

# In your VM's configuration.nix or a relevant module
{ pkgs, ... }:

let
  # Read the certificate file. Ensure this path is correct relative to your Nix expression.
  myCertContent = builtins.readFile ./certificate.crt;
in
{
  # Place the certificate in a predictable location managed by Nix.
  # This creates a symlink /etc/my-trusted-cert.pem -> /nix/store/.../my-trusted-cert.pem
  environment.etc."my-trusted-cert.pem" = {
    source = "/path/to/your/certificate.crt"; # Ensure this path is correct during the initial build
    mode = "0444"; # Read-only access
  };

  # Tell NixOS to trust this certificate by including it in the PKI configuration.
  security.pki.certificates = [
    "/etc/my-trusted-cert.pem" # Reference the symlink, Nix will resolve it to the store path.
  ];

  # Optional: If you need this certificate available system-wide for applications that
  # might not use the NixOS PKI store directly, you can also add it to the common trust store.
  # Be cautious with this, as it might affect global trust settings.
  # system.extraDependencies = [ pkgs.cacert ]; # Ensure cacert is available if needed
  # system.extraConfig = ''
  #   update-ca-certificates --add-pem /etc/my-trusted-cert.pem
  # '';
  # Note: The system.extraConfig approach is less declarative and might be less robust.
  # Relying on security.pki.certificates = [ "/etc/my-trusted-cert.pem" ]; is preferred.
}

Important Note on source for environment.etc: When using environment.etc within the context of building a VM image, the source should point to the absolute path of the certificate file on the host machine during the build, or ideally, it should be a Nix store path if the certificate itself is a derivation. For simplicity, assuming certificate.crt is in the same directory as your Nix expression:

# In your VM's configuration.nix or a relevant module
{ pkgs, ... }:

let
  # Create a derivation for the certificate file.
  # This ensures the certificate is a first-class Nix artifact.
  myCertDerivation = pkgs.runCommand "my-self-signed-cert.pem" {} ''
    mkdir -p $out
    cp ${./certificate.crt} $out/my-self-signed-cert.pem
  '';
in
{
  # Place the certificate in a predictable location managed by Nix.
  environment.etc."my-trusted-cert.pem" = {
    source = "${myCertDerivation}/my-self-signed-cert.pem"; # Reference the output from the derivation
    mode = "0444"; # Read-only access
  };

  # Tell NixOS to trust this certificate by including it in the PKI configuration.
  security.pki.certificates = [
    "/etc/my-trusted-cert.pem" # Nix resolves this symlink to the Nix store path.
  ];
}

2. During nixos-rebuild within the VM:

Simply run sudo nixos-rebuild switch (or your preferred command). The configuration.nix will be processed, and it will correctly reference /etc/my-trusted-cert.pem. Since this is a symlink to a Nix store path, and the Nix store is preserved, the certificate remains available.

Why Other Approaches Are Less Ideal

fetchUrl: While functional, the ongoing burden of managing the sha256 hash makes it less convenient for certificates that might be updated. It also introduces an external network dependency.
Parsing CA Store: This is overly complex, brittle, and not idiomatic for NixOS.

By adopting the environment.etc method, you ensure your self-signed certificate is treated as a core part of your NixOS system configuration, making it robustly persistent through any subsequent nixos-rebuild operations. This declarative and integrated approach guarantees that your VM’s trust infrastructure remains sound, allowing you to focus on your development and deployment without worrying about certificate availability. We are confident that this detailed explanation and recommended strategy will empower you to manage your NixOS VM certificates effectively.

How do I make a self-signed certificate persist in nixos?

Making Self-Signed Certificates Persistent in NixOS VMs: A Comprehensive Guide #

Understanding the NixOS PKI and Certificate Management #

Strategy 1: Preserving the Certificate within the VM’s Root Filesystem #

Method 1.1: Placing the Certificate in /root During Initial Build #

Key Benefits of environment.etc: #

Strategy 2: Leveraging fetchUrl for Dynamic Certificate Retrieval #

Method 2.1: Fetching the Certificate Declaratively #

Advanced fetchUrl Scenarios: #

Strategy 3: Extracting the Certificate from System-Wide CA Store #

Method 3.1: Parsing ca-certificates.crt (Discouraged) #

Best Practices and Recommended Approach #

Refining the Recommended Method for Maximum Resilience #

Why Other Approaches Are Less Ideal #