line
line manages one line of an existing regular file on a node. The line
module replaces the line that a regular expression or the exact text selects.
When no existing line is selected, the module adds the text from the task's
line setting. The module can also remove the selected line.
Prefer a program's drop-in directory or a whole managed file
when available. Use line for one line of a file that has no drop-in
directory, and edit_file for an edit that one line cannot
make. The page of edit_file gives the order in which to
choose between a drop-in, a whole file, line, and edit_file.
Inputs
path(string; required): absolute; an existing regular file, whose owner, group, and permissions are keptmatch(string; optional): Go regular expression tested against each line. If match is omitted, MMX selects a line by the exact text in line. More than one matching line fails the node task.line(string; optional): required with state: present; the whole line, which match must select; replaces the selected line, or is inserted where the task places it when nothing is selected; with absent, give match or lineinsert_at_end_of_file(boolean; optional): true: a new line goes at the end of the file; state: present requires exactly one of the six placing settings, applied only when nothing is selectedinsert_at_start_of_file(boolean; defaultfalse): true: a new line goes before the first lineinsert_before_first_line_matching(string; optional): Go regular expression; a new line goes directly before the first line it matches; no matching line fails the task and changes nothinginsert_before_last_line_matching(string; optional): as insert_before_first_line_matching, before the last line it matchesinsert_after_first_line_matching(string; optional): as insert_before_first_line_matching, directly after the first line it matchesinsert_after_last_line_matching(string; optional): as insert_before_first_line_matching, directly after the last line it matchescheck_new_file(mapping; optional): as for filestate(presentorabsent; defaultpresent): absent removes the selected line and needs exactly one of match or line; it takes no placing setting
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.
statuschange
What a dryrun reports
Supported; previews the edit as a file diff; a validator runs only its own dryrun command.
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
Set one line
- line:
insert_at_end_of_file: true
path: /etc/ssh/sshd_config
match: '^#?PasswordAuthentication\s'
line: PasswordAuthentication no
match is a Go regular expression tested against each line. Without match,
the exact line selects the existing line. MMX replaces the selected line,
or appends line at the end if nothing matches. The new line must itself
match match, so another run is unchanged.
Set a value whatever it was before
- line:
insert_at_end_of_file: true
path: /etc/default/grub
match: '^GRUB_CMDLINE_LINUX='
line: 'GRUB_CMDLINE_LINUX="console=ttyS0,115200"'
match selects the line that sets GRUB_CMDLINE_LINUX, whatever value it
has now. On the node, MMX replaces the line that sets GRUB_CMDLINE_LINUX
with the task's line. When no line sets GRUB_CMDLINE_LINUX, MMX adds
line at the end of /etc/default/grub.
Put a new line in a chosen place
Choose exactly one of the six insertion settings below. The chosen setting says where the new line goes when no existing line is selected:
# Put the rule before the catch-all line of the file.
- line:
path: /etc/postgresql/16/main/pg_hba.conf
line: "host app app 10.0.0.0/8 scram-sha-256"
insert_before_first_line_matching: '^host\s+all\s+all\s'
| Setting | The new line goes |
|---|---|
insert_at_end_of_file: true |
At the end of the file. MMX first ends the file's last line if it lacks a newline. |
insert_at_start_of_file: true |
Before the first line. |
insert_before_first_line_matching: <pattern> |
Directly before the first line the pattern matches. |
insert_before_last_line_matching: <pattern> |
Directly before the last line the pattern matches. |
insert_after_first_line_matching: <pattern> |
Directly after the first line the pattern matches. |
insert_after_last_line_matching: <pattern> |
Directly after the last line the pattern matches. |
A task with state: present requires exactly one of them. Each pattern is a Go regular expression, like
match. They place only a new line and never move a line that is already
there. A pattern that matches no line fails the node task and changes
nothing, so a line never lands in a place you did not choose.
Remove a line
- line:
path: /etc/ssh/sshd_config
match: '^PermitRootLogin\s'
state: absent
Use state: absent with either match or line to remove the selected line.
The task then accepts path, state, check_new_file, and one of match
or line. Nothing selected leaves the task unchanged.
How it works
match is tested against each line without its newline. path and match
are public identifiers and may be references, so one task in a loop can set
several settings. line is a private value, like file.content, and is one line. That line matches match is
checked at validation when both are known on the controller machine, and
otherwise on the node before any change.
The file must already exist; line never creates files. A missing file, a
directory, or a symlink at path fails the node task. Dryrun reports a
missing file as not checked, since an earlier node task, such as a package
installation, may create it.
The edit preserves owner, group, and mode and goes through the file
installer: a temporary new file, the optional check_new_file, and an atomic
replacement of the live file. Differences and service hashes treat the path
like a file task. The check of a new file is shared with file,
download, and edit_file, and
Check a new file before replacing the live one
and its design
describe it.
Several line node tasks can edit the same file, including within one node
task block. That file counts once in the service hash, and a dryrun applies
the edits in turn to predict it. line and edit_file node
tasks may also edit the same file in one node task block. A file node task
for the same path in that node task block is rejected, because file owns
the whole contents.
Errors and what they mean
- More than one matching line fails the node task, names the line
numbers, and changes nothing. Make
matchselect exactly one line. - A placing pattern that matches no line fails the node task and changes
nothing. Correct the pattern, or use
insert_at_end_of_file: trueto add the line at the end of the file. - A missing file fails the node task in a run. Create the file first, such as with the package that installs it.
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 (file_resources.py, task_secrets.py) and runs on every tested distribution.
Why it works this way
-
One line, at most one match. Whole files and drop-ins have obvious ownership;
linekeeps the part MMX owns as small as one line. The rule on resource ownership says why MMX manages parts of a system through native boundaries. -
A new line is placed, never moved. A pattern that matches nothing fails instead of falling back to the end, so a line never lands in a place the author did not choose.
-
The new line must match
match. The next run then finds it and reports unchanged. -
Placement is required even when replacing a line. The task must say where a missing line belongs, so a changed file cannot cause an implicit append. See required settings.
This page is docs/reference/modules/line.md in the MMX repository.