From 1ce9e2929843150f1ec1f6e265187cfe31f82f61 Mon Sep 17 00:00:00 2001 From: Petter Date: Fri, 5 Feb 2016 18:33:24 +0100 Subject: [PATCH] Merged installation proposal into guix.texi --- doc/guix.texi | 331 +++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 256 insertions(+), 75 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 66ab384..1b8d1d2 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -5623,104 +5623,230 @@ Introduction}). The installation system runs the GPM mouse daemon, which allows you to select text with the left mouse button and to paste it with the middle button. -To install the system, you would: address@hidden Keyboard address@hidden +The installation image uses the US Qwerty keyboard layout. If you want to change it you can use the @command{loadkeys} command with your preferred layout. Example @var{layout}: @samp{dvorak}. address@hidden +loadkeys @var{layout} address@hidden example address@hidden -Configure the network, by running: address@hidden Network +Run the following command see what your network interfaces are called. Wired interfaces often start with @samp{e}, like @samp{eno1}. Wireless interfaces often start with @samp{w}, like @samp{w1p2s0}. @example -ifconfig eno1 up && dhclient eno1 +ifconfig -a @end example -to get an automatically assigned IP address from the wired -network interface address@hidden address@hidden http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 -The name @code{eno1} is for the first on-board Ethernet controller. The -interface name for an Ethernet controller that is in the first slot of -the first PCI bus, for instance, would be @code{enp1s0}. Use address@hidden -a} to list all the available network interfaces.}, -or using the @command{ifconfig} command. address@hidden @asis address@hidden Wired connection +To configure a wired network run the following command, substituting @var{network-interface} with the wired interface you want to use. address@hidden +ifconfig @var{network-interface} up address@hidden example -The system automatically loads drivers for your network interface -controllers. address@hidden Wireless connection +To configure a wireless network create a configuration file and add a network stanza to it. Create and open a configuration file (location is not important) address@hidden +zile wpa_supplicant.conf address@hidden example -Setting up network access is almost always a requirement because the -image does not contain all the software and tools that may be needed. +Add the following stanza to it and update with actual ssid and password for the network you're connecting to: address@hidden address@hidden + address@hidden + key_mgmt=WPA-PSK + address@hidden address@hidden address@hidden example + +Start the wireless service and run it in the background with the following command. Substitute @var{network-interface} with the one you want to use. address@hidden +wpa_supplicant -c wpa_supplicant.conf -i @var{network-interface} -B address@hidden example address@hidden ftable address@hidden -Unless this has already been done, you must partition, and then format -the target partition. - -Preferably, assign partitions a label so that you can easily and -reliably refer to them in @code{file-system} declarations (@pxref{File -Systems}). This is typically done using the @code{-L} option of address@hidden and related commands. - -Be sure that your partition labels match the value of their respective address@hidden fields in your @code{file-system} configuration, if your address@hidden configuration sets the value of @code{title} to address@hidden'label}, as do the example configurations found on the USB -installation image under @file{/etc/configuration} (@pxref{Using the -Configuration System}). - address@hidden FIXME: Uncomment this once GRUB fully supports encrypted roots. address@hidden A typical command sequence may be: address@hidden address@hidden @example address@hidden # fdisk /dev/sdX address@hidden @dots{} Create partitions address@hidden address@hidden # cryptsetup luksFormat /dev/sdX1 address@hidden # cryptsetup open --type luks /dev/sdX1 my-partition address@hidden # mkfs.ext4 -L my-root /dev/mapper/my-partition address@hidden @end example - -The installation image includes Parted (@pxref{Overview,,, parted, GNU -Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk -encryption, and e2fsprogs, the suite of tools to manipulate -ext2/ext3/ext4 file systems. +Acquire an IP address. If you're on a network with DHCP you can run address@hidden +dhclient @var{network-interface} address@hidden example address@hidden -Once that is done, mount the target root partition under @file{/mnt}. +Try to ping a server to see if your network is up and running. address@hidden +ping -c 3 gnu.org address@hidden example address@hidden -Lastly, run @code{herd start cow-store /mnt}. +If ping fails with a @samp{ping: unknown host} error you can try restarting nscd. address@hidden +deco restart nscd address@hidden example -This will make @file{/gnu/store} copy-on-write, such that packages added -to it during the installation phase will be written to the target disk -rather than kept in memory. +The system automatically loads drivers for your network interface controllers. address@hidden enumerate +Setting up network access is almost always a requirement because the image does not contain all the software and tools that may be needed. + address@hidden Disk partitioning + +First you need to decide if you want encrypted root or not. If you're going for unencrypted skip to the next paragraph. For encrypted root you need to figure out if you want/can have /boot encrypted or not. For /boot to be encrypted you need boot firmware with an embedded boot loader, such as Coreboot/Libreboot. Otherwise you'll need to leave /boot unencrypted, in this case create a separate partition for it. 30 MB should be enough, make it type "Linux (83)". Note that the kernel and initramfs do not reside in /boot like on most other systems. On GuixSD they're stored in /gnu/store. + +Your main partition will be where you install root, /. If you're going to install a desktop this partition should be at least 15 GB. Make it use the rest of your disk (after potentially making a boot partition) if you don't know how large to make it. Make it type "Linux (83)" + +For partitioning there are several tools available, @command{cfdisk} is one. Run it and set up your disk with the partition layout you want address@hidden +cfdisk address@hidden example + address@hidden Encrypted root + address@hidden this chapter if you're not doing encrypted root.} +Encrypt the partition you've set off for root with LUKS, using your favorite cryptsetup invocation. For example the command below. Substitute @var{your-encrypted-root-partition} with the corresponding value on your system, typically @samp{/dev/sda1}. address@hidden +cryptsetup -v --cipher serpent-xts-plain64 --key-size 512 --hash whirlpool --use-random --verify-passphrase luksFormat @var{your-encrypted-root-partition} address@hidden example + +Open the LUKS partition with the command below. The last argument is the name we'll assume for the remainder of this installation. Leave it as it is unless you really want to get out of touch with this document. Its lifetime is limited to the installation process anyway. If you want to use a different name for your installed system you'll specify this later. You can verify that it works by doing @code{ls /dev/mapper} before and after the command below. On success a @samp{guixsd} file will appear. address@hidden +cryptsetup luksOpen @var{your-encrypted-root-partition} guixsd address@hidden example + +Make a filesystem, f.ex. ext4 like below. address@hidden +mkfs.ext4 /dev/mapper/guixsd address@hidden example + +Mount it under /mnt address@hidden +mount /dev/mapper/guixsd /mnt address@hidden example + address@hidden Unencrypted root + address@hidden this chapter if you're not doing unencrypted root.} + +Make a filesystem, f.ex. ext4. You can use the "-L" flag, with a string argument, to create a label for later reference. Substitute @var{your-root-partition} with the corresponding value on your system, typically @samp{/dev/sda1}. address@hidden +mkfs.ext4 -L guixsd @var{your-root-partition} address@hidden example + +Mount it under /mnt address@hidden +mount @var{your-root-partition} /mnt address@hidden example address@hidden Proceeding with the Installation address@hidden Filesystem and mount -With the target partitions ready, you now have to edit a file and -provide the declaration of the operating system to be installed. To -that end, the installation system comes with two text editors: GNU nano -(@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone. -It is better to store that file on the target root file system, say, as address@hidden/mnt/etc/config.scm}. +Run this command to make /gnu/store copy-on-write, such that packages added to it during the installation phase will be written to the target disk rather than kept in memory. address@hidden +deco start cow-store /mnt address@hidden example address@hidden the Configuration System}, for examples of operating system -configurations. These examples are available under address@hidden/etc/configuration} in the installation image, so you can copy -them and use them as a starting point for your own configuration. +Create the /etc on your mounted partition address@hidden +mkdir /mnt/etc address@hidden example -Once you are done preparing the configuration file, the new system must -be initialized (remember that the target root file system is mounted -under @file{/mnt}): address@hidden Preparing the configuration file +With the target partitions ready, you now have to edit a file and provide the declaration of the operating system to be installed. To that end, the installation system comes with two text editors: GNU nano (@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone. It is better to store that file on the target root file system, say, as @file{/mnt/etc/config.scm}. + address@hidden the Configuration System}, for examples of operating system configurations. These examples are available under @file{/etc/configuration} in the installation image, so you can copy them and use them as a starting point for your own configuration. + +Open the file in one of the editors. We'll now walk you through the updates you need to make in the operating-system declaration in turn from top to bottom. + address@hidden @asis address@hidden @samp{host-name} +Will be the name for this system. It'll be used for identifying this system on the network and should be unique amongst the computers in your LAN(s). You may also see it in shell prompts. Use ASCII letters and digits only unless you know what you're doing. + address@hidden @samp{timezone} +This value must match a supported timezone exactly. To find the value you need here you can run the command address@hidden +tzselect address@hidden example +and answer its questions. When it asks "Is the above information OK?" answer "1" (Yes). The value in the last line of output is the value to use in your configuration. +To get a shell prompt for running commands you can change virtual console (Ctrl-Alt-F#), or close the editor. + address@hidden @samp{locale} +This value must match a supported locale exactly. To get a list of supported locales and their typing run the command address@hidden +ls /run/current-system/locale/@var{X.Y} address@hidden @samp{example} +where X.Y is the libc version (just press TAB at this level). Find the locale you want in the listed output and take note of exactly how it is typed (trailing / is not included in the name). +To get a shell prompt for running commands you can change virtual console (Ctrl-Alt-F#), or close the editor. + address@hidden @samp{bootloader} +Update the @samp{device} argument according to the comment in the example configuration. Typical value is @var{/dev/sda}, note there's no trailing digit. This will instruct the installation to install GRUB to the MBR of your disk. This is fine even if you're going to use the boot loader in your boot firmware, it will just be unused in this case. address@hidden table + address@hidden Configuration for encrypted root + address@hidden this chapter if you're not doing encrypted root.} + +For encrypted root setups we need to add some lines to the configuration with instructions on how do decrypt your partition during boot. address@hidden @asis address@hidden @code{mapped-devices} +Add the @code{mapped-devices} field below to your your @code{operating-system} declaration. +(If that last sentence didn't make much sense: Insert the code snippet below between the lines (bootloader ...) and (file-systems ...)) address@hidden + (mapped-devices (list (mapped-device + (source @var{your-encrypted-root-partition}) + (target @var{target-name}) + (type luks-device-mapping)))) address@hidden example +Make sure to update the following fields: address@hidden @asis address@hidden @samp{source} +Substitute @var{your-encrypted-root-partition} with the device name of your encrypted partition. Typically @samp{/dev/sda1} address@hidden @samp{target} +Substitute @var{target-name} with a name of your choice. This is the name that will appear in @file{/dev/mapper/} when the partition has been decrypted. One suitable name is @samp{guixsd}. address@hidden table + address@hidden @code{file-systems} +Update these two fields in the @code{file-systems} field: address@hidden @asis address@hidden @samp{device} +Set this value to @file{/dev/mapper/@var{target-name}}. If you used @samp{guixsd} as @var{target-name} previously this will be @samp{/dev/mapper/guixsd} address@hidden @samp{title} +Change this value to @samp{'device}. This makes the @code{device} field be interpreted as a file name rather than a partition label name. Note that it starts with a single quote. address@hidden table address@hidden table + address@hidden Configuration for unencrypted root + address@hidden this chapter if you're not doing unencrypted root.} + +In the @code{file-systems} field, update this field: address@hidden @asis address@hidden @samp{device} +Update this value to the label you made when you created the filesystem. If you used the name that was suggested, you'll use @samp{guixsd} here. address@hidden table + address@hidden Finishing up the configuration + +And finally, update the values in the @code{users} field. address@hidden @asis address@hidden @samp{name} +The username address@hidden @samp{comment} +You can set this to the name of the user address@hidden @samp{home-directory} +Set this to @file{/home/@var{name}}, where @var{name} is the username you previously specified. address@hidden table + address@hidden Installation + +This concludes the updates to the configuration file and the preparation for installation. + +What remains now is to actually install the system. First run this command to get up to speed with the projects progress since this installer was created. address@hidden +guix pull address@hidden example + +Then run this command to initialize the system based on the configuration file you've prepared. @example guix system init /mnt/etc/config.scm /mnt @end example address@hidden -This will copy all the necessary files, and install GRUB on address@hidden/dev/sdX}, unless you pass the @option{--no-grub} option. For -more information, @pxref{Invoking guix system}. This command may trigger -downloads or builds of missing packages, which can take some time. +This will copy all the necessary files, and install GRUB on your hard disk, unless you pass the @option{--no-grub} option. For more information, @pxref{Invoking guix system}. This command may trigger downloads or builds of missing packages, which can take some time. Once that command has completed---and hopefully succeeded!---you can run @command{reboot} and boot into the new system. The @code{root} password @@ -5733,6 +5859,61 @@ Join us on @code{#guix} on the Freenode IRC network or on @file{guix-devel@@gnu.org} to share your experience---good or not so good. address@hidden Booting a fully encrypted system + address@hidden chapter is only for systems with encrypted boot.} + +To be able to boot with encrypted boot you need a system with GRUB flashed into the boot firmware, like with Coreboot/Libreboot. + address@hidden @asis address@hidden Manual steps to boot your fully encrypted system +Press @kbd{c} in GRUB to enter command mode. + +First find the partition here which corresponds to @var{your-encrypted-root-partition} from earlier. For example @file{/dev/sda1} on GPT will be @samp{ahci0,gpt1} address@hidden +ls address@hidden example + +Now decrypt it, @var{grub-partition} is the partition you found in the previous step. Don't use quotes. address@hidden +cryptomount @var{grub-partition} address@hidden example + +Load GuixSD's GRUB configuration file, you can do @command{ls} again to see what name the decrypted partition got. Typically it'll be @samp{crypto0} address@hidden +configfile (crypto0)/boot/grub/grub.cfg address@hidden example + address@hidden Update the GRUB config in your boot firmware +These are just examples for menu entries in the GRUB config, for the actual flash process you should consult with your boot firmware. + address@hidden +menuentry "GuixSD (current)" @{ + cryptomount @var{grub-partition} + set root=(crypto0) + set guix_system=/var/guix/profiles/system + linux address@hidden@}/kernel/bzImage address@hidden address@hidden@} address@hidden@}/boot + initrd address@hidden@}/initrd address@hidden address@hidden example address@hidden +menuentry "GuixSD fallback" @{ + cryptomount @var{grub-partition} + configfile (crypto0)/boot/grub/grub.cfg address@hidden address@hidden example + +Fields to update: address@hidden @asis address@hidden @samp{cryptomount} +Note there's one in each menu entry address@hidden @samp{--root option} +Point this to @address@hidden". Example @file{/dev/mapper/guixsd}. address@hidden table + address@hidden table + + @subsection Building the Installation Image The installation image described above was built using the @command{guix -- 2.6.3