# Stateless¶

In most operating systems, user data, system data, and configuration files can become intermingled, which can make them challenging to manage.

Figure 1: Without stateless, user and system files become mixed on the filesystem over time.

Clear Linux* OS has a stateless design philosophy with the goal to provide an OS that functions without excessive user configuration or customization. Stateless in this context does not mean ephemeral or non-persistent.

## File-level separation¶

To accomplish a stateless design, the Clear Linux OS filesystem hierarchy is separated between user-owned areas and Clear Linux OS-owned areas.

Figure 2: With stateless, user and system files are separated on the filesystem.

### System area¶

Files under the /usr directory are managed by Clear Linux OS as system files (except /usr/local). Files written under the /usr directory by users can get removed through system updates with swupd. This operating assumption allows Clear Linux OS to verify and maintain integrity of system files.

### User areas¶

Files under the /usr/local, /etc/, /opt, /home, and /var directories are owned and managed by the user. A freshly installed Clear Linux OS system will only have a minimal set of files in the /etc/ directory and software installed by Clear Linux OS does not write to /etc. This operating assumption allows Clear Linux OS users to clearly identify the configuration that makes their system unique.

## Software configuration¶

With stateless separation, default software configurations are read in order from predefined source code, Clear Linux OS provided defaults, and user-provided configuration.

### Default configurations¶

Software in Clear Linux OS provides default configuration values so that it is immediately functional, except for some that require additional configuration.

If an upstream software puts default configurations in multiple locations such as /usr/ and /etc, it will be modified by the Clear Linux OS distro to comply with the stateless design. Also, some default configurations may be modified to close security loopholes. Defaults will reside under /usr/share/defaults. These files can be referenced as templates for customization.

For example, after installing the httpd bundle for Apache web server, its default configurations appear in the /usr/share/defaults/httpd/ directory.

### Overriding configurations¶

If a configuration needs to be changed, the appropriate file should be modified by the user under /etc/. If the configuration file does not already exist, it can be created in the appropriate location.

User-defined configuration files should contain the minimal set of desired changes and rely on default configuration for the rest.

For example, a customized Apache configuration can be used instead by:

1. Install the Apache web server bundle.

sudo swupd bundle-add httpd

2. Create the destination directory for the configuration.

sudo mkdir /etc/httpd

3. Copy the default configuration as a reference template.

sudo cp /usr/share/defaults/httpd/httpd.conf /etc/httpd/

4. Make any desired modifications to the configurations.

sudoedit /etc/httpd/httpd.conf

5. Reload the service or reboot the system to pickup any changes.

systemctl daemon-reload httpd && systemctl restart httpd


This pattern can be used to modify the configurations of other programs too. The stateless man page has application-specific examples.

## System reset¶

One advantage of the stateless design is that the system defaults can be easily restored by simply deleting everything under /etc/ and /var.

Running the commands below effectively performs a system reset as if it was just installed:

sudo rm -rf /etc
sudo rm -rf /var


In other Linux distributions, this can be a catastrophic action that may render a system unable to boot and/or inaccessible.