Write your own module
Who acts: you, or your coding agent, in your MMX project on your
controller machine: the computer where you run mmx.
When to use this page: no module does a job that your playbooks need
again and again, and a shell node task would need several guards or
could not say correctly whether the command changed the server.
Find the module for a job
helps you decide.
What this page does: you write env_file_setting, a module that makes
sure an environment file such as /etc/shop/shop.env holds one setting,
such as SHOP_PORT=8080, and keeps the file's other lines. You describe
the module's inputs, preview the module with a dryrun, run the module, see
the module say unchanged on the next run, and restart a service when the
module changed the file. Then you write the same module as an executable.
The core module line sets one line of a file that
already exists. env_file_setting also creates the file and returns the
value that the file held before. The module is small on purpose, so that
the page is about writing a module.
Terms:
- A node is a server that MMX manages. A playbook in
playbooks/lists fleet stages. Each fleet stage picks nodes, and each of those nodes runs the fleet stage's node tasks, in order. - A module is the code that does the work of one node task. A module
of the project's own is a directory in the project's
external_modules/, named after the module. - A Starlark script is the usual kind of module of the project's own:
module.star, in Starlark, a small language that reads like Python. - A primitive is a function that MMX gives the script to read or
change the server, such as
read_fileorwrite_file. A script reads and changes the server only through primitives. - The module description is the file
module_description.yml: the module's inputs, outputs, and examples.
| What you need | Where |
|---|---|
| A module as a Starlark script, the usual kind for a module of your own | Steps |
| A service that restarts when the module changed its file | Step 9 |
| A module in Bash, Go, or another language, for a library that Starlark cannot reach | Write the module as an executable instead |
| What to test before others use the module | Test the module |
| A package module for a distribution that has none | A package module for your distribution |
| Every primitive, field, and rule | Module interface reference |
Before you start
- You have an MMX project, as in Get started, with the
group
web_serversininventories/example.yml. The examples use the serversweb01at203.0.113.11andweb02at203.0.113.12, both Debian 13. - A module runs as root on each server, so write or accept only a module that you would trust with root access to your servers.
Steps
-
Create the module's directory.
mkdir -p external_modules/env_file_settingReason: the directory's name is the module's name, which node tasks write. The module's name lists the rules, such as lower-case letters, digits, and underscores, and a name that no core module, official extra module, or node task setting has taken.
Check:
ls external_moduleslistsenv_file_setting. MMX checks the name in step 3. -
Write the script. Create
external_modules/env_file_setting/module.star:# external_modules/env_file_setting/module.star # Makes sure an environment file, such as /etc/shop/shop.env, sets one # setting to one value, and keeps the file's other lines as they are. def run_node_task(inputs): path = inputs["path"] setting = inputs["setting"] value = inputs["value"] # Rules that module_description.yml cannot state. if not path.startswith("/"): return {"status": "invalid_inputs", "reason": "path must be an absolute path, such as /etc/shop/shop.env"} if not setting.replace("_", "").isalnum() or not setting.isupper() or setting[0].isdigit(): return {"status": "invalid_inputs", "reason": "setting must use capital letters, digits, and underscores, such as SHOP_PORT"} if "\n" in value: return {"status": "invalid_inputs", "reason": "value must be one line"} # The directory must exist: an earlier node task creates it. directory = path.rsplit("/", 1)[0] or "/" if not inspect_path(directory).exists: return {"status": "missing_prerequisite", "reason": "the directory " + directory + " does not exist; create it with a directory node task before this one"} # Read the file as it is now. A missing file counts as empty. lines = [] found = inspect_path(path) if found.error: return {"status": "failed", "reason": "looking at " + path + ": " + found.error} if found.exists: if found.type != "file": return {"status": "invalid_inputs", "reason": path + " is a " + found.type + ", not a file"} current = read_file(path) if current.error: return {"status": "failed", "reason": "reading " + path + ": " + current.error} lines = current.content.splitlines() # Replace the setting's line, or add one at the end. previous_value = "" wanted = setting + "=" + value replaced = False new_lines = [] for line in lines: if line.startswith(setting + "="): if not replaced: previous_value = line[len(setting) + 1:] new_lines.append(wanted) replaced = True # A second line for the same setting is dropped. else: new_lines.append(line) if not replaced: new_lines.append(wanted) # write_file changes the file only when its content, owner, group, or # permissions differ, and changes nothing in a dryrun. The file gets # owner root, group root, and permissions 0644 (see the note below). written = write_file(path, "\n".join(new_lines) + "\n") if written.error: return {"status": "failed", "reason": "writing " + path + ": " + written.error} return {"outputs": {"previous_value": previous_value}}What the script does, in order:
- MMX calls
run_node_task(inputs)on the server, with the node task's inputs as a dictionary. - The script checks the rules that the description cannot state, and
returns
invalid_inputswhen an input breaks one. MMX then fails the node task without another try, because another try would end the same way. - A missing directory is
missing_prerequisite, because an earlier node task may still create the directory. A dryrun then reports the node tasknot_checked, and a run fails the node task. inspect_path,read_file, andwrite_fileare primitives. Each primitive returns its answer with anerrortext, which is empty when the call worked. A failed call does not stop the script, so the script returnsfailedwith a reason.- The script returns its output
previous_valueand no change. MMX decides the change: the node task sayschangedwhenwrite_filechanged the file, andunchangedwhen the file already matched. In a dryrun,write_filechanges nothing and says whether the call would change the file, so the script needs no dryrun code of its own. write_filegives the file owner root, group root, and permissions 0644, also when the file exists with other values. A module that must keep an existing file's owner, group, and permissions callsinspect_path(path)first. Whenfound.exists, the module passesfound.owner,found.group, andfound.permissions_modetowrite_fileasowner,group, andpermissions_mode. A new file keeps the defaults.
Check: none yet, because MMX reads a module only together with its description. Step 3 checks both files.
- MMX calls
-
Describe the module. Create
external_modules/env_file_setting/module_description.yml:# external_modules/env_file_setting/module_description.yml summary: Makes sure an environment file sets one setting to one value, and keeps the file's other lines. inputs: path: type: string required: true description: The absolute path of the environment file, such as /etc/shop/shop.env. Its directory must exist; the file is created when it is missing. setting: type: string required: true description: The setting's name, in capital letters, digits, and underscores, such as SHOP_PORT. value: type: string required: true description: The value, on one line, such as "8080". The file gets the line SHOP_PORT=8080. outputs: previous_value: type: string description: The value the file had before the node task, or an empty text when the file had no line for the setting. examples: - description: Set the shop's port to 8080 in /etc/shop/shop.env. config: | env_file_setting: path: /etc/shop/shop.env setting: SHOP_PORT value: "8080"Reason:
mmx validatechecks every node task that calls the module against this description, before any server is contacted. Each input needstype,required, anddescription. The module description lists every field and type.Check:
mmx describe-module env_file_setting --reference-onlyenv_file_setting: the project's own module, Starlark, in external_modules/env_file_setting/ Makes sure an environment file sets one setting to one value, and keeps the file's other lines. Inputs path string required; The absolute path of the environment file, such as /etc/shop/shop.env. Its directory must exist; the file is created when it is missing. setting string required; The setting's name, in capital letters, digits, and underscores, such as SHOP_PORT. value string required; The value, on one line, such as "8080". The file gets the line SHOP_PORT=8080. Outputs previous_value string The value the file had before the node task, or an empty text when the file had no line for the setting. Example: Set the shop's port to 8080 in /etc/shop/shop.env. env_file_setting: path: /etc/shop/shop.env setting: SHOP_PORT value: "8080" Dryrun: MMX runs the Starlark script during a dryrun; functions that would change the node report the proposed changes without applying changes Retry: bounded automatic retries by default; retry: false turns them offIf the command prints an error instead, the error names the file and the line to fix, such as
module_description.yml:5: inputs.path: the required field must be set: .... MMX also checks the example against the inputs. -
Call the module from a playbook. Create
playbooks/configure_shop.yml:# playbooks/configure_shop.yml fleet_stages: - id: configure_shop nodes: web_servers node_tasks: - id: create_settings_directory directory: path: /etc/shop - id: set_shop_port env_file_setting: # the module in external_modules/env_file_setting/ path: /etc/shop/shop.env setting: SHOP_PORT value: "8080" - id: show_previous_port show: "SHOP_PORT was {{ .node_tasks.set_shop_port.previous_value }}"A node task calls a module of the project's own exactly as it calls a core module: the module's name, with its inputs below. A later node task reads the module's output as
.node_tasks.set_shop_port.previous_value."8080"is in quotes because the description saysvalueis a string.Check:
mmx validate configure_shopprintsValid:and the project's name. A mistake names the line and the input, such asplaybooks/configure_shop.yml:14:18 (fleet_stages[0].node_tasks[1].env_file_setting.value): expected a stringforvalue: 8080without quotes. -
Preview the playbook.
mmx dryrun configure_shop echo "exit code $?"The first dryrun on a new server reports the module
not_checked, because/etc/shopdoes not exist yet. The lines forweb01:configure_shop / web01 / create_settings_directory: succeeded, would_change configure_shop / web01 / create_settings_directory: directory "/etc/shop" checked 1 directories and 0 files; 1 entries would change configure_shop / web01 / set_shop_port: not_checked, unknown — the directory /etc/shop does not exist; create it with a directory node task before this one. The earlier node task create_settings_directory would change this node first and may provide what is missing; if the run then succeeds, change nothing. configure_shop / web01 / show_previous_port: not_checked, unknown — ... ... exit code 3Reason: the script returned
missing_prerequisite, and a dryrun creates nothing, so the directory stays missing. MMX names the earlier node task that would create the directory.show_previous_portisnot_checkedtoo, because the node task readsset_shop_port's output.Check:
create_settings_directorysayswould_change,set_shop_portsaysnot_checkedwith the reason above, and the exit code is 3. Once/etc/shopexists, the dryrun checks the module for real, as step 8 shows. -
Run the playbook.
mmx run configure_shopconfigure_shop / web01 / create_settings_directory: succeeded, changed configure_shop / web01 / create_settings_directory: directory "/etc/shop" checked 1 directories and 0 files; 1 metadata updates configure_shop / web01 / set_shop_port: succeeded, changed previous_value: "" configure_shop / web01 / show_previous_port: succeeded, unchanged "SHOP_PORT was " ... Run 63887955: succeededCheck:
set_shop_portsayssucceeded, changed, and the run ends withRun ...: succeededand exit code 0. On the server,cat /etc/shop/shop.envprintsSHOP_PORT=8080, andls -l /etc/shop/shop.envshows-rw-r--r-- 1 root root.previous_valueis empty, because the file was new. -
Run the playbook again.
mmx run configure_shop --output=summaryconfigure_shop / 2 nodes [web01, web02]: succeeded configure_shop / 2 nodes [web01, web02] / create_settings_directory: succeeded, unchanged configure_shop / 2 nodes [web01, web02] / create_settings_directory: directory "/etc/shop" checked 1 directories and 0 files; 0 metadata updates configure_shop / 2 nodes [web01, web02] / set_shop_port: succeeded, unchanged previous_value: "8080" configure_shop / 2 nodes [web01, web02] / show_previous_port: succeeded, unchanged "SHOP_PORT was 8080"--output=summaryshows the servers with the same results on one line.Check:
set_shop_portsaysunchanged, becausewrite_filefound the file as the script wanted the file. If the module sayschangedon every run, the script writes something different each time, such as a time stamp. -
Add a second setting, change the port, and preview the difference. Change
value: "8080"tovalue: "8081", and add this node task afterset_shop_port:- id: set_log_level env_file_setting: path: /etc/shop/shop.env setting: SHOP_LOG_LEVEL value: infoThen preview with each file's difference:
mmx dryrun configure_shop --diff --output=summaryconfigure_shop / 2 nodes [web01, web02] / set_shop_port: succeeded, would_change previous_value: "8080" --- before +++ after @@ -1,1 +1,1 @@ -SHOP_PORT=8080 +SHOP_PORT=8081 configure_shop / 2 nodes [web01, web02] / set_log_level: succeeded, would_change previous_value: "" --- before +++ after @@ -1,1 +1,2 @@ SHOP_PORT=8080 +SHOP_LOG_LEVEL=infoMMX built the difference from the script's
write_filecall. In a dryrun,set_log_levelreads the file as the file is now, withSHOP_PORT=8080, because the dryrun did not writeset_shop_port's change. For a file that other accounts cannot read, such as mode 0640 with another owner,--diffshows the file's name and no content difference; the reference says so.Check: both node tasks say
would_change, and the exit code is 2. Then runmmx run configure_shop. On the server,cat /etc/shop/shop.envprints:SHOP_PORT=8081 SHOP_LOG_LEVEL=info -
Restart a service when the module changed the file. A program reads an environment file when the program starts, so a changed setting needs a restart. Put the module's node tasks in the
changesof a node task block, and the restart in the block'sactivate. The example serviceshop.serviceis a stand-in that prints its port. The whole playbook now reads:# playbooks/configure_shop.yml fleet_stages: - id: configure_shop nodes: web_servers node_tasks: - id: create_settings_directory directory: path: /etc/shop - task_block: id: shop_settings changes: - id: install_shop_unit systemd_unit: name: shop.service content: | [Unit] Description=Shop stand-in that prints its port [Service] EnvironmentFile=/etc/shop/shop.env ExecStart=/bin/sh -c "echo shop listens on port $SHOP_PORT; exec sleep infinity" [Install] WantedBy=multi-user.target - id: set_shop_port env_file_setting: path: /etc/shop/shop.env setting: SHOP_PORT value: "8081" - id: set_log_level env_file_setting: path: /etc/shop/shop.env setting: SHOP_LOG_LEVEL value: info activate: - id: restart_shop systemd_service: name: shop.service start_at_boot: true state: running refresh: restartRun
mmx run configure_shop --output=summary. On the first run, the service is new, so MMX starts the service instead of restarting it:configure_shop / 2 nodes [web01, web02] / shop_settings/activate/restart_shop: succeeded, changed — service is not runningThen change
value: "8081"tovalue: "8082", and run again:configure_shop / 2 nodes [web01, web02] / shop_settings/changes/set_shop_port: succeeded, changed configure_shop / 2 nodes [web01, web02] / shop_settings/changes/set_log_level: succeeded, unchanged configure_shop / 2 nodes [web01, web02] / shop_settings/activate/restart_shop: succeeded, changed — tracked input module env_file_setting changed after the service last started or reloadedReason: the module's
write_filecall changed the file, so the fingerprint of the module's kept files differs from the one the service last started with. A later run with nothing new saysunchangedforrestart_shop. Tracked input and Reload or restart explain the rules.Check: on the server,
journalctl -u shop.service -o cat | grep listensprintsshop listens on port 8081, thenshop listens on port 8082.
Write the module as an executable instead
An executable module is any program that runs on the server, such as a Bash script or a Go program. Write one when a Starlark script cannot do the work, such as with a library that exists only in another language. MMX cannot see what an executable changes, so the executable must do four things that MMX does for a script:
- change nothing in a dryrun, which MMX calls
checkmode, - report its own change:
would_changein a dryrun,changedorunchangedin a run, - report the difference that
--diffshows, - report a fingerprint, when the module is in a node task block's
changes.
The executable must also find on the server whatever it uses, such as
bash, because MMX finds no program for an executable.
These steps replace the script of env_file_setting with a Bash
executable. A module's directory holds a script or an executable, not
both, and the playbook stays the same.
-
Write the executable. Create
external_modules/env_file_setting/module_executable:#!/bin/bash # external_modules/env_file_setting/module_executable # Makes sure an environment file sets one setting to one value, and keeps # the file's other lines as they are. set -euo pipefail helper=$MMX_MODULE_HELPER # mmx-runner, which reads and writes the JSON for this script request=$("$helper" module-json request --inputs path,setting,value) mode=$("$helper" module-json get --type string /mode <<< "$request") path=$("$helper" module-json get --type string /inputs/path <<< "$request") setting=$("$helper" module-json get --type string /inputs/setting <<< "$request") value=$("$helper" module-json get --type string /inputs/value <<< "$request") change=unchanged fail() { "$helper" module-json result --mode "$mode" --status failed --change "$change" --reason "$1" exit 1 } # Rules that module_description.yml cannot state. $(...) drops a final # newline, so count the lines of value as the helper prints it. [[ $path == /* ]] || fail "path must be an absolute path, such as /etc/shop/shop.env" [[ $setting =~ ^[A-Z_][A-Z0-9_]*$ ]] || fail "setting must use capital letters, digits, and underscores, such as SHOP_PORT" lines=$("$helper" module-json get --type string /inputs/value <<< "$request" | wc -l) [[ $lines -eq 0 ]] || fail "value must be one line" # The directory must exist: an earlier node task creates it. A dryrun # reports the task not_checked, because that node task has not run yet. directory=$(dirname -- "$path") if [[ ! -d $directory ]]; then reason="the directory $directory does not exist; create it with a directory node task before this one" if [[ $mode == check ]]; then "$helper" module-json result --mode check --status not_checked --change unknown --reason "$reason" exit 0 fi fail "$reason" fi if [[ -L $path || ( -e $path && ! -f $path ) ]]; then fail "$path is not a regular file" fi # Build the new content: replace the setting's line, or add one at the end. previous_value="" found=no new_content="" if [[ -f $path ]]; then while IFS= read -r line || [[ -n $line ]]; do if [[ $line == "$setting="* ]]; then if [[ $found == no ]]; then previous_value=${line#"$setting="} new_content+="$setting=$value"$'\n' found=yes fi else new_content+="$line"$'\n' fi done < "$path" fi [[ $found == yes ]] || new_content+="$setting=$value"$'\n' fingerprint=$(printf '%s' "$new_content" | sha256sum | cut -d ' ' -f 1) # Compare with the file on the node: content, owner, group, and permissions. old_file=/dev/null if [[ -f $path ]]; then old_file=$path fi if [[ $old_file == /dev/null ]] \ || ! cmp -s -- "$path" <(printf '%s' "$new_content") \ || [[ $(stat -c '%U %G %a' -- "$path") != "root root 644" ]]; then change=would_change fi difference="" if [[ $change == would_change ]]; then difference=$(diff -u --label before --label after -- "$old_file" <(printf '%s' "$new_content") || true) fi # A run writes a new file beside the old one, then renames it into place. if [[ $mode == apply && $change == would_change ]]; then change=unchanged temporary=$(mktemp "$directory/.env_file_setting.XXXXXX") || fail "could not create a file in $directory" printf '%s' "$new_content" > "$temporary" || fail "could not write $temporary" chown root:root -- "$temporary" && chmod 0644 -- "$temporary" || fail "could not set the owner and permissions of $temporary" mv -f -- "$temporary" "$path" || fail "could not replace $path" change=changed fi printf '%s' "$difference" | "$helper" module-json result --mode "$mode" --change "$change" \ --output previous_value "$previous_value" --fingerprint "$fingerprint" --diff-stdinWhat the executable does, in order:
- MMX starts the executable once for each try, as root, and writes one
JSON request to its standard input, such as
{"protocol":1,"mode":"check","inputs":{"path":"/etc/shop/shop.env","setting":"SHOP_PORT","value":"8081"}}.modeischeckin a dryrun andapplyin a run. MMX_MODULE_HELPERnamesmmx-runner, MMX's program on the server, whosemodule-jsoncommands read the request and write the result. The executable protocol lists them.- The executable compares the file with what the file should be, and
writes the file only in
applymode. - The executable prints exactly one JSON result on its standard
output, with
would_change,changed, orunchanged, the difference, the fingerprint, and the outputprevious_value.
Then make the file executable and remove the script:
chmod +x external_modules/env_file_setting/module_executable rm external_modules/env_file_setting/module.starCheck:
mmx validate configure_shopprintsValid:. If it saysthe module's module_executable must be executable by its owner, run thechmodcommand. - MMX starts the executable once for each try, as root, and writes one
JSON request to its standard input, such as
-
Try the executable by hand. On a Linux computer with
mmxinstalled, send the executable a request incheckmode, which changes nothing.mmxprovides the samemodule-jsoncommands:export MMX_MODULE_HELPER=$(command -v mmx) mkdir -p /tmp/env-file-test printf 'SHOP_PORT=8080\n' > /tmp/env-file-test/shop.env echo '{"protocol":1,"mode":"check","inputs":{"path":"/tmp/env-file-test/shop.env","setting":"SHOP_PORT","value":"8081"}}' \ | external_modules/env_file_setting/module_executable echo "exit $?"{"protocol":1,"status":"succeeded","change":"would_change","outputs":{"previous_value":"8080"},"diff":"--- before\n+++ after\n@@ -1 +1 @@\n-SHOP_PORT=8080\n+SHOP_PORT=8081","fingerprint":"c5b0503eeda95d30e4b5e4627d0466ff7ffb3163e8bae2bf5567d9c5e46126cc"} exit 0The executable uses
stat -c, which only GNUstaton Linux accepts. On a Mac, go on to step 3, which tests the executable on the servers.Check: the result says
would_changeandprevious_valueis8080. With"setting":"shop_port"instead, the result says"status":"failed"with the reason, and the exit code is 1. Remove/tmp/env-file-testafterwards. -
Check how MMX sees the module.
mmx describe-module env_file_setting --reference-onlyCheck: the first line says
env_file_setting: the project's own module, executable, in external_modules/env_file_setting/, and theDryrun:line saysMMX runs the executable in check mode. MMX cannot see what an executable changes, so the module must keep its own dryrun promise.mmx module-usagelists the module asexecutable (Bash). -
Preview and run the playbook. Change
value: "8082"tovalue: "8083", then:mmx dryrun configure_shop --diff --output=summary mmx run configure_shop --output=summary mmx run configure_shop --output=summaryThe dryrun shows the executable's difference and the restart that a run would make:
configure_shop / 2 nodes [web01, web02] / shop_settings/changes/set_shop_port: succeeded, would_change previous_value: "8082" --- before +++ after @@ -1,2 +1,2 @@ -SHOP_PORT=8082 +SHOP_PORT=8083 ... configure_shop / 2 nodes [web01, web02] / shop_settings/activate/restart_shop: succeeded, would_change — tracked input module env_file_setting changed after the service last started or reloadedCheck: the first run says
set_shop_port: succeeded, changedandrestart_shop: succeeded, changed. The second run saysunchangedfor every node task. On the server,cat /etc/shop/shop.envprintsSHOP_PORT=8083andSHOP_LOG_LEVEL=info.
The first run after you switch a module between a script and an executable restarts the service once. Tracked input says why.
The executable protocol
lists every request and result field, the module-json commands, and the
rules for status, change, and exit code. A compiled program, such as one in
Go, can ship module_executable_linux_amd64, module_executable_linux_arm64,
or both; a node whose processor has no build fails the node task.
To build the Go example examples/external-modules/go/greeting
for both processors, run these commands from the root of a checkout of
MMX's source code. CGO_ENABLED=0 makes a program that needs no C
library on the server:
mkdir -p /tmp/greeting-build
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
-o /tmp/greeting-build/module_executable_linux_amd64 ./examples/external-modules/go/greeting
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build \
-o /tmp/greeting-build/module_executable_linux_arm64 ./examples/external-modules/go/greeting
Copy the two builds and module_description.yml into the module's
directory.
Test the module
Test a module on a test server before others use the module. Check the
server itself, such as with cat, not only the module's result:
- A dryrun on a server that already matches says
unchanged, and a dryrun that would change the server changes nothing. - A run makes the right change and says
changed. The next run saysunchanged. - Each input that breaks a rule fails with a reason that says what to write instead.
- A dryrun on a new server, where an earlier node task would create what
the module needs, says
not_checked, and the run then succeeds. - For an executable: stop the program after its change and before its
result, such as with
kill, then run the playbook again. The next run must finish the work and saychangedorunchangedcorrectly. - For a module that takes a password: the saved results and the output
hold no password. Secrets in a module
says how MMX hides an input marked
private_value: true.
If something is different
| What you see | What it means and what to do |
|---|---|
set_shop_port: failed, unchanged — setting must use capital letters, digits, and underscores, such as SHOP_PORT |
The script returned invalid_inputs. Fix the input in the playbook. MMX did not try again. |
failed, unchanged — node task did not finish after 3 tries, because each try failed or left retry.until false: the script of the module env_file_setting ended with an error: module/env_file_setting/module.star:7:21: key "settings" not in dict |
The script stopped with an error at line 7, column 21. A module's node task tries again by default, 3 tries in all. Fix the script. A script that does not parse at all (a syntax error) fails at once, without another try. MMX names the file module/<name>/module.star, wherever the module's directory is. |
the module env_file_setting in external_modules/: the module needs module.star (a Starlark script) or module_executable |
The module's directory holds neither file. Check the file name. |
the module env_file_setting in external_modules/: .../module_description.yml:5: inputs.path: the required field must be set: true if every module call must supply the input, false if the input can be omitted |
The description lacks a field. The number after the file name is the line to fix. |
unknown input "settings": the inputs of the module env_file_setting are path, setting, value |
The playbook gives an input that the description does not list. Fix the playbook, or add the input to the description. |
the input setting is required: The setting's name, ... |
The playbook leaves out an input that the description marks required: true. |
the module's module_executable must be executable by its owner |
Run chmod +x external_modules/env_file_setting/module_executable. |
mmx: external_modules/line: line is a core module of MMX; give the module another name |
Another module has the name. Rename the directory and the node tasks that call the module. The module's name lists the taken names. |
The module says changed on every run |
The script writes something different each time, or an executable reports changed without comparing. Compare the file on the server after two runs. |
| The service does not restart after the module changed the file | The module's node task is not in the same node task block's changes as the service's activate node task. |
module env_file_setting is in a node task block's changes phase; the block has service actions or commands that depend on changed inputs, so the module result must include a fingerprint |
The executable reports no fingerprint. Add --fingerprint to its module-json result call. |
Where to go next
- Module interface reference: every primitive and what it returns, the description's fields, the executable protocol, secrets, and limits.
- Change a configuration and reload its service: node task blocks, checks, and putting a file back when a change fails.
- A package module for your distribution:
a package module, built from the official extra module
pacman_package. - Add a core module: for a change to MMX itself, not to your project.
examples/external-modules/: agreetingmodule as a Starlark script, a Bash executable, and a Go executable.
This page is docs/how-to/write-your-own-module.md in the MMX repository.