pyinfra 0.11.dev3__py3-none-any.whl → 3.5.1__py3-none-any.whl

pyinfra/operations/snap.py

@@ -0,0 +1,117 @@
+"""
+Manage snap packages. See https://snapcraft.io/
+"""
+
+from __future__ import annotations
+
+from pyinfra import host
+from pyinfra.api import operation
+from pyinfra.facts.snap import SnapPackage, SnapPackages
+
+
+@operation()
+def package(
+    packages: str | list[str] | None = None,
+    channel="latest/stable",
+    classic=False,
+    present=True,
+):
+    """
+    Install/remove a snap package
+
+    + packages: List of packages
+    + channel: tracking channel
+    + classic: Use classic confinement
+    + present: whether the package should be installed
+
+    ``classic``:
+        Allows access to your system’s resources in much the same way traditional
+        packages do. This option corresponds to the ``--classic`` argument.
+
+    **Examples:**
+
+    .. code:: python
+
+        # Install vlc snap
+        snap.package(
+            name="Install vlc",
+            packages="vlc",
+        )
+
+        # Install multiple snaps
+        snap.package(
+            name="Install vlc and hello-world",
+            packages=["vlc", "hello-world"],
+        )
+
+        # Remove vlc
+        snap.package(
+            name="Remove vlc",
+            packages="vlc",
+            present=False,
+        )
+
+        # Install LXD using "4.0/stable" channel
+        snap.package(
+            name="Install LXD 4.0/stable",
+            packages=["lxd"],
+            channel="4.0/stable",
+        )
+
+        # Install neovim with classic confinement
+        snap.package(
+            name="Install Neovim",
+            packages=["nvim"],
+            classic=True,
+        )
+    """
+
+    if packages is None:
+        return
+
+    if isinstance(packages, str):
+        packages = [packages]
+
+    snap_packages = host.get_fact(SnapPackages)
+
+    install_packages = []
+    remove_packages = []
+    refresh_packages = []
+
+    for package in packages:
+        # it's installed
+        if package in snap_packages:
+            # we want the package
+            if present:
+                pkg_info = host.get_fact(SnapPackage, package=package)
+
+                # the channel is different
+                if pkg_info and "channel" in pkg_info and channel != pkg_info["channel"]:
+                    refresh_packages.append(package)
+                    pkg_info["channel"] = channel
+
+            else:
+                # we don't want it
+                remove_packages.append(package)
+
+        # it's not installed
+        if package not in snap_packages:
+            # we want it
+            if present:
+                install_packages.append(package)
+
+            # we don't want it
+            else:
+                host.noop(f"snap package {package} is not installed")
+
+    install_cmd = ["snap", "install"]
+    if classic:
+        install_cmd.append("--classic")
+    if install_packages:
+        yield " ".join(install_cmd + install_packages + [f"--channel={channel}"])
+
+    if remove_packages:
+        yield " ".join(["snap", "remove"] + remove_packages)
+
+    if refresh_packages:
+        yield " ".join(["snap", "refresh"] + refresh_packages + [f"--channel={channel}"])

pyinfra/operations/ssh.py

@@ -0,0 +1,216 @@
+"""
+Execute commands and up/download files *from* the remote host.
+
+Eg: ``pyinfra -> inventory-host.net <-> another-host.net``
+"""
+
+from __future__ import annotations
+
+import shlex
+
+from pyinfra import host
+from pyinfra.api import OperationError, operation
+from pyinfra.facts.files import File, FindInFile
+from pyinfra.facts.server import Home
+
+from . import files
+
+
+@operation()
+def keyscan(hostname: str, force=False, port=22):
+    """
+    Check/add hosts to the ``~/.ssh/known_hosts`` file.
+
+    + hostname: hostname that should have a key in ``known_hosts``
+    + force: if the key already exists, remove and rescan
+
+    **Example:**
+
+    .. code:: python
+
+        ssh.keyscan(
+            name="Set add server two to known_hosts on one",
+            hostname="two.example.com",
+        )
+    """
+
+    homedir = host.get_fact(Home)
+
+    yield from files.directory._inner(
+        "{0}/.ssh".format(homedir),
+        mode=700,
+    )
+
+    hostname_present = host.get_fact(
+        FindInFile,
+        path="{0}/.ssh/known_hosts".format(homedir),
+        pattern=hostname,
+    )
+
+    keyscan_command = "ssh-keyscan -p {0} {1} >> {2}/.ssh/known_hosts".format(
+        port,
+        hostname,
+        homedir,
+    )
+
+    if not hostname_present:
+        yield keyscan_command
+
+    elif force:
+        yield "ssh-keygen -R {0}".format(hostname)
+        yield keyscan_command
+
+    else:
+        host.noop("host key for {0} already exists".format(hostname))
+
+
+@operation(is_idempotent=False)
+def command(hostname: str, command: str, user: str | None = None, port=22):
+    """
+    Execute commands on other servers over SSH.
+
+    + hostname: the hostname to connect to
+    + command: the command to execute
+    + user: connect with this user
+    + port: connect to this port
+
+    **Example:**
+
+    .. code:: python
+
+        ssh.command(
+            name="Create file by running echo from host one to host two",
+            hostname="two.example.com",
+            command="echo 'one was here' > /tmp/one.txt",
+            user="vagrant",
+        )
+    """
+
+    command = shlex.quote(command)
+
+    connection_target = hostname
+    if user:
+        connection_target = "@".join((user, hostname))
+
+    yield "ssh -p {0} {1} {2}".format(port, connection_target, command)
+
+
+@operation(is_idempotent=False)
+def upload(
+    hostname: str,
+    filename: str,
+    remote_filename: str | None = None,
+    port=22,
+    user: str | None = None,
+    use_remote_sudo=False,
+    ssh_keyscan=False,
+):
+    """
+    Upload files to other servers using ``scp``.
+
+    + hostname: hostname to upload to
+    + filename: file to upload
+    + remote_filename: where to upload the file to (defaults to ``filename``)
+    + port: connect to this port
+    + user: connect with this user
+    + use_remote_sudo: upload to a temporary location and move using sudo
+    + ssh_keyscan: execute ``ssh.keyscan`` before uploading the file
+    """
+
+    remote_filename = remote_filename or filename
+
+    # Figure out where we're connecting (host or user@host)
+    connection_target = hostname
+    if user:
+        connection_target = "@".join((user, hostname))
+
+    if ssh_keyscan:
+        yield from keyscan._inner(hostname)
+
+    # If we're not using sudo on the remote side, just scp the file over
+    if not use_remote_sudo:
+        yield "scp -P {0} {1} {2}:{3}".format(
+            port,
+            filename,
+            connection_target,
+            remote_filename,
+        )
+
+    else:
+        # Otherwise - we need a temporary location for the file
+        temp_remote_filename = host.get_temp_filename()
+
+        # scp it to the temporary location
+        upload_cmd = "scp -P {0} {1} {2}:{3}".format(
+            port,
+            filename,
+            connection_target,
+            temp_remote_filename,
+        )
+
+        yield upload_cmd
+
+        # And sudo sudo to move it
+        yield from command._inner(
+            hostname=hostname,
+            command="sudo mv {0} {1}".format(temp_remote_filename, remote_filename),
+            port=port,
+            user=user,
+        )
+
+
+@operation()
+def download(
+    hostname: str,
+    filename: str,
+    local_filename: str | None = None,
+    force=False,
+    port=22,
+    user: str | None = None,
+    ssh_keyscan=False,
+):
+    """
+    Download files from other servers using ``scp``.
+
+    + hostname: hostname to upload to
+    + filename: file to download
+    + local_filename: where to download the file to (defaults to ``filename``)
+    + force: always download the file, even if present locally
+    + port: connect to this port
+    + user: connect with this user
+    + ssh_keyscan: execute ``ssh.keyscan`` before uploading the file
+    """
+
+    local_filename = local_filename or filename
+
+    # Get local file info
+    local_file_info = host.get_fact(File, path=local_filename)
+
+    # Local file exists but isn't a file?
+    if local_file_info is False:
+        raise OperationError(
+            "Local destination {0} already exists and is not a file".format(
+                local_filename,
+            ),
+        )
+
+    # If the local file exists and we're not forcing a re-download, no-op
+    if local_file_info and not force:
+        host.noop("file {0} is already downloaded".format(filename))
+        return
+
+    # Figure out where we're connecting (host or user@host)
+    connection_target = hostname
+    if user:
+        connection_target = "@".join((user, hostname))
+
+    if ssh_keyscan:
+        yield from keyscan._inner(hostname)
+
+    # Download the file with scp
+    yield "scp -P {0} {1}:{2} {3}".format(
+        port,
+        connection_target,
+        filename,
+        local_filename,
+    )

pyinfra/operations/systemd.py

@@ -0,0 +1,149 @@
+"""
+Manage systemd services.
+"""
+
+from __future__ import annotations
+
+import shlex
+
+from pyinfra import host
+from pyinfra.api import StringCommand, operation
+from pyinfra.facts.systemd import SystemdEnabled, SystemdStatus, _make_systemctl_cmd
+
+from .util.service import handle_service_control
+
+
+@operation(is_idempotent=False)
+def daemon_reload(user_mode=False, machine: str | None = None, user_name: str | None = None):
+    """
+    Reload the systemd daemon to read unit file changes.
+
+    + user_mode: whether to use per-user systemd (systemctl --user) or not
+    + machine: the machine name to connect to
+    + user_name: connect to a specific user's systemd session
+    """
+
+    systemctl_cmd = _make_systemctl_cmd(
+        user_mode=user_mode,
+        machine=machine,
+        user_name=user_name,
+    )
+
+    yield StringCommand(systemctl_cmd, "daemon-reload")
+
+
+_daemon_reload = daemon_reload._inner  # noqa: E305
+
+
+@operation()
+def service(
+    service: str,
+    running=True,
+    restarted=False,
+    reloaded=False,
+    command: str | None = None,
+    enabled: bool | None = None,
+    daemon_reload=False,
+    user_mode=False,
+    machine: str | None = None,
+    user_name: str | None = None,
+):
+    """
+    Manage the state of systemd managed units.
+
+    + service: name of the systemd unit to manage
+    + running: whether the unit should be running
+    + restarted: whether the unit should be restarted
+    + reloaded: whether the unit should be reloaded
+    + command: custom command to pass like: ``/etc/rc.d/<name> <command>``
+    + enabled: whether this unit should be enabled/disabled on boot
+    + daemon_reload: reload the systemd daemon to read updated unit files
+    + user_mode: whether to use per-user systemd (systemctl --user) or not
+    + machine: the machine name to connect to
+    + user_name: connect to a specific user's systemd session
+
+    **Examples:**
+
+    .. code:: python
+
+        systemd.service(
+            name="Restart and enable the dnsmasq service",
+            service="dnsmasq.service",
+            running=True,
+            restarted=True,
+            enabled=True,
+        )
+
+        systemd.service(
+            name="Enable logrotate timer",
+            service="logrotate.timer",
+            running=True,
+            enabled=True,
+        )
+
+    """
+
+    systemctl_cmd = _make_systemctl_cmd(
+        user_mode=user_mode,
+        machine=machine,
+        user_name=user_name,
+    )
+
+    if not service.endswith(
+        (
+            ".service",
+            ".socket",
+            ".device",
+            ".mount",
+            ".automount",
+            ".swap",
+            ".target",
+            ".path",
+            ".timer",
+            ".slice",
+            ".scope",
+        )
+    ):
+        service = "{0}.service".format(service)
+
+    if daemon_reload:
+        yield from _daemon_reload(
+            user_mode=user_mode,
+            machine=machine,
+            user_name=user_name,
+        )
+
+    yield from handle_service_control(
+        host,
+        service,
+        host.get_fact(
+            SystemdStatus,
+            user_mode=user_mode,
+            machine=machine,
+            user_name=user_name,
+            services=[service],
+        ),
+        " ".join([systemctl_cmd.get_raw_value(), "{1}", "{0}"]),
+        running,
+        restarted,
+        reloaded,
+        command,
+    )
+
+    if isinstance(enabled, bool):
+        systemd_enabled = host.get_fact(
+            SystemdEnabled,
+            user_mode=user_mode,
+            machine=machine,
+            user_name=user_name,
+            services=[service],
+        )
+        is_enabled = systemd_enabled.get(service, False)
+
+        # Isn't enabled and want enabled?
+        if not is_enabled and enabled is True:
+            yield "{0} enable {1}".format(systemctl_cmd, shlex.quote(service))
+
+        # Is enabled and want disabled?
+        elif is_enabled and enabled is False:
+            yield "{0} disable {1}".format(systemctl_cmd, shlex.quote(service))

pyinfra/operations/sysvinit.py

@@ -0,0 +1,141 @@
+"""
+Manage sysvinit services (``/etc/init.d``).
+"""
+
+from __future__ import annotations
+
+from pyinfra import host
+from pyinfra.api import operation
+from pyinfra.facts.files import FindLinks
+from pyinfra.facts.server import LinuxDistribution
+from pyinfra.facts.sysvinit import InitdStatus
+
+from . import files
+from .util.service import handle_service_control
+
+
+@operation()
+def service(
+    service: str,
+    running=True,
+    restarted=False,
+    reloaded=False,
+    enabled: bool | None = None,
+    command: str | None = None,
+):
+    """
+    Manage the state of SysV Init (/etc/init.d) services.
+
+    + 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
+    + enabled: whether this service should be enabled/disabled
+    + command: command (eg. reload) to run like: ``/etc/init.d/<service> <command>``
+
+    Enabled:
+        Because managing /etc/rc.d/X files is a mess, only certain Linux distributions
+        support enabling/disabling services:
+
+        + Ubuntu/Debian (``update-rc.d``)
+        + CentOS/Fedora/RHEL (``chkconfig``)
+        + Gentoo (``rc-update``)
+
+        For other distributions and more granular service control, see the
+        ``sysvinit.enable`` operation.
+
+    **Example:**
+
+    .. code:: python
+
+        sysvinit.service(
+            name="Restart and enable rsyslog",
+            service="rsyslog",
+            restarted=True,
+            enabled=True,
+        )
+    """
+
+    yield from handle_service_control(
+        host,
+        service,
+        host.get_fact(InitdStatus),
+        "/etc/init.d/{0} {1}",
+        running,
+        restarted,
+        reloaded,
+        command,
+    )
+
+    if isinstance(enabled, bool):
+        start_links = host.get_fact(
+            FindLinks,
+            path="/etc/rc*.d/S*{0}".format(service),
+            quote_path=False,  # enable path glob matching
+        )
+
+        # If no links exist, attempt to enable the service using distro-specific commands
+        if enabled is True and not start_links:
+            distro = host.get_fact(LinuxDistribution).get("name")
+
+            if distro in ("Ubuntu", "Debian"):
+                yield "update-rc.d {0} defaults".format(service)
+
+            elif distro in ("CentOS", "Fedora", "Red Hat Enterprise Linux"):
+                yield "chkconfig {0} --add".format(service)
+                yield "chkconfig {0} on".format(service)
+
+            elif distro == "Gentoo":
+                yield "rc-update add {0} default".format(service)
+
+        # Remove any /etc/rcX.d/<service> start links
+        elif enabled is False:
+            # No state checking, just blindly remove any that exist
+            for link in start_links:
+                yield "rm -f {0}".format(link)
+
+
+@operation()
+def enable(
+    service: str,
+    start_priority=20,
+    stop_priority=80,
+    start_levels=(2, 3, 4, 5),
+    stop_levels=(0, 1, 6),
+):
+    """
+    Manually enable /etc/init.d scripts by creating /etc/rcX.d/Y links.
+
+    + service: name of the service to enable
+    + start_priority: priority to start the service
+    + stop_priority: priority to stop the service
+    + start_levels: which runlevels should the service run when enabled
+    + stop_levels: which runlevels should the service stop when enabled
+
+    **Example:**
+
+    .. code:: python
+
+        init.d_enable(
+            name="Finer control on which runlevels rsyslog should run",
+            service="rsyslog",
+            start_levels=(3, 4, 5),
+            stop_levels=(0, 1, 2, 6),
+        )
+    """
+
+    # Build link list
+    links = []
+
+    for level in start_levels:
+        links.append("/etc/rc{0}.d/S{1}{2}".format(level, start_priority, service))
+
+    for level in stop_levels:
+        links.append("/etc/rc{0}.d/K{1}{2}".format(level, stop_priority, service))
+
+    # Ensure all the new links exist
+    for link in links:
+        yield from files.link._inner(
+            path=link,
+            target="/etc/init.d/{0}".format(service),
+        )

pyinfra/operations/upstart.py

@@ -0,0 +1,68 @@
+"""
+Manage upstart services.
+"""
+
+from __future__ import annotations
+
+from io import StringIO
+
+from pyinfra import host
+from pyinfra.api import operation
+from pyinfra.facts.upstart import UpstartStatus
+
+from . import files
+from .util.service import handle_service_control
+
+
+@operation()
+def service(
+    service: str,
+    running=True,
+    restarted=False,
+    reloaded=False,
+    command: str | None = None,
+    enabled: bool | None = None,
+):
+    """
+    Manage the state of upstart managed services.
+
+    + 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 to pass like: ``/etc/rc.d/<service> <command>``
+    + enabled: whether this service should be enabled/disabled on boot
+
+    Enabling/disabling services:
+        Upstart jobs define runlevels in their config files - as such there is no way to
+        edit/list these without fiddling with the config. So pyinfra simply manages the
+        existence of a ``/etc/init/<service>.override`` file, and sets its content to
+        "manual" to disable automatic start of services.
+    """
+
+    yield from handle_service_control(
+        host,
+        service,
+        host.get_fact(UpstartStatus),
+        "initctl {1} {0}",
+        running,
+        restarted,
+        reloaded,
+        command,
+    )
+
+    # Upstart jobs are setup w/runlevels etc in their config files, so here we just check
+    # there's no override file.
+    if enabled is True:
+        yield from files.file._inner(
+            path="/etc/init/{0}.override".format(service),
+            present=False,
+        )
+
+    # Set the override file to "manual" to disable automatic start
+    elif enabled is False:
+        file = StringIO("manual\n")
+        yield from files.put._inner(
+            src=file,
+            dest="/etc/init/{0}.override".format(service),
+        )

pyinfra/operations/util/__init__.py

@@ -0,0 +1,12 @@
+from typing import TYPE_CHECKING, Callable
+
+if TYPE_CHECKING:
+    from pyinfra.api.operation import OperationMeta
+
+
+def any_changed(*args: "OperationMeta") -> Callable[[], bool]:
+    return lambda: any((meta.did_change() for meta in args))
+
+
+def all_changed(*args: "OperationMeta") -> Callable[[], bool]:
+    return lambda: all((meta.did_change() for meta in args))