the nixos manual contains enough examples to support them as a proper
toc entity with specialized rendering, and if in the future the nixpkgs
wants to use nixos-render-docs we will definitely have to support them.
this also allows us to restore some examples that were lost in previous
translation steps because there were too few to add renderer support
back then.
this adds support for structural includes to nixos-render-docs.
structural includes provide a way to denote the (sub)structure of the
nixos manual in the markdown source files, very similar to how we used
literal docbook blocks before, and are processed by nixos-render-docs
without involvement of xml tooling. this will ultimately allow us to
emit the nixos manual in other formats as well, e.g. html, without going
through docbook at all.
alternatives to this source layout were also considered:
a parallel structure using e.g. toml files that describe the document
tree and links to each part is possible, but much more complicated to
implement than the solution chosen here and makes it harder to follow
which files have what substructure. it also makes it much harder to
include a substructure in the middle of a file.
much the same goes for command-line arguments to the converter, only
that command-lined arguments are even harder to specify correctly and
cannot be reasonably pulled together from many places without involving
another layer of tooling. cli arguments would also mean that the manual
structure would be fixed in default.nix, which is also not ideal.
since support for kbd elements was added with explicit intent in #175128
it seems like a good idea to support this in nixos-render-docs instead
of just dropping it in favor of `*F12*` etc. since it's a very rare
thing in the manual and purely presentational it makes sense to use
bracketed spans instead of a new myst role.
the html-elements.lua plugin is now somewhat misnamed, but it'll go away
very soon so we don't want to bother renaming it.
pandoc drops .title classes when rendering to docbook, so these are
effectively just paragraphs anyway. without support for including them
in a table of contents the complexity of parsing them in
nixos-render-docs won't be warranted.
pandoc renders these to multiple docbook paragraphs in a single
definition for the term, not multiple *actual* definitions for the same
term. this is most likely not what is intended here, so let's use
multiple paragraphs instead.
The nixos-generate-config command mentioned in the manual fails with error:
nixos-generate-config: no need to specify `/` with `--root`, it is the default
This was introduced in 611b8c4472
(#161034). Now, the command should be called without any arguments.
- Update download URLs
- Replace "USB stick"/"USB Drive" with "USB flash drive" as that seem more correct
https://en.wikipedia.org/wiki/USB_flash_drivehttps://elementary.io/docs/installation#choose-operating-system
- Don't mention CD as easiest option anymore,
as all modern systems should be able to boot from USB,
but many don't have a CD drive. Burning CDs is also usually wasteful as you
can't burn them again.
- Remove link to NixOS Wiki (Making_the_installation_media) as it is not needed
- Add Etcher and USBImager as graphical tools to create install drive
- Make dd command consistent and use block size of 4 MB for faster flashing
- More consistent text
- Add instructions for "Booting from the install medium"
Inspired by 9a91b0f495/docs/installation.md (booting-from-the-install-drive-booting-from-the-installation-medium-clear-float-2)
- Add instructions for "Graphical Installation"
- Restructure headings and anchors for "Manual Installation"
- Adding legacy anchors for "Manual Installation" to not break links
Co-authored-by: j-k <dev@j-k.io>
Co-authored-by: Sandro <sandro.jaeckel@gmail.com>
Co-authored-by: Robert Schütz <github@dotlambda.de>
Co-authored-by: Jörg Thalheim <Mic92@users.noreply.github.com>
Co-authored-by: Thiago Kenji Okada <thiagokokada@gmail.com>
$ parted /dev/nvme1n1 -- mkpart primary linux-swap -8GiB 100%
Warning: The resulting partition is not properly aligned for best performance: 3108850352s % 2048s != 0s
Ignore/Cancel?
Information: You may need to update /etc/fstab.
When using GB than parted seems to round up itself.
Without configuring the block size a default of 512 bytes is used, which can
slow down the transfer speed massively.
In a test I've done with a semi-decent USB stick, I only get a transfer speed
of around 180 KB/sec when not specifying the block size but see 27 MB/sec when
setting the block size to 1 MB. This makes the transfer of the minimal
installation ISO take half a minute instead of an hour.
The command in example is expected to be run from nixpkgs checkout, but
there's no explanation of this. Let's just use system nixpkgs: most
users will have it just working and those who use git checkouts will
figure it out.
The wpa_supplicant service in the NixOS installer is unusable because
the control socket is disabled and /etc/wpa_supplicant.conf ignored.
The manual currently recommends manually starting the daemon and using
wpa_passphrase, but this requires figuring out the interface name,
driver and only works for WPA2 personal networks.
By enabling the control socket, instead, a user can configure the
network via wpa_cli (or wpa_gui in the graphical installer), which
support more advanced network configurations.
The essential commands from the NixOS installer as a package
With this package, you get the commands like nixos-generate-config and
nixos-install that you would otherwise only find on a NixOS system, such
as an installer image.
This way, you can install NixOS using a machine that only has Nix.
It also includes the manpages, which are important because the commands
rely on those for providing --help.
We're really setting users up on the wrong path if we tell them to
nix-env -iA immediately after installing. Instead, let's just
reassure them that installing software will be covered in due course
in the manual, to encourage them to keep reading.
Right now the UX for installing NixOS on a headless system is very bad.
To enable sshd without physical steps users have to have either physical
access or need to be very knowledge-able to figure out how to modify the
installation image by hand to put an `sshd.service` symlink in the
right directory in /nix/store. This is in particular a problem on ARM
SBCs (single board computer) but also other hardware where network is
the only meaningful way to access the hardware.
This commit enables sshd by default. This does not give anyone access to
the NixOS installer since by default. There is no user with a non-empty
password or key. It makes it easy however to add ssh keys to the
installation image (usb stick, sd-card on arm boards) by simply mounting
it and adding a keys to `/root/.ssh/authorized_keys`.
Importantly this should not require nix/nixos on the machine that
prepare the installation device and even feasiable on non-linux systems
by using ext4 third party drivers.
Potential new threats: Since this enables sshd by default a
potential bug in openssh could lead to remote code execution. Openssh
has a very good track-record over the last 20 years, which makes it
far more likely that Linux itself would have a remote code execution
vulnerability. It is trusted by millions of servers on many operating
systems to be exposed to the internet by default.
Co-authored-by: Samuel Dionne-Riel <samuel@dionne-riel.com>
With 'set 3 boot on' the error 'file system "/boot" is not a FAT EFI
system partition (ESP) file system' occurs when running
"nixos-install" during the basic installation (tested in in a
VirtualBox VM).
Virtualbox recommends VMSVGA for Linux guests.
It is also currently the only one supporting 3D acceleration
and it works out of the box with NixOS and auto screen resizing.
Running the manual on a TTY is useless in the graphical ISOs and not
particularly useful in non-graphical ISOs (since you can also run
'nixos-help').
Fixes#83157.
There's many reason why it is and is going to
continue to be difficult to do this:
1. All display-managers (excluding slim) default PAM rules
disallow root auto login.
2. We can't use wayland
3. We have to use system-wide pulseaudio
4. It could break applications in the session.
This happened to dolphin in plasma5
in the past.
This is a growing technical debt, let's just use
passwordless sudo.
Compatibility with other distributions/software and expectation
of users coming from other systems should have higher priority over consistency.
In particular this fixes#51375, where the NetworkManager-wait-online.service
broke as a result of this.
