salt/doc/ref/file_server/backends.rst

.. _file-server-backends:

====================
File Server Backends
====================

In Salt 0.12.0, the modular fileserver was introduced. This feature added the
ability for the Salt Master to integrate different file server backends. File
server backends allow the Salt file server to act as a transparent bridge to
external resources. A good example of this is the :mod:`git
<salt.fileserver.git>` backend, which allows Salt to serve files sourced from
one or more git repositories, but there are several others as well. Click
:ref:`here <all-salt.fileserver>` for a full list of Salt's fileserver
backends.

Enabling a Fileserver Backend
-----------------------------

Fileserver backends can be enabled with the :conf_master:`fileserver_backend`
option.

.. code-block:: yaml

    fileserver_backend:
      - git

See the :ref:`documentation <all-salt.fileserver>` for each backend to find the
correct value to add to :conf_master:`fileserver_backend` in order to enable
them.

Using Multiple Backends
-----------------------

If :conf_master:`fileserver_backend` is not defined in the Master config file,
Salt will use the :mod:`roots <salt.fileserver.roots>` backend, but the
:conf_master:`fileserver_backend` option supports multiple backends. When more
than one backend is in use, the files from the enabled backends are merged into a
single virtual filesystem. When a file is requested, the backends will be
searched in order for that file, and the first backend to match will be the one
which returns the file.

.. code-block:: yaml

    fileserver_backend:
      - roots
      - git

With this configuration, the environments and files defined in the
:conf_master:`file_roots` parameter will be searched first, and if the file is
not found then the git repositories defined in :conf_master:`gitfs_remotes`
will be searched.

Defining Environments
---------------------

Just as the order of the values in :conf_master:`fileserver_backend` matters,
so too does the order in which different sources are defined within a
fileserver environment. For example, given the below :conf_master:`file_roots`
configuration, if both ``/srv/salt/dev/foo.txt`` and ``/srv/salt/prod/foo.txt``
exist on the Master, then ``salt://foo.txt`` would point to
``/srv/salt/dev/foo.txt`` in the ``dev`` environment, but it would point to
``/srv/salt/prod/foo.txt`` in the ``base`` environment.

.. code-block:: yaml

    file_roots:
      base:
        - /srv/salt/prod
      qa:
        - /srv/salt/qa
        - /srv/salt/prod
      dev:
        - /srv/salt/dev
        - /srv/salt/qa
        - /srv/salt/prod

Similarly, when using the :mod:`git <salt.fileserver.gitfs>` backend, if both
repositories defined below have a ``hotfix23`` branch/tag, and both of them
also contain the file ``bar.txt`` in the root of the repository at that
branch/tag, then ``salt://bar.txt`` in the ``hotfix23`` environment would be
served from the ``first`` repository.

.. code-block:: yaml

    gitfs_remotes:
      - https://mydomain.tld/repos/first.git
      - https://mydomain.tld/repos/second.git

.. note::

    Environments map differently based on the fileserver backend. For instance,
    the mappings are explicitly defined in :mod:`roots <salt.fileserver.roots>`
    backend, while in the VCS backends (:mod:`git <salt.fileserver.gitfs>`,
    :mod:`hg <salt.fileserver.hgfs>`, :mod:`svn <salt.fileserver.svnfs>`) the
    environments are created from branches/tags/bookmarks/etc. For the
    :mod:`minion <salt.fileserver.minionfs>` backend, the files are all in a
    single environment, which is specified by the :conf_master:`minionfs_env`
    option.

    See the documentation for each backend for a more detailed explanation of
    how environments are mapped.