b12f/nixpkgs
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

nixos: nixos/doc/manual/configuration/config-file.xml to CommonMark

Browse source
This commit is contained in:
Bobby Rong 2021-07-01 21:13:13 +08:00
parent bf413e4630
commit 07ca0e237e
4 changed files with 407 additions and 217 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

175
nixos/doc/manual/configuration/config-file.section.md Normal file
View file

@ -0,0 +1,175 @@
# NixOS Configuration File {#sec-configuration-file}
The NixOS configuration file generally looks like this:
```nix
{ config, pkgs, ... }:
{ option definitions
}
```
The first line (`{ config, pkgs, ... }:`) denotes that this is actually
a function that takes at least the two arguments `config` and `pkgs`.
(These are explained later, in chapter [](#sec-writing-modules)) The
function returns a *set* of option definitions (`{ ... }`).
These definitions have the form `name = value`, where `name` is the
name of an option and `value` is its value. For example,
```nix
{ config, pkgs, ... }:
{ services.httpd.enable = true;
services.httpd.adminAddr = "alice@example.org";
services.httpd.virtualHosts.localhost.documentRoot = "/webroot";
}
```
defines a configuration with three option definitions that together
enable the Apache HTTP Server with `/webroot` as the document root.
Sets can be nested, and in fact dots in option names are shorthand for
defining a set containing another set. For instance,
[`services.httpd.enable`](options.html#opt-services.httpd.enable) defines a set named
`services` that contains a set named `httpd`, which in turn contains an
option definition named `enable` with value `true`. This means that the
example above can also be written as:
```nix
{ config, pkgs, ... }:
{ services = {
httpd = {
enable = true;
adminAddr = "alice@example.org";
virtualHosts = {
localhost = {
documentRoot = "/webroot";
};
};
};
};
}
```
which may be more convenient if you have lots of option definitions that
share the same prefix (such as `services.httpd`).
NixOS checks your option definitions for correctness. For instance, if
you try to define an option that doesn't exist (that is, doesn't have a
corresponding *option declaration*), `nixos-rebuild` will give an error
like:
```plain
The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
```
Likewise, values in option definitions must have a correct type. For
instance, `services.httpd.enable` must be a Boolean (`true` or `false`).
Trying to give it a value of another type, such as a string, will cause
an error:
```plain
The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
```
Options have various types of values. The most important are:
Strings
: Strings are enclosed in double quotes, e.g.
```nix
networking.hostName = "dexter";
```
Special characters can be escaped by prefixing them with a backslash
(e.g. `\"`).
Multi-line strings can be enclosed in *double single quotes*, e.g.
```nix
networking.extraHosts =
''
127.0.0.2 other-localhost
10.0.0.1 server
'';
```
The main difference is that it strips from each line a number of
spaces equal to the minimal indentation of the string as a whole
(disregarding the indentation of empty lines), and that characters
like `"` and `\` are not special (making it more convenient for
including things like shell code). See more info about this in the
Nix manual [here](https://nixos.org/nix/manual/#ssec-values).
Booleans
: These can be `true` or `false`, e.g.
```nix
networking.firewall.enable = true;
networking.firewall.allowPing = false;
```
Integers
: For example,
```nix
boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;
```
(Note that here the attribute name `net.ipv4.tcp_keepalive_time` is
enclosed in quotes to prevent it from being interpreted as a set
named `net` containing a set named `ipv4`, and so on. This is
because it's not a NixOS option but the literal name of a Linux
kernel setting.)
Sets
: Sets were introduced above. They are name/value pairs enclosed in
braces, as in the option definition
```nix
fileSystems."/boot" =
{ device = "/dev/sda1";
fsType = "ext4";
options = [ "rw" "data=ordered" "relatime" ];
};
```
Lists
: The important thing to note about lists is that list elements are
separated by whitespace, like this:
```nix
boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
```
List elements can be any other type, e.g. sets:
```nix
swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
```
Packages
: Usually, the packages you need are already part of the Nix Packages
collection, which is a set that can be accessed through the function
argument `pkgs`. Typical uses:
```nix
environment.systemPackages =
[ pkgs.thunderbird
pkgs.emacs
];
services.postgresql.package = pkgs.postgresql_10;
```
The latter option definition changes the default PostgreSQL package
used by NixOS's PostgreSQL service to 10.x. For more information on
packages, including how to add new ones, see
[](#sec-custom-packages).

216
nixos/doc/manual/configuration/config-file.xml
View file

@ -1,216 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-configuration-file">
<title>NixOS Configuration File</title>
<para>
The NixOS configuration file generally looks like this:
<programlisting>
{ config, pkgs, ... }:
{ <replaceable>option definitions</replaceable>
}
</programlisting>
The first line (<literal>{ config, pkgs, ... }:</literal>) denotes that this
is actually a function that takes at least the two arguments
<varname>config</varname> and <varname>pkgs</varname>. (These are explained
later, in chapter <xref linkend="sec-writing-modules" />) The function returns
a <emphasis>set</emphasis> of option definitions (<literal>{
<replaceable>...</replaceable> }</literal>). These definitions have the form
<literal><replaceable>name</replaceable> =
<replaceable>value</replaceable></literal>, where
<replaceable>name</replaceable> is the name of an option and
<replaceable>value</replaceable> is its value. For example,
<programlisting>
{ config, pkgs, ... }:
{ <xref linkend="opt-services.httpd.enable"/> = true;
<xref linkend="opt-services.httpd.adminAddr"/> = "alice@example.org";
<link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.localhost.documentRoot</link> = "/webroot";
}
</programlisting>
defines a configuration with three option definitions that together enable
the Apache HTTP Server with <filename>/webroot</filename> as the document
root.
</para>
<para>
Sets can be nested, and in fact dots in option names are shorthand for
defining a set containing another set. For instance,
<xref linkend="opt-services.httpd.enable"/> defines a set named
<varname>services</varname> that contains a set named
<varname>httpd</varname>, which in turn contains an option definition named
<varname>enable</varname> with value <literal>true</literal>. This means that
the example above can also be written as:
<programlisting>
{ config, pkgs, ... }:
{ services = {
httpd = {
enable = true;
adminAddr = "alice@example.org";
virtualHosts = {
localhost = {
documentRoot = "/webroot";
};
};
};
};
}
</programlisting>
which may be more convenient if you have lots of option definitions that
share the same prefix (such as <literal>services.httpd</literal>).
</para>
<para>
NixOS checks your option definitions for correctness. For instance, if you
try to define an option that doesn’t exist (that is, doesn’t have a
corresponding <emphasis>option declaration</emphasis>),
<command>nixos-rebuild</command> will give an error like:
<screen>
The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
</screen>
Likewise, values in option definitions must have a correct type. For
instance, <option>services.httpd.enable</option> must be a Boolean
(<literal>true</literal> or <literal>false</literal>). Trying to give it a
value of another type, such as a string, will cause an error:
<screen>
The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
</screen>
</para>
<para>
Options have various types of values. The most important are:
<variablelist>
<varlistentry>
<term>
Strings
</term>
<listitem>
<para>
Strings are enclosed in double quotes, e.g.
<programlisting>
<xref linkend="opt-networking.hostName"/> = "dexter";
</programlisting>
Special characters can be escaped by prefixing them with a backslash
(e.g. <literal>\"</literal>).
</para>
<para>
Multi-line strings can be enclosed in <emphasis>double single
quotes</emphasis>, e.g.
<programlisting>
<xref linkend="opt-networking.extraHosts"/> =
''
127.0.0.2 other-localhost
10.0.0.1 server
'';
</programlisting>
The main difference is that it strips from each line a number of spaces
equal to the minimal indentation of the string as a whole (disregarding
the indentation of empty lines), and that characters like
<literal>"</literal> and <literal>\</literal> are not special (making it
more convenient for including things like shell code). See more info
about this in the Nix manual
<link
xlink:href="https://nixos.org/nix/manual/#ssec-values">here</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Booleans
</term>
<listitem>
<para>
These can be <literal>true</literal> or <literal>false</literal>, e.g.
<programlisting>
<xref linkend="opt-networking.firewall.enable"/> = true;
<xref linkend="opt-networking.firewall.allowPing"/> = false;
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Integers
</term>
<listitem>
<para>
For example,
<programlisting>
<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 60;
</programlisting>
(Note that here the attribute name
<literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in quotes to
prevent it from being interpreted as a set named <literal>net</literal>
containing a set named <literal>ipv4</literal>, and so on. This is
because it’s not a NixOS option but the literal name of a Linux kernel
setting.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Sets
</term>
<listitem>
<para>
Sets were introduced above. They are name/value pairs enclosed in braces,
as in the option definition
<programlisting>
<xref linkend="opt-fileSystems"/>."/boot" =
{ device = "/dev/sda1";
fsType = "ext4";
options = [ "rw" "data=ordered" "relatime" ];
};
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Lists
</term>
<listitem>
<para>
The important thing to note about lists is that list elements are
separated by whitespace, like this:
<programlisting>
<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
</programlisting>
List elements can be any other type, e.g. sets:
<programlisting>
swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Packages
</term>
<listitem>
<para>
Usually, the packages you need are already part of the Nix Packages
collection, which is a set that can be accessed through the function
argument <varname>pkgs</varname>. Typical uses:
<programlisting>
<xref linkend="opt-environment.systemPackages"/> =
[ pkgs.thunderbird
pkgs.emacs
];
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_10;
</programlisting>
The latter option definition changes the default PostgreSQL package used
by NixOS’s PostgreSQL service to 10.x. For more information on
packages, including how to add new ones, see
<xref linkend="sec-custom-packages"/>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>

2
nixos/doc/manual/configuration/config-syntax.xml
View file

@ -18,7 +18,7 @@ xlink:href="https://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
manual</link>, but here we give a short overview of the most important
constructs useful in NixOS configuration files.
</para>
<xi:include href="config-file.xml" />
<xi:include href="../from_md/configuration/config-file.section.xml" />
<xi:include href="../from_md/configuration/abstractions.section.xml" />
<xi:include href="modularity.xml" />
<xi:include href="summary.xml" />

231
nixos/doc/manual/from_md/configuration/config-file.section.xml Normal file
View file

@ -0,0 +1,231 @@
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-configuration-file">
<title>NixOS Configuration File</title>
<para>
The NixOS configuration file generally looks like this:
</para>
<programlisting language="bash">
{ config, pkgs, ... }:
{ option definitions
}
</programlisting>
<para>
The first line (<literal>{ config, pkgs, ... }:</literal>) denotes
that this is actually a function that takes at least the two
arguments <literal>config</literal> and <literal>pkgs</literal>.
(These are explained later, in chapter
<xref linkend="sec-writing-modules" />) The function returns a
<emphasis>set</emphasis> of option definitions
(<literal>{ ... }</literal>). These definitions have the form
<literal>name = value</literal>, where <literal>name</literal> is
the name of an option and <literal>value</literal> is its value. For
example,
</para>
<programlisting language="bash">
{ config, pkgs, ... }:
{ services.httpd.enable = true;
services.httpd.adminAddr = &quot;alice@example.org&quot;;
services.httpd.virtualHosts.localhost.documentRoot = &quot;/webroot&quot;;
}
</programlisting>
<para>
defines a configuration with three option definitions that together
enable the Apache HTTP Server with <literal>/webroot</literal> as
the document root.
</para>
<para>
Sets can be nested, and in fact dots in option names are shorthand
for defining a set containing another set. For instance,
<link xlink:href="options.html#opt-services.httpd.enable"><literal>services.httpd.enable</literal></link>
defines a set named <literal>services</literal> that contains a set
named <literal>httpd</literal>, which in turn contains an option
definition named <literal>enable</literal> with value
<literal>true</literal>. This means that the example above can also
be written as:
</para>
<programlisting language="bash">
{ config, pkgs, ... }:
{ services = {
httpd = {
enable = true;
adminAddr = &quot;alice@example.org&quot;;
virtualHosts = {
localhost = {
documentRoot = &quot;/webroot&quot;;
};
};
};
};
}
</programlisting>
<para>
which may be more convenient if you have lots of option definitions
that share the same prefix (such as
<literal>services.httpd</literal>).
</para>
<para>
NixOS checks your option definitions for correctness. For instance,
if you try to define an option that doesn’t exist (that is, doesn’t
have a corresponding <emphasis>option declaration</emphasis>),
<literal>nixos-rebuild</literal> will give an error like:
</para>
<programlisting>
The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
</programlisting>
<para>
Likewise, values in option definitions must have a correct type. For
instance, <literal>services.httpd.enable</literal> must be a Boolean
(<literal>true</literal> or <literal>false</literal>). Trying to
give it a value of another type, such as a string, will cause an
error:
</para>
<programlisting>
The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
</programlisting>
<para>
Options have various types of values. The most important are:
</para>
<variablelist>
<varlistentry>
<term>
Strings
</term>
<listitem>
<para>
Strings are enclosed in double quotes, e.g.
</para>
<programlisting language="bash">
networking.hostName = &quot;dexter&quot;;
</programlisting>
<para>
Special characters can be escaped by prefixing them with a
backslash (e.g. <literal>\&quot;</literal>).
</para>
<para>
Multi-line strings can be enclosed in <emphasis>double single
quotes</emphasis>, e.g.
</para>
<programlisting language="bash">
networking.extraHosts =
''
127.0.0.2 other-localhost
10.0.0.1 server
'';
</programlisting>
<para>
The main difference is that it strips from each line a number
of spaces equal to the minimal indentation of the string as a
whole (disregarding the indentation of empty lines), and that
characters like <literal>&quot;</literal> and
<literal>\</literal> are not special (making it more
convenient for including things like shell code). See more
info about this in the Nix manual
<link xlink:href="https://nixos.org/nix/manual/#ssec-values">here</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Booleans
</term>
<listitem>
<para>
These can be <literal>true</literal> or
<literal>false</literal>, e.g.
</para>
<programlisting language="bash">
networking.firewall.enable = true;
networking.firewall.allowPing = false;
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>
Integers
</term>
<listitem>
<para>
For example,
</para>
<programlisting language="bash">
boot.kernel.sysctl.&quot;net.ipv4.tcp_keepalive_time&quot; = 60;
</programlisting>
<para>
(Note that here the attribute name
<literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in
quotes to prevent it from being interpreted as a set named
<literal>net</literal> containing a set named
<literal>ipv4</literal>, and so on. This is because it’s not a
NixOS option but the literal name of a Linux kernel setting.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Sets
</term>
<listitem>
<para>
Sets were introduced above. They are name/value pairs enclosed
in braces, as in the option definition
</para>
<programlisting language="bash">
fileSystems.&quot;/boot&quot; =
{ device = &quot;/dev/sda1&quot;;
fsType = &quot;ext4&quot;;
options = [ &quot;rw&quot; &quot;data=ordered&quot; &quot;relatime&quot; ];
};
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>
Lists
</term>
<listitem>
<para>
The important thing to note about lists is that list elements
are separated by whitespace, like this:
</para>
<programlisting language="bash">
boot.kernelModules = [ &quot;fuse&quot; &quot;kvm-intel&quot; &quot;coretemp&quot; ];
</programlisting>
<para>
List elements can be any other type, e.g. sets:
</para>
<programlisting language="bash">
swapDevices = [ { device = &quot;/dev/disk/by-label/swap&quot;; } ];
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>
Packages
</term>
<listitem>
<para>
Usually, the packages you need are already part of the Nix
Packages collection, which is a set that can be accessed
through the function argument <literal>pkgs</literal>. Typical
uses:
</para>
<programlisting language="bash">
environment.systemPackages =
[ pkgs.thunderbird
pkgs.emacs
];
services.postgresql.package = pkgs.postgresql_10;
</programlisting>
<para>
The latter option definition changes the default PostgreSQL
package used by NixOS’s PostgreSQL service to 10.x. For more
information on packages, including how to add new ones, see
<xref linkend="sec-custom-packages" />.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>