X

News, tips, partners, and perspectives for the Oracle Solaris operating system

Using REST to Find Your Oracle Solaris Packages

In my previous blog on the REST API in Oracle Solaris I showed how you can enable the remote REST interface on Oracle Solaris and connect to it. I also mentioned the REST API is layered on top of the Remote Administration Daemon (RAD) so it gives you access to all its modules. In this blog I wanted to highlight the IPS RAD module and how you can use it through the REST interface to do some common IPS tasks using it.

Where in the previous blog I showed the initial REST calls using the Curl and Python, this time I'll be using Postman, an API development tool that can help you quickly explore a REST API. The nice thing is you can save the different calls and also allow you to create a test run in the case you want to run a series of calls in sequence. In general once they've figured out what they want to do with the API, folks will move to more programmatic methods like Python, especially if you need to recurse through a bunch of things and react to them. But for testing and exploring Postman works great, like in this case where I'll just be showing a few commands.

In this blog I'll be showing how you can use the /api/com.oracle.solaris.rad.ips/1.0 IPS API to get a list of the installed packages, searching for a specific package and getting it's info. There are also other tasks you can do like installing and removing a package, and triggering a system update to move to a new SRU, but that would make the post very long so I'll write about them in a later post.

Note that the documentation for the full REST API is available through the Web Dashboard by installing the webui-docs package.

Authenticating

Of course we first need authenticate like before but because I'm using Postman I thought I'd show how I'm doing this:

Note I'm using centrally set variables {{server}}, {{username}}, and {{password}} in the URL and the JSON payload, in part to obscure them but most importantly if I want to connect to a different server or connect under a different user ID I can change it once and all my URLs and payloads are updated where appropriate. Equally if you use a Postman test run you can load these in to fit your test.

Getting List of Installed Packages

The first real step now is to connect and ask for the list of installed packages. We do this by using the method info to the PkgImage interface of the IPS RAD module. To use this we use _rad_method to indicate we want to use a method. This is a PUT call so we also need to supply a JSON payload but initially will just send an empty { }. And thus the result looks like this:

As you can see the URI /api/com.oracle.solaris.rad.ips/1.0/PkgImage/%2F/_rad_method/info — where %2F stands for / — will give you something that looks like this:

{
        "status": "success",
        "payload": [
                {
                        "href": "/api/com.oracle.solaris.rad.ips/1.0/PkgInfo/_rad_reference/3073"
                },
                {
                        "href": "/api/com.oracle.solaris.rad.ips/1.0/PkgInfo/_rad_reference/3585"
                },
                {
                        "href": "/api/com.oracle.solaris.rad.ips/1.0/PkgInfo/_rad_reference/4097"
                },
                {
                        "href": "/api/com.oracle.solaris.rad.ips/1.0/PkgInfo/_rad_reference/4609"
                },
                {
                        "href": "/api/com.oracle.solaris.rad.ips/1.0/PkgInfo/_rad_reference/5121"
                },

...

                {
                        "href": "/api/com.oracle.solaris.rad.ips/1.0/PkgInfo/_rad_reference/320513"
                }
        ]
}

So you see this is a very long list of references each connected to a PkgInfo object. So the next step is to have a look at what these objects look like.

Checking the Package Info

To look at a specific PkgInfo object we use ?_rad_detail at the end of the URI. So taking a random reference 227329 we have a look with a GET call:

Where the /api/com.oracle.solaris.rad.ips/1.0/PkgInfo/rad_reference/227329?rad_detail URI gives:

{
        "status": "success",
        "payload": {
                "href": "/api/com.oracle.solaris.rad.ips/1.0/PkgInfo/_rad_reference/227329",
                "PkgInfo": {
                        "pkg_name": "system/io/infiniband/ib-device-mgt-agent",
                        "summary": "InfiniBand Device Manager Agent",
                        "description": "The InfiniBand Device Manager Agent (IBDMA) implements limited portions of the target (agent) side of the InfiniBand Device Management class as described in InfiniBand Architecture Specification, Volume 1: Release 1.2.1.  IBDMA responds to incoming Device Management Datagrams (MADS) by enumerating available target-side InfiniBand services.",
                        "category": "System/Hardware",
                        "state": "Installed",
                        "renamed_to": null,
                        "publisher": "solaris",
                        "last_install_time": null,
                        "last_update_time": null,
                        "size": "44.84 kB",
                        "fmri": {
                                "href": "/api/com.oracle.solaris.rad.ips/1.0/PkgFmri/_rad_reference/227585"
                        },
                        "licenses": []
                }
        }
}

And as you can see this looks a lot like the info you'd get from a regular pkg info command, no surprise I guess. The data essentially is a list of dictionaries.

Search and Get Info for a Specific Package

Now if you want to search for a specific package or packages and get its/their info you need to change the JSON payload to reflect which package(s) you're looking for, in this case I'm looking for the entire package:

{ 
	"pkg_fmri_patterns": [
        "entire"
    ]
}

And this gives us a much smaller response:

{
        "status": "success",
        "payload": [
                {
                        "href": "/api/com.oracle.solaris.rad.ips/1.0/PkgInfo/_rad_reference/2049"
                }
        ]
}

Here's the screenshot from Postman:

We can now use this reference to get further details like we did in the example above.

Note that these references are dynamic and aren't necessarily bound to a specific package, especially over different connections/authentications/reboots.

Also note that the info method give us more ways to filter the result but for that I'll refer to the documentation.

Another way to search for a specific package using the PkgImage interface and getting a PkgFmri reference directly is to use the list_packages method on the / image path. This results in the following URI:

/api/com.oracle.solaris.rad.ips/1.0/PkgImage/%2F/_rad_method/list_packages/

Where we use a similar JSON payload as before:

{
    "pkg_fmri_patterns": [
        "entire"
    ]
}

With a PUT call resulting in:

{
        "status": "success",
        "payload": [
                {
                        "href": "/api/com.oracle.solaris.rad.ips/1.0/PkgFmri/_rad_reference/2049"
                }
        ]
}

Again seen in Postman:

On the PkgFmri interface we also have individual methods to get specific piece of information, so for example if we use this URI:

/api/com.oracle.solaris.rad.ips/1.0/PkgFmri/_rad_reference/2049/_rad_method/get_fmri

With a PUT and an empty JSON payload ({ }) the response is:

{
        "status": "success",
        "payload": "pkg://solaris/entire@11.4,5.11-11.4.6.0.1.4.0:20190201T214604Z"
}

You can see that we're running 11.4 SRU 6 in on this system.

By the way, this interface only gives information which is stored in the package FMRI like the package name, the publisher, the version, the timestamp, and things like that.

Summary

In the examples above I've essentially started with the PkgImage interface and then used the RAD methods info and list_packages as ways to start looking for packages. This can be refined by altering the JSON payload you send with the PUT call. I've only used one — "pkg_fmri_patterns" — but there are many others that you can use with the different methods.

For example with the info methods I can use "info_local": <boolean> and "info_remote": <boolean> to refine my search to either on the system or in the repository. Similarly the list_packages methods has "list_upgradable": <boolean> to give you a list of packages that are upgradable, which is equivalent to the CLI pkg list -u option. So there's much more you can do with this than I've shown.

With that I'll close off. There are other things like installing and uninstalling packages as well as initiating a package update, and changing the package publisher. But these will have to wait for a future blog post.

Enjoy.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.