Re: Review of installation manual draft

[Ludovic Courtès]

Hi Petter,

Thanks a lot for the additions to the manual!

There was a lot more than I expected.  ;-)  For now, I’ve focused on the
improvements to the “System Installation” section, leading to commit
dedb8d5.

It turned out to be more work than I expected because I had to find out
what the differences were (some paragraphs had been moved to a single
line, which made it hard to spot the differences), and then ended up
doing a few things differently to preserve consistency.

In the future, it would be awesome if you could send more focused
patches and make sure the diffs don’t show unrelated “noise.”

Petter  skribis:

> +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.
> +
> +@table @asis
> +@item @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.
> +
> +@item @samp{timezone}
> +This value must match a supported timezone exactly. To find the value you 
> need here you can run the command
> +@example
> +tzselect
> +@end 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.
> +
> +@item @samp{locale}
> +This value must match a supported locale exactly. To get a list of supported 
> locales and their typing run the command
> +@example
> +ls /run/current-system/locale/@var{X.Y}
> +@end @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.
> +
> +@item @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.
> +@end table

I did not include this as is because I think most of it is redundant
with (or should be covered by) the “operating-system Reference” section.

I have not yet integrated the bits about setting up an encrypted root
etc. because I first want the bits below to be fixed in the code.

> +@subsection Booting a fully encrypted system
> +
> +@emph{This 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.

It’s not clear to me how much of it is specific to Coreboot/Libreboot.
It seems like it could equally well work when GRUB is spawned by a
random proprietary BIOS no?

> +@table @asis
> +@item Manual steps to boot your fully encrypted system
> +Press @kbd{c} in GRUB to enter command mode.

Seems to me that GuixSD should automatically DTRT when installing on an
encrypted root file system.  See .

> +menuentry "GuixSD (current)" @{
> +  cryptomount @var{grub-partition}
> +  set root=(crypto0)
> +  set guix_system=/var/guix/profiles/system
> +  linux  $@{guix_system@}/kernel/bzImage --root=@var{your-root-partition} 
> --system=$@{guix_system@} --load=$@{guix_system@}/boot
> +  initrd $@{guix_system@}/initrd
> +@}

I think this sort of answers the above bug report, no?

Thanks a lot for your feedback on this!

Ludo’.

Re: Review of installation manual draft

[Petter]

Hi Ludo,

Thanks for looking at it.

On 2016-02-10 22:16, l...@gnu.org wrote:

Hi Petter,

Thanks a lot for the additions to the manual!

There was a lot more than I expected.  ;-)  For now, I’ve focused on 
the

improvements to the “System Installation” section, leading to commit
dedb8d5.

It turned out to be more work than I expected because I had to find out
what the differences were (some paragraphs had been moved to a single
line, which made it hard to spot the differences), and then ended up
doing a few things differently to preserve consistency.

In the future, it would be awesome if you could send more focused
patches and make sure the diffs don’t show unrelated “noise.”


I'm sorry that it caused you extra work! For the record, this wasn't 
intended as a patch. We'd been working on this for a little while and 
wanted to get some feedback on particuarly the general direction before 
going any further. With a patch proposal i would have been more careful 
with noise etc.. This was really just a quick translation into guix.texi 
as requested. Maybe it would have been better if you had reviewed the 
link initially provided instead, as this was clearly not a patch.



Petter  skribis:

+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.

+
+@table @asis
+@item @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.

+
+@item @samp{timezone}
+This value must match a supported timezone exactly. To find the value 
you need here you can run the command

+@example
+tzselect
+@end 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.

+
+@item @samp{locale}
+This value must match a supported locale exactly. To get a list of 
supported locales and their typing run the command

+@example
+ls /run/current-system/locale/@var{X.Y}
+@end @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.

+
+@item @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.

+@end table


I did not include this as is because I think most of it is redundant
with (or should be covered by) the “operating-system Reference” 
section.


Ok. Well, this started as a standalone guide for libreboot.org. And the 
general idea was to guide the user through the entire installation 
process. Also there have been a few issues with locale on IRC, like 
specifying a locale that's not supported.



I have not yet integrated the bits about setting up an encrypted root
etc. because I first want the bits below to be fixed in the code.


+@subsection Booting a fully encrypted system
+
+@emph{This 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.


It’s not clear to me how much of it is specific to Coreboot/Libreboot.
It seems like it could equally well work when GRUB is spawned by a
random proprietary BIOS no?


Yes, these are GRUB specific instructions, not Coreboot/Libreboot. These 
projects are used as examples.


This should be good for any system that can start GRUB without /boot 
access. I have only tried on Libreboot, which load the crypto modules 
automatically. Other systems may not do this and these modules would 
need to be loaded manually in this case. That's the only thing i can 
think of that could be different.



+@table @asis
+@item Manual steps to boot your fully encrypted system
+Press @kbd{c} in GRUB to enter command mode.


Seems to me that GuixSD should automatically DTRT when installing on an
encrypted root file system.  See .


+menuentry "GuixSD (current)" @{
+  cryptomount @var{grub-partition}
+  set root=(crypto0)
+  set guix_system=/var/guix/profiles/system
+  linux  $@{guix_system@}/kernel/bzImage 
--root=@var{your-root-partition} --system=$@{guix_system@} 
--load=$@{guix_system@}/boot

+  initrd $@{guix_system@}/initrd

Re: Review of installation manual draft

[Petter]

Hi Ludo,

Attached is a diff against guix.texi. I'm very new to texinfo so there 
may be some silly mistakes.


Petter

On 2016-01-31 10:28, l...@gnu.org wrote:

HI Petter,

Thanks a lot for working on it!  I’m at FOSDEM now but I hope to review
while on the train later today.

It would be easier for me if it were a diff against guix.texi.  Do you
think you could do that?  That would be awesome.  (If not I’ll comment
on what you sent.)

Ludo’.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:
+@subsubsection Keyboard
 
-@enumerate
+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}.
+@example
+loadkeys @var{layout}
+@end example
 
-@item
-Configure the network, by running:
+@subsubsection 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 controller@footnote{
-@c 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
-@command{ifconfig -a} to list all the available network interfaces.},
-or using the @command{ifconfig} command.
+@ftable @asis
+@item Wired connection
+To configure a wired network run the following command, substituting @var{network-interface} with the wired interface you want to use.
+@example
+ifconfig @var{network-interface} up
+@end example
 
-The system automatically loads drivers for your network interface
-controllers.
+@item 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)
+@example
+zile wpa_supplicant.conf
+@end 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:
+@example
+network=@{
+ssid=@var{network_name}
+key_mgmt=WPA-PSK
+psk=@var{network_password}
+@}
+@end 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.
+@example
+wpa_supplicant -c wpa_supplicant.conf -i @var{network-interface} -B
+@end example
+@end ftable
 
-@item
-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
-@command{mkfs.ext4} and related commands.
-
-Be sure that your partition labels match the value of their respective
-@code{device} fields in your @code{file-system} configuration, if your
-@code{file-system} configuration sets the value of @code{title} to
-@code{'label}, as do the example configurations found on the USB
-installation image under @file{/etc/configuration} (@pxref{Using the
-Configuration System}).
-
-@c FIXME: Uncomment this once GRUB fully supports encrypted roots.
-@c A typical command sequence may be:
-@c
-@c @example
-@c # fdisk /dev/sdX
-@c @dots{} Create partitions etc.@dots{}
-@c # cryptsetup luksFormat /dev/sdX1
-@c # cryptsetup open --type luks /dev/sdX1 my-partition
-@c # mkfs.ext4 -L my-root /dev/mapper/my-partition
-@c @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
+@example
+dhclient @var{network-interface}
+@end example
 
-@item
-Once that is done, mount the target root partition under @file{/mnt}.
+Try to ping a 

Re: Review of installation manual draft

[Petter]

Hi Ludo,

Yes, i should be able to do that. I don't know texinfo yet but i'm 
learning it now.


Petter

Re: Review of installation manual draft

[Ludovic Courtès]

HI Petter,

Thanks a lot for working on it!  I’m at FOSDEM now but I hope to review
while on the train later today.

It would be easier for me if it were a diff against guix.texi.  Do you
think you could do that?  That would be awesome.  (If not I’ll comment
on what you sent.)

Ludo’.