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

Remote Client Administration: An Introduction to Client Actions with _opsi-cli_

Setting Action Requests with opsi-cli

The command line 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 and/or opsi messagebus. opsi-cli is really useful in situations when you don’t want to use a graphical user interface, like the opsi-configed or the Web GUI. The opsi-cli command client-action offers a convenient way to set action requests for clients via the sub-command set-action-request.

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 --clients=all 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']   (
[5] [2023-03-01 12:16:23.972] [               ] Handling products ['hwaudit']   (
[5] [2023-03-01 12:16:23.982] [               ] Setting 'setup' ProductActionRequest: hwaudit -> client-linux.domain.local   (
[5] [2023-03-01 12:16:23.982] [               ] Setting 'setup' ProductActionRequest: hwaudit -> client-win10.domain.local   (


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 mentioned 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 has a newer version available 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 --clients=all --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.


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

Retrying failed Installations

Correspondingly, you can retry product installations 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 --clients=all 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']   (
[5] [2023-03-01 13:58:52.777] [               ] Handling products ['runastest']   (
[5] [2023-03-01 13:58:52.788] [               ] Setting 'setup' ProductActionRequest: runastest -> client-win10.domain.local   (

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!

Related Posts

New opsi Basic License: Paid Extensions now free for 30 Clients

New opsi Basic License: Paid Extensions now free for 30 Clients

Good news for everyone out there using opsi extensions: With our new Basic license you can install (almost) all our paid extension free of charge on up to 30 clients. This article gives a brief introduction to the new opsi license.

Read More
opsiconf 2022 in Mainz: opsi Ahoy!

opsiconf 2022 in Mainz: opsi Ahoy!

Two years of calm waters are behind us, and we have reduced social contacts and work relationships to a minimum. Meeting people in real life is great, and I was excited to attend opsiconf in Mainz!

Read More
opsi-cli: Working faster with the Shell Completion

opsi-cli: Working faster with the Shell Completion

As announced in our previous blog post, we have released a new command line tool to work with opsi environments. It’s implemented in Python and offers a really cool autocompletion feature which this blog post introduces.

Read More