Skip to content

server module

Arch

The system architecture according to uname (e.g. x86_64).

Commands:

uname -m

Returns:

str

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_arch.py.

AuthorizedKeys

The SSH public keys listed in a user's ~/.ssh/authorized_keys file.

Commands:

cat ~<user>/.ssh/authorized_keys 2>/dev/null || true

Returns:

list[str]

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/server/server_authorized_keys.py.

AuthorizedKeysFile

The current content of one remote file, or None when absent.

The namespace's path-generic raw-content fact: read by server.user_authorized_keys for the key file, by server.etc_hosts for the hosts file it rewrites, by server.locale for /etc/locale.gen and by server.security_limit for /etc/security/limits.conf.

Commands:

test -e <path> && { printf '#reemote-authorizedkeysfile\n'; cat -- <path>; }

Returns:

str | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_user_authorized_keys.py.

Date

The current datetime on the server, as a timezone-aware datetime.

Commands:

date +'%Y-%m-%dT%H:%M:%S%z'

Returns:

datetime | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_date.py.

Env

The value of a given environment variable on the server (e.g. PATH).

Commands:

echo $<name>

Returns:

str

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/server/server_env.py.

EtcHosts

/etc/hosts parsed as a mapping of IP address to hostnames.

Commands:

cat <path> 2>/dev/null || true

Returns:

dict[str, list[str]]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_etc_hosts.py.

Groups

The list of group names on the system, from /etc/group.

Commands:

cat /etc/group

Returns:

list[str]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_groups.py.

HasGui

Whether the host has GUI capabilities (Linux only).

Commands:

ls /usr/bin/*session || true

Returns:

bool

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_has_gui.py.

Home

A user's home directory (e.g. /home/reemote), or None.

Commands:

echo ~<user>

Returns:

str | None

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/server/server_home.py.

Hostname

The server's hostname according to uname (e.g. my-host.net).

Commands:

uname -n

Returns:

str

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_hostname.py.

Kernel

The kernel name according to uname (e.g. Linux).

Commands:

uname -s

Returns:

str

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_kernel.py.

KernelModules

The loaded kernel modules, as a dict of module name -> info dict.

Commands:

! test -f /proc/modules || cat /proc/modules

Returns:

dict[str, dict[str, Any]]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_kernel_modules.py.

KernelVersion

The kernel version according to uname (e.g. 6.1.0-26-amd64).

Commands:

uname -r

Returns:

str

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_kernel_version.py.

Last

The login records parsed from last, as a list of dicts.

Commands:

last -Fwi 2>/dev/null || last -w 2>/dev/null || last 2>/dev/null || true

Returns:

list[dict[str, str]]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_last.py.

LinuxDistribution

The Linux distribution's name and version, as a dict.

Commands:

cd /etc/ && for file in $(ls -pdL *-release | grep -v /); do echo "/etc/${file}"; cat "/etc/${file}"; echo ---; done

Returns:

dict[str, Any]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_linux_distribution.py.

LinuxGui

The installed Linux GUIs, as a list of names (e.g. ["GNOME"]).

Commands:

ls /usr/bin/*session || true

Returns:

list[str]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_linux_gui.py.

LinuxName

The Linux distribution's pretty name (e.g. Ubuntu), or None.

Commands:

cd /etc/ && for file in $(ls -pdL *-release | grep -v /); do echo "/etc/${file}"; cat "/etc/${file}"; echo ---; done

Returns:

str | None

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_linux_name.py.

Locales

The installed locales on the system, from locale -a.

Commands:

locale -a

Returns:

list[str]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_locales.py.

LsbRelease

The release information reported by lsb_release, as a dict.

Commands:

lsb_release -ca

Returns:

dict[str, str]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_lsb_release.py.

Mounts

The mounted filesystems, as a dict of mount point -> info dict.

Commands:

cat /proc/self/mountinfo

Returns:

dict[str, dict[str, Any]]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_mounts.py.

Port

Whether a port has a listening socket, and what owns it.

Commands:

ss -lptn | grep ':<port> ' || true

Returns:

PortInfo

Raises:

CommandNotFoundError, HostConnectionError, TypeError, ValueError

Examples:

Examples can be found in examples/modules/server/server_port.py.

PortInfo

Attributes:

Name Type Description
listening

Whether the port has at least one listening socket; the answer server.wait polls.

process

Name of the process owning one of those sockets, or None when the tool reports no owner -- an unprivileged read, or a socket with no process information.

pid

PID behind process, or None under the same conditions.

Processes

The running processes, as a dict of PID -> info dict.

Commands:

LANG=C ps -eo pid,user,stat,%cpu,%mem,comm,args --no-headers

Returns:

dict[int, dict[str, Any]]

Raises:

CommandNotFoundError, HostConnectionError, TypeError

Examples:

Examples can be found in examples/modules/server/server_processes.py.

Timezone

The current system timezone (e.g. Europe/Amsterdam).

Commands:

readlink -f /etc/localtime | sed 's|.*/zoneinfo/||'

Returns:

str

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_timezone.py.

Uptime

The number of seconds the system has been up, or None.

Commands:

cut -d. -f1 /proc/uptime

Returns:

int | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_uptime.py.

User

The name of the current user (e.g. root).

Commands:

echo $USER

Returns:

str

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_user.py.

Users

The system users, as a dict of username -> details dict.

Commands:

for i in `cat /etc/passwd | cut -d: -f1`; do
    ENTRY=`grep ^$i: /etc/passwd`;
    LASTLOG=`(((lastlog -u $i || lastlogin $i) 2> /dev/null) | grep ^$i | tr -s ' ')`;
    PASSWORD=`(grep ^$i: /etc/shadow || grep ^$i: /etc/master.passwd) 2> /dev/null | cut -d: -f2`;
    echo "$ENTRY|`id -gn $i`|`id -Gn $i`|$LASTLOG|$PASSWORD";
done

Returns:

dict[str, dict[str, Any]]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_users.py.

Which

The path of a given command according to command -v, or None.

Commands:

command -v <command> || true

Returns:

str | None

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_which.py.

etc_hosts async

etc_hosts(
    ctx: OpContext,
    ip: str,
    hostnames: str
    | list[str]
    | tuple[str, ...]
    | None = None,
    present: bool = True,
    path: str = "/etc/hosts",
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add, update or remove an entry in /etc/hosts keyed by IP address.

Parameters:

Name Type Description Default
ctx OpContext

Execution context for the operation.

required
ip str

The IP address the entry is keyed by.

required
hostnames str | list[str] | tuple[str, ...] | None

The hostname(s) to associate with ip; a single string (split on whitespace) or a list/tuple of names. Prefer tuples when building requests via op(), since OperationRequest kwargs must stay hashable. Required when present=True; with present=False only the named hostnames are dropped, and omitting it removes every line for ip. Defaults to None.

None
present bool

Whether the entry should be present or absent. Defaults to True.

True
path str

Path to the hosts file. Defaults to /etc/hosts.

'/etc/hosts'
**kwargs Any

Additional keyword arguments.

{}

Yields:

Name Type Description
Command AsyncGenerator[Command]

The spool-and-install pair carrying the new hosts-file content, when the entry differs from the request.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/server/server_etc_hosts.py.

group async

group(
    ctx: OpContext,
    group: str,
    present: bool = True,
    system: bool = False,
    gid: int | str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add/remove a system group.

Parameters:

Name Type Description Default
ctx OpContext

Execution context for the operation.

required
group str

Name of the group to ensure.

required
present bool

Whether the group should be present or not. Defaults to True.

True
system bool

Whether to create a system group (groupadd -r); ignored on BSD kernels, which have no system groups. Defaults to False.

False
gid int | str | None

Use a specific group id number; a falsy gid (None or 0) is skipped, exactly like the baseline's if gid: check. Defaults to None.

None
**kwargs Any

Additional keyword arguments.

{}

Yields:

Name Type Description
Command AsyncGenerator[Command]

Generated group add/remove commands.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_group.py.

hostname async

hostname(
    ctx: OpContext, hostname: str, **kwargs: Any
) -> AsyncGenerator[Command]

Set the system hostname.

Parameters:

Name Type Description Default
ctx OpContext

Execution context for the operation.

required
hostname str

The hostname that should be set.

required
**kwargs Any

Additional keyword arguments.

{}

Yields:

Name Type Description
Command AsyncGenerator[Command]

The hostname-setting command, when the name differs.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_op_hostname.py.

kill async

kill(
    ctx: OpContext,
    pid: int,
    signal: str = "TERM",
    **kwargs: Any,
) -> AsyncGenerator[Command]

Kill a running process.

Parameters:

Name Type Description Default
ctx OpContext

Execution context for the operation.

required
pid int

PID of the process to kill.

required
signal str

Signal to send. Defaults to TERM.

'TERM'
**kwargs Any

Additional keyword arguments.

{}

Yields:

Name Type Description
Command AsyncGenerator[Command]

The kill command, always (the operation is stateless).

Raises:

None

Examples:

Examples can be found in examples/modules/server/server_kill.py.

locale async

locale(
    ctx: OpContext,
    locale: str,
    present: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Enable or disable a locale in /etc/locale.gen (Debian-family).

Parameters:

Name Type Description Default
ctx OpContext

Execution context for the operation.

required
locale str

Name of the locale to enable/disable (e.g. fr_FR.UTF-8), as spelled in /etc/locale.gen.

required
present bool

Whether the locale should be enabled. Defaults to True.

True
**kwargs Any

Additional keyword arguments.

{}

Yields:

Name Type Description
Command AsyncGenerator[Command]

The spool-and-install pair carrying the new locale.gen content (when the definition line changes), followed by one locale-gen regeneration.

Raises:

CommandNotFoundError, HostConnectionError, OperationError

Examples:

Examples can be found in examples/modules/server/server_op_locale.py.

modprobe async

modprobe(
    ctx: OpContext,
    module: str | list[str] | tuple[str, ...],
    present: bool = True,
    force: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Load/unload kernel modules.

Parameters:

Name Type Description Default
ctx OpContext

Execution context for the operation.

required
module str | list[str] | tuple[str, ...]

Name of the module to manage; a single string or a list/tuple of names. Prefer tuples when building requests via op(), since OperationRequest kwargs must stay hashable.

required
present bool

Whether the module(s) should be loaded or not. Defaults to True.

True
force bool

Whether to force any add/remove modules (modprobe -f). Defaults to False.

False
**kwargs Any

Additional keyword arguments.

{}

Yields:

Name Type Description
Command AsyncGenerator[Command]

The modprobe command, when modules differ from the request.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_modprobe.py.

mount async

mount(
    ctx: OpContext,
    path: str,
    mounted: bool = True,
    options: list[str] | tuple[str, ...] | None = None,
    device: str | None = None,
    fs_type: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Manage mounted filesystems.

Parameters:

Name Type Description Default
ctx OpContext

Execution context for the operation.

required
path str

The path of the mounted filesystem.

required
mounted bool

Whether the filesystem should be mounted. Defaults to True.

True
options list[str] | tuple[str, ...] | None

The mount options; a list/tuple of option strings (prefer tuples in op() requests, which must stay hashable). Defaults to None.

None
device str | None

The device behind the mount. Defaults to None.

None
fs_type str | None

The filesystem type. Defaults to None.

None
**kwargs Any

Additional keyword arguments.

{}

Yields:

Name Type Description
Command AsyncGenerator[Command]

The mount/unmount/remount command, when state or options differ from the request.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_mount.py.

security_limit async

security_limit(
    ctx: OpContext,
    domain: str,
    limit_type: str,
    item: str,
    value: int | str,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Ensure a resource limit line in /etc/security/limits.conf.

Parameters:

Name Type Description Default
ctx OpContext

Execution context for the operation.

required
domain str

The user, group (@group) or wildcard * the limit applies to.

required
limit_type str

soft or hard.

required
item str

The resource being limited (e.g. nofile, memlock).

required
value int | str

The limit's value; a number or a symbolic string such as unlimited (the baseline types it int but its own fixture passes "unlimited").

required
**kwargs Any

Additional keyword arguments.

{}

Yields:

Name Type Description
Command AsyncGenerator[Command]

The spool-and-install pair carrying the new limits.conf content, or nothing when the file already reads as desired.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/server_security_limit.py.

timezone async

timezone(
    ctx: OpContext, timezone: str, **kwargs: Any
) -> AsyncGenerator[Command]

Set the system timezone.

Parameters:

Name Type Description Default
ctx OpContext

Execution context for the operation.

required
timezone str

The timezone to set (e.g. Europe/Amsterdam, UTC).

required
**kwargs Any

Additional keyword arguments.

{}

Yields:

Name Type Description
Command AsyncGenerator[Command]

The timezone-setting command, when the zone differs.

Raises:

CommandNotFoundError, HostConnectionError, OperationError

Examples:

Examples can be found in examples/modules/server/server_op_timezone.py.

user async

user(
    ctx: OpContext,
    user: str,
    present: bool = True,
    home: str | None = None,
    shell: str | None = None,
    group: str | None = None,
    groups: tuple[str, ...] | None = None,
    append: bool = False,
    ensure_home: bool = True,
    create_home: bool = False,
    system: bool = False,
    uid: int | None = None,
    comment: str | None = None,
    unique: bool = True,
    password: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add, update, or remove a system user.

Parameters:

Name Type Description Default
ctx OpContext

Execution context for the operation.

required
user str

Name of the user to ensure.

required
present bool

Whether the user should exist. Defaults to True.

True
home str | None

The user's home directory; defaults to /home/<user> for a new user, or the recorded home for a present one. Defaults to None.

None
shell str | None

The user's login shell. Defaults to None.

None
group str | None

The user's primary group. Defaults to None.

None
groups tuple[str, ...] | None

The user's secondary groups. A tuple, never a list: OperationRequest hashes every argument for compose(dedupe=True), so a list would be rejected with UnhashableArgumentError. Defaults to None.

None
append bool

Whether to add the user to groups without losing membership of other groups. Defaults to False.

False
ensure_home bool

Whether to ensure the home directory exists and belongs to the user. Defaults to True.

True
create_home bool

Whether a new user's home directory is built from the system skeleton (useradd -m). Defaults to False.

False
system bool

Whether to create a system account (useradd -r); ignored on BSD kernels. Defaults to False.

False
uid int | None

Use a specific user id number; a falsy uid (None or 0) is skipped, exactly like the baseline's if uid: check. Defaults to None.

None
comment str | None

The user's GECOS comment. Defaults to None.

None
unique bool

Whether to prevent creating a user with a duplicate UID (False renders -o). Defaults to True.

True
password str | None

The encrypted password hash to set. Defaults to None.

None
**kwargs Any

Additional keyword arguments.

{}

Yields:

Name Type Description
Command AsyncGenerator[Command]

Generated user add/update/remove and home-directory commands.

Raises:

CommandNotFoundError, HostConnectionError, OperationError

Examples:

Examples can be found in examples/modules/server/server_op_user.py.

user_authorized_keys async

user_authorized_keys(
    ctx: OpContext,
    user: str,
    public_keys: str | list[str] | tuple[str, ...],
    group: str | None = None,
    delete_keys: bool = False,
    authorized_key_directory: str | None = None,
    authorized_key_filename: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add SSH public keys to a user's authorized_keys file.

Parameters:

Name Type Description Default
ctx OpContext

Execution context for the operation.

required
user str

Name of the user whose keys to manage.

required
public_keys str | list[str] | tuple[str, ...]

Public key strings to attach to the user. Prefer tuples when building requests via op(), since OperationRequest kwargs must stay hashable. Every entry is always a literal key, never a path to a key file.

required
group str | None

The group to own the .ssh directory and key file; defaults to the user's own name. Defaults to None.

None
delete_keys bool

Whether to remove any keys not specified in public_keys: the file is rewritten to exactly the requested keys (comments and blank lines included in the discard), instead of only appending the missing ones. Defaults to False.

False
authorized_key_directory str | None

The directory to write into; defaults to the user's Home fact resolved to <home>/.ssh. Defaults to None.

None
authorized_key_filename str | None

The file name to write inside authorized_key_directory; defaults to authorized_keys. Defaults to None.

None
**kwargs Any

Additional keyword arguments.

{}

Yields:

Name Type Description
Command AsyncGenerator[Command]

Generated .ssh directory/key-file setup commands and the spool-and-install pair carrying the new key-file content.

Raises:

CommandNotFoundError, HostConnectionError, OperationError, ValueError

Examples:

Examples can be found in examples/modules/server/server_user_authorized_keys.py.

wait async

wait(
    ctx: OpContext,
    port: int,
    protocol: Literal["tcp", "udp"] = "tcp",
    timeout: float = 300.0,
    interval: float = 1.0,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Wait for a port to start listening.

Parameters:

Name Type Description Default
ctx OpContext

Execution context for the operation.

required
port int

Number of the port to wait for.

required
protocol Literal['tcp', 'udp']

Protocol family whose sockets count as listening. Defaults to "tcp".

'tcp'
timeout float

Seconds to keep polling before raising WaitTimeoutError. Defaults to 300.0.

300.0
interval float

Seconds between polls. Defaults to 1.0.

1.0
**kwargs Any

Additional keyword arguments.

{}

Yields:

Name Type Description
Command AsyncGenerator[Command]

The wait command, always (a wait is not idempotent).

Raises:

CommandNotFoundError, HostConnectionError, TypeError, ValueError, WaitTimeoutError

Examples:

Examples can be found in examples/modules/server/server_op_wait.py.

wait_service async

wait_service(
    ctx: OpContext,
    service: str,
    timeout: float = 300.0,
    interval: float = 5.0,
) -> AsyncGenerator[Command]

Wait for a systemd unit to become active.

Parameters:

Name Type Description Default
ctx OpContext

Execution context for the operation.

required
service str

Name of the unit (httpd or httpd.service).

required
timeout float

Seconds to keep polling before raising WaitTimeoutError. Defaults to 300.0.

300.0
interval float

Seconds between polls. Defaults to 5.0.

5.0

Yields:

Name Type Description
Command AsyncGenerator[Command]

The wait command, always (a wait is not idempotent).

Raises:

CommandNotFoundError, HostConnectionError, WaitTimeoutError

Examples:

Examples can be found in examples/modules/server/wait_for_httpd.py.