doc: Provide more details about system installation.
* doc/guix.texi (System Installation): Turn all subsections into individual nodes. (Limitations): Update the number of packages. (Preparing for Installation)[Keyboard Layout, Networking, Disk Partitionning]: New subsections. Move the 'cow-store' thing to... (Proceeding with the Installation): ... here. Describe things in more detail. (Base Services): Add index entry for "keyboard layout". Co-authored-by: Petter <petter@mykolab.ch>.
This commit is contained in:
parent
c96ba2cf5e
commit
dedb8d5ece
doc
214
doc/guix.texi
214
doc/guix.texi
|
@ -5527,6 +5527,15 @@ link that follows: @pxref{Help,,, info, Info: An Introduction}. Hit
|
||||||
@kbd{l} afterwards to come back here.
|
@kbd{l} afterwards to come back here.
|
||||||
@end ifinfo
|
@end ifinfo
|
||||||
|
|
||||||
|
@menu
|
||||||
|
* Limitations:: What you can expect.
|
||||||
|
* USB Stick Installation:: Preparing the installation medium.
|
||||||
|
* Preparing for Installation:: Networking, partitioning, etc.
|
||||||
|
* Proceeding with the Installation:: The real thing.
|
||||||
|
* Building the Installation Image:: How this comes to be.
|
||||||
|
@end menu
|
||||||
|
|
||||||
|
@node Limitations
|
||||||
@subsection Limitations
|
@subsection Limitations
|
||||||
|
|
||||||
As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
|
As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
|
||||||
|
@ -5561,7 +5570,7 @@ Few system services are currently supported out-of-the-box
|
||||||
(@pxref{Services}).
|
(@pxref{Services}).
|
||||||
|
|
||||||
@item
|
@item
|
||||||
More than 2,000 packages are available, but you may
|
More than 3,000 packages are available, but you may
|
||||||
occasionally find that a useful package is missing.
|
occasionally find that a useful package is missing.
|
||||||
@end itemize
|
@end itemize
|
||||||
|
|
||||||
|
@ -5569,6 +5578,7 @@ You've been warned. But more than a disclaimer, this is an invitation
|
||||||
to report issues (and success stories!), and join us in improving it.
|
to report issues (and success stories!), and join us in improving it.
|
||||||
@xref{Contributing}, for more info.
|
@xref{Contributing}, for more info.
|
||||||
|
|
||||||
|
@node USB Stick Installation
|
||||||
@subsection USB Stick Installation
|
@subsection USB Stick Installation
|
||||||
|
|
||||||
An installation image for USB sticks can be downloaded from
|
An installation image for USB sticks can be downloaded from
|
||||||
|
@ -5613,6 +5623,7 @@ Once this is done, you should be able to reboot the system and boot from
|
||||||
the USB stick. The latter usually requires you to get in the BIOS' boot
|
the USB stick. The latter usually requires you to get in the BIOS' boot
|
||||||
menu, where you can choose to boot from the USB stick.
|
menu, where you can choose to boot from the USB stick.
|
||||||
|
|
||||||
|
@node Preparing for Installation
|
||||||
@subsection Preparing for Installation
|
@subsection Preparing for Installation
|
||||||
|
|
||||||
Once you have successfully booted the image on the USB stick, you should
|
Once you have successfully booted the image on the USB stick, you should
|
||||||
|
@ -5623,47 +5634,123 @@ Introduction}). The installation system runs the GPM mouse daemon,
|
||||||
which allows you to select text with the left mouse button and to paste
|
which allows you to select text with the left mouse button and to paste
|
||||||
it with the middle button.
|
it with the middle button.
|
||||||
|
|
||||||
To install the system, you would:
|
@subsubsection Keyboard Layout
|
||||||
|
|
||||||
@enumerate
|
@cindex keyboard layout
|
||||||
|
The installation image uses the US qwerty keyboard layout. If you want
|
||||||
@item
|
to change it, you can use the @command{loadkeys} command. For example,
|
||||||
Configure the network, by running:
|
the following command selects the Dvorak keyboard layout:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
ifconfig eno1 up && dhclient eno1
|
loadkeys dvorak
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
to get an automatically assigned IP address from the wired
|
See the files under @file{/run/current-system/profile/share/keymaps} for
|
||||||
network interface controller@footnote{
|
a list of available keyboard layouts. Run @command{man loadkeys} for
|
||||||
@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
|
more information.
|
||||||
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.
|
|
||||||
|
|
||||||
The system automatically loads drivers for your network interface
|
@subsubsection Networking
|
||||||
controllers.
|
|
||||||
|
Run the following command see what your network interfaces are called:
|
||||||
|
|
||||||
|
@example
|
||||||
|
ifconfig -a
|
||||||
|
@end example
|
||||||
|
|
||||||
|
@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
|
||||||
|
Wired interfaces have a name starting with @samp{e}; for example, the
|
||||||
|
interface corresponding to the first on-board Ethernet controller is
|
||||||
|
called @samp{eno1}. Wireless interfaces have a name starting with
|
||||||
|
@samp{w}, like @samp{w1p2s0}.
|
||||||
|
|
||||||
|
@table @asis
|
||||||
|
@item Wired connection
|
||||||
|
To configure a wired network run the following command, substituting
|
||||||
|
@var{interface} with the name of the wired interface you want to use.
|
||||||
|
|
||||||
|
@example
|
||||||
|
ifconfig @var{interface} up
|
||||||
|
@end example
|
||||||
|
|
||||||
|
@item Wireless connection
|
||||||
|
To configure wireless networking, you can create a configuration file
|
||||||
|
for the @command{wpa_supplicant} configuration tool (its location is not
|
||||||
|
important) using one of the available text editors such as
|
||||||
|
@command{zile}:
|
||||||
|
|
||||||
|
@example
|
||||||
|
zile wpa_supplicant.conf
|
||||||
|
@end example
|
||||||
|
|
||||||
|
As an example, the following stanza can go to this file and will work
|
||||||
|
for many wireless networks, provided you give the actual SSID and
|
||||||
|
passphrase for the network you are connecting to:
|
||||||
|
|
||||||
|
@example
|
||||||
|
network=@{
|
||||||
|
ssid=@var{my-ssid}
|
||||||
|
key_mgmt=WPA-PSK
|
||||||
|
psk="the network's secret passphrase"
|
||||||
|
@}
|
||||||
|
@end example
|
||||||
|
|
||||||
|
Start the wireless service and run it in the background with the
|
||||||
|
following command (substitute @var{interface} with the name of the
|
||||||
|
network interface you want to use):
|
||||||
|
|
||||||
|
@example
|
||||||
|
wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
|
||||||
|
@end example
|
||||||
|
|
||||||
|
Run @command{man wpa_supplication} for more information.
|
||||||
|
@end table
|
||||||
|
|
||||||
|
At this point, you need to acquire an IP address. On a network where IP
|
||||||
|
addresses are automatically assigned @i{via} DHCP, you can run:
|
||||||
|
|
||||||
|
@example
|
||||||
|
dhclient @var{interface}
|
||||||
|
@end example
|
||||||
|
|
||||||
|
Try to ping a server to see if networking is up and running:
|
||||||
|
|
||||||
|
@example
|
||||||
|
ping -c 3 gnu.org
|
||||||
|
@end example
|
||||||
|
|
||||||
Setting up network access is almost always a requirement because the
|
Setting up network access is almost always a requirement because the
|
||||||
image does not contain all the software and tools that may be needed.
|
image does not contain all the software and tools that may be needed.
|
||||||
|
|
||||||
@item
|
@subsubsection Disk Partitioning
|
||||||
Unless this has already been done, you must partition, and then format
|
|
||||||
the target partition.
|
Unless this has already been done, the next step is to partition, and
|
||||||
|
then format the target partition(s).
|
||||||
|
|
||||||
|
The installation image includes several partitioning tools, including
|
||||||
|
Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
|
||||||
|
@command{fdisk}, and @command{cfdisk}. Run it and set up your disk with
|
||||||
|
the partition layout you want:
|
||||||
|
|
||||||
|
@example
|
||||||
|
cfdisk
|
||||||
|
@end example
|
||||||
|
|
||||||
|
Once you are done partitioning the target hard disk drive, you have to
|
||||||
|
create a file system on the relevant partition(s)@footnote{Currently
|
||||||
|
GuixSD pretty much assumes an ext4 file system. In particular, code
|
||||||
|
that reads partition UUIDs and labels only works with ext4. This will
|
||||||
|
be fixed in the future.}.
|
||||||
|
|
||||||
Preferably, assign partitions a label so that you can easily and
|
Preferably, assign partitions a label so that you can easily and
|
||||||
reliably refer to them in @code{file-system} declarations (@pxref{File
|
reliably refer to them in @code{file-system} declarations (@pxref{File
|
||||||
Systems}). This is typically done using the @code{-L} option of
|
Systems}). This is typically done using the @code{-L} option of
|
||||||
@command{mkfs.ext4} and related commands.
|
@command{mkfs.ext4} and related commands. So, assuming the target root
|
||||||
|
partition lives at @file{/dev/sda1}, a file system with the label
|
||||||
|
@code{my-root} can be created with:
|
||||||
|
|
||||||
Be sure that your partition labels match the value of their respective
|
@example
|
||||||
@code{device} fields in your @code{file-system} configuration, if your
|
mkfs.ext4 -L my-root /dev/sda1
|
||||||
@code{file-system} configuration sets the value of @code{title} to
|
@end example
|
||||||
@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 FIXME: Uncomment this once GRUB fully supports encrypted roots.
|
||||||
@c A typical command sequence may be:
|
@c A typical command sequence may be:
|
||||||
|
@ -5676,37 +5763,66 @@ Configuration System}).
|
||||||
@c # mkfs.ext4 -L my-root /dev/mapper/my-partition
|
@c # mkfs.ext4 -L my-root /dev/mapper/my-partition
|
||||||
@c @end example
|
@c @end example
|
||||||
|
|
||||||
The installation image includes Parted (@pxref{Overview,,, parted, GNU
|
In addition to e2fsprogs, the suite of tools to manipulate
|
||||||
Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
|
ext2/ext3/ext4 file systems, the installation image includes
|
||||||
encryption, and e2fsprogs, the suite of tools to manipulate
|
Cryptsetup/LUKS for disk encryption.
|
||||||
ext2/ext3/ext4 file systems.
|
|
||||||
|
|
||||||
@item
|
Once that is done, mount the target root partition under @file{/mnt}
|
||||||
Once that is done, mount the target root partition under @file{/mnt}.
|
with a command like (again, assuming @file{/dev/sda1} is the root
|
||||||
|
partition):
|
||||||
@item
|
|
||||||
Lastly, run @code{herd start cow-store /mnt}.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
@end enumerate
|
|
||||||
|
|
||||||
|
@example
|
||||||
|
mount /dev/sda1 /mnt
|
||||||
|
@end example
|
||||||
|
|
||||||
|
@node Proceeding with the Installation
|
||||||
@subsection Proceeding with the Installation
|
@subsection Proceeding with the Installation
|
||||||
|
|
||||||
With the target partitions ready, you now have to edit a file and
|
With the target partitions ready and the target root mounted on
|
||||||
|
@file{/mnt}, we're ready to go. First, run:
|
||||||
|
|
||||||
|
@example
|
||||||
|
herd start cow-store /mnt
|
||||||
|
@end example
|
||||||
|
|
||||||
|
This makes @file{/gnu/store} copy-on-write, such that packages added to
|
||||||
|
it during the installation phase are written to the target disk rather
|
||||||
|
than kept in memory.
|
||||||
|
|
||||||
|
Next, you have to edit a file and
|
||||||
provide the declaration of the operating system to be installed. To
|
provide the declaration of the operating system to be installed. To
|
||||||
that end, the installation system comes with two text editors: GNU nano
|
that end, the installation system comes with two text editors: GNU nano
|
||||||
(@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
|
(@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
|
It is better to store that file on the target root file system, say, as
|
||||||
@file{/mnt/etc/config.scm}.
|
@file{/mnt/etc/config.scm}.
|
||||||
|
|
||||||
@xref{Using the Configuration System}, for examples of operating system
|
@xref{Using the Configuration System}, for an overview of the
|
||||||
configurations. These examples are available under
|
configuration file. The example configurations discussed in that
|
||||||
@file{/etc/configuration} in the installation image, so you can copy
|
section are available under @file{/etc/configuration} in the
|
||||||
them and use them as a starting point for your own configuration.
|
installation image. Thus, to get started with a system configuration
|
||||||
|
providing a graphical display server (a ``desktop'' system), you can run
|
||||||
|
something along these lines:
|
||||||
|
|
||||||
|
@example
|
||||||
|
# mkdir /mnt/etc
|
||||||
|
# cp /etc/configuration/desktop.scm /mnt/etc/config.scm
|
||||||
|
# zile /mnt/etc/config.scm
|
||||||
|
@end example
|
||||||
|
|
||||||
|
You should pay attention to what your configuration file contains, and
|
||||||
|
in particular:
|
||||||
|
|
||||||
|
@itemize
|
||||||
|
@item
|
||||||
|
Make sure the @code{grub-configuration} form refers to the device you
|
||||||
|
want to install GRUB on.
|
||||||
|
|
||||||
|
@item
|
||||||
|
Be sure that your partition labels match the value of their respective
|
||||||
|
@code{device} fields in your @code{file-system} configuration, assuming
|
||||||
|
your @code{file-system} configuration sets the value of @code{title} to
|
||||||
|
@code{'label}.
|
||||||
|
@end itemize
|
||||||
|
|
||||||
Once you are done preparing the configuration file, the new system must
|
Once you are done preparing the configuration file, the new system must
|
||||||
be initialized (remember that the target root file system is mounted
|
be initialized (remember that the target root file system is mounted
|
||||||
|
@ -5717,7 +5833,7 @@ guix system init /mnt/etc/config.scm /mnt
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
@noindent
|
@noindent
|
||||||
This will copy all the necessary files, and install GRUB on
|
This copies all the necessary files and installs GRUB on
|
||||||
@file{/dev/sdX}, unless you pass the @option{--no-grub} option. For
|
@file{/dev/sdX}, unless you pass the @option{--no-grub} option. For
|
||||||
more information, @pxref{Invoking guix system}. This command may trigger
|
more information, @pxref{Invoking guix system}. This command may trigger
|
||||||
downloads or builds of missing packages, which can take some time.
|
downloads or builds of missing packages, which can take some time.
|
||||||
|
@ -5733,6 +5849,7 @@ 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
|
@file{guix-devel@@gnu.org} to share your experience---good or not so
|
||||||
good.
|
good.
|
||||||
|
|
||||||
|
@node Building the Installation Image
|
||||||
@subsection Building the Installation Image
|
@subsection Building the Installation Image
|
||||||
|
|
||||||
The installation image described above was built using the @command{guix
|
The installation image described above was built using the @command{guix
|
||||||
|
@ -6844,6 +6961,7 @@ Run @var{udev}, which populates the @file{/dev} directory dynamically.
|
||||||
@end deffn
|
@end deffn
|
||||||
|
|
||||||
@deffn {Scheme Procedure} console-keymap-service @var{file}
|
@deffn {Scheme Procedure} console-keymap-service @var{file}
|
||||||
|
@cindex keyboard layout
|
||||||
Return a service to load console keymap from @var{file} using
|
Return a service to load console keymap from @var{file} using
|
||||||
@command{loadkeys} command.
|
@command{loadkeys} command.
|
||||||
@end deffn
|
@end deffn
|
||||||
|
|
Loading…
Reference in New Issue