Cfgmgmt

@swamp/cfgmgmtv2026.10.27.1· AGPL-3.0-or-later· 3d agoBEHAVIORSREPORTSACCEPTED WARNINGS

01README

SSH-based configuration management for Linux, with package and command models for macOS.

Manage remote systems over SSH using the check/apply pattern — every model is idempotent and reports whether resources are compliant, non-compliant, applied, or failed. Convergence failures propagate as step failures so workflow orchestration can detect and react to errors.

Includes 36 model types:

@swamp/cfgmgmt/node — Gather system facts (OS, arch, package managers)
@swamp/cfgmgmt/file — Create, update, or remove files
@swamp/cfgmgmt/template — Render EJS templates and deploy to remote hosts. Uses <%= var %> for plain string interpolation (HTML escaping is disabled). Whitespace control: -%> strips the trailing newline (use on loop/conditional lines to avoid blank lines in output), <%_ %> strips leading whitespace, _%> strips all trailing whitespace.
@swamp/cfgmgmt/directory — Create or remove directories
@swamp/cfgmgmt/link — Manage symbolic links
@swamp/cfgmgmt/line — Edit individual lines in files using regex matching
@swamp/cfgmgmt/exec — Run commands with onlyIf/notIf guards
@swamp/cfgmgmt/systemd — Manage systemd services and unit files
@swamp/cfgmgmt/dnf — Manage packages on Fedora/RHEL (with version pinning)
@swamp/cfgmgmt/apt — Manage packages on Debian/Ubuntu (with version pinning)
@swamp/cfgmgmt/pacman — Manage packages on Arch Linux
@swamp/cfgmgmt/homebrew — Manage packages on macOS
@swamp/cfgmgmt/apt_repository — Manage apt sources and GPG keys
@swamp/cfgmgmt/dnf_repository — Manage dnf/yum repository files
@swamp/cfgmgmt/hostname — Set system hostname
@swamp/cfgmgmt/timezone — Set system timezone
@swamp/cfgmgmt/user — Manage system users
@swamp/cfgmgmt/group — Manage system groups
@swamp/cfgmgmt/authorized_key — Manage SSH authorized keys
@swamp/cfgmgmt/host_entry — Manage /etc/hosts entries
@swamp/cfgmgmt/sysctl — Manage kernel parameters
@swamp/cfgmgmt/kernel_module — Load/unload kernel modules with persistence
@swamp/cfgmgmt/cron — Manage cron jobs
@swamp/cfgmgmt/mount — Manage filesystem mounts and fstab
@swamp/cfgmgmt/firewall — Manage firewall rules (ufw/firewalld/iptables)
@swamp/cfgmgmt/selinux — Manage SELinux mode and booleans
@swamp/cfgmgmt/docker_image — Manage Docker images
@swamp/cfgmgmt/docker_container — Manage Docker containers
@swamp/cfgmgmt/git — Manage git repository checkouts
@swamp/cfgmgmt/archive — Extract archives idempotently
@swamp/cfgmgmt/copy_file — Copy a local file to remote hosts via SCP
@swamp/cfgmgmt/fetch — Download files from URLs with checksum verification
@swamp/cfgmgmt/reboot — Reboot hosts and wait for SSH reconnection
@swamp/cfgmgmt/debug_exec — Run a command on a remote host and capture stdout, stderr, and exit code as data
@swamp/cfgmgmt/debug_file — Fetch a remote file's content and store it as data
@swamp/cfgmgmt/certificate — Deploy SSL/TLS certificates with validation

Every model is a factory across hosts — a single definition can target multiple hosts via workflow forEach, with per-host data stored separately.

Connections are multiplexed via OpenSSH ControlMaster sockets. All models (except node and homebrew) support sudo privilege escalation.

Requirements

OpenSSH client (ssh, scp) on the runner.
sudo on the target for any model run with become: true.
GNU coreutils (stat, readlink -f) on targets managed by the file models (file, template, directory, copy_file, line, fetch, certificate, authorized_key): these models support Linux targets.

Moving from @adam/cfgmgmt

This extension was previously published as @adam/cfgmgmt. The models are the same; only the type prefix changed. Update existing definitions with:

grep -rl '@adam/cfgmgmt/' models/ | xargs sed -i.bak 's#@adam/cfgmgmt/#@swamp/cfgmgmt/#g'
swamp extension pull @swamp/cfgmgmt

02Behaviors36

@swamp/cfgmgmt/nodev2026.10.27.1node.ts

Global Arguments

Argument	Type	Required	Description
hostname	string	yes	Hostname or IP of the remote node
sshUser?	string	no	SSH username
sshPort?	number	no	SSH port
sshIdentityFile?	string	no	Path to SSH private key

fn gather()

SSH to node and gather system facts

Resources

info(infinite)— Facts gathered from the node

@swamp/cfgmgmt/filev2026.10.27.1file.ts

Global Arguments

Argument	Type	Required	Description
path	string	yes	Absolute path of the file on the remote node
ensure	enum	yes	Whether file should be present or absent
content?	string	no	Desired file content. When omitted, a missing file is created empty and an existing file's content is left alone
owner?	string	no	File owner
group?	string	no	File group
mode?	string	no	File permissions in octal (e.g. 0644)
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if file matches desired state (dry-run)

fn apply()

Apply desired file state to the remote node

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/templatev2026.10.27.1template.ts

Global Arguments

Argument	Type	Required	Description
path	string	yes	Absolute path of the file on the remote node
ensure	enum	yes	Whether file should be present or absent
template?	string	no	EJS template string
variables?	record	no	Template variables passed to EJS
owner?	string	no	File owner
group?	string	no	File group
mode?	string	no	File permissions in octal (e.g. 0644)
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if rendered template matches desired state (dry-run)

fn apply()

Render template and apply desired file state to the remote node

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/directoryv2026.10.27.1directory.ts

Global Arguments

Argument	Type	Required	Description
path	string	yes	Absolute path of the directory
ensure	enum	yes	Whether directory should be present or absent
owner?	string	no	Directory owner
group?	string	no	Directory group
mode?	string	no	Directory permissions in octal (e.g. 0755)
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if directory matches desired state (dry-run)

fn apply()

Apply desired directory state to the remote node

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/linkv2026.10.27.1link.ts

Global Arguments

Argument	Type	Required	Description
path	string	yes	Path where the symlink should exist
ensure	enum	yes	Whether symlink should be present or absent
target?	string	no	Target the symlink should point to
owner?	string	no	Symlink owner
group?	string	no	Symlink group
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if symlink matches desired state (dry-run)

fn apply()

Apply desired symlink state to the remote node

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/execv2026.10.27.1exec.ts

Global Arguments

Argument	Type	Required	Description
command	string	yes	The command to execute
onlyIf?	string	no	Guard: only run if this command exits 0
notIf?	string	no	Guard: skip if this command exits 0
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Dry-run: evaluate the onlyIf/notIf guards without executing the command

fn apply()

Execute the command on the remote node via SSH

Resources

state(infinite)— Result of command execution

@swamp/cfgmgmt/systemdv2026.10.27.1systemd.ts

Global Arguments

Argument	Type	Required	Description
service	string	yes	Service name (e.g. nginx or nginx.service)
ensure?	enum	no	Whether service should be running or stopped
enabled?	boolean	no	Whether the service should be enabled at boot
unitFile?	string	no	Full content of a systemd unit file to deploy
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if service matches desired state (dry-run)

fn apply()

Apply desired service state to the remote node

fn restart()

Restart the service (imperative, always runs)

fn logs(lines?: number)

Fetch recent journal logs for the service

Argument	Type	Required	Description
lines?	number	no	Number of journal lines to fetch

Resources

state(infinite)— Result of check or apply operation

logs(infinite)— Journal log output for the service

@swamp/cfgmgmt/dnfv2026.10.27.1dnf.ts

Global Arguments

Argument	Type	Required	Description
packages?	array	no	Package names to manage
ensure?	enum	no	Whether packages should be present or absent
version?	string	no	Pin to a specific package version (e.g. 1.24.0-1.el9). Applies to all packages in the list.
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if packages match desired state without modifying

fn apply()

Install or remove packages based on ensure state

fn refresh()

Refresh the dnf package metadata

fn upgrade()

Upgrade all installed packages

fn list()

List all installed packages

Resources

state(infinite)— Package operation state

installed(infinite)— All installed packages

@swamp/cfgmgmt/aptv2026.10.27.1apt.ts

Global Arguments

Argument	Type	Required	Description
packages?	array	no	Package names to manage
ensure?	enum	no	Whether packages should be present or absent
version?	string	no	Pin to a specific package version (e.g. 1.24.0-1ubuntu1). Applies to all packages in the list.
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if packages match desired state without modifying

fn apply()

Install or remove packages based on ensure state

fn refresh()

Update the apt package database

fn upgrade()

Upgrade all installed packages

fn list()

List all installed packages

Resources

state(infinite)— Package operation state

installed(infinite)— All installed packages

@swamp/cfgmgmt/pacmanv2026.10.27.1pacman.ts

Global Arguments

Argument	Type	Required	Description
packages?	array	no	Package names to manage
ensure?	enum	no	Whether packages should be present or absent
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if packages match desired state without modifying

fn apply()

Install or remove packages based on ensure state

fn refresh()

Update the pacman package database

fn upgrade()

Upgrade all installed packages

fn list()

List all installed packages

Resources

state(infinite)— Package operation state

installed(infinite)— All installed packages

@swamp/cfgmgmt/homebrewv2026.10.27.1homebrew.ts

Global Arguments

Argument	Type	Required	Description
packages?	array	no	Formula names to manage
ensure?	enum	no	Whether packages should be present or absent
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Accepted but ignored (brew forbids root)
becomeUser?	string	no	Accepted but ignored
becomePassword?	string	no	Accepted but ignored

fn check()

Check if packages match desired state without modifying

fn apply()

Install or remove packages based on ensure state

fn refresh()

Update the homebrew package database

fn upgrade()

Upgrade all installed packages

fn list()

List all installed packages

Resources

state(infinite)— Package operation state

installed(infinite)— All installed packages

@swamp/cfgmgmt/hostnamev2026.10.27.1hostname.ts

Global Arguments

Argument	Type	Required	Description
name	string	yes	Desired system hostname
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if hostname matches desired state (dry-run)

fn apply()

Set the system hostname to the desired value

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/timezonev2026.10.27.1timezone.ts

Global Arguments

Argument	Type	Required	Description
timezone	string	yes	Desired IANA timezone (e.g. America/New_York)
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if timezone matches desired state (dry-run)

fn apply()

Set the system timezone to the desired value

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/userv2026.10.27.1user.ts

Global Arguments

Argument	Type	Required	Description
username	string	yes	Username to manage
ensure	enum	yes	Whether user should be present or absent
uid?	number	no	Desired UID
gid?	number	no	Desired primary GID
groups?	array	no	Supplementary groups
home?	string	no	Home directory path
shell?	string	no	Login shell
system?	boolean	no	Create as system user
managehome?	boolean	no	Manage home directory (create with useradd -m, remove with userdel -r)
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if user matches desired state (dry-run)

fn apply()

Create, modify, or remove a system user

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/groupv2026.10.27.1group.ts

Global Arguments

Argument	Type	Required	Description
groupname	string	yes	Group name to manage
ensure	enum	yes	Whether group should be present or absent
gid?	number	no	Desired GID
members?	array	no	Group members
system?	boolean	no	Create as system group
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if group matches desired state (dry-run)

fn apply()

Create, modify, or remove a system group

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/authorized_keyv2026.10.27.1authorized_key.ts

Global Arguments

Argument	Type	Required	Description
user	string	yes	User whose authorized_keys file to manage
key	string	yes	Full SSH public key line
ensure	enum	yes	Whether the key should be present or absent
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if SSH authorized key matches desired state (dry-run)

fn apply()

Add or remove an SSH public key from a user's authorized_keys

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/host_entryv2026.10.27.1host_entry.ts

Global Arguments

Argument	Type	Required	Description
hostname	string	yes	Primary hostname for the /etc/hosts entry
ip	string	yes	IP address for the entry
aliases?	array	no	Additional hostname aliases
ensure	enum	yes	Whether the entry should be present or absent
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if /etc/hosts entry matches desired state (dry-run)

fn apply()

Add, update, or remove an /etc/hosts entry

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/sysctlv2026.10.27.1sysctl.ts

Global Arguments

Argument	Type	Required	Description
key	string	yes	Sysctl key (e.g. net.ipv4.ip_forward)
value	string	yes	Desired value
ensure?	enum	no	Whether the sysctl parameter should be present or absent
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if sysctl parameter matches desired state (dry-run)

fn apply()

Set or remove a sysctl kernel parameter

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/cronv2026.10.27.1cron.ts

Global Arguments

Argument	Type	Required	Description
name	string	yes	Unique identifier for this cron job
ensure	enum	yes	Whether the cron job should be present or absent
command	string	yes	Command to run
user?	string	no	User whose crontab to manage
minute?	string	no	Minute (0-59 or *)
hour?	string	no	Hour (0-23 or *)
day?	string	no	Day of month (1-31 or *)
month?	string	no	Month (1-12 or *)
weekday?	string	no	Day of week (0-7 or *)
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if cron job matches desired state (dry-run)

fn apply()

Add, update, or remove a cron job

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/mountv2026.10.27.1mount.ts

Global Arguments

Argument	Type	Required	Description
path	string	yes	Mount point path
device	string	yes	Device or remote filesystem to mount
fstype	string	yes	Filesystem type (e.g. ext4, nfs, tmpfs)
options?	string	no	Mount options (e.g. defaults,noatime)
ensure	enum	yes	Desired mount state: mounted=fstab+mounted, unmounted=fstab+not mounted, present=fstab only, absent=remove fstab+unmount
dump?	number	no	fstab dump field
pass?	number	no	fstab pass field
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if mount matches desired state (dry-run)

fn apply()

Manage filesystem mount and fstab entry

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/firewallv2026.10.27.1firewall.ts

Global Arguments

Argument	Type	Required	Description
port	number	yes	Port number
protocol?	enum	no	Protocol (tcp or udp)
action	enum	yes	Firewall action for the rule
direction?	enum	no	Traffic direction
source?	string	no	Source CIDR (e.g. 10.0.0.0/8)
ensure?	enum	no	Whether the rule should be present or absent
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if firewall rule matches desired state (dry-run)

fn apply()

Add or remove a firewall rule

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/selinuxv2026.10.27.1selinux.ts

Global Arguments

Argument	Type	Required	Description
mode?	enum	no	Desired SELinux mode (mutually exclusive with boolean)
boolean?	string	no	SELinux boolean name (mutually exclusive with mode)
booleanValue?	enum	no	Desired boolean value
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if SELinux matches desired state (dry-run)

fn apply()

Set SELinux mode or boolean value

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/docker_imagev2026.10.27.1docker_image.ts

Global Arguments

Argument	Type	Required	Description
image	string	yes	Docker image name with tag (e.g. nginx:1.25)
ensure	enum	yes	Whether image should be present or absent
force?	boolean	no	Force pull even if image is already present
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if Docker image matches desired state (dry-run)

fn apply()

Pull or remove a Docker image

fn prune()

Remove dangling Docker images (imperative, always runs)

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/docker_containerv2026.10.27.1docker_container.ts

Global Arguments

Argument	Type	Required	Description
name	string	yes	Container name
image	string	yes	Docker image (e.g. nginx:1.25)
ensure	enum	yes	Desired container state
ports?	array	no	Port mappings (e.g. ["8080:80", "443:443"])
environment?	array	no	Environment variables (e.g. ["FOO=bar"])
volumes?	array	no	Volume mounts (e.g. ["/host:/container"])
restart?	enum	no	Restart policy
command?	string	no	Override container command
network?	string	no	Docker network to connect to
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if Docker container matches desired state (dry-run)

fn apply()

Create, start, stop, or remove a Docker container

fn logs(lines?: number)

Fetch recent container logs

Argument	Type	Required	Description
lines?	number	no	Number of log lines to fetch

fn restart()

Restart the container (imperative, always runs)

Resources

state(infinite)— Result of check or apply operation

logs(infinite)— Container log output

@swamp/cfgmgmt/gitv2026.10.27.1git.ts

Global Arguments

Argument	Type	Required	Description
path	string	yes	Local path for the repository
repo	string	yes	Git repository URL
revision?	string	no	Branch, tag, or commit hash (default HEAD = default branch)
ensure	enum	yes	Whether the repository should be present or absent
depth?	number	no	Shallow clone depth
owner?	string	no	Repository owner
group?	string	no	Repository group
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if git repository matches desired state (dry-run)

fn apply()

Clone, update, or remove a git repository

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/archivev2026.10.27.1archive.ts

Global Arguments

Argument	Type	Required	Description
source	string	yes	Path to the archive file on the remote node
dest	string	yes	Extraction destination directory
format?	enum	no	Archive format; `auto` detects it from the source's extension
creates?	string	no	Idempotency guard: skip extraction if this path exists. Without it,
owner?	string	no	Owner for extracted files
group?	string	no	Group for extracted files
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if archive has been extracted (dry-run)

fn apply()

Extract an archive to the destination directory

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/linev2026.10.27.1line.ts

Global Arguments

Argument	Type	Required	Description
path	string	yes	Absolute path of the file on the remote node
regexp	string	yes	Regular expression to match the target line. First match is used.
line?	string	no	The line to insert or replace. Required when ensure is present.
ensure?	enum	no	Whether the matching line should be present or absent
insertAfter?	string	no	Regex pattern — insert the line after the last match of this pattern if regexp has no match. Defaults to EOF.
insertBefore?	string	no	Regex pattern — insert the line before the first match of this pattern if regexp has no match
createFile?	boolean	no	Create the file if it does not exist (ensure=present only)
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if the line matches desired state in the file (dry-run)

fn apply()

Ensure a line is present/absent in the file

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/copy_filev2026.10.27.1copy_file.ts

Global Arguments

Argument	Type	Required	Description
source	string	yes	Path to the local source file. Resolved relative to the repository root if not absolute.
path	string	yes	Absolute path of the file on the remote node
ensure	enum	yes	Whether file should be present or absent
owner?	string	no	File owner
group?	string	no	File group
mode?	string	no	File permissions in octal (e.g. 0644)
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if remote file matches local source file (dry-run)

fn apply()

Copy local source file to the remote node

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/fetchv2026.10.27.1fetch.ts

Global Arguments

Argument	Type	Required	Description
url	string	yes	URL to download (http, https or ftp)
path	string	yes	Absolute path where the downloaded file should be placed on the remote node
checksum?	string	no	Expected checksum of the file (e.g. sha256:abc123...). Used for idempotency.
checksumType?	enum	no	Checksum algorithm to use (md5 is deprecated, prefer sha256)
owner?	string	no	File owner
group?	string	no	File group
mode?	string	no	File permissions in octal (e.g. 0755)
force?	boolean	no	Re-download even if the file already exists and checksum matches
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if the file has been downloaded and matches expected state (dry-run)

fn apply()

Download a file from a URL to the remote node

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/apt_repositoryv2026.10.27.1apt_repository.ts

Global Arguments

Argument	Type	Required	Description
name	string	yes	Repository identifier used for the .list/.sources filename (e.g. docker, nodesource)
ensure?	enum	no	Whether the repository should be present or absent
uris?	array	no	Repository URIs (e.g. ['https://download.docker.com/linux/ubuntu']). For DEB822 format.
suites?	array	no	Repository suites (e.g. ['noble']). For DEB822 format.
components?	array	no	Repository components (e.g. ['stable']). For DEB822 format.
architectures?	array	no	Architectures to enable (e.g. ['amd64']). For DEB822 format.
signedBy?	string	no	Path to the GPG keyring file on the remote node (e.g. /usr/share/keyrings/docker.gpg)
gpgKeyUrl?	string	no	URL to download the GPG key from. Will be dearmored and saved to signedBy path.
sourceLine?	string	no	Legacy one-line format: 'deb [options] uri suite component...' — written to /etc/apt/sources.list.d/<name>.list. Mutually exclusive with uris/suites/components.
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if the apt repository is configured as desired (dry-run)

fn apply()

Configure or remove an apt repository on the remote node

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/dnf_repositoryv2026.10.27.1dnf_repository.ts

Global Arguments

Argument	Type	Required	Description
name	string	yes	Repository ID used as the [section] name and .repo filename (e.g. docker-ce-stable)
ensure?	enum	no	Whether the repository should be present or absent
description?	string	no	Human-readable repository name (e.g. 'Docker CE Stable')
baseurl?	string	no	Base URL of the repository (e.g. https://download.docker.com/linux/fedora/$releasever/$basearch/stable)
metalink?	string	no	Metalink URL (alternative to baseurl)
mirrorlist?	string	no	Mirror list URL (alternative to baseurl)
enabled?	boolean	no	Whether the repository is enabled
gpgcheck?	boolean	no	Whether GPG signature checking is enabled
gpgkey?	string	no	URL of the GPG key for the repository (e.g. https://download.docker.com/linux/fedora/gpg)
sslverify?	boolean	no	Whether to verify SSL certificates
repo_gpgcheck?	boolean	no	Whether to verify repository metadata GPG signatures
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if the dnf repository is configured as desired (dry-run)

fn apply()

Configure or remove a dnf/yum repository on the remote node

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/kernel_modulev2026.10.27.1kernel_module.ts

Global Arguments

Argument	Type	Required	Description
name	string	yes	Kernel module name (e.g. br_netfilter, overlay)
ensure?	enum	no	Whether the module should be loaded or unloaded
params?	string	no	Module parameters (e.g. 'option1=value1 option2=value2')
persist?	boolean	no	Persist the module across reboots via /etc/modules-load.d/
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if the kernel module is loaded/persisted as desired (dry-run)

fn apply()

Load or unload a kernel module and manage persistence

Resources

state(infinite)— Result of check or apply operation

@swamp/cfgmgmt/rebootv2026.10.27.1reboot.ts

Global Arguments

Argument	Type	Required	Description
timeout?	number	no	Maximum seconds to wait for the host to come back after reboot
message?	string	no	Broadcast message before reboot
testCommand?	string	no	Command to run after reconnection to verify the host is healthy
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check is always non-compliant — reboot is an imperative action

fn apply()

Reboot the remote host and wait for SSH to become available again

Resources

state(infinite)— Result of the reboot operation

@swamp/cfgmgmt/debug_execv2026.10.27.1debug_exec.ts

Global Arguments

Argument	Type	Required	Description
command	string	yes	The command to execute on the remote host
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn run()

Execute the command on the remote host and capture output as data

Resources

state(infinite)— Output captured from remote command execution

@swamp/cfgmgmt/debug_filev2026.10.27.1debug_file.ts

Global Arguments

Argument	Type	Required	Description
path	string	yes	Absolute path of the file to read on the remote node
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn run()

Fetch the file content from the remote host and store it as data

Resources

state(infinite)— Content fetched from a remote file

@swamp/cfgmgmt/certificatev2026.10.27.1certificate.ts

Global Arguments

Argument	Type	Required	Description
name	string	yes	Certificate name — used as a label in state output
certContent	string	yes	PEM-encoded certificate content
keyContent	string	yes	PEM-encoded private key content
chainContent?	string	no	PEM-encoded certificate chain (intermediate + root CAs)
certPath	string	yes	Absolute path for the certificate file on the remote node
keyPath	string	yes	Absolute path for the private key file on the remote node
chainPath?	string	no	Absolute path for the chain file on the remote node
owner?	string	no	Owner for all certificate files
group?	string	no	Group for all certificate files
certMode?	string	no	Permissions for the certificate file
keyMode?	string	no	Permissions for the private key file (default: restricted)
chainMode?	string	no	Permissions for the chain file
validate?	boolean	no	Validate that the certificate and key match using openssl
nodeHost	string	yes	Hostname or IP of the remote node
nodeUser?	string	no	SSH username
nodePort?	number	no	SSH port
nodeIdentityFile?	string	no	Path to SSH private key
become?	boolean	no	Enable sudo privilege escalation
becomeUser?	string	no	User to become via sudo
becomePassword?	string	no	Password for sudo -S

fn check()

Check if certificates are deployed and match desired state (dry-run)

fn apply()

Deploy certificate, key, and optional chain to the remote node

Resources

state(infinite)— Result of check or apply operation

03Reports3

@swamp/cfgmgmt-node-statemethod

node_state.ts

Node info after gathering facts

cfgmgmt

@swamp/cfgmgmt-statemethod

state.ts

Compliance state after check or apply

cfgmgmtcompliance

@swamp/cfgmgmt-workflow-summaryworkflow

workflow_summary.ts

Aggregated compliance summary for a workflow run

cfgmgmtcompliance

04Stats

100 / 100

Downloads

510

Archive size

211.8 KB

Verified by Swamp

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Docs keep secrets in a vault1/1earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License2/2earned
Verified public repository2/2earned

Repository

https://github.com/swamp-club/swamp-extensions

06Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64 windows · x86_64

07Labels

#cfgmgmt #ssh #linux #macos #fedora #debian #ubuntu #archlinux

Requirements

Moving from @adam/cfgmgmt

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

Global Arguments

Resources

05Accepted warnings8