=========
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) <swupd.1.html>`__ 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) <swupd.1.html>`__.

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) <swupd.1.html>`__ 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 <unit>``.

To enable services to start at boot time, use ``systemctl enable <unit>``.


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) <swupd.1.html>`__
* ``systemd``\(1)
* https://clearlinux.org/documentation/
* https://clearlinux.org/features/stateless
* https://github.com/clearlinux/swupd-client/
