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 |
|
process |
Name of the process owning one of those sockets, or |
|
pid |
PID behind |
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 |
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'
|
**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
( |
False
|
gid
|
int | str | None
|
Use a specific group id number; a
falsy gid ( |
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
¶
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 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'
|
**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.
|
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
|
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 |
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
( |
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
|
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 ( |
required |
limit_type
|
str
|
|
required |
item
|
str
|
The resource being limited (e.g. |
required |
value
|
int | str
|
The limit's value; a number or a symbolic string
such as |
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
¶
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. |
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 |
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: |
None
|
append
|
bool
|
Whether to add the user to |
False
|
ensure_home
|
bool
|
Whether to ensure the |
True
|
create_home
|
bool
|
Whether a new user's home directory
is built from the system skeleton ( |
False
|
system
|
bool
|
Whether to create a system account
( |
False
|
uid
|
int | None
|
Use a specific user id number; a
falsy uid ( |
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 ( |
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
|
required |
group
|
str | None
|
The group to own the |
None
|
delete_keys
|
bool
|
Whether to remove any keys not
specified in |
False
|
authorized_key_directory
|
str | None
|
The directory to
write into; defaults to the user's |
None
|
authorized_key_filename
|
str | None
|
The file name to
write inside |
None
|
**kwargs
|
Any
|
Additional keyword arguments. |
{}
|
Yields:
| Name | Type | Description |
|---|---|---|
Command |
AsyncGenerator[Command]
|
Generated |
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
|
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 ( |
required |
timeout
|
float
|
Seconds to keep polling before raising
|
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.