diff --git a/README.md b/README.md index 6c74bb3..0f122ef 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # nixos-anywhere -***Install NixOS everywhere via ssh*** +**_Install NixOS everywhere via ssh_** ![](https://raw.githubusercontent.com/numtide/nixos-anywhere/main/docs/logo.png) @@ -27,7 +27,7 @@ You first create Nix configurations to specify partitioning, formatting and NixO Once the configuration has been created, a single command will: - Connect to the remote server via SSH -- Detect whether a NixOS installer is present; if not, it will use the Linux ```kexec``` tool to boot into a Nixos installer. +- Detect whether a NixOS installer is present; if not, it will use the Linux `kexec` tool to boot into a Nixos installer. - Use the [disko](https://github.com/nix-community/disko) tool to partition and format the hard drive - Install NixOS - Optionally install any Nix packages and other software required. @@ -40,14 +40,11 @@ It's also possible to use **nixos-anywhere** to simplify the installation on a m ## Prerequisites - Source Machine: - - - Can be any Linux machine with Nix installed, or a NixOS machine. - Target Machine: - - - Unless you're using the option to boot from a NixOS installer image, or providing your own ```kexec``` image, it must be running x86-64 Linux with kexec support. Most x86_64 Linux systems do have kexec support. By providing your own [image](./docs/how_to.md#using-your-own-kexec-image) you can also perform kexec for other architectures eg aarch64 - + + - Unless you're using the option to boot from a NixOS installer image, or providing your own `kexec` image, it must be running x86-64 Linux with kexec support. Most x86_64 Linux systems do have kexec support. By providing your own [image](./docs/how_to.md#using-your-own-kexec-image) you can also perform kexec for other architectures eg aarch64 - Must have at least 1.5 GB of RAM, excluding swap. - ## How to use nixos-anywhere @@ -55,11 +52,11 @@ Here’s  a quick summary of how to use **nixos-anywhere**. You can find more i The tool doesn't need to be installed, since it can be run directly from this repository. -First create a repo that includes the disk configuration and a [flake](https://nixos.wiki/wiki/Flakes) to configure your options. This example assumes that flakes have been enabled on your source machine. +First create a repo that includes the disk configuration and a [flake](https://nixos.wiki/wiki/Flakes) to configure your options. This example assumes that flakes have been enabled on your source machine. Here’s an example of a simple disk configuration: -``` +```nix { disks ? [ "/dev/vda" ], ... }: { disk = { @@ -111,7 +108,7 @@ The [disko repository](https://github.com/nix-community/disko/tree/master/exampl A simple flake may look like this: -``` +```nix { inputs.nixpkgs.url = github:NixOS/nixpkgs; inputs.disko.url = github:nix-community/disko; @@ -178,7 +175,7 @@ If you would like to become a contributor, please see our [contribution guidelin --- -This project is supported by [Numtide](https://numtide.com/).  ![Untitledpng](https://codahosted.io/docs/6FCIMTRM0p/blobs/bl-sgSunaXYWX/077f3f9d7d76d6a228a937afa0658292584dedb5b852a8ca370b6c61dabb7872b7f617e603f1793928dc5410c74b3e77af21a89e435fa71a681a868d21fd1f599dd10a647dd855e14043979f1df7956f67c3260c0442e24b34662307204b83ea34de929d)     +This project is supported by [Numtide](https://numtide.com/).  ![Untitledpng](https://codahosted.io/docs/6FCIMTRM0p/blobs/bl-sgSunaXYWX/077f3f9d7d76d6a228a937afa0658292584dedb5b852a8ca370b6c61dabb7872b7f617e603f1793928dc5410c74b3e77af21a89e435fa71a681a868d21fd1f599dd10a647dd855e14043979f1df7956f67c3260c0442e24b34662307204b83ea34de929d) We are a team of independent freelancers that love open source.  We help our customers make their project lifecycles more efficient by: diff --git a/docs/howtos.md b/docs/howtos.md index a8cfdd3..1696645 100644 --- a/docs/howtos.md +++ b/docs/howtos.md @@ -1,42 +1,40 @@ -# How To Guide: nixos-anywhere - -## Contents - -[Installing on a machine with no operating system](#installing-on-a-machine-with-no-operating-system) - -[Using your own kexec image](#using-your-own-kexec-image) - -[Using nixos-anywhere without flakes](#using-nixos-anywhere-without-flakes) - -TODO: Add more topics - -## Installing on a machine with no operating system - -TODO: Still to be documented - -Include: - -`nixos-anywhere` can detect a nixos installer if it contains the identifier `VARIANT=installer` in its `/etc/os-release` file. This is the case for the nixos-unstable installer and will be also part of nixos 23.05. If an installer is detected `nixos-anywhere` will not try to kexec into its own image. - -## Using your own kexec image - -By default `nixos-anywhere` will download the kexec image from [here](https://github.com/nix-community/nixos-images#kexec-tarballs). It is also possible to provide your own by using the command line switch `--kexec` to specify the image file. The image will then be uploaded prior to executing. - -``` -nixos-anywhere \ - --kexec "$(nix build --print-out-paths github:nix-community/nixos-images#packages.x86_64-linux.kexec-installer-noninteractive-nixos-unstable)/nixos-kexec-installer-noninteractive-x86_64-linux.tar.gz" \ - --flake 'github:your-user/your-repo#your-system' \ - root@yourip -``` - -This is particularly useful for distributions like aarch64-linux, where there is no pre-build image. The following example assumes that your local machine can build for aarch64-linux either natively or through a remote builder - -## Using nixos-anywhere without flakes - -TODO: Add content - -``` - -``` - - +# How To Guide: nixos-anywhere + +## Contents + +[Installing on a machine with no operating system](#installing-on-a-machine-with-no-operating-system) + +[Using your own kexec image](#using-your-own-kexec-image) + +[Using nixos-anywhere without flakes](#using-nixos-anywhere-without-flakes) + +TODO: Add more topics + +## Installing on a machine with no operating system + +TODO: Still to be documented + +Include: + +`nixos-anywhere` can detect a nixos installer if it contains the identifier `VARIANT=installer` in its `/etc/os-release` file. This is the case for the nixos-unstable installer and will be also part of nixos 23.05. If an installer is detected `nixos-anywhere` will not try to kexec into its own image. + +## Using your own kexec image + +By default `nixos-anywhere` will download the kexec image from [here](https://github.com/nix-community/nixos-images#kexec-tarballs). It is also possible to provide your own by using the command line switch `--kexec` to specify the image file. The image will then be uploaded prior to executing. + +``` +nixos-anywhere \ + --kexec "$(nix build --print-out-paths github:nix-community/nixos-images#packages.x86_64-linux.kexec-installer-noninteractive-nixos-unstable)/nixos-kexec-installer-noninteractive-x86_64-linux.tar.gz" \ + --flake 'github:your-user/your-repo#your-system' \ + root@yourip +``` + +This is particularly useful for distributions like aarch64-linux, where there is no pre-build image. The following example assumes that your local machine can build for aarch64-linux either natively or through a remote builder + +## Using nixos-anywhere without flakes + +TODO: Add content + +``` + +``` diff --git a/docs/quickstart.md b/docs/quickstart.md index 0c16531..2b00181 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,5 +1,5 @@ -# Quickstart Guide: nixos-anywhere - -This document describes how to use **nixos-anywhere** in its simplest case: installing NixOS on an existing Linux distribution via SSH. - -TODO: Populate this guide +# Quickstart Guide: nixos-anywhere + +This document describes how to use **nixos-anywhere** in its simplest case: installing NixOS on an existing Linux distribution via SSH. + +TODO: Populate this guide diff --git a/docs/reference.md b/docs/reference.md index fef3617..191c82a 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,69 +1,70 @@ -# Reference Manual: nixos-anywhere - -TODO: Populate this guide properly - -## Contents - -[Command Line Usage](#command-line-usage) - -[Developer guide](#developer-guide) - -[Explanation of known error messages](#explanation-of-known-error-messages) - -## Command Line Usage - - -``` -Usage: nixos-anywhere [options] ssh-host - -Options: - -* -f, --flake flake - set the flake to install the system from -* -L, --print-build-logs - print full build logs -* -s, --store-paths - set the store paths to the disko-script and nixos-system directly - if this is give, flake is not needed -* --no-reboot - do not reboot after installation, allowing further customization of the target installation. -* --kexec url - use another kexec tarball to bootstrap NixOS -* --stop-after-disko - exit after disko formating, you can then proceed to install manually or some other way -* --extra-files files - files to copy into the new nixos installation -* --disk-encryption-keys remote_path local_path - copy the contents of the file or pipe in local_path to remote_path in the installer environment, - after kexec but before installation. Can be repeated. -* --no-substitute-on-destination - disable passing --substitute-on-destination to nix-copy -* --debug - enable debug output -* --option KEY VALUE - nix option to pass to every nix related command -* --from store-uri - URL of the source Nix store to copy the nixos and disko closure from -* --build-on-remote - build the closure on the remote machine instead of locally and copy-closuring it -``` - -## Developer guide - -To run `nixos-anywhere` from the repo: - -```shell -nix run . -- --help -``` - -To format the code - -```shell -nix fmt -``` - -## Explanation of known error messages - -TODO: List actual error messages and meanings. Include: - -If you do not have enough RAM you will see failures unpacking the initrd), this is because kexec needs to load the whole nixos into memory. +# Reference Manual: nixos-anywhere + +TODO: Populate this guide properly + +## Contents + +[Command Line Usage](#command-line-usage) + +[Developer guide](#developer-guide) + +[Explanation of known error messages](#explanation-of-known-error-messages) + +## Command Line Usage + + + +``` +Usage: nixos-anywhere [options] ssh-host + +Options: + +* -f, --flake flake + set the flake to install the system from +* -L, --print-build-logs + print full build logs +* -s, --store-paths + set the store paths to the disko-script and nixos-system directly + if this is give, flake is not needed +* --no-reboot + do not reboot after installation, allowing further customization of the target installation. +* --kexec url + use another kexec tarball to bootstrap NixOS +* --stop-after-disko + exit after disko formating, you can then proceed to install manually or some other way +* --extra-files files + files to copy into the new nixos installation +* --disk-encryption-keys remote_path local_path + copy the contents of the file or pipe in local_path to remote_path in the installer environment, + after kexec but before installation. Can be repeated. +* --no-substitute-on-destination + disable passing --substitute-on-destination to nix-copy +* --debug + enable debug output +* --option KEY VALUE + nix option to pass to every nix related command +* --from store-uri + URL of the source Nix store to copy the nixos and disko closure from +* --build-on-remote + build the closure on the remote machine instead of locally and copy-closuring it +``` + +## Developer guide + +To run `nixos-anywhere` from the repo: + +```shell +nix run . -- --help +``` + +To format the code + +```shell +nix fmt +``` + +## Explanation of known error messages + +TODO: List actual error messages and meanings. Include: + +If you do not have enough RAM you will see failures unpacking the initrd), this is because kexec needs to load the whole nixos into memory. diff --git a/flake.nix b/flake.nix index cd314ca..6e1a3f1 100644 --- a/flake.nix +++ b/flake.nix @@ -31,6 +31,7 @@ programs.nixpkgs-fmt.enable = true; programs.shellcheck.enable = true; programs.shfmt.enable = true; + programs.prettier.enable = true; settings.formatter.shellcheck.options = [ "-s" "bash" ]; }; formatter = config.treefmt.build.wrapper;