From mboxrd@z Thu Jan 1 00:00:00 1970 From: Petter Subject: Review of installation manual draft Date: Wed, 27 Jan 2016 20:21:11 +0100 Message-ID: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:46632) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aOVeZ-0007yu-F2 for guix-devel@gnu.org; Wed, 27 Jan 2016 14:21:21 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aOVeV-00065A-Ap for guix-devel@gnu.org; Wed, 27 Jan 2016 14:21:19 -0500 Received: from mx01.mykolab.com ([95.128.36.1]:10691 helo=mx-out01.mykolab.com) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aOVeU-00063D-W5 for guix-devel@gnu.org; Wed, 27 Jan 2016 14:21:15 -0500 Received: from mx03.mykolab.com (mx03.mykolab.com [10.20.7.101]) by mx-out01.mykolab.com (Postfix) with ESMTPS id 869B1601B1 for ; Wed, 27 Jan 2016 20:21:11 +0100 (CET) List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: guix-devel@gnu.org Hi, During the last week on IRC a few of us have been putting together a=20 proposal for updating the GuixSD installation instructions in the=20 manual. It was initially intended to be a guide for how to install=20 GuixSD with encrypted root to the Libreboot site; but as the steps are=20 generic, and the GuixSD manual doesn't address this we thought we'd make=20 a proposal here instead. The instructions for encrypted root are quite=20 detailed, and to try and keep the entire installation manual in the same=20 vein, other steps have been redone with detailed, step for step,=20 instructions. Which will hopefully make it easier for less experienced=20 users to get GuixSD up and running, with or without encryption. First of all we'd like to know if there are any major issues/objections=20 with this proposal, issues that would result in restructuring, or even=20 that we drop it altogether. Better we know now before going into polish=20 mode. We're also very interested in comments and suggestions to make it=20 better of course. Current issues: - typing in the mapped-devices field perfectly is error-prone, maybe=20 put a commented out mapped-devices field in the example configuration=20 instead and the manual will say to enable it for users opting for=20 encryption. - it would be nice to print a list of available layouts for the=20 loadkeys command. Please let me know if you know how to do this. - maybe elaborate on how to use cfdisk and/or similar tools Ideas: - maybe it would be good to use a dedicated bare-bones config for (1)=20 fully encrypted, (2) encrypted root without /boot, (3) encrypted /home,=20 (4) unencrypted; to get people up and running quickly, then add desktop=20 environment etc. in a post-installation document. Thanks, Petter ------------------current draft------------------------------- 7.1.3 Booting the installation image Once you have successfully booted the image on the USB stick, you should=20 end up with a root prompt. Several console TTYs are configured and can=20 be used to run commands as root. TTY2 shows this documentation,=20 browsable using the Info reader commands (see Help in Info: An=20 Introduction). 7.1.3.1 Keyboard The installation image uses the US Qwerty keyboard layout. To change you=20 can use the "loadkeys" command with your preferred layout. Example=20 : "dvorak". # loadkeys 7.1.3.2 Network Run this to see what your network interfaces are called: # ifconfig -a To configure the network run this command, substituting=20 with the one you want to use. Example=20 : "eno1". # ifconfig up && dhclient Try to ping a server to see if a connection was established. For=20 example, gnu.org. # ping -c 3 gnu.org If ping fails with a `ping: unknown host` error, first check if there is=20 an issue with your cable. If not, try to restart nscd. # deco restart nscd 7.1.4 Preparing the disk First you need to decide if you want encrypted root or not. If you're=20 going for unencrypted skip to the next paragraph. For encrypted root you=20 need to figure out if you can have /boot encrypted or not. For /boot to=20 be encrypted you need boot firmware with an embedded boot loader, such=20 as Coreboot/Libreboot. Otherwise you'll need to leave /boot unencrypted,=20 in this case create a separate partition for it. 100 MB should be=20 enough, make it type "Linux (83)". Your main partition will be where you install root (/). If you're going=20 to install a desktop this partition should be at least 15 GB. Make it=20 use the rest of your disk (after potentially making a boot partition) if=20 you don't know how large to make it. Make it type "Linux (83)" 7.1.4.1 Disk partitioning Before proceeding with partitioning you need to be sure about the device=20 name of the disk you're installing to. Example "/dev/sda" For partitioning there are several tools available, cfdisk is one. # cfdisk /dev/ If you went for unencrypted we'll refer to your root partition as=20 "". If you went for encrypted we'll refer to your encrypted root partition=20 as "". Any separate partition for /boot=20 will be referred to as "". Typical value: "sda1". 7.1.4.2 Disk encryption Skip this chapter if you're not doing encrypted root. Encrypt the encrypted partition with LUKS, using your favorite=20 cryptsetup invocation, for example: # cryptsetup -v --cipher serpent-xts-plain64 --key-size 512 --hash=20 whirlpool --use-random --verify-passphrase luksFormat=20 /dev/ Open the LUKS partition. You can verify its effect by doing "ls=20 /dev/mapper" before and after this command, on success a "guixsd" file=20 will appear. # cryptsetup luksOpen /dev/ guixsd We'll later refer to your mapped device (f.ex. "mapper/guixsd") as=20 "". 7.1.4.3 Filesystem and mount Make a filesystem, f.ex. ext4. For unencrypted root you can use the "-L"=20 flag, with a string argument, to create a label for later reference. # mkfs.ext4 /dev/ Mount it under /mnt # mount /dev/ /mnt Run this command to make /gnu/store copy-on-write, such that packages=20 added to it during the installation phase will be written to the target=20 disk rather than kept in memory. # deco start cow-store /mnt Create the /etc on your mounted partition # mkdir /mnt/etc 7.1.5 Preparing the configuration file Now we're going to prepare the configuration file. There are two example=20 configuration files available in the live image, located in=20 /etc/configuration. "bare-bones.scm" is a minimal configuration with no X11 display server. "desktop.scm" will install some desktop environments. Even if you want a desktop eventually you can start with=20 "bare-bones.scm"; and once you're able to boot properly add X11 and=20 desktop environments etc. to your configuration and reconfigure your=20 system. This will save you time if you run into problems and need to=20 install GuixSD again. # cp /etc/configuration/bare-bones.scm /mnt/etc/config.scm Now we'll open and modify the configuration file. The live image comes=20 with two text editors: GNU nano (see GNU nano Manual), and GNU Zile, an=20 Emacs clone. Open your configuration file with one of them. # zile /mnt/etc/config.scm We'll do the updates in turn from top to bottom. you'll recognize some=20 of the crypto steps from earlier, but note that previously we've been=20 setting up the partition for the installation. These steps gives=20 instructions to be used when booting the system. Adjust "host-name", "timezone" and "locale" to your wishes. If you're=20 going to change locale you should check what is available and exactly=20 how it is typed; close the editor or change virtual console=20 (Ctrl-Alt-F#), and run the command "locale -a". Update "device" in the bootloader field to "/dev/". This will=20 instruct the installation to install GRUB to the MBR of your disk. This=20 is fine even if you're going to use the boot loader in your boot=20 firmware, it will just be unused in this case. 7.1.5.1 Special configuration for encrypted root Skip this chapter if you're doing unencrypted root. For encrypted root setups we need to add some lines to the configuration=20 with instructions on how do decrypt your partition during boot. Add the=20 "mapped-devices" field below to your your operating-system declaration. (If that last sentence didn't make much sense: Insert the code snippet=20 below between the lines (bootloader ...) and (file-systems ...)) Make sure to update the following fields: "source", the device name of your encrypted partition. Example=20 "/dev/sda1" "target", a name you make up that will appear in /dev/mapper/ after=20 decryption. We'll later refer to this as "". Example=20 "guixsd". (mapped-devices (list (mapped-device (source "/dev/") (target "") (type luks-device-mapping)))) Moving on to the file-systems field, update these two fields: "device", set this value to "/dev/mapper/". Example=20 "/dev/mapper/guixsd" "title", change this value to "'device". (Makes the "device" field be=20 interpreted as a file name rather than a partition label name) *****TODO: Unencrypted /boot***** 7.1.5.2 Special configuration for unencrypted root Skip this chapter if you're doing encrypted root. In the file-systems field, update this field: "device", set this value to the label you made when you created the=20 filesystem. Example "my-root" 7.1.5.3 Finishing up the configuration And finally, update the values in the "users" field. "name", the username. "comment", you can set this to the name of the user. "home-directory", set this to "/home/". This concludes the updates to the configuration file and the preparation=20 for installation. 7.1.6 Installation What remains now is to actually install the system. First run this=20 command to get up to speed with the project's progress since this=20 installer was created. # guix pull Then run this command to initialize the system based on the=20 configuration file you've prepared. # guix system init /mnt/etc/config.scm /mnt This will copy all the necessary files, and install GRUB on /dev/,=20 unless you pass the --no-grub option. For more information, see Invoking=20 guix system. This command may trigger downloads or builds of missing=20 packages, which can take some time. Once that command has completed=E2=80=94and hopefully succeeded!=E2=80=94= you can run=20 reboot and boot into the new system. The root password in the new system=20 is initially empty; other users=E2=80=99 passwords need to be initialized= by=20 running the passwd command as root, unless your configuration specifies=20 otherwise (see user account passwords). Join us on #guix on the Freenode IRC network or on guix-devel@gnu.org to=20 share your experience=E2=80=94good or not so good. ADDENDUM #1 Manual steps to boot your fully encrypted system from an embedded GRUB. Press "c" in GRUB to enter command mode. First find the partition here which corresponds to your /dev/ from=20 earlier. For example "/dev/sda1" on GPT will be "ahci0,gpt1" # ls Now decrypt it, is the partition you found in the=20 previous step. Don't use quotes. # cryptomount Load GuixSD's GRUB configuration file # configfile (crypto0)/boot/grub/grub.cfg ADDENDUM #2 When you're ready to update the GRUB configuration file in your boot=20 firmware you can base them off of these examples. Values to update: "cryptomount" (there's one in both menu entries). "--root" flag, to point to "/dev/". Example=20 "/dev/mapper/guixsd". menuentry "GuixSD (current)" { cryptomount set root=3D(crypto0) set guix_system=3D/var/guix/profiles/system linux ${guix_system}/kernel/bzImage --root=3D/dev/=20 --system=3D${guix_system} --load=3D${guix_system}/boot initrd ${guix_system}/initrd } menuentry "GuixSD fallback" { cryptomount configfile (crypto0)/boot/grub/grub.cfg }