Libraries

Reference documentation for Etcha’s Jsonnet libraries.

Native Functions

Native Functions are custom Jsonnet functions provided by the Etcha binary. Etcha provides these as an importable helper file via init under lib/etcha/native.libsonnet.

Commands

Etcha contains numerous importable Command functions that will template out Commands. We are constantly adding more of these and encourage the community to contribute others. All Commands shipped in Etcha are linted and tested.

See Writing Patterns for more information about initializing these files.

Think we’re missing something? Request a library on GitHub.

apt

local apt = import 'lib/etcha/apt.libsonnet'

{
  run: {
    // Install package using apt, optionally ignoring recommends.
    apt(name, options='', recommends=false, skipRemove=false),
  },
}

aptKey

local aptKey = import 'lib/etcha/aptKey.libsonnet'

{
  run: {
    // Create an apt PGP key with name from src under path.
    aptKey(name, path='/etc/apt/trusted.gpg.d', skipRemove=false, src),
  },
}

container

local container = import 'lib/etcha/container.libsonnet'

{
  run: {
    // Manages a container using Docker or Podman.  Will automatically detect the engine from sysinfo, or one can be provided.
    container(args='', cap_add=[], command='', deviceChown=false, devices=[], engine='', env=[], image, name, network='', options='', onChange=[], ports=[], privileged=false, pull='', restart='on-failure', skipRemove=false, user='', volumes=[], workdir=''),
  },
}

copy

local copy = import 'lib/etcha/copy.libsonnet'

{
  run: {
    // Copy a file from src to dst.  Will use wget to download the file.  Can optionally provide a custom check function.
    copy(check='', dst, skipRemove=false, src),
  },
}

dir

local dir = import 'lib/etcha/dir.libsonnet'

{
  run: {
    // Manage a directory at path with a specific mode.
    dir(absent=false, force=true, group='""', mode='0755', owner='""', path, skipRemove=false),
  },
}

dnf

local dnf = import 'lib/etcha/dnf.libsonnet'

{
  run: {
    // Install a package using dnf, optionally ignoring weak dependencies.
    dnf(name, options='', skipRemove=false, weakdepends=false),
  },
}

etcha

local etcha = import 'lib/etcha/etcha.libsonnet'

{
  run: {
    // Install the latest version of Etcha to dst.  Will cache the file to cacheDir for subsequent runs, if specified
    etcha.install(arch='amd64', cacheDir='', dst, onChange=[], skipRemove=false, src='https://etcha.dev/releases'),
    // Create a systemd service for Etcha.
    etcha.service(config='/etc/etcha.jsonnet', dir='/etc/systemd/system', enable=true, name='etcha.service', reload=true, restart=true, skipRemove=false, start=true),
  },
}

file

local file = import 'lib/etcha/file.libsonnet'

{
  run: {
    // Manage a file at path.  Can set the contents, optionally expand variables, the owner and group, ignore content changes, and set the mode.
    file(absent=false, contents='', expand=false, group='""', ignoreContents=false, mode='0644', owner='""', path, skipRemove=false),
  },
}

group

local group = import 'lib/etcha/group.libsonnet'

{
  run: {
    // Manage a local group.  Must specify id and name.  Can optionally specify members, paths to group and gshadow, and enable removal.
    group(id, members='', name, pathGroup='/etc/group', pathGshadow='/etc/gshadow', skipRemove=false),
  },
}

line

local line = import 'lib/etcha/line.libsonnet'

{
  run: {
    // Manage a line at path.  Can set the match regexp, the path to the file, the replacement strings for change, optionally for check (will use change if not specified) and remove (will not remove line if not specified).  Will append the line to the end of the file during a change if nothing matches.
    line(match, path, replaceChange, replaceCheck=null, replaceRemove=null),
  },
}

mount

local mount = import 'lib/etcha/mount.libsonnet'

{
  run: {
    // Mount src to dst using args.
    mount(dst, options='', skipRemove=false, src, type),
  },
}

native

local native = import 'lib/etcha/native.libsonnet'

{
  run: {
  },
}

package

local package = import 'lib/etcha/package.libsonnet'

{
  run: {
    // Install package using the sysinfo.packageManager, optionally ignoring related packages.
    package(name, options='', related=false, skipRemove=false),
  },
}

rot

local rot = import 'lib/etcha/rot.libsonnet'

{
  run: {
    // Install the latest version of Rot to dst.  Will cache the file to cacheDir for subsequent runs, if specified
    rot.install(arch='amd64', cacheDir='', dst, onChange=[], skipRemove=false, src='https://rotx.dev/releases'),
  },
}

symlink

local symlink = import 'lib/etcha/symlink.libsonnet'

{
  run: {
    // Manage a symlink at dst pointing to src.
    symlink(dst, skipRemove=false, src),
  },
}

systemdNetwork

local systemdNetwork = import 'lib/etcha/systemdNetwork.libsonnet'

{
  run: {
    // Manage systemd network files and services.  Requires a map of files, where the key is the file name (like 00-enp1s0.network) and the contents of the file as the value.  Can optionally provide a separate path for the files, and whether to enable or restart systemd-networkd on changes.
    systemdNetwork(enable=true, expand=false, files, path='/etc/systemd/network', restart=true, skipRemove=false, start=true),
  },
}

systemdUnit

local systemdUnit = import 'lib/etcha/systemdUnit.libsonnet'

{
  run: {
    // Manage a systemd unit with name and optionally enable/restart it.
    systemdUnit(contents='', dir='/etc/systemd/system', enable=true, name, reload=true, restart=true, skipRemove=false, start=true),
  },
}

user

local user = import 'lib/etcha/user.libsonnet'

{
  run: {
    // Manage a local user.  Must specify gid, id and name.  Can optionally specify comment, password hash, paths to passwd/shadow, whether to remove the user, and a shell.
    user(comment='', gid, hash='*', home='/bin', id, name, pathPasswd='/etc/passwd', pathShadow='/etc/shadow', shell='/usr/sbin/nologin', skipRemove=false),
  },
}