diff options
| -rw-r--r-- | src/admin/10_help.xml | 6 | ||||
| -rw-r--r-- | src/admin/11_quickref.xml | 6 | ||||
| -rw-r--r-- | src/admin/1_intro.xml | 8 | ||||
| -rw-r--r-- | src/admin/3_packages.xml | 6 | ||||
| -rw-r--r-- | src/admin/4_services.xml | 5 | ||||
| -rw-r--r-- | src/admin/5_networking.xml | 50 | ||||
| -rw-r--r-- | src/admin/6_security.xml | 8 | ||||
| -rw-r--r-- | src/admin/7_config.xml | 339 | ||||
| -rw-r--r-- | src/admin/8_fslayout.xml | 14 | ||||
| -rw-r--r-- | src/admin/9_standards.xml | 2 | ||||
| -rw-r--r-- | src/admin/adminbook.xml | 2 |
11 files changed, 344 insertions, 102 deletions
diff --git a/src/admin/10_help.xml b/src/admin/10_help.xml index 5cb0021..2fb8559 100644 --- a/src/admin/10_help.xml +++ b/src/admin/10_help.xml @@ -2,7 +2,7 @@ <chapter label="10" id="help"> <title>If You Need Help</title> <highlights><para>If you experience an issue that you cannot solve by reading the Adélie Linux documentation, there are a large variety of avenues available to you to ask the community for help.</para></highlights> - <section> + <section id="mailing_lists"> <title>Mailing Lists</title> <para>The Adélie Linux mailing lists are a great way to obtain answers to any number of issues. Helpful members of the community, along with most of the Adélie Linux development team, are always monitoring the mailing lists and are ready to help you with your issue. There are three main mailing lists that would be of interest to systems administrators:</para> <itemizedlist> @@ -26,13 +26,13 @@ </listitem> </itemizedlist> </section> - <section> + <section id="chat"> <title>Community Chat</title> <para>The Adélie Linux community has a dedicated online chat system for asking quick questions about using the Adélie Linux system. We welcome all of our users to our chat, and we look forward to seeing you! Please note that detailed or complex issues may be referred to the mailing lists.</para> <para>The chat system uses the Internet Relay Chat (IRC) protocol; to join the chat, you will need to use an IRC client. Three popular clients are packaged in the Adélie Linux system: <package>Konversation</package> (the KDE IRC client), <package>Quassel</package> (a popular Qt IRC client), and <package>WeeChat</package> (a terminal-based IRC client).</para> <para>To join our chat, connect to the Interlinked IRC network at irc.interlinked.me (TLS port 6697), and then join the #Adelie-Support channel.</para> </section> - <section> + <section id="more_help"> <title>Other avenues of support</title> <para>If you have found an issue with a package (a segmentation fault, crash, or hang/freeze), you may file an issue at <ulink url="https://bts.adelielinux.org/">the Adélie Linux issue tracker</ulink>.</para> <para>The <ulink url="https://www.reddit.com/r/AdelieLinux/">Adélie Linux sub on Reddit</ulink> is sometimes used for asking for help, but it is highly recommended to use the mailing lists instead.</para> diff --git a/src/admin/11_quickref.xml b/src/admin/11_quickref.xml index eab36e9..d9e2448 100644 --- a/src/admin/11_quickref.xml +++ b/src/admin/11_quickref.xml @@ -2,7 +2,7 @@ <chapter label="11" id="quickref"> <title>Quick References</title> <highlights><para>In this chapter, we will lay out common tasks and how to perform them using Adélie Linux.</para></highlights> - <section> + <section id="quick_apk"> <title>Package management</title> <table> <title>Package management command quick-reference</title> @@ -38,7 +38,7 @@ </tgroup> </table> </section> - <section> + <section id="quick_rc"> <title>Service management</title> <table> <title>Service management command quick-reference</title> @@ -82,7 +82,7 @@ </tgroup> </table> </section> - <section> + <section id="quick_net"> <title>Networking</title> <table> <title>Networking command quick-reference</title> diff --git a/src/admin/1_intro.xml b/src/admin/1_intro.xml index 17bb2b3..3a77db5 100644 --- a/src/admin/1_intro.xml +++ b/src/admin/1_intro.xml @@ -2,7 +2,7 @@ <chapter label="1" id="introduction"> <title>Introduction</title> <highlights><para>Welcome to the Adélie Linux 1.0 Administrator's Handbook. You'll learn a lot about how to administrate your Adélie Linux computer. We'll get started by looking at how Adélie Linux compares to other popular operating environments. We will also review some of the software used that will feature in the chapters ahead.</para></highlights> - <section> + <section id="compare"> <title>Comparison of Adélie with other environments</title> <para>Adélie Linux is a Linux distribution focused on security, speed, reliability, and correctness. Since it is based on the Linux kernel, it shares some common traits with other Linux distributions. However, it has many unique facets as well.</para> <para>One of the defining differences of Adélie Linux is the commitment to run on many different hardware platforms. The first comparison we will review is the hardware platforms that various environments support.</para> @@ -306,7 +306,7 @@ </tgroup> </table> </section> - <section> + <section id="differences"> <title>What sets Adélie apart</title> <para>The Adélie Linux operating environment has many features that stand out from other environments.</para> <section> @@ -328,9 +328,9 @@ <para>Adélie Linux supports many different hardware platforms, allowing you to truly use your hardware your way. All Adélie Linux packages are tested on all tier 1 architectures before being released. From your PowerPC/POWER workstation, to your dusty old Intel x86 notebook, to your ARM 64 tablet, you can ensure you are getting the most from your computers by using Adélie Linux on them.</para> </section> </section> - <section> + <section id="familiarising"> <title>Familiarising yourself with Adélie</title> - <para>Now it's time to go over a brief run-down of the day-to-day administration of an Adélie system. These will be covered with more depth in later chapters.</para> + <para>Now let's brief go over some of the essentials of day-to-day administration of an Adélie Linux system. These will be covered with more depth in later chapters.</para> <section> <title>The shell environment</title> <para>The <firstterm>shell environment</firstterm>, also called a terminal or console, is an interface where you type commands in to a command processor (the <firstterm>shell</firstterm>), and view the results of the command on your screen. Windows users may know this environment as a "Command Prompt". The shell environment is an essential part of administrating any Linux system. Adélie Linux is designed to make the shell environment easy to use while still providing you the ability to view and edit nearly every detail about your system.</para> diff --git a/src/admin/3_packages.xml b/src/admin/3_packages.xml index e7e70bb..58ca9a1 100644 --- a/src/admin/3_packages.xml +++ b/src/admin/3_packages.xml @@ -2,7 +2,7 @@ <chapter label="3" id="packages"> <title>Package Management</title> <highlights><para>In this chapter, we will discuss package management in the Adélie Linux operating environment, including the APK package manager.</para></highlights> - <section> + <section id="introduction3"> <title>Introduction</title> <para>We'll start off by learning what a package is, and about the package manager used by Adélie Linux.</para> <section> @@ -17,7 +17,7 @@ <para>APK refers the entire set of packages you have chosen to install on your computer as a "<firstterm>world</firstterm>". When you install a package, you are adding it to the "world". When you uninstall a package, you are removing it from the "world". The world file exists at <filename>/etc/apk/world</filename> and is a text file with each package you have chosen to install on a single line.</para> </section> </section> - <section> + <section id="install_uninstall"> <title>Installing and uninstalling packages</title> <para>When you want to install a package on your Adélie Linux system, you may use the command <command>apk add <userinput>PACKAGE</userinput></command>, where <userinput>PACKAGE</userinput> is the name of the package you want to install. You may install multiple packages at the same time by separating them with spaces. For example, <command>apk add firefox thunderbird</command> will install the Firefox web browser and Thunderbird email client.</para> <para>To uninstall a package on your Adélie Linux system, you may use the command <command>apk del <userinput>PACKAGE</userinput></command>, where <userinput>PACKAGE</userinput> is the name of the package you want to uninstall. As with package installation, you may uninstall multiple packages at the same time by separating them with spaces.</para> @@ -29,7 +29,7 @@ World updated, but the following packages are not removed due to: </screen> <para>This indicates that the <package>fts</package> package was removed from your "world" file (if it was listed there), but it is still required by the <package>dracut</package> package that is currently installed on your computer.</para> </section> - <section> + <section id="integrity"> <title>Ensuring package integrity</title> <para>The APK package manager can help you ensure continuing system integrity, and can also help you correct some issues as they arise. Every file installed on your computer by APK has a cryptographic signature and checksum. You may use the command <command>apk audit</command> to audit your entire system for integrity, or <command>apk audit <userinput>PATH</userinput></command> to audit a specific file or directory on your system. Note that <userinput>PATH</userinput> must be an <firstterm>absolute path</firstterm>; it must be the entire path beginning with a /. For example, the command <command>apk audit /usr/bin/vim</command> is valid; the command <command>apk audit vim</command>, even if it is run from inside the /usr/bin directory, is not.</para> <para>The typical output of an <command>apk audit</command> run will look something like the following:</para> diff --git a/src/admin/4_services.xml b/src/admin/4_services.xml index 7be2602..85b9414 100644 --- a/src/admin/4_services.xml +++ b/src/admin/4_services.xml @@ -27,12 +27,11 @@ <para>To view the status of all services on your system, you may use the command <command>rc-status</command>. If any services are listed under "Dynamic Runlevel: manual", these are services that have been started but do not belong to any runlevel. That means they have been started without being enabled first, and will not automatically start on next system boot.</para> </section> </section> - <section> + <section id="at"> <title>Scheduling a process to run later</title> <warning><title>Not Yet Written</title><para>This section has not yet been written.</para></warning> - <para>You may wish to run a command at a specific time. Therefore, we should describe <command>at</command> here some day.</para> </section> - <section> + <section id="cron"> <title>Scheduling a process to run periodically</title> <warning><title>Not Yet Written</title><para>This section has not yet been written.</para></warning> </section> diff --git a/src/admin/5_networking.xml b/src/admin/5_networking.xml index 06bd313..1febe4b 100644 --- a/src/admin/5_networking.xml +++ b/src/admin/5_networking.xml @@ -2,7 +2,7 @@ <chapter label="5" id="networking"> <title>Networking</title> <highlights><para>In this chapter, we will discuss how to configure your Adélie Linux system for networking. Wired, wireless, and VPN connections using both static and dynamic IP addressing will be covered. In addition, advanced topics including interface bondage and KVM configuration will also be discussed.</para></highlights> - <section> + <section id="introduction5"> <title>Introduction</title> <para>The Adélie Linux system uses <firstterm><package>netifrc</package></firstterm> as its network configuration and management system. The netifrc system uses a declarative configuration syntax in a single file, <filename>/etc/conf.d/net</filename>, for ease of administration. All main system network configuration is declared in this file. Some additional configuration may be required for wireless or VPN connections; notably, wireless connections require WPA Supplicant to be configured using either <package>wpa_gui</package> (on computers that use X11), or in the <filename>/etc/wpa_supplicant/wpa_supplicant.conf</filename> file.</para> <para>The default configuration for the Adélie Linux system uses the traditional Linux interface names (such as "eth0", "eth1", and "wlan0"). If you prefer the new "predictable" interface names (such as "enP2p36s15f0" or "wlp9s0"), refer to <xref linkend="crappy_udev_ifs" />.</para> @@ -17,7 +17,7 @@ <para>Before we begin configuring the network, we will list the network adaptors available on your computer. This will ensure that the adaptor or adaptors were detected successfully by the kernel. To do this, ensure the <package>iproute2</package> package is installed, and run the command <command>ip link</command> as root.</para> </section> </section> - <section> + <section id="wired"> <title>Wired connections</title> <para>For the purposes of this handbook, a <firstterm>wired connection</firstterm> is a connection to a network that utilises Ethernet. While the Adélie Linux system supports ATM, CAN bus, IEEE 1394, and Token Ring networking, these connection types are exceedingly rare and out of the scope of this handbook.</para> <section id="how2dhcp"> @@ -42,42 +42,42 @@ nameserver 84.200.69.80 </section> </section> </section> - <section> + <section id="wireless"> <title>Wireless connections</title> <para></para> - <section> + <section id="wpa"> <title>WPA-based authentication</title> - <para></para> + <warning><title>Not Yet Written</title><para>This section has not yet been written.</para></warning> </section> - <section> + <section id="radius"> <title>RADIUS (certificate-based) authentication</title> - <para></para> + <warning><title>Not Yet Written</title><para>This section has not yet been written.</para></warning> </section> - <section> + <section id="multi_ap"> <title>Configuring for multiple access points</title> - <para></para> + <warning><title>Not Yet Written</title><para>This section has not yet been written.</para></warning> </section> </section> - <section> + <section id="vpn"> <title>VPN connections</title> <para></para> - <section> + <section id="openvpn"> <title>OpenVPN</title> - <para></para> + <warning><title>Not Yet Written</title><para>This section has not yet been written.</para></warning> </section> - <section> + <section id="strongswan"> <title>StrongSwan</title> - <para></para> + <warning><title>Not Yet Written</title><para>This section has not yet been written.</para></warning> </section> </section> - <section> + <section id="kvm"> <title>Virtual machine networking</title> <para></para> - <section> + <section id="hostonly"> <title>Networking guests with each other only</title> - <para></para> + <warning><title>Not Yet Written</title><para>This section has not yet been written.</para></warning> </section> - <section> + <section id="bridged_kvm"> <title>Sharing a host network with guests</title> <para>The Adélie Linux system can be configured to provide bridged networking to a QEMU virtual machine or KVM guest using TAP networking. You will need the <package>iproute2</package> package installed.</para> <para>First, we will need to add a <firstterm>bridge</firstterm> to netifrc. A bridge allows multiple network adaptors to combine multiple network segments into a single aggregate. For our purposes, we will be combining the physical network adaptor on the host with the virtual network adaptors on each guest. The bridge will have your physical network adaptor as its first member. This way, no network reconfiguration will be required when you start or stop virtual machines. You will need to move the configuration for your physical network adaptor to the bridge, so that all members of the bridge may share that connection. In the following example, the interface <literal>eth0</literal> is the physical adaptor and the bridge is set to use a static IPv6 address, which will then be used by the physical adaptor as well.</para> @@ -122,25 +122,25 @@ ip tuntap del name $1 <para>This will start a machine with network access and a MAC address of <literal>02:00:00:00:00:01</literal>.</para> </section> </section> - <section> + <section id="advanced"> <title>Advanced topics</title> <para></para> <section id="crappy_udev_ifs"> <title>Advanced: Using "predictable" network interface names</title> - <para></para> + <warning><title>Not Yet Written</title><para>This section has not yet been written.</para></warning> </section> - <section> + <section id="multi_if"> <title>Advanced: Multiple interfaces</title> <para></para> <para>Note that by default, all interfaces must be active before the rest of the system will consider the network to be active. This will cause network services to delay start-up until all interfaces are active. If this is not desired, you may set <varname>rc_depend_strict</varname> to <literal>NO</literal> in <filename>/etc/rc.conf</filename>.</para> </section> - <section> + <section id="bondage"> <title>Advanced: Interface bondage</title> - <para></para> + <warning><title>Not Yet Written</title><para>This section has not yet been written.</para></warning> </section> - <section> + <section id="eth_auth"> <title>Advanced: 802.1X authentication</title> - <para></para> + <warning><title>Not Yet Written</title><para>This section has not yet been written.</para></warning> </section> <section id="dhcphax"> <title>Advanced: Customising dynamic addressing</title> diff --git a/src/admin/6_security.xml b/src/admin/6_security.xml index 18c16bd..f0226ee 100644 --- a/src/admin/6_security.xml +++ b/src/admin/6_security.xml @@ -2,12 +2,12 @@ <chapter label="6" id="security"> <title>Security</title> <highlights><para>In this chapter, we will review best practices for keeping your Adélie Linux systems secure.</para></highlights> - <section> + <section id="introduction6"> <title>Introduction to computer security</title> - <para>No one book can teach you everything about computer security. Computer security is not simply an item on a list that must be done once and then it is "completed". Computers are very powerful tools, and just as they can be used to teach, create, and produce, they can also be used for more nefarious purposes. By taking a proactive approach to computer security, and treating it as a process, you will be much more successful in keeping the security, confidentiality, and integrity of your data intact.</para> + <para>No one book can teach you everything about computer security. Computer security is not simply an item on a list that must be done once and then it is "completed". Computers are very powerful tools, and just as they can be used to teach, create, and produce, they can also be used for more nefarious purposes. By taking a proactive approach to computer security, and treating it as a process, you will be much more successful in keeping the security, confidentiality, and integrity of your data intact. You first need to identify your <firstterm>threat model</firstterm>; that is, what advisaries are you attempting to keep out? A sophisticated nation-state requires a much different security plan than a random hacker.</para> <para>The suggestions in this handbook are a starting point to help you develop an actionable plan to keep your computer secure. They are by no means exhaustive. Remember to always keep learning; knowledge is power.</para> </section> - <section> + <section id="apk_sec"> <title>APK</title> <itemizedlist> <listitem><para>Only use repositories and mirrors with HTTPS.</para></listitem> @@ -15,7 +15,7 @@ <listitem><para>Ensure any custom or third-party repositories have high-grade signature keys and that you trust the developers.</para></listitem> </itemizedlist> </section> - <section> + <section id="service_sec"> <title>Services</title> <itemizedlist> <listitem><para>If a service is only being used in your internal network, make sure it is configured to only accept connections from that network. This reduces the chance that an external attacker from the Internet can connect to it.</para></listitem> diff --git a/src/admin/7_config.xml b/src/admin/7_config.xml index 82c1548..deaaad1 100644 --- a/src/admin/7_config.xml +++ b/src/admin/7_config.xml @@ -2,7 +2,7 @@ <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> + <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> @@ -12,7 +12,7 @@ <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> + <section id="e-abuild"> <title><filename>/etc/abuild.conf</filename>: Package build configuration</title> <section role="NotInToc"> <title>Purpose</title> @@ -43,7 +43,7 @@ <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> + <section id="e-asound"> <title><filename>/etc/asound.conf</filename>: System audio configuration</title> <section role="NotInToc"> <title>Purpose</title> @@ -58,7 +58,7 @@ <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> + <section id="e-b-b"> <title><filename>/etc/bash/bashrc</filename>: Bash shell startup configuration</title> <section role="NotInToc"> <title>Purpose</title> @@ -73,7 +73,7 @@ <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> + <section id="e-c-alsa"> <title><filename>/etc/conf.d/alsa</filename>: Mixer level configuration</title> <section role="NotInToc"> <title>Purpose</title> @@ -88,7 +88,7 @@ <para>For more information, refer to the comments in the <filename>/etc/conf.d/alsa</filename> file.</para> </section> </section> - <section> + <section id="e-c-bootmisc"> <title><filename>/etc/conf.d/bootmisc</filename>: Boot behaviour configuration</title> <section role="NotInToc"> <title>Purpose</title> @@ -100,7 +100,7 @@ </section> <section role="NotInToc"> <title>Detailed Information</title> - <para>The following variables are configurable in the <filename>/etc/conf.d/bootmisc</filename> file:</para> + <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"> @@ -137,7 +137,7 @@ </table> </section> </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> @@ -152,7 +152,7 @@ <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> + <section id="e-c-dmesg"> <title><filename>/etc/conf.d/dmesg</filename>: <literal>dmesg</literal> configuration</title> <section role="NotInToc"> <title>Purpose</title> @@ -167,7 +167,7 @@ <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> + <section id="e-c-fsck"> <title><filename>/etc/conf.d/fsck</filename>: Startup file system check configuration</title> <section role="NotInToc"> <title>Purpose</title> @@ -179,7 +179,7 @@ </section> <section role="NotInToc"> <title>Detailed Information</title> - <para>The following variables are configurable in the <filename>/etc/conf.d/fsck</filename> file:</para> + <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"> @@ -221,7 +221,7 @@ </table> </section> </section> - <section> + <section id="e-c-gettys"> <title><filename>/etc/conf.d/gettys</filename>: System console configuration</title> <section role="NotInToc"> <title>Purpose</title> @@ -249,7 +249,7 @@ <important><title>Important</title><para>Changes to this file will not take effect until the system is restarted.</para></important> </section> </section> - <section> + <!-- <section> <title><filename>/etc/conf.d/hwclock</filename>: System time configuration</title> <section role="NotInToc"> <title>Purpose</title> @@ -263,110 +263,353 @@ <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> - <title><filename>/etc/conf.d/keymaps</filename>: Keyboard layout configuration</title> + <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/keymaps</filename> file determines certain behaviours of the keyboard connected to the system console.</para> + <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. Variables are in lowercase. Booleans may be set as <literal>YES</literal> or <literal>NO</literal>.</para> + <para>Shell script style.</para> </section> <section role="NotInToc"> <title>Detailed Information</title> - <para>The <filename>/etc/conf.d/keymaps</filename> file </para> + <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/modules</filename>: Kernel module configuration</title> + <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/</filename> file </para> + <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 </para> + <para>Shell script. Variables are in lowercase.</para> </section> <section role="NotInToc"> <title>Detailed Information</title> - <para></para> + <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> - <title><filename>/etc/conf.d/net</filename>: Network configuration</title> + <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/conf.d/net</filename> file determines the configuration of the network adaptor(s) installed in the system.</para> + <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.</para> + <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>Refer to <xref linkend="networking" /> for information on configuring networks using the Adélie Linux system.</para> + <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> - <title><filename>/etc/conf.d/netmount</filename>: Network file system configuration</title> + <section id="e-fstab"> + <title><filename>/etc/fstab</filename>: Filesystem mount point configuration</title> <section role="NotInToc"> <title>Purpose</title> - <para>The <filename>/etc/conf.d/</filename> file </para> + <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>Shell script. Variables are in </para> + <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></para> + <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 — with the default Adélie Linux kernel, this is "<literal>adelie</literal>".</para> </section> </section> - <section> - <title><filename>/etc/conf.d/swap</filename>: Network swap file configuration</title> + <section id="e-inputrc"> + <title><filename>/etc/inputrc</filename>: Bash shell keyboard configuration</title> <section role="NotInToc"> <title>Purpose</title> - <para>The <filename>/etc/conf.d/</filename> file </para> + <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>Shell script. Variables are in </para> + <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><escape sequence></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></para> + <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> - <title><filename>/etc/conf.d/udev-trigger</filename>: Hardware hot-plug configuration</title> + <section id="e-login-defs"> + <title><filename>/etc/login.defs</filename>: Login configuration</title> <section role="NotInToc"> <title>Purpose</title> - <para>The <filename>/etc/conf.d/</filename> file </para> + <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>Shell script. Variables are in </para> + <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></para> + <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> - <title><filename>/etc/conf.d/urandom</filename>: Random number configuration</title> + <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>/etc/conf.d/</filename> file </para> + <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 script. Variables are in </para> + <para>Shell scripts.</para> </section> <section role="NotInToc"> <title>Detailed Information</title> - <para></para> + <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> diff --git a/src/admin/8_fslayout.xml b/src/admin/8_fslayout.xml index 3aac814..e34b78c 100644 --- a/src/admin/8_fslayout.xml +++ b/src/admin/8_fslayout.xml @@ -2,13 +2,13 @@ <chapter label="8" id="fslayout"> <title>File System Layout</title> <highlights><para>In this chapter, we will review directories and files common to all Adélie Linux systems. Adélie Linux is based on the Filesystem Hierarchy Standard (FHS) 3.0 specification; directories and files specified in FHS are not covered here.</para></highlights> - <section> + <section id="etc"> <title><filename class="directory">/etc</filename>: Host-specific system configuration</title> - <section> + <section role="NotInToc"> <title>Purpose</title> <para>As in FHS, the /etc hierarchy contains configuration files specific to a single host.</para> </section> - <section> + <section role="NotInToc"> <title>Requirements</title> <para>The following directories, or symbolic links to directories, must be present in <filename class="directory">/etc</filename>:</para> <table frame="none"> @@ -47,7 +47,7 @@ </tgroup> </table> </section> - <section> + <section role="NotInToc"> <title>Specific Options</title> <para>The following files, or symbolic links to files, must be present in <filename class="directory">/etc</filename>, if the corresponding subsystem is installed:</para> <table frame="none"> @@ -76,13 +76,13 @@ </tgroup> </table> </section> - <section> + <section id="etc-apk"> <title><filename class="directory">/etc/apk</filename>: Configuration files for the package manager</title> - <section> + <section role="NotInToc"> <title>Purpose</title> <para><filename class="directory">/etc/apk</filename> is used for configuring the Adélie Linux package manager, as described in <xref linkend="packages"/>.</para> </section> - <section> + <section role="NotInToc"> <title>Requirements</title> <para>The following directories, or symbolic links to directories, must be present in <filename class="directory">/etc/apk</filename>:</para> <table frame="none"> diff --git a/src/admin/9_standards.xml b/src/admin/9_standards.xml index 746f490..7b2b3a8 100644 --- a/src/admin/9_standards.xml +++ b/src/admin/9_standards.xml @@ -2,7 +2,7 @@ <chapter label="9" id="standards"> <title>Standards Conformance</title> <highlights><para>In this chapter, we will review the standards with which the Adélie Linux operating environment is certified to be conformant.</para></highlights> - <section> + <section id="fhs3"> <title>Filesystem Hierarchy Standard 3.0</title> <para>The Adélie Linux operating environment is believed to be fully compliant with the <ulink url="http://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html">Filesystem Hierarchy Standard, version 3.0</ulink>. If you find an issue that may cause non-conformance while using Adélie Linux, please file an issue at the <ulink url="https://bts.adelielinux.org/">Adélie Linux Issue Tracker</ulink>.</para> </section> diff --git a/src/admin/adminbook.xml b/src/admin/adminbook.xml index c91a91f..0c94bd2 100644 --- a/src/admin/adminbook.xml +++ b/src/admin/adminbook.xml @@ -35,7 +35,7 @@ </bookinfo> <preface> <title>Preface</title> - <para>This Administrator's Handbook is the official comprehensive manual to administrating systems running the Adélie Linux 1.0 operating environment. It includes differences between Adélie Linux and other Linux and Unix® environments, and detailed information on the design and implementation of Adélie Linux 1.0.</para> + <para>This Administrator's Handbook is the official comprehensive manual for the day-to-day use and administration of systems running the Adélie Linux 1.0 operating environment. It additionally includes differences between Adélie Linux and other Linux and Unix® environments, and detailed information on the design and implementation of Adélie Linux 1.0.</para> <para>Many contributed to the final version of this handbook. This includes <personname><firstname>Marcus</firstname><surname>Comstedt</surname></personname>, <personname><firstname>Michael</firstname><surname>Siegel</surname></personname>, and <personname><firstname>Tambra</firstname><surname>Wilcox</surname></personname>.</para> <para>It is assumed that you, the reader, are familiar with using a terminal or command line interface, and the use of Unix commands. If you are not yet familiar with these concepts, start with our User's Handbook, which will assist you in learning them.</para> <para>Please also ensure that you are comfortable and properly rested before reading this handbook. This will allow you to learn quicker, and be able to recall the information you have learned easier.</para> |