========= stateless ========= --------------------------------------------------------------------------- A guide to stateless configuration in Clear Linux OS for Intel Architecture --------------------------------------------------------------------------- :Copyright: \(C) 2017 Intel Corporation, CC-BY-SA-3.0 :Manual section: 7 SYNOPSIS ======== ``/etc/`` ``/usr/share/defaults/`` ``/usr/share/defaults/etc/`` ``/var/`` ``/var/cache/`` ``/usr/local/`` ``/usr/src/`` ``/usr/lib/kernel/`` ``/usr/lib/modules/`` DESCRIPTION =========== The Clear Linux OS for Intel Architecture has a unique way of providing customization and configuration to system administrators and users. This man page aims to provide both an explanation of what this method is and how users of Clear Linux can use it and benefit from it. The goal of "stateless" is to provide a system OS that functions without user configuration. A system should not require editing of configuration files by the end user before it is functional, nor should it place lengthy and confusing configuration files automatically in user-maintained file system areas (``/etc/``) by default. And additionally, any configuration placed in user-maintained configuration should be removable without breaking functionality. This is achieved by several methods, each of which implements a part of the stateless goal. * Removal of configuration files The first step taken to achieve stateless configuration is to embed proper default configuration values in the software. Any missing critical configuration value should have a built-in default value. * Providing of default configuration files outside of ``/etc/`` Software is adjusted to use a distribution provided default configuration file in ``/usr/share/defaults``. If no configuration file exists in ``/etc/`` for the software, the software must use the distribution default configuration file. * Allowing the end user to provide configuration in ``/etc/`` If the user provides a properly formatted configuration file in the ``/etc/`` filesystem area (or, wherever it is relevant for the software), the software is instructed to use this configuration file instead of any other. Consequences for the system administrator (user) ------------------------------------------------ The user should create configuration files as needed and avoid modifying distribution provided defaults. The filesystem folders and all content under ``/etc/`` and ``/var/`` may be modified as needed, but the content under ``/usr/``, ``/lib/``, ``/lib64/``, ``/bin/``, ``/sbin/`` should never be modified, and will be overwritten by `swupd(1) `__ as needed. Some default configuration structure and data is automatically created under ``/etc/`` and ``/var/``. The user may remove these file system structures entirely - a reboot of the OS should properly restore the system to its factory default. This may also provide the user with a way to repair a defective system configuration. The user should, if user configuration of a service is needed, attempt to place the configuration file in the ``/etc/`` structure as the service requests. Often, template files for the configuration format can be found under the ``/usr/share/defaults/`` file structure, and these files can be copied to the ``/etc/`` file structure. To modify system service configuration (``systemd``\(1) service units), the user should not touch or modify unit files under the ``/usr/`` file structure directly, as changes in those files will be lost after a system software update with `swupd(1) `__. A list of package specific hints and best practices is listed below. In many cases, the man pages for the respective packages also provides detailed information as to how to configure the software. Please consult the relevant manual pages for the software to find information on the specific syntax and options for each software. Where can I install system-wide files then? ------------------------------------------- `swupd(1) `__ has a list of exempted locations where the system administrator can place files that will not get overwritten or removed at all. The default whitelisted directories are: ``/usr/lib/modules`` ``/usr/lib/kernel`` ``/usr/local`` ``/usr/src`` Using these locations for your own software is highly recommended. Not only do these locations provide a standard FHS compliant way of adding local software, they are sufficiently separated from OS software that maintaining them will be much more simple. ldconfig -------- ``ldconfig``\(8) The default paths that the linker searches includes only ``/usr/lib64`` and paths below that. This explicitly omits ``/usr/local/``. If you compile libraries manually and install them in other paths, you may need to configure the ``ld.so``\(8) linker to find these before you run ``ldconfig``. For example: ``echo "/usr/local/lib" | sudo tee -a /etc/ld.so.conf`` ``sudo ldconfig`` systemd ------- ``systemd``\(1) Unit files can be created under ``/etc/systemd/system`` as needed and function normally. To override unit file options, the simplest method is to have ``systemctl``\(1) copy it for you by invoking it as: ``systemctl edit --full foo.service`` This creates an exact copy of the default unit file and invokes the editor for the user, allowing the user to override any part of the unit. Unit files can be started as normal with ``systemctl start ``. To enable services to start at boot time, use ``systemctl enable ``. sshd ---- ``sshd``\(8) ``sshd_config``\(5) The SSH daemon has all of its configuration built in and no template configuration file is present on the file system. The man page for ``sshd_config``\(5) explains the format, and it suffices to put only a single option in the file ``/etc/ssh/sshd_config`` For example, to enable X11 forwarding through sshd all one has to do is add one line containing ``X11Forwarding yes``. Other often used options include ``PermitRootLogin yes`` to allow root ssh login access, and the following 3 lines to disable password authentication entirely: ``ChallengeResponseAuthentication no`` ``PasswordAuthentication no`` ``UsePAM no`` To modify the listening port of sshd, one needs to determine whether ``sshd.socket`` or ``sshd.service`` is enabled first, since the methods for changing the port number depend on whether ``sshd``\(8) is controlling the port number, or whether ``systemd``\(1) is: ``systemctl is-enabled sshd.socket`` If enabled, the ``sshd.socket`` unit should be edited to modify the port: ``systemctl edit --full sshd.socket`` And, the user should modify the port number at ``ListenStream=`` to the desired new port number. If ``sshd.service`` is enabled, the user should create, and edit a new ``/etc/ssh/sshd_config`` file: ``mkdir -p /etc/ssh/`` ``vi /etc/ssh/sshd_config`` And add a line in that file that reads: ``Port 10022`` to, for instance, change the port number sshd.service will listen on to port 10022. Root login over SSH is disabled by default and should remain disabled for most systemd. However, in some cases this is acceptable and it can be easily enabled by adding the following line to ``/etc/ssh/sshd_config`` that reads: ``PermitRootLogin yes`` nginx ----- Nginx ships by default in a non-functional configuration. However, an example configuration file is present that can be used to enable a simple server. To use this template configuration, create: ``mkdir -p /etc/nginx/conf.d`` And then copy configuration templates over to this folder: ``cp /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf`` ``cp /usr/share/nginx/conf/server.conf.example /etc/nginx/conf.d/server.conf`` Edit the file to assure options such as SSL and PHP are enabled in the preferred method. In the default configuration, PHP is enabled to run listening to ``/run/php-fpm.sock``. The template file has PHP by default disabled, but the listed example lines can be uncommented to make the nginx service process php documents. php-fpm ------- ``php-fpm``\(8) Php's default configuration file doesn't allow us to provide an alternative as it is programmed to only read the builtin file. If you wish to have php-fpm use a different configuration, you must pass it a startup option to tell it where it is. This can be done by ``systemctl edit --full php-fpm.service``. That command copies the default php-fpm service unit to ``/etc/systemd/system/`` and allows the user to override any option. It spawns an editor with the copy. Then, the user should change the line: ``ExecStart=/usr/sbin/php-fpm --nodaemonize`` to: ``ExecStart=/usr/sbin/php-fpm --nodaemonize --fpm-config /etc/php-fpm.conf`` The template php-fpm.conf can be found at ``/usr/share/defaults/php/php-fpm.conf``. One should copy this to a place in ``/etc/``: ``cp /usr/share/defaults/php/php-fpm.conf /etc/php-fpm.conf`` Then, the user should edit ``/etc/php-fpm.conf`` and assure that configuration options are all properly set as needed. Care must be taken using the default ``pool`` configuration. If needed, the user should also create ``/etc/php-fpm.d/`` and include pool configuration files from either ``/usr/share/defaults/php/php-fpm.d/`` or copy them and modify them as needed as well, as well as adjust the ``include`` configuration option in ``php-fpm.conf`` to point to a new location for pool configuration files. Network interface management ---------------------------- Clear Linux has switched the network interface management model to be fully managed by NetworkManager when installed on real hardware. Previously, Ethernet interfaces were managed by systemd-networkd whereas Wi-Fi and others were managed by NetworkManager. Clear Linux cloud images continue to use systemd-networkd. When updating from previous versions of Clear Linux, the installation will be reconfigured to continue with systemd-networkd managing the Ethernet interfaces. Since the connectivity could be lost during the procedure, physical access to the system is required. To switch to NetworkManager for all the interfaces, the user should disable and stop systemd-networkd: ``sudo systemctl disable systemd-networkd`` ``sudo systemctl stop systemd-networkd`` Then, remove the file ``/etc/NetworkManager/conf.d/systemd-networkd-unmanaged.conf`` Finally, restart NetworkManager ``sudo systemctl restart NetworkManager`` SEE ALSO ======== * `swupd(1) `__ * ``systemd``\(1) * https://clearlinux.org/documentation/ * https://clearlinux.org/features/stateless * https://github.com/clearlinux/swupd-client/