server Operations¶

The server module takes care of os-level state. Targets POSIX compatibility, tested on Linux/BSD.

Facts used in these operations: server.AuthorizedKeys, files.Directory, server.EtcHosts, files.FileContents, files.FindInFile, server.Groups, server.Home, server.Hostname, server.Kernel, server.KernelModules, files.Link, server.Locales, server.Mounts, server.Os, server.Sysctl, server.Timezone, server.Uptime, server.Users, server.Which.

server.etc_hosts¶

Add, update or remove an entry in /etc/hosts (or another hosts-file path) keyed by IP address.

server.etc_hosts(
         ip: 'str',
         hostnames: 'str | list[str] | None' = None,
         present: 'bool' = True,
         path: 'str' = '/etc/hosts',
         **kwargs,
    )

• ip: the IP address the entry is keyed by
• hostnames: hostname (str) or list of hostnames to associate with ip
• present: whether the entry should be present (True) or absent (False)
• path: path to the hosts file (defaults to /etc/hosts)

Behavior: When present=True the line for ip is ensured to be exactly <ip> <hostnames...>, adding it if missing or replacing it if the stored hostnames differ. Other lines are left untouched.

When `present=False` and `hostnames` is omitted, every line for `ip`
is removed. When `hostnames` is given, only those names are dropped
from the IP's line; the line is removed entirely if no hostnames remain.

Comments on the edited line are not preserved.

Examples:

server.etc_hosts(
    name="Register db.internal in /etc/hosts",
    ip="192.168.1.10",
    hostnames=["db.internal", "db"],
)

server.etc_hosts(
    name="Drop the legacy hostname",
    ip="192.168.1.10",
    hostnames="db",
    present=False,
)

server.etc_hosts(
    name="Remove 10.0.0.1 entirely",
    ip="10.0.0.1",
    present=False,
)

server.group¶

Add/remove system groups.

server.group(group: 'str', present=True, system=False, gid: 'int | str | None' = None,
         **kwargs,
    )

• group: name of the group to ensure
• present: whether the group should be present or not
• system: whether to create a system group
• gid: use a specific groupid number

System users: System users don't exist on BSD, so the argument is ignored for BSD targets.

Examples:

server.group(
    name="Create docker group",
    group="docker",
)

# multiple groups
for group in ["wheel", "lusers"]:
    server.group(
        name=f"Create the group {group}",
        group=group,
    )

server.hostname¶

Set the system hostname using hostnamectl or hostname on older systems.

server.hostname(hostname: 'str', hostname_file: 'str | None' = None,
         **kwargs,
    )

• hostname: the hostname that should be set
• hostname_file: the file that permanently sets the hostname

Hostname file: The hostname file only matters no systems that do not have hostnamectl, which is part of systemd.

By default pyinfra will auto detect this by targeting `/etc/hostname`
on Linux and `/etc/myname` on OpenBSD.

To completely disable writing the hostname file, set `hostname_file=False`.

Example:

server.hostname(
    name="Set the hostname",
    hostname="server1.example.com",
)

server.kill¶

Kill a running process.

server.kill(pid: 'int', signal: 'str' = 'TERM',
         **kwargs,
    )

• pid: PID of the process to kill
• signal: signal to send (default TERM)

Example:

server.kill(
    name="Kill process 1234",
    pid=1234,
    signal="KILL",
)

server.locale¶

Enable/Disable locale.

server.locale(locale: 'str', present=True,
         **kwargs,
    )

• locale: name of the locale to enable/disable
• present: whether this locale should be present or not

Examples:

server.locale(
    name="Ensure en_GB.UTF-8 locale is not present",
    locale="en_GB.UTF-8",
    present=False,
)

server.locale(
    name="Ensure en_GB.UTF-8 locale is present",
    locale="en_GB.UTF-8",
)

server.modprobe¶

Load/unload kernel modules.

server.modprobe(module: 'str', present=True, force=False,
         **kwargs,
    )

• module: name of the module to manage
• present: whether the module should be loaded or not
• force: whether to force any add/remove modules

Example:

server.modprobe(
    name="Silly example for modprobe",
    module="floppy",
)

server.mount¶

Manage mounted filesystems.

server.mount(
         path: 'str',
         mounted=True,
         options: 'list[str] | None' = None,
         device: 'str | None' = None,
         fs_type: 'str | None' = None,
         **kwargs,
    )

• path: the path of the mounted filesystem
• mounted: whether the filesystem should be mounted
• options: the mount options

Options: If the currently mounted filesystem does not have all of the provided options it will be remounted with the options provided.

/etc/fstab: This operation does not attempt to modify the on disk fstab file - for that you should use the files.line operation <./files.html#files-line>_.

server.packages¶

Add or remove system packages. This command checks for the presence of all the system package managers pyinfra can handle and executes the relevant operation.

server.packages(packages: 'str | list[str]', present=True,
         **kwargs,
    )

• packages: list of packages to ensure
• present: whether the packages should be installed

Example:

server.packages(
    name="Install Vim and vimpager",
    packages=["vimpager", "vim"],
)

server.reboot¶

Reboot the server and wait for reconnection.

server.reboot(delay=10, interval=1, reboot_timeout=300,
         **kwargs,
    )

• delay: number of seconds to wait before attempting reconnect
• interval: interval (s) between reconnect attempts
• reboot_timeout: total time before giving up reconnecting

Example:

from pyinfra.operations import server
server.reboot(
    name="Reboot the server and wait to reconnect",
    delay=60,
    reboot_timeout=600,
)

server.script¶

Upload and execute a local script on the remote host.

server.script(src: 'str', args=(),
         **kwargs,
    )

• src: local script filename to upload & execute
• args: iterable to pass as arguments to the script

Example:

# Note: This assumes there is a file in files/hello.bash locally.
server.script(
    name="Hello",
    src="files/hello.bash",
)

# Example passing arguments to the script
server.script(
    name="Hello",
    src="files/hello.bash",
    args=("do-something", "with-this"),
)

server.script_template¶

Generate, upload and execute a local script template on the remote host.

server.script_template(src: 'str', args=(), **data,
         **kwargs,
    )

• src: local script template filename

Example:

# Example showing how to pass python variable to a script template file.
# The .j2 file can use `{{ some_var }}` to be interpolated.
# To see output need to run pyinfra with '-v'
# Note: This assumes there is a file in templates/hello2.bash.j2 locally.
some_var = 'blah blah blah '
server.script_template(
    name="Hello from script",
    src="templates/hello2.bash.j2",
    some_var=some_var,
)

server.security_limit¶

Edit /etc/security/limits.conf configuration.

server.security_limit(domain: 'str', limit_type: 'str', item: 'str', value: 'int',
         **kwargs,
    )

• domain: the domain (user, group, or wildcard) for the limit
• limit_type: the type of limit (hard or soft)
• item: the item to limit (e.g., nofile, nproc)
• value: the value for the limit

Example:

security_limit(
    name="Set nofile limit for all users",
    domain='*',
    limit_type='soft',
    item='nofile',
    value=1024,
)

server.service¶

Manage the state of services. This command checks for the presence of all the Linux init systems pyinfra can handle and executes the relevant operation.

server.service(
         service: 'str',
         running=True,
         restarted=False,
         reloaded=False,
         command: 'str | None' = None,
         enabled: 'bool | None' = None,
         **kwargs,
    )

• service: name of the service to manage
• running: whether the service should be running
• restarted: whether the service should be restarted
• reloaded: whether the service should be reloaded
• command: custom command execute
• enabled: whether this service should be enabled/disabled on boot

Example:

server.service(
    name="Enable open-vm-tools service",
    service="open-vm-tools",
    enabled=True,
)

server.shell¶

Run raw shell code on server during a deploy. If the command would modify data that would be in a fact, the fact would not be updated since facts are only run at the start of a deploy.

server.shell(commands: 'str | list[str]',
         **kwargs,
    )

• commands: command or list of commands to execute on the remote server

Example:

server.shell(
    name="Run lxd auto init",
    commands=["lxd init --auto"],
)

server.sysctl¶

Edit sysctl configuration.

server.sysctl(
         key: 'str',
         value: 'str | int | list[str | int]',
         persist=False,
         persist_file='/etc/sysctl.conf',
         **kwargs,
    )

• key: name of the sysctl setting to ensure
• value: the value or list of values the sysctl should be
• persist: whether to write this sysctl to the config
• persist_file: file to write the sysctl to persist on reboot

Example:

server.sysctl(
    name="Change the fs.file-max value",
    key="fs.file-max",
    value=100000,
    persist=True,
)

server.timezone¶

Set the system timezone.

server.timezone(timezone: 'str',
         **kwargs,
    )

Uses timedatectl when available (systemd systems), otherwise falls back to symlinking /etc/localtime directly.

• timezone: the timezone to set (e.g. Europe/Amsterdam, UTC)

Example:

server.timezone(
    name="Set the timezone to Europe/Amsterdam",
    timezone="Europe/Amsterdam",
)

server.user¶

Add/remove/update system users & their ssh authorized_keys.

server.user(
         user: 'str',
         present=True,
         home: 'str | None' = None,
         shell: 'str | None' = None,
         group: 'str | None' = None,
         groups: 'list[str] | None' = None,
         append=False,
         public_keys: 'str | list[str] | None' = None,
         delete_keys=False,
         ensure_home=True,
         create_home=False,
         system=False,
         uid: 'int | None' = None,
         comment: 'str | None' = None,
         unique=True,
         password: 'str | None' = None,
         **kwargs,
    )

• user: name of the user to ensure
• present: whether this user should exist
• home: the user's home directory
• shell: the user's shell
• group: the user's primary group
• groups: the user's secondary groups
• append: whether to add user to groups, w/o losing membership of other groups
• public_keys: list of public keys to attach to this user, home must be specified
• delete_keys: whether to remove any keys not specified in public_keys
• ensure_home: whether to ensure the home directory exists
• create_home: whether user create new user home directories from the system skeleton
• system: whether to create a system account
• uid: use a specific userid number
• comment: the user GECOS comment
• unique: prevent creating users with duplicate UID
• password: set the encrypted password for the user

Home directory: When ensure_home or public_keys are provided, home defaults to /home/{name}. When create_home is True any newly created users will be created with the -m flag to build a new home directory from the system's skeleton directory.

Public keys: These can be provided as strings containing the public key or as a path to a public key file which pyinfra will read.

Examples:

server.user(
    name="Ensure user is removed",
    user="kevin",
    present=False,
)

server.user(
    name="Ensure myweb user exists",
    user="myweb",
    shell="/bin/bash",
)

# multiple users
for user in ["kevin", "bob"]:
    server.user(
        name=f"Ensure user {user} is removed",
        user=user,
        present=False,
    )

server.user_authorized_keys¶

Manage authorized_keys of system users.

server.user_authorized_keys(
         user: 'str',
         public_keys: 'str | list[str]',
         group: 'str | None' = None,
         delete_keys=False,
         authorized_key_directory: 'str | None' = None,
         authorized_key_filename: 'str | None' = None,
         **kwargs,
    )

• user: name of the user to ensure
• public_keys: list of public keys to attach to this user, home must be specified
• group: the user's primary group
• delete_keys: whether to remove any keys not specified in public_keys

Public keys: These can be provided as strings containing the public key or as a path to a public key file which pyinfra will read.

Examples:

server.user_authorized_keys(
    name="Ensure user has a public key",
    user="kevin",
    public_keys=["ed25519..."],
)

server.wait¶

Waits for a port to come active on the target machine. Requires netstat, checks every second.

server.wait(port: 'int',
         **kwargs,
    )

• port: port number to wait for

Example:

server.wait(
    name="Wait for webserver to start",
    port=80,
)