UnionFS

Overview

Installs and configures MergerFS to create a union filesystem merging local and remote storage paths, managing Docker services during mount operations.

UnionFS is a filesystem service for Linux, FreeBSD and NetBSD which implements a union mount for other file systems.

---

Deployment

Saltbox dependency.

sb install mounts

Role Defaults

Info

Variables can be overridden in /srv/git/saltbox/inventories/host_vars/localhost.yml.

Example Override

local_mount_branch: "custom_value"

GlobalMergerFSGlobal Override Options

local_mount_branch

# Type: string
local_mount_branch: "/mnt/local=RW:"

custom_mount_branch

# Type: string
custom_mount_branch: "" # Format: "/mnt/remote/someremote=NC"

mergerfs_override_service

# Type: bool (true/false)
mergerfs_override_service: true

mergerfs_service_name

# Type: string
mergerfs_service_name: "saltbox_managed_mergerfs.service"

mergerfs_version

# Type: string
mergerfs_version: latest

mergerfs_github_endpoint

# Type: string
mergerfs_github_endpoint: "{{ 'latest' if (mergerfs_version == 'latest') else 'tags/' + mergerfs_version }}"

mergerfs_releases_url

# Type: string
mergerfs_releases_url: "{{ svm }}https://api.github.com/repos/trapexit/mergerfs/releases/{{ mergerfs_github_endpoint }}"

mergerfs_releases_download_url

# Type: string
mergerfs_releases_download_url: https://github.com/trapexit/mergerfs/releases/download

mergerfs_release_distribution

# Type: string
mergerfs_release_distribution: "{{ ansible_facts['distribution_release'] | lower }}"

mergerfs_release_lookup_command

# Type: string
mergerfs_release_lookup_command: |
  curl -s {{ mergerfs_releases_url }} \
    | jq -r ".assets[] | select(.name | test(\"{{ ansible_facts['distribution'] | lower }}-{{ mergerfs_release_distribution }}_amd64\")) \
    | .browser_download_url"

mergerfs_download_backup_version

# Type: string
mergerfs_download_backup_version: 2.40.2

mergerfs_download_backup_url

# Type: string
mergerfs_download_backup_url: "
  {{ mergerfs_releases_download_url }}/\
  {{ mergerfs_download_backup_version }}/\
  mergerfs_{{ mergerfs_download_backup_version }}.\
  {{ ansible_facts['distribution'] | lower }}-\
  {{ mergerfs_release_distribution }}_amd64.deb"

mergerfs_mount_branches

# Type: string
mergerfs_mount_branches: "{{ local_mount_branch }}{{ _remotes_list }}"

mergerfs_branch_mode

# Type: string
mergerfs_branch_mode: "NC"

mergerfs_remote_branch_mode_lookup

# Type: string
mergerfs_remote_branch_mode_lookup: "{{ lookup('vars', 'mergerfs_remote_' + rclone_remote_name + '_branch_mode', default=mergerfs_branch_mode) }}"

mergerfs_mount_service_after

# Type: string
mergerfs_mount_service_after: "network-online.target"

mergerfs_mount_readdir_policy

# Type: string
mergerfs_mount_readdir_policy: "seq"

mergerfs_mount_policy_action

# Type: string
mergerfs_mount_policy_action: "epall"

mergerfs_mount_policy_create

# Type: string
mergerfs_mount_policy_create: "ff"

mergerfs_mount_policy_search

# Type: string
mergerfs_mount_policy_search: "ff"

mergerfs_mount_umask

# Type: string
mergerfs_mount_umask: "002"

mergerfs_mount_xattr

# Type: string
mergerfs_mount_xattr: "nosys"

mergerfs_mount_start_command

# Type: string
mergerfs_mount_start_command: |-
  /usr/bin/mergerfs \
    -o category.create={{ mergerfs_mount_policy_create }},async_read=true,cache.files=partial \
    -o category.action={{ mergerfs_mount_policy_action }},category.search={{ mergerfs_mount_policy_search }} \
    -o dropcacheonclose=true,minfreespace=0,fsname=mergerfs \
    -o xattr={{ mergerfs_mount_xattr }},statfs=base,statfs_ignore=nc,umask={{ mergerfs_mount_umask }},noatime \
    -o func.readdir={{ mergerfs_mount_readdir_policy }} \
    "{{ mergerfs_mount_branches }}" /mnt/unionfs

mergerfs_mount_stop_command

# Type: string
mergerfs_mount_stop_command: /bin/fusermount3 -uz /mnt/unionfs

unionfs_role_autoheal_enabled

# Enable or disable Autoheal monitoring for the container created when deploying
# Type: bool (true/false)
unionfs_role_autoheal_enabled: true

unionfs_role_depends_on

# List of container dependencies that must be running before the container start
# Type: string
unionfs_role_depends_on: ""

unionfs_role_depends_on_delay

# Delay in seconds before starting the container after dependencies are ready
# Type: string (quoted number)
unionfs_role_depends_on_delay: "0"

unionfs_role_depends_on_healthchecks

# Enable healthcheck waiting for container dependencies
# Type: string ("true"/"false")
unionfs_role_depends_on_healthchecks:

unionfs_role_diun_enabled

# Enable or disable Diun update notifications for the container created when deploying
# Type: bool (true/false)
unionfs_role_diun_enabled: true

unionfs_role_dns_enabled

# Enable or disable automatic DNS record creation for the container
# Type: bool (true/false)
unionfs_role_dns_enabled: true

unionfs_role_docker_controller

# Enable or disable Saltbox Docker Controller management for the container
# Type: bool (true/false)
unionfs_role_docker_controller: true

unionfs_role_traefik_autodetect_enabled

# Enable Traefik autodetect middleware for the container
# Type: bool (true/false)
unionfs_role_traefik_autodetect_enabled: false

unionfs_role_traefik_crowdsec_enabled

# Enable CrowdSec middleware for the container
# Type: bool (true/false)
unionfs_role_traefik_crowdsec_enabled: false

unionfs_role_traefik_error_pages_enabled

# Enable custom error pages middleware for the container
# Type: bool (true/false)
unionfs_role_traefik_error_pages_enabled: false

unionfs_role_traefik_gzip_enabled

# Enable gzip compression middleware for the container
# Type: bool (true/false)
unionfs_role_traefik_gzip_enabled: false

unionfs_role_traefik_middleware_http_api_insecure

# Type: bool (true/false)
unionfs_role_traefik_middleware_http_api_insecure:

unionfs_role_traefik_middleware_http_insecure

# Type: bool (true/false)
unionfs_role_traefik_middleware_http_insecure:

unionfs_role_traefik_robot_enabled

# Enable robots.txt middleware for the container
# Type: bool (true/false)
unionfs_role_traefik_robot_enabled: true

unionfs_role_traefik_tailscale_enabled

# Enable Tailscale-specific Traefik configuration for the container
# Type: bool (true/false)
unionfs_role_traefik_tailscale_enabled: false

unionfs_role_traefik_wildcard_enabled

# Enable wildcard certificate for the container
# Type: bool (true/false)
unionfs_role_traefik_wildcard_enabled: true

unionfs_role_web_fqdn_override

# Override the Traefik fully qualified domain name (FQDN) for the container
# Type: list
unionfs_role_web_fqdn_override:

Example Override

unionfs_role_web_fqdn_override:
  - "{{ traefik_host }}"
  - "unionfs2.{{ user.domain }}"
  - "unionfs.otherdomain.tld"

Note: Include {{ traefik_host }} to preserve the default FQDN alongside your custom entries

unionfs_role_web_host_override

# Override the Traefik web host configuration for the container
# Type: string
unionfs_role_web_host_override:

Example Override

unionfs_role_web_host_override: "Host(`{{ traefik_host }}`) || Host(`{{ 'unionfs2.' + user.domain }}`)"

Note: Use {{ traefik_host }} to include the default host configuration in your custom rule

unionfs_role_web_scheme

# URL scheme to use for web access to the container
# Type: string ("http"/"https")
unionfs_role_web_scheme: