Server Operations¶

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

`server.crontab`¶

Add/remove/update crontab entries.

server.crontab(
    command, present=True, user=None, cron_name=None, minute='*', hour='*', month='*',
    day_of_week='*', day_of_month='*', special_time=None, interpolate_variables=False,
)

command: the command for the cron
present: whether this cron command should exist
user: the user whose crontab to manage
cron_name: name the cronjob so future changes to the command will overwrite
minute: which minutes to execute the cron
hour: which hours to execute the cron
month: which months to execute the cron
day_of_week: which day of the week to execute the cron
day_of_month: which day of the month to execute the cron
special_time: cron “nickname” time (@reboot, @daily, etc), overrides others
interpolate_variables: whether to interpolate variables in command

Cron commands:: Unless name is specified the command is used to identify crontab entries. This means commands must be unique within a given users crontab. If you require multiple identical commands, provide a different name argument for each.
Special times:: When provided, special_time will be used instead of any values passed in for minute/hour/month/day_of_week/day_of_month.

Example:

# simple example for a crontab
server.crontab(
    name='Backup /etc weekly',
    command='/bin/tar cf /tmp/etc_bup.tar /etc',
    name='backup_etc',
    day_of_week=0,
    hour=1,
    minute=0,
)

`server.group`¶

Add/remove system groups.

server.group(group, present=True, system=False, gid=None)

group: name of the group to ensure
present: whether the group should be present or not
system: whether to create a system group

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, hostname_file=None)

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 targetting /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.modprobe`¶

Load/unload kernel modules.

server.modprobe(module, present=True, force=False)

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, mounted=True, options=None)

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.

`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, present=True)

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)

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

Example:

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)

src: local script filename to upload & execute

Example:

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

`server.script_template`¶

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

server.script_template(src)

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.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, running=True, restarted=False, reloaded=False, command=None, enabled=None)

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)

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, value, persist=False, persist_file='/etc/sysctl.conf')

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.user`¶

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

server.user(
    user, present=True, home=None, shell=None, group=None, groups=None, public_keys=None,
    delete_keys=False, ensure_home=True, system=False, uid=None, comment=None,
    add_deploy_dir=True, unique=True,
)

user: name of the user to ensure
present: whether this user should exist
home: the users home directory
shell: the users shell
group: the users primary group
groups: the users secondary 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
system: whether to create a system account
comment: the user GECOS comment
add_deploy_dir: any public_key filenames are relative to the deploy directory
unique: prevent creating users with duplicate UID

Home directory:: When ensure_home or public_keys are provided, home defaults to /home/{name}.
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.wait`¶

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

server.wait(port=None)

port: port number to wait for

Example:

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

Server Operations¶

server.crontab¶

server.group¶

server.hostname¶

server.modprobe¶

server.mount¶

server.packages¶

server.reboot¶

server.script¶

server.script_template¶

server.service¶

server.shell¶

server.sysctl¶

server.user¶

server.wait¶

`server.crontab`¶

`server.group`¶

`server.hostname`¶

`server.modprobe`¶

`server.mount`¶

`server.packages`¶

`server.reboot`¶

`server.script`¶

`server.script_template`¶

`server.service`¶

`server.shell`¶

`server.sysctl`¶

`server.user`¶

`server.wait`¶