path: root/src/admin/7_config.xml

<?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 id="introduction7">
        <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 id="e-abuild">
        <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 id="e-asound">
        <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 of 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 id="e-b-b">
        <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 id="e-c-alsa">
        <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 id="e-c-bootmisc">
        <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 <filename>/etc/conf.d/bootmisc</filename> file defines the following configuration variables:</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 id="e-c-devfs">
        <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 id="e-c-dmesg">
        <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 id="e-c-fsck">
        <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 <filename>/etc/conf.d/fsck</filename> file defines the following configuration variables:</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 id="e-c-gettys">
        <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 id="e-c-modules">
        <title><filename>/etc/conf.d/modules</filename>: Kernel module configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/modules</filename> file specifies additional kernel modules to load during system initialisation.</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 <filename>/etc/conf.d/modules</filename> file allows you to specify additional kernel modules for the system to load during initialisation.  This is typically unnecessary as the <package>eudev</package> system will automatically load any modules required for the correct functioning of your hardware.  However, some advanced use cases may require the loading of additional kernel modules.</para>
            <para>The <filename>/etc/conf.d/modules</filename> file defines the <varname>modules</varname> configuration variables.  This is a space-delimited list of modules to load.</para>
            <para>For each module specified, an additional variable, <varname>module_<replaceable>MODNAME</replaceable>_args</varname>, is defined, where <replaceable>MODNAME</replaceable> is the name of the module.  The <varname>module_<replaceable>MODNAME</replaceable>_args</varname> variable controls the arguments passed to the module.  Refer to the documentation for each module for a list of arguments it supports.</para>
        </section>
    </section>
    <section id="e-c-net">
        <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 id="e-c-urandom">
        <title><filename>/etc/conf.d/urandom</filename>: Random number configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/conf.d/urandom</filename> file determines the path where the random number seed is stored when the system is shut down.</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 <filename>/etc/conf.d/urandom</filename> file defines a single configuration variable, <varname>urandom_seed</varname>, which specifies the path in which to save the random number seed when the system is shut down.  The default is <filename>/var/lib/misc/random-seed</filename>.  This variable must point to a path that is on the root filesystem; if <filename class="directory">/var</filename> is a separate filesystem, you must configure this variable to use a different path.</para>
        </section>
    </section>
    <section id="e-d-console-setup">
        <title><filename>/etc/default/console-setup</filename>: Virtual terminal configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/default/console-setup</filename> file determines the configuration of the system virtual terminals or consoles.  Note that this does not include graphical terminals run inside X11 (such as Konsole or XFCE Terminal).</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script style.  Variables are in uppercase.</para>
        </section>
        <section role="NotInToc">
            <title>External References</title>
            <para>For more information, consult the official manual page for console-setup(5).  This manual page is available in the <package>console-setup-doc</package> package.  If your computer has an Internet connection, you may also read it <ulink url="https://manpages.debian.org/stable/console-setup/console-setup.5.en.html">on the Web</ulink>.</para>
        </section>
    </section>
    <section id="e-d-keyboard">
        <title><filename>/etc/default/keyboard</filename>: Console keyboard configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/default/keyboard</filename> file determines the configuration of the keyboard on the system virtual terminals or consoles.  This file does not control the configuration of the keyboard inside X11 or a desktop environment (such as KDE or LXQt).</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script style.  Variables are in uppercase.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>The <filename>/etc/default/keyboard</filename> file is used by the <package>console-setup</package> package (when the <literal>console-setup</literal> service is enabled) to configure the keyboard model and layout in use on the system's virtual terminals.  The most important variables in the <filename>/etc/default/keyboard</filename> file are the <varname>XKBMODEL</varname> variable, which controls the model of keyboard, and the <varname>XKBLAYOUT</varname> variable, which controls the layout of the keyboard.</para>
            <para>In order to use additional keyboard layouts, you must install the <package>console-keymaps</package> package.</para>
        </section>
        <section role="NotInToc">
            <title>External Resources</title>
            <para>For more information, consult the official manual page for keyboard(5).  This manual page is available in the <package>console-setup-doc</package> package.  If your computer has an Internet connection, you may also read it <ulink url="https://manpages.debian.org/stable/console-setup/keyboard.5.en.html">on the Web</ulink>.</para>
        </section>
    </section>
    <section id="e-dracut">
        <title><filename class="directory">/etc/dracut.conf.d/</filename>: Early system initialisation configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename class="directory">/etc/dracut.conf.d</filename> directory contains files that determine the configuration of <package>dracut</package>, the initial RAM disk generation system for the Adélie Linux system.  The initial RAM disk is needed on some computers during system initialisation; tasks it may perform include enabling access to a disk, unlocking an encrypted partition, or establishing a network connection.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell script style.  Variables are in lowercase.</para>
        </section>
        <section role="NotInToc">
            <title>External Resources</title>
            <para>For more information, consult the dracut.conf(5) manual page.  This manual page is available in the <package>dracut-doc</package> package.</para>
        </section>
    </section>
    <section id="e-fstab">
        <title><filename>/etc/fstab</filename>: Filesystem mount point configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/fstab</filename> file determines the mount points of file systems on the hard disk(s) connected to a system.  It may also control whether or not users may mount removable storage devices such as CD-ROM devices, and where they may mount them.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>The syntax for <filename>/etc/fstab</filename> is columnar in nature.  There may be any amount of whitespace between columns; the following two lines will be viewed identically to the system:</para>
            <informalexample>
<programlisting>
/dev/sda1 /boot ext3 defaults 0 1
/dev/sda1       /boot       ext3        defaults    0   1
</programlisting>
            </informalexample>
        </section>
        <section role="NotInToc">
            <title>External Resources</title>
            <para>For more information, consult the fstab(5) manual page.  This manual page is available in the <package>util-linux-doc</package> package.</para>
        </section>
    </section>
    <section id="e-hostname">
        <title><filename>/etc/hostname</filename>: Host name configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/hostname</filename> file determines the host name of the system.  This is used in system prompts, and for identification on a network.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>The host name must appear as the only content of this file.  Any other contents are invalid.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>The <filename>/etc/hostname</filename> is read during system initialisation.  The system host name is set to the contents of this file.  If the <filename>/etc/hostname</filename> file is missing or corrupt, the system will retain the kernel's default host name &mdash; with the default Adélie Linux kernel, this is "<literal>adelie</literal>".</para>
        </section>
    </section>
    <section id="e-inputrc">
        <title><filename>/etc/inputrc</filename>: Bash shell keyboard configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/inputrc</filename> file determines the behaviour of keyboard input and the system bell in programs that use the GNU readline library.  The GNU readline library is not packaged for the Adélie Linux system; therefore, the only system packages that would use the configuration in this file are <package>bash</package> and <package>gdb</package>, which contain their own private copies of the GNU readline library.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>The <filename>/etc/inputrc</filename> is declarative in nature; variables are set using the <command>set</command> command, and escape sequences are mapped to functions using the format: <literal>"<replaceable>&lt;escape sequence&gt;</replaceable>": <replaceable>function</replaceable></literal>.</para>
        </section>
        <section role="NotInToc">
            <title>External Resources</title>
            <para>There are a few comments in the <filename>/etc/inputrc</filename> file.  Since the GNU readline library is not packaged for the Adélie Linux system, it is not possible to read the manual page.</para>
        </section>
    </section>
    <section id="e-issue">
        <title><filename>/etc/issue</filename>: System identification configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/issue</filename> file determines the message that will be displayed on virtual terminals and consoles before the login prompt.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Text file.  Escape sequences are supported.</para>
        </section>
        <section role="NotInToc">
            <title>External References</title>
            <para>For more information, refer to the Issue Files section of the agetty(8) manual page.  The agetty(8) manual page is available in the <package>util-linux-doc</package> package.</para>
        </section>
    </section>
    <!-- <section id="e-ld-musl">
        <title><filename>/etc/ld-musl-<replaceable>ARCH</replaceable>.path</filename>: Dynamic linker configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/ld-musl-<replaceable>ARCH</replaceable>.path</filename> file determines the paths that will be used by the dynamic linker to resolve shared libraries.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>One directory per line.  Comments are not allowed.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>We really should write how musl works internally and publish it as a chapter in this book for the 2.0 cycle.  After all, the front matter refers to this as not only a handbook for day-to-day utilisation and administration of Adélie, but also an introduction to the "design and implementation of the system".  Perhaps we should take Kiyoshi's idea and split this into two or more parts, to accomplish that.  (It may stop being a handbook and become a book, then, though.)</para>
        </section>
    </section> -->
    <section id="e-localtime">
        <title><filename>/etc/localtime</filename>: Time zone configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/localtime</filename> file determines the system's time zone.  The system time zone is shown in <command>date</command>(1), file modification times, log files, and other functions.  It is important to ensure this file is correct.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Binary time zone file.  Please do not edit the file directly in an editor.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>The <package>tzdata</package> package provides a number of time zone files in the <filename class="directory">/usr/share/zoneinfo</filename> directory.  When configuring the system time zone, you should make a symbolic link from your time zone to <filename>/etc/localtime</filename>.  Alternatively, if you are using a split <filename class="directory">/usr</filename> (not common), you may copy the file directly.  For example, to set the system time zone to American Central Time, you would run <command>ln -s /usr/share/zoneinfo/America/Chicago /etc/localtime</command>; or, if you are using a split <filename class="directory">/usr</filename> (not common), you would run <command>cp /usr/share/zoneinfo/America/Chicago /etc/localtime</command>.  For a full list of time zones available, run <command>find /usr/share/zoneinfo</command>.</para>
        </section>
    </section>
    <section id="e-login-defs">
        <title><filename>/etc/login.defs</filename>: Login configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/login.defs</filename> file determines the configuration for the <package>shadow</package> package, which is responsible for all logins and the <command>su</command> command on the Adélie Linux system.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Each line describes a configuration value; the name and value are separated by whitespace.  Blank lines and comment lines are ignored.  Comments may not appear anywhere other than the beginning of a line.</para>
        </section>
        <section role="NotInToc">
            <title>External References</title>
            <para>For more information, refer to the login.defs(5) manual page.  The login.defs(5) manual page is available in the <package>shadow-doc</package> package.</para>
        </section>
    </section>
    <section id="e-motd">
        <title><filename>/etc/motd</filename>: Login message configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/motd</filename> file determines the message that will be displayed to users when they log in to the system.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Plain text.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>The entire contents of the <filename>/etc/motd</filename> file are displayed to a user when they log in to the system.  No command substitution or escape sequences are recognised; the file is entirely plain text.  The default login message provides pointers on where to find the documentation for the Adélie Linux system.</para>
        </section>
    </section>
    <section id="e-p-d">
        <title><filename class="directory">/etc/profile.d/</filename>: Shell startup configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename class="directory">/etc/profile.d</filename> directory contains files that determine the shell environment for all users on the system.</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Shell scripts.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>The <filename>/etc/profile</filename> script is sourced by most shells during interactive logins.  This script enumerates all shell scripts present in <filename class="directory">/etc/profile.d</filename> and sources them.  Adding an executable shell script to <filename class="directory">/etc/profile.d</filename> allows you to set environment variables or add shell functions for interactive use.  Note that most shells will not source these files during non-interactive logins.</para>
        </section>
    </section>
    <section id="e-rc-conf">
        <title><filename>/etc/rc.conf</filename>: Service manager configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/rc.conf</filename> file determines the behaviour of the service manager, which is partially responsible for system initialisation.</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/rc.conf</filename> file defines the following configuration variables:</para>
            <table frame="none">
                <title>Configurable variables in <filename>/etc/rc.conf</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>rc_parallel</varname></entry>
                        <entry>
                            Determines whether the system should attempt to start multiple services at the same time.
                            <warning><title>Danger</title><para>This option may harm the stability of your system or render it inoperable.  Take extreme caution before changing the default.</para></warning>
                        </entry>
                        <entry><literal>NO</literal></entry>
                    </row>
                    <row>
                        <entry><varname>rc_interactive</varname></entry>
                        <entry>Determines whether the system should allow a user to hold the "I" key during system initialisation to choose which services to start.</entry>
                        <entry><literal>NO</literal></entry>
                    </row>
                    <row>
                        <entry><varname>rc_shell</varname></entry>
                        <entry>Determines the shell to spawn if the system fails to initialise correctly.</entry>
                        <entry><literal>/bin/sh</literal></entry>
                    </row>
                    <row>
                        <entry><varname>rc_depend_strict</varname></entry>
                        <entry>Determines whether all providers of a dependency are required to start before dependent services are started.  For an example, refer to <xref linkend="multi_if" />.</entry>
                        <entry><literal>YES</literal></entry>
                    </row>
                    <row>
                        <entry><varname>rc_logger</varname></entry>
                        <entry>Determines whether system initialisation activity is logged to disk for review by the system administrator.</entry>
                        <entry><literal>YES</literal></entry>
                    </row>
                    <row>
                        <entry><varname>rc_log_path</varname></entry>
                        <entry>Determines the path in which to write the system initialisation activity log, if <varname>rc_logger</varname> is set to <literal>YES</literal>.</entry>
                        <entry><literal>/var/log/rc.log</literal></entry>
                    </row>
                    <row>
                        <entry><varname>rc_verbose</varname></entry>
                        <entry>Determines if the service manager should output extra messages, which can be useful for debugging an issue with services.</entry>
                        <entry><literal>NO</literal></entry>
                    </row>
                    <row>
                        <entry><varname>rc_nocolor</varname></entry>
                        <entry>Determines if colourful output should be suppressed.</entry>
                        <entry><literal>NO</literal></entry>
                    </row>
                    <row>
                        <entry><varname>unicode</varname></entry>
                        <entry>
                            Determines if the system terminal supports Unicode.
                            <warning><title>Warning</title><para>Disabling Unicode support may cause some applications to work improperly.</para></warning>
                        </entry>
                        <entry><literal>YES</literal></entry>
                    </row>
                    <row>
                        <entry><varname>rc_sys</varname></entry>
                        <entry>Determines the system environment.  This may be autodetected.  Only set this option if autodetection does not work.  Valid options are "<literal></literal>" for a typical Adélie Linux system; "<literal>docker</literal>" for a Docker container; "<literal>lxc</literal>" for a LXC container; "<literal>openvz</literal>" for an OpenVZ container; "<literal>xen0</literal>" for a Xen domain 0 instance; and "<literal>xenU</literal>" for a Xen guest domain instance.</entry>
                        <entry><literal></literal></entry>
                    </row>
                    <row>
                        <entry><varname>rc_tty_number</varname></entry>
                        <entry>Determines how many TTYs the service manager should allow services to configure.  This does not impact the number of TTYs actually allocated; refer to <xref linkend="e-c-gettys" /> for this option.</entry>
                        <entry><literal>12</literal></entry>
                    </row>
                    <row>
                        <entry><varname>rc_controller_cgroups</varname></entry>
                        <entry>Determines whether cgroups should be used for services.  Refer to the kernel documentation on cgroups for more information.</entry>
                        <entry><literal>NO</literal></entry>
                    </row>
                </tbody>
                </tgroup>
            </table>
        </section>
    </section>
    <section id="e-resolv-conf">
        <title><filename>/etc/resolv.conf</filename>: Network name resolution configuration</title>
        <section role="NotInToc">
            <title>Purpose</title>
            <para>The <filename>/etc/resolv.conf</filename> file determines how names are resolved on the network.  This includes the domain suffix that should be searched when the system searches for a host name on the network.  This additionally includes the nameservers used to resolve names into IP addresses (typically via DNS).</para>
        </section>
        <section role="NotInToc">
            <title>Syntax</title>
            <para>Each line describes a configuration value; the name and value are separated by whitespace.  Blank lines and comment lines are ignored.</para>
        </section>
        <section role="NotInToc">
            <title>Detailed Information</title>
            <para>For more information about configuring name resolution, refer to <xref linkend="how2dns" />.</para>
        </section>
    </section>
</chapter>