Administrative Compatibility Tool: Online Manual

← Back to the project page

NAME

act - administrative compatibility tool

SYNOPSIS

act [OPTION]... ACTION [ARGUMENTS]...
act [-h|-V]

DESCRIPTION

act provides a consistent interface for system administration activities across multiple types of Unix-like operating system.

The tool is intended to simplify administrative tasks across a heterogeneous estate, especially when performing automated updates, managing systems in bulk via a terminal multiplexer, or running under the control of a management interface. It is not intended to completely replace native administrative commands for more advanced usage.

User-defined hooks can be added, which run before and after each action; see the HOOKS section. For example, these may be useful if you are running a file system monitoring tool such as iwatch(8) and would like to ensure it's stopped before packages are updated, and started again afterwards.

OPTIONS

Note that options must come before the actions and arguments.

-n, --non-interactive

Run all actions in non-interactive mode even when standard input is a terminal.

-i, --interactive

Run all actions in interactive mode even when standard input is not a terminal.

-v, --verbose

Write details of the commands being called to stderr.

-vv, --debug

Write debugging information to stderr.

-q, --quiet

Discard all errors.

-qq, --very-quiet

Discard all output as well as all errors.

-h, --help

Print a usage message on standard output and exit successfully.

-V, --version

Print version information on standard output and exit successfully.

ACTIONS

Individual package management

These actions take one or more arguments, which are the names of the packages to operate on. Package names may not contain /, ;, spaces, or begin with -.

package-install

Install one or more packages. Depending on the package manager, this may also automatically install other packages on which the specified packages depend.

package-upgrade

Upgrade one or more packages to the latest available version.

package-downgrade

Downgrade one or more packages to the available version.

package-remove

Remove (uninstall) one or more packages. Depending on the package manager, this may automatically remove other packages in the process. Use this action with caution.

package-reinstall

Reinstall one or more packages.

package-info

Output information about one or more packages. The output format consists of one line per package, with the following fields on each line, separated by TAB characters:

package

The name of the package.

architecture

The package architecture, as reported by the package manager.

version

The version of the package.

install time

The epoch time at which the package was installed.

vendor

The package vendor, as reported by the package manager.

type

The type of package, such as "deb".

summary

The package summary or short description.

package-files

Output a list of the files owned by the named package.

package-owning-file

Given a filename, output the name of the package which owns that file, if any.

Bulk package management

These actions do not take any arguments.

package-cache-update

Update the package manager's cache of software repository information.

package-cache-clean

Clean up the package manager's caches of downloaded files and information.

package-upgrade-list

Output a list of packages for which upgrades are available. The output format consists of one line per package, with the following fields on each line, separated by TAB characters:

package

The name of the package.

architecture

The package architecture, as reported by the package manager.

target version

The version of the package that will be installed by the upgrade.

repository

The name of the repository from which the package will be retrieved.

type

The type of package, such as "deb".

package-upgrade-all

Upgrade all packages for which upgrades are available.

package-list-installed

List all currently installed packages, in the same format as the package-info action listed above.

Individual service management

These actions take a single argument, which is the service to act upon.

service-start

Start the service.

service-stop

Stop the service.

service-restart

Stop and start the service; if it was not running, this will start it.

service-try-restart

Restart the service, but only if it was already running, otherwise do nothing.

service-reload

Tell the service to reload its configuration.

service-enable

Enable the service so that it will start on boot. This will fail if the service is masked. Note that this does not start the service.

service-disable

Disable the service so that it will not start on boot. This will fail if the service is masked. Note that this does not stop the service if it is already running.

service-mask

Mask the service so that it will not start on boot and cannot be started. Note that this does not stop the service if it is already running.

service-unmask

Unmask the service so that it can be enabled, disabled, stopped, and started. Note that this does not enable, disable, stop, or start the service.

service-is-known

Output "true" and exit with status 0 if the service is known to the system at all, or output "false" and exit with status 1 if it is not.

service-is-running

Output "true" and exit with status 0 if the service is running, or output "false" and exit with status 1 if it is not. It is not an error if the service is not known to the system.

service-is-enabled

Output "true" and exit with status 0 if the service is enabled, or output "false" and exit with status 1 if it is not. It is not an error if the service is not known to the system.

service-is-masked

Output "true" and exit with status 0 if the service is masked, or output "false" and exit with status 1 if it is not. It is not an error if the service is not known to the system.

Bulk service management

These actions do not take any arguments.

service-list-all

List all services known to the system. The output format consists of one line per service, with the following fields on each line, separated by TAB characters:

service

The name of the service.

boot

The startup status of the service - enabled, disabled, or masked.

active

The current status of the service - inactive, activating, or active.

description

A short description of the service.

HOOKS

User-defined hooks can be placed in the hook directory, which is usually /usr/libexec/act/hook/. In the hook directory, there is a "pre" and "post" subdirectory for every action, as well as for the overall action class (which is the part of the action up to the first hyphen), and for all actions.

Within those subdirectories, every file ending in ".sh" will be executed in alphanumeric order.

For example, the package-install action will call these scripts before performing the action:

And then, after the action:

The scripts should ideally avoid producing any output.

Each script will be called with the action variable set to the action, the actionArguments variable set to the action's arguments, and for the "post" hooks, the exitStatus variable set to the exit status of the action. Hook scripts should not modify these variables.

Recursion is avoided by preventing future invocations of act from loading the same hooks again. The ACT_HOOKS_LOADED environment variable is used by act to pass lists of the hooks it has already loaded between its different invocations within the same run. It should therefore be safe to call act from within a hook script.

Hook example

To stop the iwatch(8) service before applying package changes, and start it again afterwards - but only if it was running already - place this in /usr/libexec/act/hook/pre/package/00-iwatch-stop.sh:

iwatchNeedsStarting=false
if act -qq service-is-running iwatch; then
act -qq service-stop iwatch
iwatchNeedsStarting=true
fi

Then, place this in /usr/libexec/act/hook/post/package/99-iwatch-start.sh:

if test "${iwatchNeedsStarting}" = "true"; then
act -qq service-start iwatch
fi

Hooks like this could be included in standardised configuration deployed to all systems using whatever management mechanism is appropriate for your estate.

EXIT STATUS

0

Action completed successfully.

1

Action not completed successfully.

2

Action not supported on this operating system.

CAVEATS

Service masking is not supported on either FreeBSD or OpenBSD.

On systems which use System V init, service masking is emulated by changing the permissions of the service file in /etc/init.d to 000.

The “activating” service status is only supported on systems using systemd(1). All other service managers will only show a status of “active” or “inactive”.

The “service-list-all” action leaves the short description empty for all services on OpenBSD.

Downgrading packages with “package-downgrade” is unsupported on FreeBSD.

Refreshing and cleaning the package cache is unsupported on OpenBSD.

On OpenBSD, the package installation timestamp reported by “package-info” and “package-list-installed” is derived from the last-modification time of the associated directory under /var/db/pkg/, which is not a documented method and may be unreliable.

When listing upgrades with “package-upgrade-list”, OpenBSD does not provide repository information, so the repository is always reported as “-” on that platform.

REPORTING BUGS

Please report any bugs to act@ivarch.com.

Alternatively, use the issue tracker linked from the act home page: <https://www.ivarch.com/programs/act.shtml>

SEE ALSO

apt-get(8), zypper(8), yum(8), dnf(8), pkg(8), pkg_add(8), pkg_delete(8), pkg_info(8), service(8), rcctl(8), systemctl(1)

Copyright © 2023-2024 Andrew Wood.

License GPLv3+: GNU GPL version 3 or later <https://www.gnu.org/licenses/gpl-3.0.html>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

← Back to the project page