DEBOPS.FHS(5)

NAME
debops.fhs - Create base directory hierarchy used by DebOps roles

SYNOPSIS

debops service/fhs [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

By default various DebOps application roles install their data in directories designated by the Filesystem Hierarchy Standard <https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard> for locally-installed software - for example /usr/local/bin/ for binaries, /usr/local/src/ for source code, and so on. To allow system administrators to easily change the preferred location of various resources without the need to modify multiple roles separately, the debops.fhs role is a central place which defines base directories for other roles to use.

The base directories are created by the role, and a special /etc/ansible/facts.d/fhs.fact script is generated on the host. It serves dual purpose - the facts are used to ensure that any changes in the directory paths don't affect existing installations, and can be used by other Ansible roles to define various resource paths in their variables.

GETTING STARTED

  Ansible local facts

The debops.fhs role creates a local fact script on the managed hosts which defines variables under the ansible_local.fhs.* hierarchy. Other Ansible roles can use these variables to reference the base directories managed by the debops.fhs role. This method provides a central place to control where various data (shared files, binaries, application directories, etc.) is stored in the filesystem. Furthermore, the role takes extra care to not modify existing paths once applied, to ensure that the local facts stay consistent.

An example usage of the Ansible local facts defined by the role - define path to the home directory of an application in the role default variables:

application__user: 'example-app'
application__home: '{{ (ansible_local.fhs.home | d("/var/local"))
                       + "/" + application__user }}'

  Example inventory

The debops.fhs role is included in the common.yml DebOps playbook as well as the bootstrap playbooks and you don't need to do anything to apply it on the host.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.fhs role:

---
- name: Configure base directory hierarchy
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_fhs' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: fhs
      tags: [ 'role::fhs', 'skip::fhs' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::fhs
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

DEFAULT VARIABLE DETAILS

Some of debops.fhs default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  fhs__directories

The fhs__*_directories variables define the list of base directories to create by the role. The directory paths are saved using an Ansible local fact to ensure that any changes after applying the role don't affect an existing installation. To modify existing paths, the /etc/ansible/facts.d/fhs.fact script should be removed from the host, this will ensure that the role does not use existing paths from the facts.

  Examples

Modify the application data directory to store them in a separate mount point instead of the /srv/ directory (you can use debops.mount role to mount a local device under that directory, or debops.nfs to configure a remote NFS filesystem):

fhs__directories:
  - name: 'data'
    path: '/data'

Remember that this change will only take effect on first application of the role, therefore it should be defined in the Ansible inventory before the host is provisioned.

The role will create the /srv/www/ directory by default since it's a common place for home directories of web applications. To avoid this on non-www related hosts, you can put the configuration below in the inventory:

fhs__directories:
  - name: 'www'
    state: 'absent'

  Syntax

Each base directory is defined as a YAML dictionary with specific parameters:

name
    Required. The short name of the directory, used as a reference in the Ansible local facts. The configuration entries with the same name parameter are merged together, this can be used to modify the paths defined by the role via Ansible inventory.

path
    Required. An absolute path of the base directory to create. The path needs to start with the / character, otherwise it will not be created by the role.

mode
    Optional. Specify the permissions of the base directory. If not specified, 0755 will be used by default.

state
    Optional. If not specified or present, the path will be created by the role. If absent, the role will not create this path (existing paths are not removed).

SEE ALSO

•   Manual pages: hier(7) <https://manpages.debian.org/hier(7)>

•   Filesystem Hierarchy Standard v3.0 specification <https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html>

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others