summaryrefslogtreecommitdiff
path: root/src/admin/7_config.xml
blob: 82c15487d10155af075e8ff40961092c9569ef71 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
<?xml version="1.0" encoding="utf-8"?>
<chapter label="7" id="config">
    <title>System Configuration</title>
    <highlights><para>In this chapter, we will overview the main configuration files present in the Adélie Linux system.</para></highlights>
    <section>
        <title>Introduction</title>
        <para>This chapter will cover the main configuration files that are commonly referenced in the daily administration of Adélie Linux systems.  This list is not exhaustive, and is not a list of every configuration file in the Adélie Linux system.  Some configuration files are only present when a specific system option (such as audio, graphics, or networking) is installed.</para>
        <para>Each section in this chapter has the following subsections:</para>
        <itemizedlist>
            <listitem><para><firstterm>Purpose</firstterm>, which describes for what the configuration file is responsible;</para></listitem>
            <listitem><para><firstterm>Syntax</firstterm>, which describes the high-level syntax type used by the configuration file; and finally,</para></listitem>
            <listitem><para>either <firstterm>Detailed Information</firstterm> for information on configuration files specific to the Adélie Linux system, or <firstterm>External References</firstterm> for either manual pages or online links to more information about configuration files from packages.</para></listitem>
        </itemizedlist>
    </section>
    <section>
        <title><filename>/etc/abuild.conf</filename>: Package build configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/abuild.conf</filename> file determines how packages are built on the system.  This file sets global parameters; <filename>$HOME/.abuild.conf</filename> can override any setting from the <filename>/etc/abuild.conf</filename> on a per-user basis.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Comments may appear anywhere, and start with '<literal>#</literal>'.  Variables are in uppercase and follow shell quote syntax.</para>
        </section>
        <section role="NotInToc">
            <title>External References</title>
            <para>Please reference the Adélie Linux Developer's Handbook for more information about how to configure <filename>/etc/abuild.conf</filename>.  If you are reading this documentation on your local computer, the Developer's Handbook may be found in the <filename class="directory">devel/</filename> directory at the same level as this handbook's <filename class="directory">admin/</filename> directory.  If you are reading this documentation online via the Internet, you may find the newest version of the Developer's Handbook at the <ulink url="https://help.adelielinux.org/html/devel/">Adélie Linux Help Centre</ulink>.</para>
        </section>
    </section>
    <section id="e-a-r">
        <title><filename>/etc/apk/repositories</filename>: Package repository configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/apk/repositories</filename> file determines the repositories used by the APK package manager for obtaining packages.  As noted in <xref linkend="apk_repos" />, package repositories contain packages that you may install and uninstall on an Adélie Linux system.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>A single URL or file location per line.  Comments are not allowed.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>A repository must be either a URL (beginning with <literal>https://</literal>) or an absolute path (such as <filename class="directory">/srv/packages</filename>).  The computer's architecture (as specified in <filename>/etc/apk/arch</filename>) will be appened to the path &ndash; for example, specifying the path <filename class="directory">/srv/packages/repository</filename> on a <literal>ppc64</literal> computer will result in the packages and <filename>APKINDEX</filename> being retrieved from <filename class="directory">/srv/packages/repository/ppc64</filename>.</para>
            <para>If a repository is invalid, does not have a recognised signing key, or does not exist, it will not be considered by APK.  Depending on the parameters passed to APK and the operation being performed, this may be a warning or a fatal error.</para>
        </section>
    </section>
    <section>
        <title><filename>/etc/asound.conf</filename>: System audio configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/asound.conf</filename> file determines the behaviour audio hardware present on the system.  It can be used to select default bitrates, configure hardware options, and determine which sound card is the default/primary in a system with multiple sound cards present.  This file is only significant on systems that have audio options installed.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Sections are blocks, with the name followed by curly braces (<literal>{</literal> and <literal>}</literal>) where the options are specified for that section.  See the external reference for more information.</para>
        </section>
        <section role="NotInToc">
            <title>External References</title>
            <para>For more information on configuring system audio hardware, refer to <ulink url="https://www.alsa-project.org/main/index.php/Asoundrc">the official documentation at the ALSA Project Web site</ulink> on the Internet.  <!-- If you do not have an internet connection, XXX TODO help!  does anyone know if asoundrc(5) exists?  can't find it in any of our packages --></para>
        </section>
    </section>
    <section>
        <title><filename>/etc/bash/bashrc</filename>: Bash shell startup configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/bash/bashrc</filename> file is sourced by the Bash shell when it starts up.  This can set shell options and configure the shell environment for you.  It is highly recommended to create your own scripts inside <filename class="directory">/etc/profile.d</filename> instead of modifying <filename>/etc/bash/bashrc</filename>, since it may change during upgrades to the Bash package.  This file is only present on systems that have the Bash shell installed.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.</para>
        </section>
        <section role="NotInToc">
            <title>External References</title>
            <para>For more information, refer to the bash(1) manpage.  If this manpage is not present on your system, it may be installed via the <package>bash-doc</package> package.</para>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/alsa</filename>: Mixer level configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/alsa</filename> file determines if volume levels are preserved across system restarts when the <literal>alsasound</literal> service is enabled.  This file is only significant on systems that have audio options installed.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Variables are in uppercase.</para>
        </section>
        <section role="NotInToc">
            <title>External References</title>
            <para>For more information, refer to the comments in the <filename>/etc/conf.d/alsa</filename> file.</para>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/bootmisc</filename>: Boot behaviour configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/bootmisc</filename> file determines certain characteristics about boot behaviour.  It controls whether the <filename class="directory">/tmp</filename> directory is cleaned, and whether <literal>dmesg</literal> is written to <filename>/var/log/dmesg</filename> on boot.  It also controls if the previous <filename>/var/log/dmesg</filename> is renamed to <filename>/var/log/dmesg.old</filename> for later comparison.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Variables are in lowercase.  Booleans may be set as <literal>YES</literal> or <literal>NO</literal>.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>The following variables are configurable in the <filename>/etc/conf.d/bootmisc</filename> file:</para>
            <table frame="none">
                <title>Configurable variables in <filename>/etc/conf.d/bootmisc</filename></title>
                <tgroup cols="3" align="left" colsep="1" rowsep="1">
                <thead>
                    <row>
                        <entry>Variable</entry>
                        <entry>Meaning</entry>
                        <entry>Default</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry><varname>clean_tmp_dirs</varname></entry>
                        <entry>Directories to be treated as temporary, to be cleaned when <varname>wipe_tmp</varname> is <literal>YES</literal>.</entry>
                        <entry><literal><filename class="directory">/tmp</filename></literal></entry>
                    </row>
                    <row>
                        <entry><varname>wipe_tmp</varname></entry>
                        <entry>Determines if the directories listed in <varname>clean_tmp_dirs</varname> are completely erased on system boot.</entry>
                        <entry><literal>YES</literal></entry>
                    </row>
                    <row>
                        <entry><varname>log_dmesg</varname></entry>
                        <entry>Determines if the contents of the <literal>dmesg</literal> kernel message buffer are written to <filename>/var/log/dmesg</filename> on system boot.</entry>
                        <entry><literal>YES</literal></entry>
                    </row>
                    <row>
                        <entry><varname>previous_dmesg</varname></entry>
                        <entry>When <varname>log_dmesg</varname> is <literal>YES</literal>, determines if <filename>/var/log/dmesg</filename> is moved to <filename>/var/log/dmesg.old</filename> on system boot instead of being overwritten.</entry>
                        <entry><literal>NO</literal></entry>
                    </row>
                </tbody>
                </tgroup>
            </table>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/devfs</filename>: <filename class="directory">/dev</filename> configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/devfs</filename> file determines if the system attempts to mount <filename class="directory">/dev</filename> during system initialisation.  Most systems will not need this configuration modified.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Variables are in lowercase.  Booleans may be set as <literal>YES</literal> or <literal>NO</literal>.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>The <varname>skip_mount_dev</varname> variable may be set to <literal>YES</literal> to prevent the system from automatically attempting to mount <filename class="directory">/dev</filename> during system initialisation.  The default setting of the <varname>skip_mount_dev</varname> variable is <literal>NO</literal>.</para>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/dmesg</filename>: <literal>dmesg</literal> configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/dmesg</filename> file determines the behaviour of the <literal>dmesg</literal> kernel log buffer.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Variables are in lowercase.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>The <varname>dmesg_level</varname> controls the "console level", or the severity required for a message to be printed to the system console.  The default value is <literal>1</literal>, which corresponds to the <literal>emerg</literal> log level.  This prevents all messages from being written to the console except kernel panics.</para>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/fsck</filename>: Startup file system check configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/fsck</filename> file determines the behaviour of the <command>fsck</command> (file system check) command during system initialisation.  It is important to note that the configuration in the <filename>/etc/conf.d/fsck</filename> does not control manual invocations of the <command>fsck</command> command.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Variables are in lowercase.  Booleans may be set as <literal>YES</literal> or <literal>NO</literal>.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>The following variables are configurable in the <filename>/etc/conf.d/fsck</filename> file:</para>
            <table frame="none">
                <title>Configurable variables in <filename>/etc/conf.d/fsck</filename></title>
                <tgroup cols="3" align="left" colsep="1" rowsep="1">
                <thead>
                    <row>
                        <entry>Variable</entry>
                        <entry>Meaning</entry>
                        <entry>Default</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry><varname>fsck_args</varname></entry>
                        <entry>Determines the command line arguments passed for routine <command>fsck</command>.</entry>
                        <entry><literal>-p -C0 -T -A</literal></entry>
                    </row>
                    <row>
                        <entry><varname>fsck_passno</varname></entry>
                        <entry>Determines which file systems will be checked by routine <command>fsck</command> during system initialisation by their "pass number" in <filename>/etc/fstab</filename>.</entry>
                        <entry><literal></literal></entry>
                    </row>
                    <row>
                        <entry><varname>fsck_on_battery</varname></entry>
                        <entry>Determines if <command>fsck</command> will be run on startup if the computer is running on battery power.</entry>
                        <entry><literal>YES</literal></entry>
                    </row>
                    <row>
                        <entry><varname>fsck_shutdown</varname></entry>
                        <entry>Determines if routine <command>fsck</command> should be performed during system shutdown, instead of during system initialisation.</entry>
                        <entry><literal>NO</literal></entry>
                    </row>
                    <row>
                        <entry><varname>fsck_abort_on_errors</varname></entry>
                        <entry>Determines if system initialisation should be halted if <command>fsck</command> finds errors.</entry>
                        <entry><literal>YES</literal></entry>
                    </row>
                </tbody>
                </tgroup>
            </table>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/gettys</filename>: System console configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/gettys</filename> file determines the parameters and behaviour of virtual terminals (VTs) and serial consoles on the system.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Variables are mixed-case.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>The <filename>/etc/conf.d/gettys</filename> file defines the variable <varname>GETTYS</varname>.  The <varname>GETTYS</varname> variable controls the devices that the system will search for, on which to run VTs.  Each device is separated by a space ("<literal> </literal>").  The default is "<literal>tty1 tty2 tty3 tty4 tty5 tty6 hvc0</literal>", which will start a VT on each virtual TTY 1-6, and also start a VT on <literal>hvc0</literal> if it exists.  The <literal>hvc0</literal> device is present on most IBM servers, and also most Xen guests.</para>
            <para>For every device specified in <varname>GETTYS</varname>, the following two variables can be used for further device configuration:</para>
            <variablelist>
                <title>Configuration variables in <filename>/etc/conf.d/gettys</filename></title>
                <varlistentry>
                    <term><varname>GETTYS_<replaceable>term</replaceable>_OPTIONS</varname></term>
                    <listitem><para>Determines the options passed to <command>agetty</command> for this VT.  For more information, refer to the <command>agetty</command> manual, found in the <package>util-linux-doc</package> package.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><varname>GETTYS_<replaceable>term</replaceable>_BAUDRATE</varname></term>
                    <listitem><para>Determines the baud rate of the specified serial line.  This option is only effective on devices that act as serial lines.</para></listitem>
                </varlistentry>
            </variablelist>
            <important><title>Important</title><para>Changes to this file will not take effect until the system is restarted.</para></important>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/hwclock</filename>: System time configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/hwclock</filename> file determines how the system will use the hardware real time clock (RTC), if present.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Variables are in lowercase.  Booleans may be set as <literal>YES</literal> or <literal>NO</literal>.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para></para>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/keymaps</filename>: Keyboard layout configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/keymaps</filename> file determines certain behaviours of the keyboard connected to the system console.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Variables are in lowercase.  Booleans may be set as <literal>YES</literal> or <literal>NO</literal>.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>The <filename>/etc/conf.d/keymaps</filename> file </para>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/modules</filename>: Kernel module configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/</filename> file </para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Variables are in </para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para></para>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/net</filename>: Network configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/net</filename> file determines the configuration of the network adaptor(s) installed in the system.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script style.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>Refer to <xref linkend="networking" /> for information on configuring networks using the Adélie Linux system.</para>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/netmount</filename>: Network file system configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/</filename> file </para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Variables are in </para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para></para>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/swap</filename>: Network swap file configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/</filename> file </para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Variables are in </para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para></para>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/udev-trigger</filename>: Hardware hot-plug configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/</filename> file </para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Variables are in </para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para></para>
        </section>
    </section>
    <section>
        <title><filename>/etc/conf.d/urandom</filename>: Random number configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/</filename> file </para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script.  Variables are in </para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para></para>
        </section>
    </section>
</chapter>