selinux_file_context

SELinux is the access control layer that the Red Hat family turns on by default. It refuses what its policy does not allow, even to a process that runs as root: a web server may not read files outside its content directories until the policy says so. SELinux decides by the label of each file, and the policy gives each path a label. selinux_file_context owns the node's local label rule for one path, or for a path and everything below it, and then gives the existing files there the label of the rule.

MMX's own file writers give every file the label the policy has for its path, so no file module has a field for the label. A path that needs another label gets a rule from this module.

Four modules change SELinux, each in one way:

  • selinux_boolean switches a permission of the policy on or off;
  • selinux_file_context gives the files of a path another label;
  • selinux_port gives a network port another type;
  • selinux_mode sets whether SELinux enforces its policy or only reports.

Set up

selinux_file_context runs semanage and restorecon on the node. restorecon is in policycoreutils, which every Red Hat family server has. semanage is in policycoreutils-python-utils, which many server images leave out, so install it before the first SELinux node task:

- dnf_package:
    packages:
      - {name: policycoreutils-python-utils, version: newest_when_first_installed}

Inputs

  • path (string; required): absolute; a missing path is not an error
  • also_apply_to_everything_inside (boolean; required): true: the rule covers path and everything below it; false: path alone
  • selinux_type (string; required): the SELinux type, such as httpd_sys_content_t; omit with absent
  • state (present or absent; default present): absent removes the rule and accepts only path and also_apply_to_everything_inside

Outputs

The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.

  • status
  • change
  • value.rule
  • value.paths_relabeled

What a dryrun reports

Supported; reports the rule change, and the number of paths to relabel once the rule is in the policy; every run relabels the existing paths whose label differs from the policy's.

Retries and time limits

Bounded automatic retries by default; retry: false turns them off.

The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.

Examples

Serve a website from its own directory

A web server serves files from /srv/www, connects to the network, and listens on port 8443:

- task_block:
    id: web_content
    changes:
      - selinux_boolean:
          name: httpd_can_network_connect
          enabled: true
      - selinux_file_context:
          path: /srv/www
          also_apply_to_everything_inside: true
          selinux_type: httpd_sys_content_t
      - selinux_port:
          port: 8443
          protocol: tcp
          selinux_type: http_port_t
      - file:
          permissions_mode: "0644"
          path: /etc/httpd/conf.d/site.conf
          source: files/site.conf
    activate:
      - systemd_service: {name: httpd, start_at_boot: true, refresh: reload, state: running}

On the node, the first node task lets the web server connect to the network. The second adds the label rule httpd_sys_content_t for /srv/www and everything below it, and relabels the files there. The third gives port 8443 the type http_port_t, so the web server may listen on it. Then MMX writes the web server's configuration file, and activate reloads the web server.

Put selinux_port and selinux_file_context before the node tasks that write the files, and before activate.

Remove the rule

- selinux_file_context:
    path: /srv/www
    also_apply_to_everything_inside: true
    state: absent

state: absent takes path and also_apply_to_everything_inside, and removes the rule.

How it works

  • path is absolute. also_apply_to_everything_inside: true makes the rule cover path and everything below it; false covers path alone.
  • The module inspects before it acts, and changes the running node and the stored policy together.
  • Relabeling never depends on whether the rule changed. On every run, selinux_file_context asks the node which existing paths carry another label than the policy gives them (restorecon -n), and relabels when there are any. That repairs an interrupted run, files moved in with an old label, and a label changed by hand.
  • A missing path is not an error.
  • The result value says rule: added, updated, or removed when the rule changed, and paths_relabeled with the number of paths the node task relabeled. A run that fails lists only what it did before the failure, so a node task in on_failure can read what happened.
  • A dryrun reports the number of paths to relabel once the rule is in the policy. While the rule still has to be added, the paths are not checked yet.
  • On a node where SELinux is disabled or not installed, the node task reports skipped with the reason "SELinux is not enabled on this node". The fact .node.selinux.mode says enforcing, permissive, or disabled (facts).

Errors and what they mean

The reason holds What it means, and what to do
semanage is not installed; install the package policycoreutils-python-utils first The node lacks semanage; the same reason names restorecon and policycoreutils when that program is missing. Install the package in an earlier node task; see Set up. A dryrun reports the node task not checked, because an earlier node task may install the package.

Tested on

Distributions: Rocky Linux 9, AlmaLinux 10, Fedora 45.

The suite tests/integration/firewalld_and_selinux.py runs on seven distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10, and Fedora 45. On the three distributions that use SELinux, Rocky Linux 9, AlmaLinux 10, and Fedora 45, it runs in a virtual machine with SELinux enforcing, as installed. On the other four it runs in a container without SELinux and checks that the module reports skipped. The validation record has the latest results.

Why it works this way

  • Four SELinux modules, and no field for a label on file. MMX's writers give each file the label of its path, and a path that needs another label gets a rule that survives a relabel.
  • Every run relabels what differs from the policy, not only a run that changed the rule. That way an interrupted run, files moved in with an old label, and a label changed by hand are all repaired.

This page is docs/reference/modules/selinux_file_context.md in the MMX repository.