Ansible Role: FACL

Install POSIX file access control list tools on supported Linux systems.

This role installs the operating-system acl package, keeps the historical facl_pkg_state_latest switch for compatibility, and validates that getfacl and setfacl are available after installation.

Table of Contents

• Overview
• Role Flow
• Requirements
• Installation
• Variables
• Supported Linux Matrix
• Examples
• Testing
• Jenkins CI
• Publishing
• Development Notes
• Changelog
• Maintainer
• Inspiration
• Support
• Repository
• License

Overview

The role is intentionally small and focused:

• install the system package that provides POSIX FACL tools
• support present and latest package states
• verify that getfacl and setfacl are callable after installation
• exercise the role through a Workspace-managed Docker test matrix

The role does not provision cloud resources. Local Docker validation is enough because the role only manages operating-system packages and command-line tools.

Role Flow

This role flow is defined by tasks/main.yml, tasks/install.yml, and tasks/verify.yml.

flowchart LR
  accTitle: Role execution flow
  accDescr: Shows validation, package installation, optional apt cache refresh, and tool verification.
  start["Run role"] --> validate["Validate settings"]
  validate --> apt{"Apt target?"}
  apt -->|Yes| cache["Refresh cache"]
  apt -->|No| install["Install package"]
  cache --> install
  install --> verify{"Verify enabled?"}
  verify -->|Yes| commands["Check ACL tools"]
  verify -->|No| complete["Complete"]
  commands --> complete

Loading

Requirements

• Ansible Core 2.16 or newer
• a supported Linux target with administrator or sudo access
• an operating-system package repository that exposes the acl package
• the community.docker collection and local Docker service for the default container-backed test harness

Installation

Current local development role name:

ansible-facl

Intended Ansible Galaxy role name:

inviqa.facl

After the first Inviqa Galaxy import is complete, install a pinned release with:

ansible-galaxy role install inviqa.facl,<version>

Until that import exists, consume the role from a local checkout or a pinned Git reference.

Variables

Variable	Default	Notes
facl_package_name	acl	Operating-system package that provides the FACL tools.
facl_pkg_state_latest	false	Compatibility switch for consumers familiar with the role this work was inspired by. When true, facl_package_state resolves to latest.
facl_package_state	{{ 'latest' if facl_pkg_state_latest | bool else 'present' }}	Package state passed to ansible.builtin.package. Supported values are present and latest.
facl_apt_update_cache	true	Update the apt cache before installing the package on apt-based targets.
facl_apt_cache_valid_time	3600	Cache validity window, in seconds, passed to ansible.builtin.apt.
facl_verify_install	true	Verify the FACL command-line tools after package installation.
facl_getfacl_command	getfacl	Command used for getfacl verification and tests.
facl_setfacl_command	setfacl	Command used for setfacl verification and tests.

Supported Linux Matrix

The practical validation matrix is intentionally aligned with the local Docker test harness. It covers the latest stable release and one still-relevant previous stable or LTS release for each primary family:

Family	Latest stable test image	Previous stable or LTS test image
Debian	geerlingguy/docker-debian13-ansible:latest	geerlingguy/docker-debian12-ansible:latest
Enterprise Linux	geerlingguy/docker-rockylinux10-ansible:latest	geerlingguy/docker-rockylinux9-ansible:latest
Ubuntu	geerlingguy/docker-ubuntu2604-ansible:latest	geerlingguy/docker-ubuntu2404-ansible:latest

Galaxy metadata also advertises current Debian, Ubuntu, Fedora, Enterprise Linux, and openSUSE releases where the acl package is expected to be available through the standard package manager.

Run this role as a privileged user or set become: true in the calling playbook when the target user cannot install packages directly.

Examples

---
- name: Install FACL tools
  hosts: linux_devices
  become: true
  roles:
    - role: inviqa.facl
      vars:
        facl_pkg_state_latest: false

Use the newer package-state variable when writing fresh playbooks:

---
- name: Install latest FACL tools
  hosts: linux_devices
  become: true
  roles:
    - role: inviqa.facl
      vars:
        facl_package_state: latest

For local checkout testing before Galaxy publication, use the local role name ansible-facl.

Testing

The current test workflow is documented in docs/testing.md. It covers Workspace commands, container tests, syntax checks, Jenkinsfile lint, cleanup, and the Workspace CLI install command.

Jenkins CI

docs/jenkins-ci.md documents the private Jenkins pipeline, required credential IDs and bindings, Jenkinsfile lint helper, and container-backed validation sequence.

Publishing

docs/ansible-galaxy-release.md documents the GitHub release and Ansible Galaxy import runbook.

After the GitHub release and tag exist on main, import the role into Galaxy with:

ws github release check
ws ansible galaxy publish

The commands use github.api_token and ansible.galaxy.token from workspace.override.yml, or GITHUB_TOKEN and ANSIBLE_GALAXY_TOKEN from the shell environment.

Jenkins can also create the GitHub release and import the role into Galaxy from the main branch with separate publication build parameters. See docs/jenkins-ci.md for the required Jenkins credentials and publication controls.

Development Notes

• AGENTS.md defines strict repository linting and documentation rules for AI coding agents.
• .ansible/ is generated dependency/cache output and should not be committed.
• workspace.override.yml is gitignored and may hold local release tokens.
• The Workspace console mounts only the repository and Docker socket; this role has no SSH-agent or SSH config dependency.
• Keep the role support matrix aligned with the tested Linux matrix before publishing a new Galaxy release.

Changelog

See CHANGELOG.md for release history.

Maintainer

• Author: Marco Massari Calderone <marco.massari-calder@inviqa.com>
• Copyright holder for Inviqa-maintained changes: Inviqa UK Ltd

Inspiration

This role is inspired by Barney Hanlon's earlier MIT-licensed FACL role from the shrikeh-ansible-roles/ansible-facl GitHub organization. The current role has been substantially rebuilt for the Inviqa Ansible role toolchain, documentation model, and test harness.

Support

For current maintenance and publication work, contact the maintainer above. If the role is published publicly, issue-tracking and support paths should be documented alongside the published source.

Repository

• Public repository URL: https://github.com/inviqa/ansible-facl
• Inspiration: https://github.com/shrikeh-ansible-roles/ansible-facl
• Ansible Galaxy role: https://galaxy.ansible.com/ui/standalone/roles/inviqa/facl/
• Publication status: pending first Inviqa Ansible Galaxy import

License

MIT