API: What is the signature of a method?

The opsi API does not get changed often but it happens. Additions happen as part of the normal development cycle but removals usually only appear as part of larger releases like the release of opsi 4.1. There is also the chance of a changed method signature. The same rules as above apply to the method signatures.

If one of the changes affects a method you use there are different possibilities to handle them.

Checking the version

If you know what version a change appeared in you can use this knowledge to check for a specific version. Reading the changelog of python-opsi is usually a good starting point to find out what changed. This is the module that contains the business logic and API.

The API method backend_info will return a JSON object that contains opsiVersion which is basically the version of python-opsi.

You can easily try it for yourself:

curl -X POST --user youruser --data '{"params": [], "id": 1, "method": "backend_info"}' https://localhost:4447/rpc

This approach works very well for the object-oriented API methods. These have the form objectType_action.

Checking method signature

In opsi we also have dynamically loaded backend extensions. The official extensions are distributed through the package python-opsi but nothing keeps you from using extensions from different versions. There could also be custom extensions that are not distributed through python-opsi. Methods defined through extensions usually don't follow the naming convention of objectType_action but there is no enforcing of this. As you see checking just the version may not work when the method originates from an backend extension.

Lucky for us it is possible to get a description of the available API methods and their signatures through another API call: backend_getInterface.

curl -X POST --user youruser --data '{"params": [], "id": 1, "method": "backend_getInterface"}' https://localhost:4447/rpc

This lists all available methods with their name, params and defaults among others. The values listed in params show how many parameters a method accepts and what their names are. If a parameter has one leading asterik (i.e. *attributes as a parameter of host_getObjects) then this indicates that this is an optional parameter. If a parameter has two leading asteriks (i.e. **filter as a parameter of host_getObjects) then this indicates that the value is optional and a JSON dictionary is expected. If defaults are listed then it contains the default values of optional parameters excluding those with two asteriks.

Summary

Handling multiple API version with opsi isn't too hard but it all depends on what was changed.

With backend_info you can easily check the version.

The powerful backend_getInterface will list the methods exposed through the API. This can be used to handled changed methods but it can also be useful to see what methods are available on the server.

opsi-linux-bootimage and new Dell devices

Within the last week we encountered a problem with our opsi-linux-bootimage in combination with new Dell devices. This problem results in a black screen and a seemingly dead machine whenever a Windows or 32bit Linux netboot installations runs. Furthermore an analysis is hard as the machine runs in a black screen of death (BSOD) before even properly starting the opsi-linux-bootimage kernel itself. However we have a workaround for this issue: use the 64Bit bootimage.

By default setting a windows netboot product on setup, triggers the opsipxeconfd, which uses a template to generate a specific PXE pipe. This file is within the opsi tftpboot directory. This directory is /tftpboot/linux on most opsi supported distributions (or /var/lib/tftpboot/opsi on SUSE based distributions). Within this tftpboot directory the PXE templates are found within the pxelinux.cfg directory. The specific template is the file install. This file has to be modified to use the 64bit kernel and miniroot of the opsi-linux-bootimage. The template should look like this after the modification:

default opsi-install

label opsi-install
  kernel install-x64
  append initrd=miniroot-x64.bz2 video=vesa:ywrap,mtrr vga=791 quiet splash --no-log console=tty1 console=ttyS0

The downside of this modification is that after an update one has to modify the template again. We are currently working on a permanent solution.