diff options
Diffstat (limited to 'nixos/doc/manual/from_md/configuration')
13 files changed, 343 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml b/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml new file mode 100644 index 00000000000..4fa40d61966 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml @@ -0,0 +1,80 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-custom-packages"> + <title>Adding Custom Packages</title> + <para> + It’s possible that a package you need is not available in NixOS. In + that case, you can do two things. First, you can clone the Nixpkgs + repository, add the package to your clone, and (optionally) submit a + patch or pull request to have it accepted into the main Nixpkgs + repository. This is described in detail in the + <link xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs + manual</link>. In short, you clone Nixpkgs: + </para> + <programlisting> +$ git clone https://github.com/NixOS/nixpkgs +$ cd nixpkgs +</programlisting> + <para> + Then you write and test the package as described in the Nixpkgs + manual. Finally, you add it to + <xref linkend="opt-environment.systemPackages" />, e.g. + </para> + <programlisting language="bash"> +environment.systemPackages = [ pkgs.my-package ]; +</programlisting> + <para> + and you run <literal>nixos-rebuild</literal>, specifying your own + Nixpkgs tree: + </para> + <programlisting> +# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs +</programlisting> + <para> + The second possibility is to add the package outside of the Nixpkgs + tree. For instance, here is how you specify a build of the + <link xlink:href="https://www.gnu.org/software/hello/">GNU + Hello</link> package directly in + <literal>configuration.nix</literal>: + </para> + <programlisting language="bash"> +environment.systemPackages = + let + my-hello = with pkgs; stdenv.mkDerivation rec { + name = "hello-2.8"; + src = fetchurl { + url = "mirror://gnu/hello/${name}.tar.gz"; + sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; + }; + }; + in + [ my-hello ]; +</programlisting> + <para> + Of course, you can also move the definition of + <literal>my-hello</literal> into a separate Nix expression, e.g. + </para> + <programlisting language="bash"> +environment.systemPackages = [ (import ./my-hello.nix) ]; +</programlisting> + <para> + where <literal>my-hello.nix</literal> contains: + </para> + <programlisting language="bash"> +with import <nixpkgs> {}; # bring all of Nixpkgs into scope + +stdenv.mkDerivation rec { + name = "hello-2.8"; + src = fetchurl { + url = "mirror://gnu/hello/${name}.tar.gz"; + sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; + }; +} +</programlisting> + <para> + This allows testing the package easily: + </para> + <programlisting> +$ nix-build my-hello.nix +$ ./result/bin/hello +Hello, world! +</programlisting> +</section> diff --git a/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml b/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml new file mode 100644 index 00000000000..f78b5dc5460 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml @@ -0,0 +1,90 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-customising-packages"> + <title>Customising Packages</title> + <para> + Some packages in Nixpkgs have options to enable or disable optional + functionality or change other aspects of the package. For instance, + the Firefox wrapper package (which provides Firefox with a set of + plugins such as the Adobe Flash player) has an option to enable the + Google Talk plugin. It can be set in + <literal>configuration.nix</literal> as follows: + <literal>nixpkgs.config.firefox.enableGoogleTalkPlugin = true;</literal> + </para> + <warning> + <para> + Unfortunately, Nixpkgs currently lacks a way to query available + configuration options. + </para> + </warning> + <para> + Apart from high-level options, it’s possible to tweak a package in + almost arbitrary ways, such as changing or disabling dependencies of + a package. For instance, the Emacs package in Nixpkgs by default has + a dependency on GTK 2. If you want to build it against GTK 3, you + can specify that as follows: + </para> + <programlisting language="bash"> +environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; +</programlisting> + <para> + The function <literal>override</literal> performs the call to the + Nix function that produces Emacs, with the original arguments + amended by the set of arguments specified by you. So here the + function argument <literal>gtk</literal> gets the value + <literal>pkgs.gtk3</literal>, causing Emacs to depend on GTK 3. (The + parentheses are necessary because in Nix, function application binds + more weakly than list construction, so without them, + <xref linkend="opt-environment.systemPackages" /> would be a list + with two elements.) + </para> + <para> + Even greater customisation is possible using the function + <literal>overrideAttrs</literal>. While the + <literal>override</literal> mechanism above overrides the arguments + of a package function, <literal>overrideAttrs</literal> allows + changing the <emphasis>attributes</emphasis> passed to + <literal>mkDerivation</literal>. This permits changing any aspect of + the package, such as the source code. For instance, if you want to + override the source code of Emacs, you can say: + </para> + <programlisting language="bash"> +environment.systemPackages = [ + (pkgs.emacs.overrideAttrs (oldAttrs: { + name = "emacs-25.0-pre"; + src = /path/to/my/emacs/tree; + })) +]; +</programlisting> + <para> + Here, <literal>overrideAttrs</literal> takes the Nix derivation + specified by <literal>pkgs.emacs</literal> and produces a new + derivation in which the original’s <literal>name</literal> and + <literal>src</literal> attribute have been replaced by the given + values by re-calling <literal>stdenv.mkDerivation</literal>. The + original attributes are accessible via the function argument, which + is conventionally named <literal>oldAttrs</literal>. + </para> + <para> + The overrides shown above are not global. They do not affect the + original package; other packages in Nixpkgs continue to depend on + the original rather than the customised package. This means that if + another package in your system depends on the original package, you + end up with two instances of the package. If you want to have + everything depend on your customised instance, you can apply a + <emphasis>global</emphasis> override as follows: + </para> + <programlisting language="bash"> +nixpkgs.config.packageOverrides = pkgs: + { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; }; + }; +</programlisting> + <para> + The effect of this definition is essentially equivalent to modifying + the <literal>emacs</literal> attribute in the Nixpkgs source tree. + Any package in Nixpkgs that depends on <literal>emacs</literal> will + be passed your customised instance. (However, the value + <literal>pkgs.emacs</literal> in + <literal>nixpkgs.config.packageOverrides</literal> refers to the + original rather than overridden instance, to prevent an infinite + recursion.) + </para> +</section> diff --git a/nixos/doc/manual/from_md/configuration/profiles/all-hardware.section.xml b/nixos/doc/manual/from_md/configuration/profiles/all-hardware.section.xml new file mode 100644 index 00000000000..43ac5edea7f --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/profiles/all-hardware.section.xml @@ -0,0 +1,15 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-profile-all-hardware"> + <title>All Hardware</title> + <para> + Enables all hardware supported by NixOS: i.e., all firmware is + included, and all devices from which one may boot are enabled in the + initrd. Its primary use is in the NixOS installation CDs. + </para> + <para> + The enabled kernel modules include support for SATA and PATA, SCSI + (partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), + VMware, and Hyper-V. Additionally, + <xref linkend="opt-hardware.enableAllFirmware" /> is enabled, and + the firmware for the ZyDAS ZD1211 chipset is specifically installed. + </para> +</section> diff --git a/nixos/doc/manual/from_md/configuration/profiles/base.section.xml b/nixos/doc/manual/from_md/configuration/profiles/base.section.xml new file mode 100644 index 00000000000..83d35bd2867 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/profiles/base.section.xml @@ -0,0 +1,10 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-profile-base"> + <title>Base</title> + <para> + Defines the software packages included in the <quote>minimal</quote> + installation CD. It installs several utilities useful in a simple + recovery or install media, such as a text-mode web browser, and + tools for manipulating block devices, networking, hardware + diagnostics, and filesystems (with their respective kernel modules). + </para> +</section> diff --git a/nixos/doc/manual/from_md/configuration/profiles/clone-config.section.xml b/nixos/doc/manual/from_md/configuration/profiles/clone-config.section.xml new file mode 100644 index 00000000000..9430b49ea33 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/profiles/clone-config.section.xml @@ -0,0 +1,16 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-profile-clone-config"> + <title>Clone Config</title> + <para> + This profile is used in installer images. It provides an editable + configuration.nix that imports all the modules that were also used + when creating the image in the first place. As a result it allows + users to edit and rebuild the live-system. + </para> + <para> + On images where the installation media also becomes an installation + target, copying over <literal>configuration.nix</literal> should be + disabled by setting <literal>installer.cloneConfig</literal> to + <literal>false</literal>. For example, this is done in + <literal>sd-image-aarch64-installer.nix</literal>. + </para> +</section> diff --git a/nixos/doc/manual/from_md/configuration/profiles/demo.section.xml b/nixos/doc/manual/from_md/configuration/profiles/demo.section.xml new file mode 100644 index 00000000000..09c2680a106 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/profiles/demo.section.xml @@ -0,0 +1,10 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-profile-demo"> + <title>Demo</title> + <para> + This profile just enables a <literal>demo</literal> user, with + password <literal>demo</literal>, uid <literal>1000</literal>, + <literal>wheel</literal> group and + <link linkend="opt-services.xserver.displayManager.autoLogin">autologin + in the SDDM display manager</link>. + </para> +</section> diff --git a/nixos/doc/manual/from_md/configuration/profiles/docker-container.section.xml b/nixos/doc/manual/from_md/configuration/profiles/docker-container.section.xml new file mode 100644 index 00000000000..97c2a92dcab --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/profiles/docker-container.section.xml @@ -0,0 +1,12 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-profile-docker-container"> + <title>Docker Container</title> + <para> + This is the profile from which the Docker images are generated. It + prepares a working system by importing the + <link linkend="sec-profile-minimal">Minimal</link> and + <link linkend="sec-profile-clone-config">Clone Config</link> + profiles, and setting appropriate configuration options that are + useful inside a container context, like + <xref linkend="opt-boot.isContainer" />. + </para> +</section> diff --git a/nixos/doc/manual/from_md/configuration/profiles/graphical.section.xml b/nixos/doc/manual/from_md/configuration/profiles/graphical.section.xml new file mode 100644 index 00000000000..1b109519d43 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/profiles/graphical.section.xml @@ -0,0 +1,14 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-profile-graphical"> + <title>Graphical</title> + <para> + Defines a NixOS configuration with the Plasma 5 desktop. It’s used + by the graphical installation CD. + </para> + <para> + It sets <xref linkend="opt-services.xserver.enable" />, + <xref linkend="opt-services.xserver.displayManager.sddm.enable" />, + <xref linkend="opt-services.xserver.desktopManager.plasma5.enable" />, + and <xref linkend="opt-services.xserver.libinput.enable" /> to true. + It also includes glxinfo and firefox in the system packages list. + </para> +</section> diff --git a/nixos/doc/manual/from_md/configuration/profiles/hardened.section.xml b/nixos/doc/manual/from_md/configuration/profiles/hardened.section.xml new file mode 100644 index 00000000000..44c11786d94 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/profiles/hardened.section.xml @@ -0,0 +1,25 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-profile-hardened"> + <title>Hardened</title> + <para> + A profile with most (vanilla) hardening options enabled by default, + potentially at the cost of stability, features and performance. + </para> + <para> + This includes a hardened kernel, and limiting the system information + available to processes through the <literal>/sys</literal> and + <literal>/proc</literal> filesystems. It also disables the User + Namespaces feature of the kernel, which stops Nix from being able to + build anything (this particular setting can be overriden via + <xref linkend="opt-security.allowUserNamespaces" />). See the + <link xlink:href="https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix">profile + source</link> for further detail on which settings are altered. + </para> + <warning> + <para> + This profile enables options that are known to affect system + stability. If you experience any stability issues when using the + profile, try disabling it. If you report an issue and use this + profile, always mention that you do. + </para> + </warning> +</section> diff --git a/nixos/doc/manual/from_md/configuration/profiles/headless.section.xml b/nixos/doc/manual/from_md/configuration/profiles/headless.section.xml new file mode 100644 index 00000000000..0910b9ffaad --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/profiles/headless.section.xml @@ -0,0 +1,15 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-profile-headless"> + <title>Headless</title> + <para> + Common configuration for headless machines (e.g., Amazon EC2 + instances). + </para> + <para> + Disables <link linkend="opt-sound.enable">sound</link>, + <link linkend="opt-boot.vesa">vesa</link>, serial consoles, + <link linkend="opt-systemd.enableEmergencyMode">emergency + mode</link>, <link linkend="opt-boot.loader.grub.splashImage">grub + splash images</link> and configures the kernel to reboot + automatically on panic. + </para> +</section> diff --git a/nixos/doc/manual/from_md/configuration/profiles/installation-device.section.xml b/nixos/doc/manual/from_md/configuration/profiles/installation-device.section.xml new file mode 100644 index 00000000000..837e69df06e --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/profiles/installation-device.section.xml @@ -0,0 +1,32 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-profile-installation-device"> + <title>Installation Device</title> + <para> + Provides a basic configuration for installation devices like CDs. + This enables redistributable firmware, includes the + <link linkend="sec-profile-clone-config">Clone Config profile</link> + and a copy of the Nixpkgs channel, so + <literal>nixos-install</literal> works out of the box. + </para> + <para> + Documentation for + <link linkend="opt-documentation.enable">Nixpkgs</link> and + <link linkend="opt-documentation.nixos.enable">NixOS</link> are + forcefully enabled (to override the + <link linkend="sec-profile-minimal">Minimal profile</link> + preference); the NixOS manual is shown automatically on TTY 8, + udisks is disabled. Autologin is enabled as <literal>nixos</literal> + user, while passwordless login as both <literal>root</literal> and + <literal>nixos</literal> is possible. Passwordless + <literal>sudo</literal> is enabled too. + <link linkend="opt-networking.wireless.enable">wpa_supplicant</link> + is enabled, but configured to not autostart. + </para> + <para> + It is explained how to login, start the ssh server, and if + available, how to start the display manager. + </para> + <para> + Several settings are tweaked so that the installer has a better + chance of succeeding under low-memory environments. + </para> +</section> diff --git a/nixos/doc/manual/from_md/configuration/profiles/minimal.section.xml b/nixos/doc/manual/from_md/configuration/profiles/minimal.section.xml new file mode 100644 index 00000000000..a3fe30357df --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/profiles/minimal.section.xml @@ -0,0 +1,13 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-profile-minimal"> + <title>Minimal</title> + <para> + This profile defines a small NixOS configuration. It does not + contain any graphical stuff. It’s a very short file that enables + <link linkend="opt-environment.noXlibs">noXlibs</link>, sets + <xref linkend="opt-i18n.supportedLocales" /> to only support the + user-selected locale, + <link linkend="opt-documentation.enable">disables packages’ + documentation</link>, and <link linkend="opt-sound.enable">disables + sound</link>. + </para> +</section> diff --git a/nixos/doc/manual/from_md/configuration/profiles/qemu-guest.section.xml b/nixos/doc/manual/from_md/configuration/profiles/qemu-guest.section.xml new file mode 100644 index 00000000000..f33464f9db4 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/profiles/qemu-guest.section.xml @@ -0,0 +1,11 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-profile-qemu-guest"> + <title>QEMU Guest</title> + <para> + This profile contains common configuration for virtual machines + running under QEMU (using virtio). + </para> + <para> + It makes virtio modules available on the initrd and sets the system + time from the hardware clock to work around a bug in qemu-kvm. + </para> +</section> |