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
, andcsv
)
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).