git.iko.soy/typeable/nixpkgs
on master help sign in
Merge pull request #49821 from DIzFer/profiles-documentation

Docs: Add chapter on Profiles

commit6f607b806d55f9fbaa67e12ad473ece36e81a497 authorJörg Thalheim <Mic92@users.noreply.github.com> dateWed 14 Nov 2018, 11:32 (8 years ago) parent4822b08bac8725
13 files changed+246
nixos/doc/manual/configuration/configuration.xml+1 nixos/doc/manual/configuration/profiles.xml+39 nixos/doc/manual/configuration/profiles/all-hardware.xml+20 nixos/doc/manual/configuration/profiles/base.xml+15 nixos/doc/manual/configuration/profiles/clone-config.xml+14 nixos/doc/manual/configuration/profiles/demo.xml+13 nixos/doc/manual/configuration/profiles/docker-container.xml+15 nixos/doc/manual/configuration/profiles/graphical.xml+21 nixos/doc/manual/configuration/profiles/hardened.xml+22 nixos/doc/manual/configuration/profiles/headless.xml+18 nixos/doc/manual/configuration/profiles/installation-device.xml+35 nixos/doc/manual/configuration/profiles/minimal.xml+17 nixos/doc/manual/configuration/profiles/qemu-guest.xml+16
nixos/doc/manual/configuration/configuration.xml+1
@@ -22,5 +22,6 @@
2222 <xi:include href="networking.xml" />
2323 <xi:include href="linux-kernel.xml" />
2424 <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
25+ <xi:include href="profiles.xml" />
2526<!-- Apache; libvirtd virtualisation -->
2627</part>
nixos/doc/manual/configuration/profiles.xmlnew file+39
@@ -0,0 +1,39 @@
1+<chapter xmlns="http://docbook.org/ns/docbook"
2+ xmlns:xlink="http://www.w3.org/1999/xlink"
3+ xmlns:xi="http://www.w3.org/2001/XInclude"
4+ version="5.0"
5+ xml:id="ch-profiles">
6+ <title>Profiles</title>
7+ <para>
8+ In some cases, it may be desirable to take advantage of commonly-used,
9+ predefined configurations provided by nixpkgs, but different from those that
10+ come as default. This is a role fulfilled by NixOS's Profiles, which come as
11+ files living in <filename>&lt;nixpkgs/nixos/modules/profiles&gt;</filename>.
12+ That is to say, expected usage is to add them to the imports list of your
13+ <filename>/etc/configuration.nix</filename> as such:
14+ </para>
15+ <programlisting>
16+ imports = [
17+ &lt;nixpkgs/nixos/modules/profiles/profile-name.nix&gt;
18+ ];
19+ </programlisting>
20+ <para>
21+ Even if some of these profiles seem only useful in the context of
22+ install media, many are actually intended to be used in real installs.
23+ </para>
24+ <para>
25+ What follows is a brief explanation on the purpose and use-case for each
26+ profile. Detailing each option configured by each one is out of scope.
27+ </para>
28+ <xi:include href="profiles/all-hardware.xml" />
29+ <xi:include href="profiles/base.xml" />
30+ <xi:include href="profiles/clone-config.xml" />
31+ <xi:include href="profiles/demo.xml" />
32+ <xi:include href="profiles/docker-container.xml" />
33+ <xi:include href="profiles/graphical.xml" />
34+ <xi:include href="profiles/hardened.xml" />
35+ <xi:include href="profiles/headless.xml" />
36+ <xi:include href="profiles/installation-device.xml" />
37+ <xi:include href="profiles/minimal.xml" />
38+ <xi:include href="profiles/qemu-guest.xml" />
39+</chapter>
nixos/doc/manual/configuration/profiles/all-hardware.xmlnew file+20
@@ -0,0 +1,20 @@
1+
2+<section xmlns="http://docbook.org/ns/docbook"
3+ xmlns:xlink="http://www.w3.org/1999/xlink"
4+ xmlns:xi="http://www.w3.org/2001/XInclude"
5+ version="5.0"
6+ xml:id="sec-profile-all-hardware">
7+ <title>All Hardware</title>
8+ <para>
9+ Enables all hardware supported by NixOS: i.e., all firmware is
10+ included, and all devices from which one may boot are enabled in the initrd.
11+ Its primary use is in the NixOS installation CDs.
12+ </para>
13+ <para>
14+ The enabled kernel modules include support for SATA and PATA, SCSI
15+ (partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and
16+ Hyper-V. Additionally, <xref linkend="opt-hardware.enableAllFirmware"/> is
17+ enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically
18+ installed.
19+ </para>
20+</section>
nixos/doc/manual/configuration/profiles/base.xmlnew file+15
@@ -0,0 +1,15 @@
1+
2+<section xmlns="http://docbook.org/ns/docbook"
3+ xmlns:xlink="http://www.w3.org/1999/xlink"
4+ xmlns:xi="http://www.w3.org/2001/XInclude"
5+ version="5.0"
6+ xml:id="sec-profile-base">
7+ <title>Base</title>
8+ <para>
9+ Defines the software packages included in the "minimal"
10+ installation CD. It installs several utilities useful in a simple recovery or
11+ install media, such as a text-mode web browser, and tools for manipulating
12+ block devices, networking, hardware diagnostics, and filesystems (with their
13+ respective kernel modules).
14+ </para>
15+</section>
nixos/doc/manual/configuration/profiles/clone-config.xmlnew file+14
@@ -0,0 +1,14 @@
1+
2+<section xmlns="http://docbook.org/ns/docbook"
3+ xmlns:xlink="http://www.w3.org/1999/xlink"
4+ xmlns:xi="http://www.w3.org/2001/XInclude"
5+ version="5.0"
6+ xml:id="sec-profile-clone-config">
7+ <title>Clone Config</title>
8+ <para>
9+ This profile is used in installer images.
10+ It provides an editable configuration.nix that imports all the modules that
11+ were also used when creating the image in the first place.
12+ As a result it allows users to edit and rebuild the live-system.
13+ </para>
14+</section>
nixos/doc/manual/configuration/profiles/demo.xmlnew file+13
@@ -0,0 +1,13 @@
1+
2+<section xmlns="http://docbook.org/ns/docbook"
3+ xmlns:xlink="http://www.w3.org/1999/xlink"
4+ xmlns:xi="http://www.w3.org/2001/XInclude"
5+ version="5.0"
6+ xml:id="sec-profile-demo">
7+ <title>Demo</title>
8+ <para>
9+ This profile just enables a <systemitem class="username">demo</systemitem> user, with password <literal>demo</literal>, uid <literal>1000</literal>, <systemitem class="groupname">wheel</systemitem>
10+ group and <link linkend="opt-services.xserver.displayManager.sddm.autoLogin">
11+ autologin in the SDDM display manager</link>.
12+ </para>
13+</section>
nixos/doc/manual/configuration/profiles/docker-container.xmlnew file+15
@@ -0,0 +1,15 @@
1+
2+<section xmlns="http://docbook.org/ns/docbook"
3+ xmlns:xlink="http://www.w3.org/1999/xlink"
4+ xmlns:xi="http://www.w3.org/2001/XInclude"
5+ version="5.0"
6+ xml:id="sec-profile-docker-container">
7+ <title>Docker Container</title>
8+ <para>
9+ This is the profile from which the Docker images are generated. It prepares a
10+ working system by importing the <link linkend="sec-profile-minimal">Minimal</link> and
11+ <link linkend="sec-profile-clone-config">Clone Config</link> profiles, and setting appropriate
12+ configuration options that are useful inside a container context, like
13+ <xref linkend="opt-boot.isContainer"/>.
14+ </para>
15+</section>
nixos/doc/manual/configuration/profiles/graphical.xmlnew file+21
@@ -0,0 +1,21 @@
1+
2+<section xmlns="http://docbook.org/ns/docbook"
3+ xmlns:xlink="http://www.w3.org/1999/xlink"
4+ xmlns:xi="http://www.w3.org/2001/XInclude"
5+ version="5.0"
6+ xml:id="sec-profile-graphical">
7+ <title>Graphical</title>
8+ <para>
9+ Defines a NixOS configuration with the Plasma 5 desktop. It's used by the
10+ graphical installation CD.
11+ </para>
12+ <para>
13+ It sets <xref linkend="opt-services.xserver.enable"/>,
14+ <xref linkend="opt-services.xserver.displayManager.sddm.enable"/>,
15+ <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> (
16+ <link linkend="opt-services.xserver.desktopManager.plasma5.enableQt4Support">
17+ without Qt4 Support</link>), and
18+ <xref linkend="opt-services.xserver.libinput.enable"/> to true. It also
19+ includes glxinfo and firefox in the system packages list.
20+ </para>
21+</section>
nixos/doc/manual/configuration/profiles/hardened.xmlnew file+22
@@ -0,0 +1,22 @@
1+
2+<section xmlns="http://docbook.org/ns/docbook"
3+ xmlns:xlink="http://www.w3.org/1999/xlink"
4+ xmlns:xi="http://www.w3.org/2001/XInclude"
5+ version="5.0"
6+ xml:id="sec-profile-hardened">
7+ <title>Hardened</title>
8+ <para>
9+ A profile with most (vanilla) hardening options enabled by default,
10+ potentially at the cost of features and performance.
11+ </para>
12+ <para>
13+ This includes a hardened kernel, and limiting the system information
14+ available to processes through the <filename>/sys</filename> and
15+ <filename>/proc</filename> filesystems. It also disables the User Namespaces
16+ feature of the kernel, which stops Nix from being able to build anything
17+ (this particular setting can be overriden via
18+ <xref linkend="opt-security.allowUserNamespaces"/>). See the <literal
19+ xlink:href="https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix">
20+ profile source</literal> for further detail on which settings are altered.
21+ </para>
22+</section>
nixos/doc/manual/configuration/profiles/headless.xmlnew file+18
@@ -0,0 +1,18 @@
1+
2+<section xmlns="http://docbook.org/ns/docbook"
3+ xmlns:xlink="http://www.w3.org/1999/xlink"
4+ xmlns:xi="http://www.w3.org/2001/XInclude"
5+ version="5.0"
6+ xml:id="sec-profile-headless">
7+ <title>Headless</title>
8+ <para>
9+ Common configuration for headless machines (e.g., Amazon EC2 instances).
10+ </para>
11+ <para>
12+ Disables <link linkend="opt-sound.enable">sound</link>,
13+ <link linkend="opt-boot.vesa">vesa</link>, serial consoles,
14+ <link linkend="opt-systemd.enableEmergencyMode">emergency mode</link>,
15+ <link linkend="opt-boot.loader.grub.splashImage">grub splash images</link> and
16+ configures the kernel to reboot automatically on panic.
17+ </para>
18+</section>
nixos/doc/manual/configuration/profiles/installation-device.xmlnew file+35
@@ -0,0 +1,35 @@
1+
2+<section xmlns="http://docbook.org/ns/docbook"
3+ xmlns:xlink="http://www.w3.org/1999/xlink"
4+ xmlns:xi="http://www.w3.org/2001/XInclude"
5+ version="5.0"
6+ xml:id="sec-profile-installation-device">
7+ <title>Installation Device</title>
8+ <para>
9+ Provides a basic configuration for installation devices like CDs. This means
10+ enabling hardware scans, using the <link linkend="sec-profile-clone-config">
11+ Clone Config profile</link> to guarantee
12+ <filename>/etc/nixos/configuration.nix</filename> exists (for
13+ <command>nixos-rebuild</command> to work), a copy of the Nixpkgs channel
14+ snapshot used to create the install media.
15+ </para>
16+ <para>
17+ Additionally, documentation for <link linkend="opt-documentation.enable">
18+ Nixpkgs</link> and <link linkend="opt-documentation.nixos.enable">NixOS
19+ </link> are forcefully enabled (to override the
20+ <link linkend="sec-profile-minimal">Minimal profile</link> preference); the
21+ NixOS manual is shown automatically on TTY 8, sudo and udisks are disabled.
22+ Autologin is enabled as root.
23+ </para>
24+ <para>
25+ A message is shown to the user to start a display manager if needed,
26+ ssh with <xref linkend="opt-services.openssh.permitRootLogin"/> are enabled (but
27+ doesn't autostart). WPA Supplicant is also enabled without autostart.
28+ </para>
29+ <para>
30+ Finally, vim is installed, root is set to not have a password, the kernel is
31+ made more silent for remote public IP installs, and several settings are
32+ tweaked so that the installer has a better chance of succeeding under
33+ low-memory environments.
34+ </para>
35+</section>
nixos/doc/manual/configuration/profiles/minimal.xmlnew file+17
@@ -0,0 +1,17 @@
1+
2+<section xmlns="http://docbook.org/ns/docbook"
3+ xmlns:xlink="http://www.w3.org/1999/xlink"
4+ xmlns:xi="http://www.w3.org/2001/XInclude"
5+ version="5.0"
6+ xml:id="sec-profile-minimal">
7+ <title>Minimal</title>
8+ <para>
9+ This profile defines a small NixOS configuration. It does not contain any
10+ graphical stuff. It's a very short file that enables
11+ <link linkend="opt-environment.noXlibs">noXlibs</link>, sets
12+ <link linkend="opt-i18n.supportedLocales">i18n.supportedLocales</link>
13+ to only support the user-selected locale,
14+ <link linkend="opt-documentation.enable">disables packages' documentation
15+ </link>, and <link linkend="opt-sound.enable">disables sound</link>.
16+ </para>
17+</section>
nixos/doc/manual/configuration/profiles/qemu-guest.xmlnew file+16
@@ -0,0 +1,16 @@
1+<section xmlns="http://docbook.org/ns/docbook"
2+ xmlns:xlink="http://www.w3.org/1999/xlink"
3+ xmlns:xi="http://www.w3.org/2001/XInclude"
4+ version="5.0"
5+ xml:id="sec-profile-qemu-guest">
6+ <title>QEMU Guest</title>
7+ <para>
8+ This profile contains common configuration for virtual machines running under
9+ QEMU (using virtio).
10+ </para>
11+ <para>
12+ It makes virtio modules available on the initrd, sets the system time from
13+ the hardware clock to work around a bug in qemu-kvm, and
14+ <link linkend="opt-security.rngd.enable">enables rngd</link>.
15+ </para>
16+</section>