From 9f6428761dca9ce0b11ee621fd9575589b64a7f6 Mon Sep 17 00:00:00 2001 From: Bryan Bennett Date: Mon, 8 Feb 2021 10:33:39 -0500 Subject: [PATCH] Rewrite README (#67) Increase clarity of operation procedure, explicitly state tested hosters & OS versions, and switch to using semantic linefeeds. --- README.md | 154 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 102 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index cf9eef3..82f3878 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,73 @@ -This script aims to install NixOS on Digital Ocean droplets, Vultr servers, or -OVH Virtual Private Servers (starting from distros that these services support -out of the box). +# NixOS-Infect -## Source Distros +## What is this? +A script to install NixOS on non-NixOS hosts. -This script has been tested and can install NixOS from the following source distros: +NixOS-Infect is so named because of the high likelihood of rendering a system inoperable. +Use with extreme caution and preferably only on newly provisioned systems. -On Digital Ocean: -- Fedora 24 x64 -- Ubuntu 20.04 x64 +This script has successfully been tested on at least the follow hosting providers and plans: -On Vultr: -- Ubuntu 18.10 x64 +* [DigitalOcean](https://www.digitalocean.com/products/droplets/) +* [Hetzner Cloud](https://www.hetzner.com/cloud) +* [Vultr](https://www.vultr.com/) +* [Interserver VPS](https://www.interserver.net/vps/) -On OVH Virtual Private Servers (experimental): -- Debian +Should you find that it works on your hoster, +feel free to update this README and issue a pull request. -On Hetzner cloud: -- Ubuntu 18.04 +> *NB:* OpenVZ-based virtualization providers are known not to work with `nixos-infect` (or any other OS takeover script). +> This is core to how OpenVZ operates and cannot be resolved. -YMMV with any other hoster + image combination. +## Motivation -If you have a OpenVZ based virtualization solution then this, or any other OS takeover script will not work, this is fundamental to how OpenVZ works. +Motivation for this script: nixos-assimilate should supplant this script entirely, +if it's ever completed. +nixos-in-place was quite broken when I tried it, +and also took a pretty janky approach that was substantially more complex than this +(although it supported more platforms): +it didn't install to root (/nixos instead), +left dregs of the old filesystem +(almost always unnecessary since starting from a fresh deployment), +and most importantly, simply didn't work for me! +(old system was being because grub wasnt properly reinstalled) -## Considerations +## How do I use it? -nixos-infect is so named because of the high likelihood of rendering a system -inoperable. Use with caution and preferably only on newly-provisioned -systems. +0) **Read and understand the [the script](./nixos-infect)** +1) Deploy any custom configuration you want on your host +2) Deploy your host as non-Nix Operating System. +3) Deploy an SSH key for the root user. -*WARNING NB*: This script wipes out the targeted host's root filesystem when it -runs to completion. Any errors halt execution. It's advised to run with -`bash -x` to help debug, as often a failed run leaves the system in an -inconsistent state, requiring a rebuild (in DigitalOcean panel: Droplet -Settings -> "Destroy" -> "Rebuild from original"). +> *NB:* This step is important. +> The root user will not have a password when nixos-infect runs to completion. +> To enable root login, you *must* have an SSH key configured. -## Digital Ocean +4) run the script with: +``` + curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | NIX_CHANNEL=nixos-20.09 bash -x +``` -*TO USE:* -- Add any custom config you want (see notes below) -- Deploy the droplet indicated at the top of the file, enable ipv6, add your ssh key -- `cat customConfig.optional nixos-infect | ssh root@targethost` +*NB*: This script wipes out the targeted host's root filesystem when it runs to completion. +Any errors halt execution. +A failure will leave the system in an inconsistent state, +and so it is advised to run with `bash -x`. -Alternatively, you may utilize Digital Ocean's "user data" mechanism (found in the Web UI or HTTP API), and supply to it the following example yaml stanzas: +## Hoster notes: +### Digital Ocean +You mmay utilize Digital Ocean's "user data" mechanism (found in the Web UI or HTTP API), +and supply to it the following example yaml stanzas: ```yaml #cloud-config runcmd: - - curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | PROVIDER=digitalocean NIX_CHANNEL=nixos-20.03 bash 2>&1 | tee /tmp/infect.log + - curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | PROVIDER=digitalocean NIX_CHANNEL=nixos-20.09 bash 2>&1 | tee /tmp/infect.log ``` -Potential tweaks: + +#### Potential tweaks: - `/etc/nixos/{,hardware-}configuration.nix`: rudimentary mostly static config -- `/etc/nixos/networking.nix`, networking settings determined at runtime tweak - if no ipv6, different number of adapters, etc. +- `/etc/nixos/networking.nix`: networking settings determined at runtime tweak if no ipv6, different number of adapters, etc. ```yaml #cloud-config @@ -66,39 +80,75 @@ write_files: environment.systemPackages = with pkgs; [ vim ]; } runcmd: - - curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | PROVIDER=digitalocean NIXOS_IMPORT=./host.nix NIX_CHANNEL=nixos-20.03 bash 2>&1 | tee /tmp/infect.log - + - curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | PROVIDER=digitalocean NIXOS_IMPORT=./host.nix NIX_CHANNEL=nixos-20.09 bash 2>&1 | tee /tmp/infect.log ``` -## Vultr -To set up a NixOS Vultr server, instantiate an Ubuntu box with the following "Startup Script": +#### Tested on +|Distribution| Name | Status | test date| +|------------|-----------------|-----------|----------| +|CentOS |6.9 x32 | _failure_ |2020-03-30| +|CentOS |6.9 x64 | _failure_ |2020-03-30| +|CentOS |7.6 x64 | _failure_ |2020-03-30| +|CentOS |8.1 x64 |**success**|2020-03-30| +|CoreOS |2345.3.0 (stable)| _unable_ |2020-03-30| +|CoreOS |2411.1.0 (beta) | _unable_ |2020-03-30| +|CoreOS |2430.0.0 (alpha) | _unable_ |2020-03-30| +|Debian |10.3 x64 |**success**|2020-03-30| +|Debian |9.12 x64 |**success**|2020-03-30| +|Fedora |30 x64 |**success**|2020-03-30| +|Fedora |31 x64 |**success**|2020-03-30| +|FreeBSD |11.3 x64 ufs | _failure_ |2020-03-30| +|FreeBSD |11.3 x64 zfs | _failure_ |2020-03-30| +|FreeBSD |12.1 x64 ufs | _failure_ |2020-03-30| +|FreeBSD |12.1 x64 zfs | _failure_ |2020-03-30| +|RancherOS |v1.5.5 | _unable_ |2020-03-30| +|Ubuntu |16.04.6 (LTS) x32|**success**|2020-03-30| +|Ubuntu |16.04.6 (LTS) x64|**success**|2020-03-30| +|Ubuntu |18.04.3 (LTS) x64|**success**|2020-03-30| +|Ubuntu |19.10 x64 |**success**|2020-03-30| + +### Vultr + +To set up a NixOS Vultr server, +instantiate an Ubuntu box with the following "Startup Script": ```bash #!/bin/sh -curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | NIX_CHANNEL=nixos-20.03 bash +curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | NIX_CHANNEL=nixos-20.09 bash ``` Allow for a few minutes over the usual Ubuntu deployment time for NixOS to download & install itself. -## Hetzner cloud +#### Tested on +|Distribution| Name | Status | test date| Slug | ID | +|------------|-----------------|-----------|----------|------------------|---------| +| Ubuntu | 18.10 x64 |**success**|(Unknown) | (Unknown) |(Unknown)| -Hetzner cloud works out of the box. When creating a server provide the following script as "User data" (this has been tested using Ubuntu 20.04 as a base OS). + +### Hetzner cloud + +Hetzner cloud works out of the box. +When creating a server provide the following script as "User data": ``` #!/bin/sh -curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | NIX_CHANNEL=nixos-20.03 bash 2>&1 | tee /tmp/infect.log +curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | NIX_CHANNEL=nixos-20.09 bash 2>&1 | tee /tmp/infect.log ``` -## Motivation +#### Tested on +|Distribution| Name | Status | test date| +|------------|-----------------|-----------|----------| +|Ubuntu | 20.04 x64 |**success**|(Unknown) | -Motivation for this script: nixos-assimilate should supplant this script -entirely, if it's ever completed. nixos-in-place was quite broken when I -tried it, and also took a pretty janky approach that was substantially more -complex than this (although it supported more platforms): it didn't install -to root (/nixos instead), left dregs of the old filesystem (almost always -unnecessary since starting from a fresh deployment), and most importantly, -simply didn't work for me! (old system was being because grub wasnt properly -reinstalled) +### InterServer VPS +#### Tested on +|Distribution| Name | Status | test date| +|------------|-----------------|-----------|----------| +|Debian | 9 |**success**|2021-01-29| +|Debian | 10 |**success**|2021-01-29| +|Ubuntu | 20.04 |**success**|2021-01-29| +|Ubuntu | 18.04 |**success**|2021-01-29| +|Ubuntu | 14.04 |**success**|2021-01-29|