directory
directory manages one directory on a node: it creates the directory or
changes its owner, group, and permissions. It can also set the owner, group,
and permissions of everything inside the directory, copy a directory from the
controller machine into it, delete it, or delete what it does not list.
file and symlink never delete directories;
directory does. A directory that an archive fills is
unpack_archive's, and a Git checkout is
git's.
Inputs
path(string; required): absolute; the parent directory must exist, unless create_missing_parent_directories is true; a directory MMX deletes or deletes from is at least two levels deep, such as /srv/app, and is not a symlinkcreate_missing_parent_directories(boolean; defaultfalse): true creates the missing parent directories of path, as mkdir -p does, each owned by root with permissions_mode 0755, and lists them in the result and the dryrun; false leaves a missing parent a missing prerequisite; not with state: absentowner(account name or integer; optional): an account name, or a numeric ID written without quotesgroup(group name or integer; optional): a group name, or a numeric ID written without quotespermissions_mode(string; optional): quoted octal for directories, such as "0750"; a new directory gets the source directory's mode with source, otherwise 0755also_apply_to_everything_inside(boolean; defaultfalse): true also applies owner, group, permissions_mode, and file_permissions_mode to everything below pathfile_permissions_mode(string; optional): quoted octal for the files inside, such as "0640"; needs also_apply_to_everything_inside or sourcesource(string; optional): local directory copied into path, relative to the project root, or to the role's directory inside a role; not with also_apply_to_everything_insidealso_delete_entries_not_in_source(boolean; defaultfalse): with source: deletes entries at every depth under path that the frozen source tree does not list, under the deletion safeguards; not with if_source_directory_is_missing: copy_nothing, because a missing source directory would delete everything inside pathif_source_directory_is_missing(failorcopy_nothing; defaultfail): with source: copy_nothing treats a source directory missing on the controller machine as empty, so the task only makes sure path exists (a new one gets 0755) and leaves what it holds; fail refuses the playbook before any connectionstate(presentorabsent; defaultpresent): absent deletes the directory: only an empty one, unless also_delete_everything_inside; accepts only path, state, and also_delete_everything_inside; a missing path is unchangedalso_delete_everything_inside(boolean; defaultfalse): with state: absent: deletes the directory with its whole tree, renamed beside it first so the next run finishes an interrupted deletion; a mount point anywhere inside fails the task before anything is deleteddelete_everything_inside_except(list of strings; optional): the names that belong directly inside path; every other entry there is deleted with its whole tree, under the same safeguards; [] empties the directory; the names are not created; a missing directory is created with owner, group, and permissions_mode, as by any directory task with state: present, and holds nothing to delete; accepts path, create_missing_parent_directories, owner, group, and permissions_mode for the directory itself
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.
statuschangevalue.deleted_entriesvalue.deleted_names
What a dryrun reports
Supported; inspects only; recursive and copied trees report counts and up to ten examples; a deletion reports deleted_entries (also with also_delete_entries_not_in_source), and delete_everything_inside_except also deleted_names, without deleting; delete_everything_inside_except on a missing directory reports its creation, as for any new directory; not_checked while the parent directory is missing, unless an earlier node task of the dryrun would create it or create_missing_parent_directories is true.
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
Create a directory
- directory:
path: /srv/app
owner: app
group: app
permissions_mode: "0750"
On the node, MMX creates /srv/app when it is missing, or changes the owner,
group, and permissions of the directory that is there. The parent, /srv,
must exist. Entries inside /srv/app stay unchanged.
Create a directory and its missing parents
- directory:
path: /srv/shop/shared/uploads
create_missing_parent_directories: true
owner: shop
group: shop
permissions_mode: "0750"
On a new node where /srv exists, MMX creates /srv/shop and
/srv/shop/shared as mkdir -p does, each owned by root with
permissions_mode 0755, then /srv/shop/shared/uploads as the task says.
Dryrun creates nothing and lists the parent directories a run would create.
The run's result lists the parent directories MMX created. To give a parent
different ownership or permissions, add a separate directory task before
the task that creates /srv/shop/shared/uploads.
Copy a directory from the controller machine
Use directory.source to copy the contents of a local directory onto a node:
- directory:
path: /etc/myapp/conf.d
source: files/conf.d
owner: root
group: root
permissions_mode: "0755"
file_permissions_mode: "0644"
Copies include dotfiles and empty directories. Names and contents stay literal. The destination's parent must exist. Each file uses the ordinary atomic installer. The directory-copy example combines this with validation and a service reload.
Resume uses the saved directory tree and bytes. Rerunning finishes partial work. Copied file contents contribute to service hashes; metadata-only changes do not trigger a reload.
Delete entries that the source no longer has
- directory:
path: /etc/myapp/conf.d
source: files/myapp_conf.d
also_delete_entries_not_in_source: true
On the node, MMX copies the source and deletes every entry under
/etc/myapp/conf.d that files/myapp_conf.d does not have,
at every depth. An extra directory is deleted with its whole tree. A link
is deleted as a link; its target stays untouched. The entries that the
source has are copied as usual, and a conflict of types, such as a
directory on the node where the source has a file, still fails the task.
An unchanged rerun reports unchanged.
also_delete_entries_not_in_source: true requires source.
A task with also_delete_entries_not_in_source: true cannot use
if_source_directory_is_missing: copy_nothing. A missing source directory
on the controller machine would then delete everything inside path.
The deletion safeguards apply before anything is deleted.
Dryrun deletes nothing. The directory summary counts proposed deletions and
shows up to ten example changes in total across copying and deletion.
value.deleted_entries counts every deleted file, link, directory, and
other entry, including the contents of deleted directories. The summary
counts deleted links and special files as files. value.deleted_names
remains specific to
delete_everything_inside_except, where names mean direct children rather
than paths at several depths.
Copy a directory that the project may not have
A missing source directory stops the playbook before MMX connects to any node. Some projects have a source directory only when they need it, such as a directory of the project's own check scripts that many projects leave out. For projects with an optional source directory, set the task to copy nothing when the source directory is missing:
- directory:
path: /etc/myapp/checks.d
source: check_scripts
if_source_directory_is_missing: copy_nothing
permissions_mode: "0755"
Without check_scripts/ in the project, the task only makes sure
/etc/myapp/checks.d exists, empty on a new node, and leaves anything already
in it alone. A new directory gets mode 0755 unless permissions_mode says
otherwise. Once the project has check_scripts/, the next run copies it as
usual. An application can use this for a directory of project-specific modules,
which a project may not have. Only a missing directory counts as empty: a file or a link in its place
still fails. The default, fail, refuses a missing source.
Set ownership and permissions across a node's directory tree
- directory:
path: /srv/myapp
also_apply_to_everything_inside: true
owner: myapp
group: myapp
permissions_mode: "0750"
file_permissions_mode: "0640"
permissions_mode applies to directories. file_permissions_mode applies to
regular files and requires either also_apply_to_everything_inside: true or
source. Omitted fields preserve each entry's current values. Without
source or also_apply_to_everything_inside: true, MMX manages only the
named directory.
A directory owned by a numeric ID
owner and group take an account name, or a number. A number is the
numeric ID itself and needs no account on the node. Use numeric owner and
group values for a directory owned by a container process whose IDs have no
accounts on the node:
- directory:
path: /srv/postgres-data
owner: 999 # the ID of the postgres account inside the container
group: 999
permissions_mode: "0700"
Write the number without quotes. owner: "999" is refused, so that text
always means a name and a number always means an ID. Prefer a name where the
node has an account: a bare number may be the ID of another account on this
node, now or later. To keep the number and still have a name, create the
account with that ID and use its name:
- user:
create_home_directory: false
name: postgres-container
uid: 999
system: true
- directory:
path: /srv/postgres-data
owner: postgres-container
The same rule holds for file, download, and unpack_archive;
Owner and group are an account name or a number
owns it.
Delete a directory, or what it no longer lists
Removing a task from YAML never deletes what the task created. To delete a
directory, say so with state: absent:
# Delete an old installation and everything in it.
- directory:
path: /home/deploy/old-api
state: absent
also_delete_everything_inside: true
Without also_delete_everything_inside: true, state: absent deletes only an
empty directory and fails on one that has entries, naming how many.
To keep a directory and delete what does not belong in it, list the names that belong directly inside:
# Keep the current and the previous release and delete every other entry
# of /srv/myapp/releases. release and previous_release are variables you define.
- directory:
path: /srv/myapp/releases
owner: myapp
group: myapp
permissions_mode: "0750"
delete_everything_inside_except:
- "{{ .vars.release }}"
- "{{ .vars.previous_release }}"
On the node, MMX deletes every other entry directly inside
/srv/myapp/releases, each with everything in it, and gives the directory
itself the owner, group, and permissions that the task names. [] empties
the directory. A name in the list that does not exist is not created.
When /srv/myapp/releases is missing, MMX creates it, as every directory
task creates a missing directory: owned by myapp, group myapp, with
permissions 0750, and empty, so there is nothing to delete. The result is
changed, and a later node task can write into the directory. The parent,
/srv/myapp, must exist, unless create_missing_parent_directories is
true.
Dryrun reports the result value deleted_entries, the number of files,
links, and directories that would be deleted, counting each directory; with
delete_everything_inside_except it also lists deleted_names, the names of
the entries it would delete directly inside the directory. A run reports the
same values for what it deleted.
How it works
One directory
Without source or also_apply_to_everything_inside, directory creates one
directory or changes its explicit owner, group, and mode. The parent must
exist, unless create_missing_parent_directories is true. A new directory gets mode 0755 unless permissions_mode says
otherwise; omitted metadata on an existing directory stays unchanged. When a
mode is omitted, MMX preserves executable and special permission bits as well
as ordinary permissions. Children are preserved, and a symlink at the path is
refused. During dryrun, ownership by an account that does not exist yet is
reported as not checked.
Copying a directory
The source is a path on the controller machine, resolved like
file.source. Its entries
(directories, including empty ones, and regular files, including dotfiles)
are saved with the run; resume uses that snapshot. Contents are not rendered.
Source symlinks, source special files, and special permission bits are
rejected before MMX sends the work to any node. Conflicting destination types
fail without being replaced, and destination links are not followed. The
root is created if missing; its parent must exist, unless
create_missing_parent_directories is true.
By default, the source owns only its listed paths. Entries not listed in the
source stay untouched on the node, including files removed from a later
source tree. With also_delete_entries_not_in_source: true, MMX deletes
those entries at every depth. The list of source entries that MMX reads when
the run starts decides what is kept, also when mmx resume finishes the
run. There is no include or exclude.
owner and group apply to the root and the copied entries. Omitted
metadata preserves existing entries. New entries use the source's modes and
normal ownership defaults. Explicit ownership and directory or file modes
apply only to copied paths. Do not combine source with
also_apply_to_everything_inside: true.
Each file uses the ordinary atomic installer; the tree is not a transaction,
and a rerun finishes partial work. Dryrun creates nothing. Dryrun and results
show one directory_change summary with up to ten example file or directory
changes. --diff shows bounded text previews for them, with the same
private-file and secret suppression as individual file node tasks; see
Preview file changes.
Everything inside a directory
With also_apply_to_everything_inside: true, owner and group apply to the
root, descendant directories, and regular files. A missing root directory
without a source is created with default mode 0755; its parent must exist,
unless create_missing_parent_directories is true.
The named root itself cannot be a symlink. Traversal skips symlinks, special
files, and entries on another filesystem device, and never follows links.
The walk is one local operation on the node, not one task per entry. It
changes only differing metadata and sets directory metadata after visiting
children. It returns one summary: entries checked, changed, and skipped, with
up to ten examples. Dryrun inspects without changing anything and reports
counts. --diff adds up to ten example metadata changes. Saved JSON includes
directory_change; mmx results --diff shows the same summary. Partial
failures retain the number of updates made. Another run reconciles the
current metadata.
Missing parent directories
With create_missing_parent_directories: true, MMX creates each missing
parent of path in order, as mkdir -p does. Each one is owned by root
with permissions_mode 0755, also under a directory whose set-group-ID bit
would pass its group on. Links in the part of the path that exists are
followed, as mkdir -p follows them. Each new parent is created and opened
inside the one before it, and stays private until it has its owner and
permissions. The result's directory_change.created_parent_directories
lists the parents MMX created; in a dryrun it lists the parents a run would
create, and nothing is created. A parent that exists is never changed.
The field does not go with state: absent: a directory that MMX deletes
needs no parents. With delete_everything_inside_except, it creates the
missing parents of a missing directory, as for any other directory task.
Deleting
Before it deletes anything, MMX checks the safeguards:
- The path is absolute and at least two levels deep, such as
/srv/myapp;/srvor/is refused. - The path is not a symbolic link. A link inside what MMX deletes is deleted as a link, never what it points to.
- Nothing that would be deleted is a mount point, nor has one anywhere inside it. A mounted filesystem or a bind mount there fails the node task before anything is deleted. Unmount it first.
The path itself may be a mount point with delete_everything_inside_except
or also_delete_entries_not_in_source:
the entries it deletes then all live on that filesystem. A state: absent
task refuses a path that is a mount point.
MMX first renames a tree it deletes to a staging name beside it,
.mmx-staging-<name>, then deletes the staging tree. If the deletion stops
part of the way, for example on a file the kernel refuses to delete, only the
staging directory is left, and the next run of the task deletes it. With
delete_everything_inside_except, that staging directory is inside the
directory and not listed, so the next run deletes it too. The same applies
to also_delete_entries_not_in_source at every depth. If a source entry owns
the staging name needed for a deletion, MMX refuses before deleting anything;
rename that source entry first so staging cannot erase a source-owned path.
state: absent and also_delete_everything_inside take no other field.
delete_everything_inside_except also accepts owner, group, and
permissions_mode for the directory itself, and
create_missing_parent_directories. Entries that the task keeps retain
their metadata.
A delete_everything_inside_except task creates a missing directory exactly
as a directory task without the list does, with the task's owner,
group, and permissions_mode; without permissions_mode the new directory
gets mode 0755. The new directory is empty, so the task deletes nothing,
and the names in the list are not created. A dryrun reports the creation as
it does for any new directory, and creates nothing. A link or a file at the
path fails the node task; MMX replaces neither.
In a node task block
Copied file contents contribute to the service configuration hash; directories and metadata do not, so permission changes alone do not trigger service reloads.
In a node task block's changes, a deletion is a tracked input: the existence
of the directory for state: absent, and the names directly inside it for
delete_everything_inside_except. A deletion alone therefore restarts or
reloads the block's service, also after a run that stopped between the
deletion and the restart.
When delete_everything_inside_except creates a missing directory, that
tracked input changes once, from a missing directory to an empty one. A
running service of the block is then restarted or reloaded once, and a
dryrun reports that it would be. The next run finds the same directory with
the same names and refreshes nothing.
Errors and what they mean
also_delete_entries_not_in_sourcewithoutsourcefails validation. Name the source directory whose entries MMX must keep.also_delete_entries_not_in_sourcewithcopy_nothingfails validation: a missing source directory would delete everything insidepath. Keepif_source_directory_is_missing: failfor a copy that deletes extra entries.- A missing source directory stops the playbook before MMX connects to any
node. Correct the path, or set
if_source_directory_is_missing: copy_nothingwhen the project may leave the directory out. - A symlink or a special file in the source, or a destination entry of another type than the source's, fails without replacing anything. Change the source, or remove the entry at the destination first.
state: absenton a directory that has entries fails and names how many. Addalso_delete_everything_inside: truewhen everything in it may go.- A mount point in what MMX would delete fails the node task before anything is deleted. Unmount it first.
the parent directory /var/backups does not exist; create it with an earlier directory node task: the directory that would hold the new one is missing. The node task fails once and is not tried again. Create the parent with an earlierdirectorynode task, or setcreate_missing_parent_directories: trueon this one. A dryrun reports the node task not checked, or previews it when an earlier node task of the dryrun would create the parent.
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45.
The base suite covers this module (directory_resources.py, directory_copy.py, account_units.py) and runs on every tested distribution.
Why it works this way
-
Missing parents are created only when the task says so. A mistyped path, such as
/srv/shpo/uploads, should fail and name the missing/srv/shpo, not quietly create a tree beside the real one. Ansible'sfilecreates parents always, and real playbooks rely on it, so the field is one line where a playbook needs it. -
Created parents are root's, with
0755. A parent that MMX creates on the way is not the task's directory, so the task's owner and permissions do not apply to it. Root with0755is whatmkdir -pgives as root with the usual umask, and every account can pass through it to the directory below. -
A missing source directory stops the playbook. A mistyped path should not quietly copy nothing.
-
Removing a task never deletes; a deletion is written out. A directory full of data is never deleted by a line that does not say so.
-
delete_everything_inside_exceptlists the whole set. A reviewer sees on the page what the task deletes. The rule on resource ownership owns this principle. -
MMX refuses to delete through a mount point. Deleting through it would delete files of another filesystem.
-
MMX renames a tree before it deletes it. The path is gone at once, so nothing reads a half-deleted directory there, and the next run finishes an interrupted deletion.
-
Cleanup may also manage the directory's metadata. Its owner, group, and mode describe the same resource; a separate task would repeat the path. Kept entries remain outside that metadata change.
-
delete_everything_inside_exceptcreates a missing directory. Adirectorytask hasstate: presentby default, which says that the directory exists. The list adds what it holds. One task can then state the directory's owner, group, permissions, and its whole contents, and the next node task that writes into the directory finds it, on a new node as on an old one.
This page is docs/reference/modules/directory.md in the MMX repository.