.. highlight:: ini

===============
 Configuration
===============

The backup "app" you have installed is really just Rattail proper, so
the config we will describe adheres to normal Rattail conventions.
See :doc:`/base/config/index` for more background on that.

We put all pertinent config in one file at
``/srv/envs/backup/app/rattail.conf`` and this will control behavior
of the ``rattail backup`` command.


Config File: ``rattail.conf``
=============================

This is the primary config file for the backup app.  Out of necessity
it will vary for different people and the different machines they need
to backup.  As such there is no "official" copy to be deployed by
Fabric.

So create the file at ``/srv/envs/backup/app/rattail.conf`` and in it
put these contents as your starting point::

   ############################################################
   #
   # config for backups
   #
   ############################################################


   ##############################
   # rattail
   ##############################

   [rattail]
   timezone.default = America/Chicago

   [rattail.config]
   configure_logging = true

   [rattail.backup]
   dbdump = true
   rsync = false
   borg.enabled = false


   ##############################
   # logging
   ##############################

   [loggers]
   keys = root

   [handlers]
   keys = file, console

   [formatters]
   keys = generic, console

   [logger_root]
   handlers = file, console
   level = DEBUG

   [handler_file]
   class = handlers.RotatingFileHandler
   args = ('/srv/envs/backup/app/log/rattail.log', 'a', 1000000, 20, 'utf_8')
   formatter = generic

   [handler_console]
   class = StreamHandler
   args = (sys.stderr,)
   formatter = console

   [formatter_generic]
   format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(funcName)s: %(message)s
   datefmt = %Y-%m-%d %H:%M:%S

   [formatter_console]
   format = %(levelname)-5.5s [%(name)s][%(threadName)s] %(funcName)s: %(message)s

.. caution::
   It is a good idea to "lock down" this file.  There are no secrets
   (passwords etc.) in the example above, but it's possible you may
   need to add them in the future, e.g. Borg encryption passphrase.
   So it's recommended that you go ahead and lock this down now:

   .. code-block:: sh

      sudo chown rattail: /srv/envs/backup/app/rattail.conf
      sudo chmod 0600 /srv/envs/backup/app/rattail.conf

The above config file says the following:

* declares local time zone to be ``America/Chicago``
* tells Rattail that it should configure logging

  * logging should be written to file at ``/srv/envs/backup/app/log/rattail.log``
  * log file should be rotated when it reaches ~1MB
  * logging also should go to console

* when ``rattail backup`` runs, it should:

  * dump all databases to file (for postgres and mysql)
  * do *not* run ``rsync``
  * do *not* run ``borg create``

Later on we'll describe how to enable more features etc.  But it's
recommended to follow along in order, and get the basics working
first.


Config File: ``silent.conf``
============================

The convention is to make ``rattail.conf`` specify ``DEBUG`` as the
main log level, not only for logging to file but also to console.  For
instance that is what the above example does.

So the convention also is to add a ``silent.conf`` file which
suppresses "normal" noise for the console logging.  Warnings and
errors will still make it through, so "silent" does not mean "silent
failure" - just "no ambient noise".

Rattail can create this file for you:

.. code-block:: sh

   cd /srv/envs/backup
   sudo -u rattail bin/rattail -c app/rattail.conf make-config -T silent -O app

After that you can specify ``app/silent.conf`` for your commands when
you want them to be "silent" - e.g. when running overnight:

.. code-block:: sh

   cd /srv/envs/backup
   sudo -u rattail bin/rattail -c app/silent.conf backup --help

Note that ``silent.conf`` inherits from ``rattail.conf`` so all config
from that file will still be in effect.

.. note::
   When you run e.g. the default ``backup-everything`` script, if you
   pass the ``--verbose`` flag then it will use ``rattail.conf`` but
   if you do not then it will use ``silent.conf`` instead.