pyrox.dev
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="sec-writing-modules">
6 <title>Writing NixOS Modules</title>
7 <para>
8 NixOS has a modular system for declarative configuration. This system
9 combines multiple <emphasis>modules</emphasis> to produce the full system
10 configuration. One of the modules that constitute the configuration is
11 <filename>/etc/nixos/configuration.nix</filename>. Most of the others live in
12 the
13 <link
14xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"><filename>nixos/modules</filename></link>
15 subdirectory of the Nixpkgs tree.
16 </para>
17 <para>
18 Each NixOS module is a file that handles one logical aspect of the
19 configuration, such as a specific kind of hardware, a service, or network
20 settings. A module configuration does not have to handle everything from
21 scratch; it can use the functionality provided by other modules for its
22 implementation. Thus a module can <emphasis>declare</emphasis> options that
23 can be used by other modules, and conversely can <emphasis>define</emphasis>
24 options provided by other modules in its own implementation. For example, the
25 module
26 <link
27xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><filename>pam.nix</filename></link>
28 declares the option <option>security.pam.services</option> that allows other
29 modules (e.g.
30 <link
31xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><filename>sshd.nix</filename></link>)
32 to define PAM services; and it defines the option
33 <option>environment.etc</option> (declared by
34 <link
35xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><filename>etc.nix</filename></link>)
36 to cause files to be created in <filename>/etc/pam.d</filename>.
37 </para>
38 <para xml:id="para-module-syn">
39 In <xref
40linkend="sec-configuration-syntax"/>, we saw the following structure
41 of NixOS modules:
42<programlisting>
43{ config, pkgs, ... }:
44
45{ <replaceable>option definitions</replaceable>
46}
47</programlisting>
48 This is actually an <emphasis>abbreviated</emphasis> form of module that only
49 defines options, but does not declare any. The structure of full NixOS
50 modules is shown in <xref linkend='ex-module-syntax' />.
51 </para>
52 <example xml:id='ex-module-syntax'>
53 <title>Structure of NixOS Modules</title>
54<programlisting>
55{ config, pkgs, ... }: <co xml:id='module-syntax-1' />
56
57{
58 imports =
59 [ <replaceable>paths of other modules</replaceable> <co xml:id='module-syntax-2' />
60 ];
61
62 options = {
63 <replaceable>option declarations</replaceable> <co xml:id='module-syntax-3' />
64 };
65
66 config = {
67 <replaceable>option definitions</replaceable> <co xml:id='module-syntax-4' />
68 };
69}</programlisting>
70 </example>
71 <para>
72 The meaning of each part is as follows.
73 <calloutlist>
74 <callout arearefs='module-syntax-1'>
75 <para>
76 This line makes the current Nix expression a function. The variable
77 <varname>pkgs</varname> contains Nixpkgs, while <varname>config</varname>
78 contains the full system configuration. This line can be omitted if there
79 is no reference to <varname>pkgs</varname> and <varname>config</varname>
80 inside the module.
81 </para>
82 </callout>
83 <callout arearefs='module-syntax-2'>
84 <para>
85 This list enumerates the paths to other NixOS modules that should be
86 included in the evaluation of the system configuration. A default set of
87 modules is defined in the file
88 <filename>modules/module-list.nix</filename>. These don't need to be added
89 in the import list.
90 </para>
91 </callout>
92 <callout arearefs='module-syntax-3'>
93 <para>
94 The attribute <varname>options</varname> is a nested set of
95 <emphasis>option declarations</emphasis> (described below).
96 </para>
97 </callout>
98 <callout arearefs='module-syntax-4'>
99 <para>
100 The attribute <varname>config</varname> is a nested set of
101 <emphasis>option definitions</emphasis> (also described below).
102 </para>
103 </callout>
104 </calloutlist>
105 </para>
106 <para>
107 <xref linkend='locate-example' /> shows a module that handles the regular
108 update of the “locate” database, an index of all files in the file
109 system. This module declares two options that can be defined by other modules
110 (typically the user’s <filename>configuration.nix</filename>):
111 <option>services.locate.enable</option> (whether the database should be
112 updated) and <option>services.locate.interval</option> (when the update
113 should be done). It implements its functionality by defining two options
114 declared by other modules: <option>systemd.services</option> (the set of all
115 systemd services) and <option>systemd.timers</option> (the list of commands
116 to be executed periodically by <command>systemd</command>).
117 </para>
118 <example xml:id='locate-example'>
119 <title>NixOS Module for the “locate” Service</title>
120<programlisting>
121{ config, lib, pkgs, ... }:
122
123with lib;
124
125let
126 cfg = config.services.locate;
127in {
128 options.services.locate = {
129 enable = mkOption {
130 type = types.bool;
131 default = false;
132 description = ''
133 If enabled, NixOS will periodically update the database of
134 files used by the <command>locate</command> command.
135 '';
136 };
137
138 interval = mkOption {
139 type = types.str;
140 default = "02:15";
141 example = "hourly";
142 description = ''
143 Update the locate database at this interval. Updates by
144 default at 2:15 AM every day.
145
146 The format is described in
147 <citerefentry><refentrytitle>systemd.time</refentrytitle>
148 <manvolnum>7</manvolnum></citerefentry>.
149 '';
150 };
151
152 # Other options omitted for documentation
153 };
154
155 config = {
156 systemd.services.update-locatedb =
157 { description = "Update Locate Database";
158 path = [ pkgs.su ];
159 script =
160 ''
161 mkdir -m 0755 -p $(dirname ${toString cfg.output})
162 exec updatedb \
163 --localuser=${cfg.localuser} \
164 ${optionalString (!cfg.includeStore) "--prunepaths='/nix/store'"} \
165 --output=${toString cfg.output} ${concatStringsSep " " cfg.extraFlags}
166 '';
167 };
168
169 systemd.timers.update-locatedb = mkIf cfg.enable
170 { description = "Update timer for locate database";
171 partOf = [ "update-locatedb.service" ];
172 wantedBy = [ "timers.target" ];
173 timerConfig.OnCalendar = cfg.interval;
174 };
175 };
176}
177</programlisting>
178 </example>
179 <xi:include href="option-declarations.xml" />
180 <xi:include href="option-types.xml" />
181 <xi:include href="option-def.xml" />
182 <xi:include href="assertions.xml" />
183 <xi:include href="meta-attributes.xml" />
184 <xi:include href="importing-modules.xml" />
185 <xi:include href="replace-modules.xml" />
186</chapter>