Simplifying Remote Administration: An Introduction to JSON-RPC and opsi-cli

Are you looking for a more efficient way to access your opsi server remotely? This blog post explores the benefits of JSON-RPC, a stateless and lightweight protocol which simplifies the transmission of data between a server and a client. Discover the opsi-cli command jsonrpc, a user-friendly way to execute JSON-RPC methods on an opsi server. Available on Windows, Linux, and macOS, you no longer need to rely on SSH clients to manage your opsi environment.

Efficient Remote Administration: opsi-cli and JSON-RPC

One of the main advantages of opsi-cli is its ability to simplify the process of remotely administering an opsi server. With opsi-cli, you no longer need to rely on PuTTY or other SSH clients to connect to the server and manually enter opsi-admin commands. Instead, opsi-cli offers a convenient way allowing you to execute methods on the opsi server via JSON-RPC.

You may already be familiar with the JSON-RPC methods used in opsi-admin. We have designed opsi-cli to provide access to the same methods. On top of that, opsi-cli offers a more user-friendly experience than opsi-admin in an SSH session. Thanks to its advanced output formats and filtering options, navigating and understanding the commands' output becomes a lot easier.

opsi-cli is available as part of opsi-utils as well as opsi package in our public repositories at download.uib.de.

Configuring opsi-cli for Remote Access to your opsi Server

You can use opsi-cli to access a remote or a local opsi server. First, you provide the necessary access data. Use the config command to view and change the opsi-cli configuration. To display a table showing all stored access data (password is obfuscated), type the following command:

opsi-cli config service list

To register a new service, you can run this command:

opsi-cli config service add --name testsystem --username <adminuser> --password <strong_password> https://192.168.56.1:4447

testsystem is an arbitrary name to quickly reference the server. Replace <adminuser>, <strong_password>, and the URL shown in this example with the correct values for your environment. Afterwards, the command opsi-cli config service list should display the server's access data.

Note: Since you can store access data for multiple servers, make sure to define the correct default server to connect to:

opsi-cli config set service testsystem

Instead of the name (testsystem) you can also use the server's URL.

Exploring the jsonrpc command

The jsonrpc command is used to access and execute JSON-RPC methods on an opsi server. It supports two subcommands:

• opsi-cli jsonrpc methods: Prints a list of all available API methods and parameters.
• opsi-cli jsonrpc execute <method>: Executes the define method.

To display a list of all available methods with their mandatory and optional parameters, run the following command:

opsi-cli jsonrpc methods

This list also shows if a method is marked as "deprecated" and suggests an alternative as recommended fallback. So this command can be used as a reference. Let's now look at some examples for executing a JSON-RPC method.

To execute a specific method, define its name after the opsi-cli jsonrpc execute command, for example:

doerrer@me:~$ opsi-cli jsonrpc execute getClientIDs
[
  "client-linux.domain.local",
  "client-macos.domain.local",
  "client-win10.domain.local"
]

TIP: The output is in JSON format by default, but we've added colours and line indentation to improve the readability.

Example: Displaying Messages on opsi Clients

You can use the opsi-cli jsonrpc execute command, for example, to print a message on an opsi client's desktop. To send "have a nice day" to the opsi-client client-linux.domain.local, type this:

doerrer@me:~$ opsi-cli jsonrpc execute hostControlSafe_showPopup "have a nice day" client-linux.domain.local
{
  "client-linux.domain.local": {
    "result": null,
    "error": null
  }
}

If the called JSON-RPC method does not produce any output, the result is the JSON-RPC response, showing any errors if present. So, if result contains something, only that is displayed (for example, the requested data). If not, you will see the "raw state".

The previous example shows "result": null which basically means that the method has no result.

Example: Displaying Hosts' Information

The next example is a bit more complex. This command (output omitted) shows host information for all OpsiConfigserver and OpsiDepotserver objects:

opsi-cli jsonrpc execute host_getObjects [] '{"type":["OpsiConfigserver","OpsiDepotserver"]}

To further improve human readability and to limit the output to only a handful of relevant attributes, you can use the two parameters --attributes and --output-format:

doerrer@me:~/Documents/uib/blog.opsi.org$ opsi-cli --attributes=id,ipAddress,type --output-format=table jsonrpc execute host_getObjects [] '{"type":["OpsiConfigserver","OpsiDepotserver"]}'
╭──────────────────────────┬──────────────┬──────────────────╮
│ id                       │ ipAddress    │ type             │
├──────────────────────────┼──────────────┼──────────────────┤
│ opsi-server.domain.local │ 192.168.56.1 │ OpsiConfigserver │
│ opsi-depot.domain.local  │ 192.168.56.2 │ OpsiDepotserver  │
╰──────────────────────────┴──────────────┴──────────────────╯

• --attributes is used to specify the fields which you want to keep in the output (comma-separated list)
• --output-format changes the appearance of the displayed result (available formats: auto, json, pretty-json, msgpack, table, and csv)

Using opsi-cli in Scripts

If you want to process the output of a JSON-RPC method on the command line, it's usually a good idea to select json, msgpack, or csv as output format. Let's look at this example:

opsi-cli --output-format=json jsonrpc execute host_getObjects [] '{"id": "client-win10.domain.local"}' | sed -e 's/"notes":"[^"]*"/"notes":"modified by opsi-cli"/' | opsi-cli jsonrpc execute host_updateObjects

The host object for the opsi client client-win10.domain.local is retrieved from the database. The output in JSON format is passed via a pipe to the next process. The sed command shown in the example above changes "notes":"created by opsi-deploy-client-agent" to "notes":"modified by opsi-cli".

This modified JSON representation of a host object is then passed to another opsi-cli command which executes a JSON-RPC method to update the corresponding host object in the database. As a result, the next time host_getObjects is called for client-win10.domain.local, the notes data field will contain the new string "modified by opsi-cli".

Tips and Tricks

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

• If you manage multiple opsi servers, you can have their access data stored and switch between them using the opsi-cli config set service <opsi_server_name> command. Alternatively, you can use the --service parameter: opsi-cli --service=<opsi_server_name> jsonrpc execute <method>
• You can use the [Tab] key for autocompletion and suggestions on JSON-RPC methods and their arguments. Have a look at our blog post opsi-cli: Shell Completion to learn more about the autocompletion feature.
• If you want to store or automatically process large amounts of data, we recommend using --output-format=msgpack. It enhances the performance and produces the most compact of all the available output formats.
• JSON-RPC methods are usually quite efficient, but there is an overhead in the network communication and assembly of data. Try to avoid sending a large number of JSON-RPC methods (e.g. in a loop). It's better to send one large request (and then continue to process the data locally) than to send many small requests.

Have fun experimenting! If you want to share any feedback, please feel free to do so (e.g. in our forum).