Remote Client Administration: An Introduction to Client Actions with `opsi-cli`

Are you tired of manually setting dozens of action requests for your clients? Or are you looking for a way to automate weekly updates? This blog post demonstrates how to make these things easier with opsi-cli and its command client-action. You can use it to set action requests for specific products or product groups on certain clients or client groups.

Setting Action Requests with opsi-cli

The commandline tool opsi-cli is available for Linux, Windows, and macOS. It works as a client component outside the opsi server and communicates via the opsi web service. opsi-cli is really useful if you't don't have access to a graphical user interface, like opsi-configed or the Web GUI. The opsi-cli command client-action offers a convenient way to set action requests, and the sub-command set-action-request enables the setting of product actions for clients. It operates on an exclusion principle: without specifying and filtering clients and products explicitly, the action will affect everything.

Let's look at our first example. The following command sets the action request setup (which is the default) for the hwaudit and swaudit packages on all clients:

opsi-cli client-action set-action-request --products=hwaudit,swaudit

It's easy to limit the pool of affected clients. Either use --clients or --client-groups and supply a list of comma-separated names. The next example sets the action request only for opsi clients which belong to the testgroup group:

doerrer@me:~$ opsi-cli -l 5 client-action --client-groups=testgroup set-action-request --products=hwaudit
[5] [2023-03-01 12:16:23.922] [               ] Selected clients: ['client-linux.domain.local', 'client-win10.domain.local']   (client_action_worker.py:56)
[5] [2023-03-01 12:16:23.972] [               ] Handling products ['hwaudit']   (set_action_request_worker.py:120)
[5] [2023-03-01 12:16:23.982] [               ] Setting 'setup' ProductActionRequest: hwaudit -> client-linux.domain.local   (set_action_request_worker.py:158)
[5] [2023-03-01 12:16:23.982] [               ] Setting 'setup' ProductActionRequest: hwaudit -> client-win10.domain.local   (set_action_request_worker.py:158)

TIP: To actually print those messages in the console, we've set the log level to 5, using the -l switch.

You can specify the type of action request with the --request-type parameter. As I said before, the default is setup. To reset an action request, use --request-type=none. This comes in handy when you want to remove action requests you set by mistake. The screenshot illustrates this: the first action request is setup for the localboot product opsi-client-agent on the opsi client client-linux.domain.local, followed by a command which revokes this with --request-type=none. The third command sets the action request for a Windows client.

opsi-cli enables to perform client actions called from your linux, macos or windows machine

Keeping Packages Up to Date on your Clients

You can also use set-action-request to perform more complex tasks. The parameter --where-outdated affects all products installed on a client which show a newer version in the associated software depot. This way you can use opsi-cli client-action to insure that software on the clients is up to date. You can use the following parameters to select the clients:

  • --clients: comma-separated list of client names or all
  • --client-groups: comma-separated list of host groups
  • --exclude-clients: do not perform actions on these clients
  • --exclude-client-groups: do not perform actions on these host groups

The following example demonstrates how to set all outdated products to setup on all clients, except the ones in the testgroup group:

opsi-cli -l 5 client-action --exclude-client-groups=testgroup set-action-request --where-outdated

Similarly, you can exclude specific products or product groups using --products, --product-groups, --exclude-products, and --exclude-product-groups.

Note: Please note that there is a list of products which are always excluded for these types of calls, including opsi-script, opsi-auto-update, windomain, etc.

Retrying failed Installations

Correspondingly, you can retry installing products with the parameter --where-failed. It sets a new action request for all products which have the status failed.

The following example sets the product runastest to setup on all clients where the previous installation failed:

doerrer@me:~$ opsi-cli -l 5 client-action set-action-request --where-failed --products=runastest
[5] [2023-03-01 13:58:52.715] [               ] Selected clients: ['client-linux.domain.local', 'client-macos.domain.local', 'client-win10.domain.local']   (client_action_worker.py:56)
[5] [2023-03-01 13:58:52.777] [               ] Handling products ['runastest']   (set_action_request_worker.py:120)
[5] [2023-03-01 13:58:52.788] [               ] Setting 'setup' ProductActionRequest: runastest -> client-win10.domain.local   (set_action_request_worker.py:158)

This is useful in test environments or in case some dependencies were missing when the product was first installed.

Tips & Tricks for client-action

In this last paragraph, we've collected some tips and tricks for you:

  • If you want to learn about available options of a command, call it with the parameter --help.
  • You can use cron to set up a schedule for opsi-cli commands on a Linux server (see chapter scheduling installations).
  • If you've written your own scripts to regularly update packages in your depot, you can simply include opsi-cli client-action set-action-request --where-outdated to run the update on your clients as soon as possible.
  • For a full list of commands, parameters, and options, please read our documentation (see chapter opsi command line tools and processes).

Happy tinkering!