Skip to main content

NixOS

NixOS is a Linux distribution that uses the Nix package manager to provide reliable and reproducible system configurations.

Rebuilding System Configuration​

If you just need to do a rebuild in one single line:

sudo NIX_CONFIG="access-tokens = github.com=" nixos-rebuild switch --flake 'nixpkgs-matrix-private#PROFILE'

Once you have XDG_CONFIG_HOME setup and ~/.config/nix/nix.conf with the necessary access token, you can use sudo -E or --use-remote-sudo to inherit authority to contact nixpkgs-matrix-private repository, and not have to always specify the NIX_CONFIG environment variable.

The ~/.config/nix/nix.conf should look like:

extra-access-tokens = github.com=GITHUB_PAT

Make sure to replace GITHUB_PAT with your actual GitHub PAT that has the authority to read-only the contents of https://github.com/MatrixAI/nixpkgs-matrix-private.

These commands are now possible:

# Using `sudo -E` inherits user environment variables
# Rebuilding from indirect flake reference
sudo -E nixos-rebuild switch --flake 'nixpkgs-matrix-private#PROFILE'

# Using `--use-remote-sudo` will trigger `sudo` lazily, allowing the command to inherit user environment variables
# Rebuilding from indirect flake reference and refreshed inputs
nixos-rebuild switch --flake 'nixpkgs-matrix-private#PROFILE' --refresh --use-remote-sudo

# If you have cloned the `nixpkgs-matrix-private` directly you can also refer to the local flake
nixos-rebuild switch --flake '.#PROFILE' --refresh --use-remote-sudo

Take note of the --refresh option which forces Nix to update the flake inputs before performing the rebuild.

If you need to rebuild configuration with respect to a specific feature branch, use a full github reference:

sudo \
  NIX_CONFIG="access-tokens = github.com=" \
  nixos-rebuild switch \
  --flake 'github:MatrixAI/nixpkgs-matrix-private/feature-branch#PROFILE' \
  --refresh

Note that some configuration rebuilds cannot be activated without a reboot. In those cases, you should use nixos-rebuild boot instead of nixos-rebuild switch. Then reboot to apply the changes.

Garbage Collection​

# User profile garbage collection
nix-collect-garbage -d
# Root level garbage collection
sudo nix-collect-garbage -d

Note that boot entries will only be cleared AFTER you first garbage collect then run a nixos-rebuild switch.

Boot Process Overview​

The boot process is structured into several critical stages, each responsible for preparing the system for the next phase:

  1. Stage-0: This initial stage involves the preboot configuration handled by BIOS/EFI. It is responsible for executing the kernel along with the initrd and a stage-1 script.
  2. Stage-1: In this stage, the bootloader takes over, facilitating the preliminary preparation needed before the root filesystem is mounted. It concludes by executing the stage-2 script.
  3. Stage-2: This stage handles the operating system setup that must occur right before systemd comes into play. At the end of this stage, systemd is executed, transitioning the boot process to its subsequent phase.
  4. Stage-3: With systemd now in control, this stage initializes and manages all the system services necessary for the operating system to run. Once completed, the computer is considered booted and operational.
  5. Stage-4: This final stage is concerned with user-level initialization. It establishes a user session, logging the user in and ensuring that all necessary user-level services are started.

Each phase of the boot process seamlessly hands off control to the next, ensuring a structured and orderly start-up of the system.

To remotely control Stage-0, you need a KVM or BMC.

To remotely control Stage-1, you need stage-1 SSH.

Take note that it's possible to have internet setup at Stage-0. You just need a specialized bootloader or BIOS configuration to use iPXE or PXE.