.. _master_config:

====================
Master Configuration
====================


Master configuration file is the one that usually at
``/etc/lithos/master.yaml`` and defines small subset of global configuration
parameters. Minimal configuration is an *empty file* but it **must exist**
anyway. Here is the reference of the parameters along with the default values:

.. opt:: sandboxes-dir

    The directory for per-application configuration files which contain limits
    of what application might use. If path is relative it's relative to
    the directory where configuration file is. Default is ``./sandboxes``.

.. opt:: processes-dir

    The directory for per-application configuration files which contain name of
    image directory, instance number, etc., to run. If path is relative it's
    relative to the directory where configuration file is. Default is
    ``./processes``.

.. opt:: runtime-dir

    The directory where ``pid`` file of master process is stored and also
    the base directory for ``state-dir`` and ``mount-dir``. Path must be
    absolute. It's expected to be stored on ``tmpfs``. Default
    ``/run/lithos``.

.. opt:: state-dir

    The directory where to keep container's state dirs. If path is relative
    it's relative to ``runtime-dir``. Default ``state``
    (i.e. ``/run/lithos/state``). Path should be on ``tmpfs``.

.. opt:: mount-dir

    An empty directory to use for mounting. If path is relative it's relative
    to ``runtime-dir``. Default ``mnt``.

.. opt:: devfs-dir

    The directory where ``/dev`` filesystem for container exists. If it's
    not ``/dev`` (which is not recommended), you should create the directory
    with ``lithos_mkdev`` script. Default ``/var/lib/lithos/dev``.

.. opt:: cgroup-name

    The name of the root cgroup for all lithos processes. Specify ``null`` (or
    any other form of YAMLy null) to turn cgroups off completely.

.. opt:: cgroup-controllers

    List of cgroup controllers to initialize for each container. Note: the
    empty list is treated as default. Default is
    ``[name, cpu, cpuacct, memory, blkio]``. If you have some controllers
    joined together like ``cpu,cpuacct`` it's ok.

    Use ``cgroup-name: null`` to turn cgroup tracking off (not empty list
    here).  And use ``cgroup-controllers: [name]`` to only use cgroups for
    naming processes but not for resource control.

    .. note:: turning off cgroups means that resource limits does not work
       completely. lithos will not try to enforce them by polling or some
       other means

.. opt:: default-log-dir

   (default ``/var/log/lithos``) The directory where master and each of the
   application logs are created (unless are overrided by sandbox config).

.. opt:: config-log-dir

   (default ``/var/log/lithos/config``) The directory where configurations of
   the processes are stored. These are used by ``lithos_clean`` to find out
   when it's safe to clean directories. You may also reconstruct
   processes configuration at any point in time using this directory.

   .. versionchanged:: 0.10.2

      Parameter can be ``null``:

      .. code-block:: yaml

         config-log-dir: null

      In this case no configuration logging is done. This is mainly useful if
      you track configurations and versions by some other means.

      .. note:: This is enabled by default for backwards-compatibility reasons.
         We consider resetting this value to ``null`` by default
         in ``lithos 1.0`` as this parameter is not as useful as were expected.


.. opt:: stdio-log-dir

   (default ``/var/log/lithos/stderr``) The directory where stderr of the
   processes will be forwarded. One file per sandbox is created.

   These files are created by lithos and file descriptor is passed to the
   application as both the stdout and stderr. Lithos does not parse, copy or
   otherwise proxy the data. The operating system does all the work. This also
   means lithos can't rotate or do any other magical things with the log.

   This should be used only to tackle the critical errors. Application should
   send log to a syslog or write some rotating log files on it's own, because
   there is no good tools to groups lines of the stderr into solid log messages
   that include tracebacks and other fancy stuff.

   Good utilities to manage the files:

   * ``logrotate`` in ``copytruncate`` mode
   * ``rsyslog`` with file input plugin

   This can be overridden in process by :opt:`stdout-stderr-file`.

   .. note:: The path is reopened on process restart.
      If :opt:`restart-process-only` is `true` then it's only reopened when
      configuration changes. This is good to know if you remove or rename
      the file by hand.

.. opt:: log-file

   (default ``master.log``) Master log file. Relative paths are treated from
   :opt:`default-log-dir`.

.. opt:: log-level

   (default ``warn``) Level of logging. Can be overriden on the command line.

.. opt:: syslog-facility

   (no default) Enables logging to syslog (with specified facility) instead of
   file.

.. opt:: syslog-name

   (default ``lithos``) Application name for master process in syslog. The
   child processes are prefixed by this value. For example ``lithos-django``
   (where ``django`` is a sandbox name).