Action Utils#
Several utilities to help with the implementation of actions and diagnostic tests are implemented in this module.
Python action utility functions.
- class plinth.action_utils.WebserverChange[source]#
Context to restart/reload Apache after configuration changes.
- plinth.action_utils.apt_hold(packages)[source]#
Prevent packages from being removed during apt operations.
apt-mark hold PACKAGES accepts a list of packages. But if one of the package is missing from the apt repository, then it will fail to hold any of the listed packages. So it is necessary to try to hold each package by itself.
Packages held by this context will be unheld when leaving the context. But if a package was already held beforehand, it will be ignored (and not unheld).
- plinth.action_utils.apt_hold_freedombox()[source]#
Prevent freedombox package from being removed during apt operations.
- plinth.action_utils.apt_unhold_freedombox()[source]#
Remove any hold on freedombox package, and clear flag.
- plinth.action_utils.debconf_set_selections(presets)[source]#
Answer debconf questions before installing a package.
- plinth.action_utils.dpkg_reconfigure(package, config)[source]#
Reconfigure package using debconf database override.
- plinth.action_utils.get_addresses() list[dict[str, str | bool]][source]#
Return a list of IP addresses and hostnames.
- plinth.action_utils.get_ip_addresses() list[dict[str, str | bool]][source]#
Return a list of IP addresses assigned to the system.
- plinth.action_utils.is_disk_image()[source]#
Return whether the current machine is from a disk image.
Two primary ways to install FreedomBox are: - Using FreedomBox image for various hardware platforms. - Installing packages on a Debian machine using apt.
- plinth.action_utils.is_package_manager_busy()[source]#
Return whether package manager is busy. This command uses the lsof command to check whether the dpkg lock file is open which indicates that the package manager is busy
- plinth.action_utils.move_uploaded_file(source: str | Path, destination_dir: str | Path, destination_file_name: str, allow_overwrite: bool = False, user: str = 'root', group: str = 'root', permissions: int = 420)[source]#
Move an uploaded file from Django upload directory to a destination.
Sets the expected ownership and permissions on the destination file. If possible, performs a simple rename operation. Otherwise, copies the file to the destination.
The source must be regular file under the currently configured Django file upload directory. It must be a absolute path that can be verified to be under Django settings FILE_UPLOAD_TEMP_DIR.
The destination_dir must be a directory. destination_file_name must be a simple file name without any other path components. When concatenated together, they specify the full destination path to move the file to.
If allow_overwrite is set to False and destination file exists, an exception is raised.
- plinth.action_utils.podman_create(container_name: str, image_name: str, volume_name: str, volume_path: str, volumes: dict[str, str] | None = None, env: dict[str, str] | None = None, binds_to: list[str] | None = None, devices: dict[str, str] | None = None)[source]#
Remove and recreate a podman container.
- plinth.action_utils.podman_disable(container_name: str)[source]#
Disable container to start on boot.
- plinth.action_utils.podman_is_enabled(container_name: str) bool[source]#
Return whether the container to start on boot.
- plinth.action_utils.podman_uninstall(container_name: str, volume_name: str, image_name: str, volume_path: str)[source]#
Remove a podman container’s components and systemd unit.
- plinth.action_utils.run(command, **kwargs)[source]#
Run subprocess.run but capture stdout and stderr in thread storage.
- plinth.action_utils.run_apt_command(arguments, enable_triggers: bool = False)[source]#
Run apt-get with provided arguments.
- plinth.action_utils.run_as_user(command, username, **kwargs)[source]#
Run a command as another user.
Uses ‘runuser’ which is similar to ‘su’. Creates PAM session unlike setpriv. Sets real/effective uid/gid and resets the environment.
- plinth.action_utils.service_action(service_name: str, action: str, check: bool = False)[source]#
Perform the given action on the service_name.
- plinth.action_utils.service_daemon_reload()[source]#
Reload systemd to ensure that newer unit files are read.
- plinth.action_utils.service_disable(service_name: str, check: bool = False)[source]#
Disable and stop service in systemd.
- plinth.action_utils.service_enable(service_name: str, check: bool = False)[source]#
Enable and start a service in systemd.
- plinth.action_utils.service_ensure_running(service_name)[source]#
Ensure a service is running and return to previous state.
- plinth.action_utils.service_ensure_stopped(service_name)[source]#
Ensure a service is stopped and return to previous state.
- plinth.action_utils.service_get_logs(service_name: str) str[source]#
Return the last lines of journal entries for a unit.
- plinth.action_utils.service_is_enabled(service_name, strict_check=False)[source]#
Check if service is enabled in systemd.
In some cases, after disabling a service, systemd puts it into a state called ‘enabled-runtime’ and returns a positive response to ‘is-enabled’ query. Until we understand better, a conservative work around is to pass strict=True to services effected by this behavior.
- plinth.action_utils.service_is_running(servicename)[source]#
Return whether a service is currently running.
Does not need to run as root.
- plinth.action_utils.service_reload(service_name: str, check: bool = False)[source]#
Reload a service with systemd.
- plinth.action_utils.service_reset_failed(service_name: str, check: bool = False)[source]#
Reset the ‘failed’ state of units.
- plinth.action_utils.service_restart(service_name: str, check: bool = False)[source]#
Restart a service with systemd.
- plinth.action_utils.service_show(service_name: str) dict[str, str][source]#
Return the status of the service in dictionary format.
- plinth.action_utils.service_start(service_name: str, check: bool = False)[source]#
Start a service with systemd.
- plinth.action_utils.service_stop(service_name: str, check: bool = False)[source]#
Stop a service with systemd.
- plinth.action_utils.service_try_reload_or_restart(service_name: str, check: bool = False)[source]#
Reload a service if it supports reloading, otherwise restart.
Do nothing if service is not running.
- plinth.action_utils.service_try_restart(service_name: str, check: bool = False)[source]#
Try to restart a service with systemd.
- plinth.action_utils.service_unmask(service_name: str, check: bool = False)[source]#
Unmask a service
- plinth.action_utils.systemd_get_default() str[source]#
Return the default target that systemd will boot into.
- plinth.action_utils.systemd_set_default(target: str)[source]#
Set the default target that systemd will boot into.
- plinth.action_utils.umask(mask) Generator[source]#
Set the umask temporarily for a operation and then revert it.
- plinth.action_utils.uwsgi_disable(config_name)[source]#
Disable a uwsgi configuration that runs under uwsgi.
- plinth.action_utils.uwsgi_enable(config_name)[source]#
Enable a uwsgi configuration that runs under uwsgi.
- plinth.action_utils.uwsgi_is_enabled(config_name)[source]#
Return whether a uwsgi config is enabled.
- plinth.action_utils.webserver_disable(name, kind='config', apply_changes=True)[source]#
Disable config/module/site in Apache.
Restart/reload the webserver if apply_changes is True. Return whether restart(‘restart’), reload(‘reload’) or no action (None) is required. If changes have been applied, then performed action is returned.
- plinth.action_utils.webserver_enable(name, kind='config', apply_changes=True)[source]#
Enable a config/module/site in Apache.
Restart/reload the webserver if apply_changes is True. Return whether restart(‘restart’), reload(‘reload’) or no action (None) is required. If changes have been applied, then performed action is returned.