Web service / API methods

object oriented methods

Since opsi 4 we have to different kinds of API methods:

'object oriented' methods
'action oriented' methods

opsi has a python library which provides an API for opsi configuration. Documentation for this API regarding python-opsi https://docs.opsi.org/python-docs/python-opsi and opsicommon https://docs.opsi.org/python-docs/python-opsi-common is at docs.opsi.org.

Overview

The opsi4 backends are based on objects. An object has a set of attributes.

As an example serves here the object 'Product'. The object of type 'Product' which describes the opsi package 'javavm' looks for example like this:

"ident": "javavm;1.6.0.20;2"
"id": "javavm"
"description": "Java 1.6"
"changelog": ""
"advice": ""
"userLoginScript": ""
"name": "SunJavaRuntimeEnvironment"
"priority": 0
"packageVersion": "2"
"productVersion": "1.6.0.20"
"windowsSoftwareIds": null
"productClassIds": null
"type": "LocalbootProduct"
"licenseRequired": false
"setupScript": "javavm.ins"
"updateScript": ""
"uninstallScript": "deljvm.ins"
"alwaysScript": ""
"onceScript": ""
"customScript": ""

For each object there is a set of operations. Usually these are:

'getObjects': returns a list of objects that match the specified filter. If a list of attributes is specified, only these will be populated from the backend.
'getHashes': Like 'getObjects', except that unchecked raw data from the backend is delivered directly. Works more performant than 'getObjects', but should be used with caution.
'getIdents' Returns a list of object IDs that match the specified filter. The 'returnType' can be used to select the data structure of the elements in the result. Possible values are: 'unicode', 'list' and 'hash'.
insertObject': Creates a new object. If the object already exists, it will be completely overwritten with the new values. Attributes that are not passed (or passed with the value 'null') will be set to 'null' in the backend.
updateObject': Updates an object. Attributes that are not passed (or passed with the value 'null'), will not be changed in the backend. If the object does not exist, no change takes place, no object is created.
'createObjects': An object or a list of objects can be passed. Each object is passed internally to 'insertObject'.
'updateObjects': An object or a list of objects can be passed. Each object is passed internally to 'insertObject' if it does not exist yet, otherwise to 'updateObject'.
'create': Creates a new object and takes all possible attributes as single parameters. Internally 'createObjects' is used. Existing objects will be overwritten completely.
'deleteObjects': Deletes a list of objects. It is mandatory to pass a list. Only the attributes identifying the object ('type'/'id'/'ident') are used to select the objects to be deleted.
'delete': Deletes the object identified by the specified parameters.

To update an object, it is usually a good idea to use the 'updateObjects' method. For example, 'productOnClient_updateObjects' can be used to update the state of a package on a client. Whether the object already exists or not is then irrelevant.

The names of the methods are composed of:

'<object-type>_<operation>'

Thus they differ from the 'legacy' methods from opsi 3.x which usually start with 'get', 'set' or 'create'.

The 'getObjects' methods have two optional parameters:

'attributes'
'filter'

The 'attributes' parameter is used to query only certain attributes of the object, which can provide speed advantages. If a list of attributes is specified, only these are read from the backend. The remaining attributes are returned with the value 'null'. Attributes that identify the object ('type'/'id'/'ident') are always filled. If all attributes should be read (default), 'null' or '[]' can be passed as 'attributes'.

Example for the method 'product_getObjects', parameterized with 'attributes:["name"]' for the package ('Product') 'javavm':

"onceScript": null,
"ident": "javavm;1.6.0.20;2",
"windowsSoftwareIds": null,
"description": null,
"setupScript": null,
"changelog": null,
"customScript": null,
"advice": null,
"uninstallScript": null,
"userLoginScript": null,
"name": "Sun Java Runtime Environment",
"priority": null,
"packageVersion": "2",
"productVersion": "1.6.0.20",
"updateScript": null,
"productClassIds": null,
"alwaysScript": null,
"type": "LocalbootProduct",
"id": "javavm",
"licenseRequired": null

If you don’t want to ask for attributes but instead you need to use the second parameter 'filter' you have to pass the attribute parameter as '[]'.

The parameter filter is used to define which objects you want to get. For example if you are using the filter '{"id":"javavm"}' on the method 'product_getObjects' the backend will return the 'Product' object 'javavm' only.

The 'filter' parameter can be used to filter the list of objects. For example, for 'product_getObjects' the filter '{"id": "javavm"}' restricts the return to the object with the ID 'javavm'. Multiple passed filter attributes are 'AND'-linked here. If a list of values is passed for an attribute, this results in an 'OR' operation. For strings, a '*' can be used as a placeholder. If you do not want to filter (default), you can pass 'null' or '{}' as 'filter'.

Example for 'product_getIdents' with filter '{"id":["opsi-client-agent", "opsi-script"], "productVersion": "4.1*"}' ('returnType' = 'hash'):

[
    {
        "id": "opsi-client-agent",
        "productVersion": "4.1.0.0",
        "packageVersion": "47"
    },
    {
        "id": "opsi-client-agent",
        "productVersion": "4.1.1.40",
        "packageVersion": "1"
    },
    {
        "id": "opsi-script",
        "productVersion": "4.12.4.21",
        "packageVersion": "1"
    },
    {
        "id": "opsi-script",
        "productVersion": "4.12.4.23",
        "packageVersion": "1"
    }
]

For the methods to which one or more objects are passed, this must be done as a JSON object or a list of JSON objects.

The most important objects are:

'auditHardwareOnHost' (client specific hardware information)
'auditHardware' (client independent hardware information)
'auditSoftwareOnClient' (client specific software information)
'auditSoftware' (client independent software information)
'auditSoftwareToLicensePool' (license management)
'configState' (administration of client host parameters)
'config' (administration of host parameter defaults)
'group' (group administration)
'host' (server and clients)
'licenseContract' (license management)
'licenseOnClient' (license management)
'licensePool' (license management)
'objectToGroup' (group administration)
'productDependency' (product dependencies)
'productOnClient' (client specific information to a product e.g. installation state)
'productOnDepot' (depot specific information to a product)
'productPropertyState' (depot or client specific product property settings)
'productProperty' (definition of product properties)
'product' (product meta data)
'softwareLicenseToLicensePool' (license management)
'softwareLicense' (license management)

In addition to the described objects and methods there are some more for special operations.

This design:

is created to transfer information about clients (severals) faster
filter data with a unified syntax
allows to check all input for correct syntax

This results in improved stability and higher performance.

'Host' (server and clients)

Example of a OpsiClient:

 method host_getObjects [] {"id":"xpclient.vmnat.local"}
[
          {
          "ident" : "xpclient.vmnat.local",
          "description" : "",
          "created" : "2012-03-22 12:13:52",
          "inventoryNumber" : "",
          "ipAddress" : "172.16.166.101",
          "notes" : "Created by opsi-deploy-client-agent at Wed, 24 Aug 2011 10:24:36",
          "oneTimePassword" : "",
          "lastSeen" : "2012-03-30 16:20:04",
          "hardwareAddress" : "00:0c:29:35:70:a7",
          "opsiHostKey" : "1234567890abcef1234567890abcdef",
          "type" : "OpsiClient",
          "id" : "xpclient.vmnat.local"
          }
]

Most of this data is displayed on the 'clients' tab of the opsi-configed.

Possible types are:

'OpsiClient'
'OpsiConfigserver' (which means implicit this is also a 'OpsiDepotserver')
'OpsiDepotserver'

The server type have different and additional data.

Example of a server:

 method host_getObjects [] {"id":"sepiolina.vmnat.local"}
[
          {
          "masterDepotId" : null,
          "ident" : "sepiolina.vmnat.local",
          "networkAddress" : "172.16.166.0/255.255.255.128",
          "description" : "",
          "inventoryNumber" : "",
          "ipAddress" : "172.16.166.1",
          "repositoryRemoteUrl" : "webdavs://sepiolina.vmnat.local:4447/repository",
          "depotLocalUrl" : "file:///var/lib/opsi/depot",
          "isMasterDepot" : true,
          "notes" : "",
          "hardwareAddress" : null,
          "maxBandwidth" : 0,
          "repositoryLocalUrl" : "file:///var/lib/opsi/repository",
          "opsiHostKey" : "1234567890abcef1234567890abcdef",
          "type" : "OpsiConfigserver",
          "id" : "sepiolina.vmnat.local",
          "depotWebdavUrl" : "webdavs://sepiolina:4447/depot",
          "depotRemoteUrl" : "smb://sepiolina/opsi_depot"
          }
]

Most of this data is displayed on the 'depot configuration' of the opsi-configed.

'Group' (group administration)

Describes groups and their hierarchical structure. The types 'HostGroup' and 'ProductGroup' exist.

Example of a 'Group' object:

 method group_getObjects
 [
       {
          "ident" : "sub2",
          "description" : "sub2",
          "notes" : "",
          "parentGroupId" : null,
          "type" : "HostGroup",
          "id" : "sub2"
          },
          {
          "ident" : "subsub",
          "description" : "subsub",
          "notes" : "",
          "parentGroupId" : "sub2",
          "type" : "HostGroup",
          "id" : "subsub"
          }
]

'ObjectToGroup' (group membership administration)

Describes the membership of an object in a group. Example of 'ObjectToGroup' objects:

 method objectToGroup_getObjects
[
         {
          "groupType" : "HostGroup",
          "ident" : "HostGroup;sub2;win7.vmnat.local",
          "type" : "ObjectToGroup",
          "groupId" : "sub2",
          "objectId" : "win7.vmnat.local"
          },
          {
          "groupType" : "HostGroup",
          "ident" : "HostGroup;subsub;win7x64.vmnat.local",
          "type" : "ObjectToGroup",
          "groupId" : "subsub",
          "objectId" : "win7x64.vmnat.local"
          },
        {
          "groupType" : "ProductGroup",
          "ident" : "ProductGroup;opsiessentials;opsi-client-agent",
          "type" : "ObjectToGroup",
          "groupId" : "opsiessentials",
          "objectId" : "opsi-client-agent"
          },
          {
          "groupType" : "ProductGroup",
          "ident" : "ProductGroup;opsiessentials;opsi-winst",
          "type" : "ObjectToGroup",
          "groupId" : "opsiessentials",
          "objectId" : "opsi-winst"
          }
]

'Product' (package meta data)

Describes the meta data of a product which are defined while creating the package.

Example of a product object:

 method product_getObjects [] {"id":"jedit","productVersion":"4.5"}
[
          {
          "onceScript" : "",
          "ident" : "jedit;4.5;3",
          "windowsSoftwareIds" :
                    [

                    ],
          "description" : "jEdit with opsi-winst Syntax-Highlighting",
          "setupScript" : "setup.ins",
          "changelog" : "",
          "customScript" : "",
          "advice" : "",
          "uninstallScript" : "uninstall.ins",
          "userLoginScript" : "",
          "name" : "jEdit programmer's text editor",
          "priority" : 0,
          "packageVersion" : "3",
          "productVersion" : "4.5",
          "updateScript" : "update.ins",
          "productClassIds" :
                    [

                    ],
          "alwaysScript" : "",
          "type" : "LocalbootProduct",
          "id" : "jedit",
          "licenseRequired" : false
          }
]

If you have multiple depot servers, you may have different versions of one product.

The attributes 'productClassIds' and 'windowsSoftwareIds' are currently unused.

'ProductProperty' (definition of product properties)

Describes the properties of a 'Product'' which are defined while creating the package.

Example of a 'ProductProperty' object:

 method productProperty_getObjects [] {"productId":"jedit","productVersion":"4.5"}
[
          {
          "ident" : "jedit;4.5;3;start_server",
          "description" : "Should the jedit server be started at every startup ?",
          "editable" : false,
          "defaultValues" :
                    [
                    false
                    ],
          "multiValue" : false,
          "productVersion" : "4.5",
          "possibleValues" :
                    [
                    false,
                    true
                    ],
          "packageVersion" : "3",
          "type" : "BoolProductProperty",
          "propertyId" : "start_server",
          "productId" : "jedit"
          }
]

The real default values are stored in the context of the depot in a productPropertyState object.

'productPropertyState' (depot or client specific package settings)

Describes:

The default value for a 'ProductProperty' on a depot
The client specific settings of a 'ProductProperty'.

Example for 'ProductPropertyState' objects:

 method productPropertyState_getObjects [] {"productId":"jedit"}
[
          {
          "ident" : "jedit;start_server;sepiolina.vmnat.local",
          "objectId" : "sepiolina.vmnat.local",
          "values" :
                    [
                    false
                    ],
          "type" : "ProductPropertyState",
          "propertyId" : "start_server",
          "productId" : "jedit"
          },
         {
          "ident" : "jedit;start_server;xpclient.vmnat.local",
          "objectId" : "xpclient.vmnat.local",
          "values" :
                    [
                    true
                    ],
          "type" : "ProductPropertyState",
          "propertyId" : "start_server",
          "productId" : "jedit"
          }

]

'ProductDependency' (product dependencies)

Describes the dependencies of a package to another package as it is defined while creating the package.

Example of a 'ProductDependency' object:

method productDependency_getObjects [] {"productId":"jedit","productVersion":"4.5"}
[
          {
          "ident" : "jedit;4.5;3;setup;javavm",
          "productAction" : "setup",
          "requiredPackageVersion" : null,
          "requirementType" : "before",
          "requiredInstallationStatus" : "installed",
          "productVersion" : "4.5",
          "requiredProductId" : "javavm",
          "requiredAction" : null,
          "requiredProductVersion" : null,
          "type" : "ProductDependency",
          "packageVersion" : "3",
          "productId" : "jedit"
          }
]

'productOnClient' (client specific information of a package like the installation status)

Describes which packages and versions are installed on which client.

Example of a 'ProductOnClient' object:

 method productOnClient_getObjects [] {"productId":"jedit","clientId":"xpclient.vmnat.local"}
[
          {
          "ident" : "jedit;LocalbootProduct;xpclient.vmnat.local",
          "actionProgress" : "",
          "actionResult" : "successful",
          "clientId" : "xpclient.vmnat.local",
          "modificationTime" : "2012-03-30 15:49:04",
          "actionRequest" : "none",
          "targetConfiguration" : "installed",
          "productVersion" : "4.5",
          "productType" : "LocalbootProduct",
          "lastAction" : "setup",
          "packageVersion" : "3",
          "actionSequence" : -1,
          "type" : "ProductOnClient",
          "installationStatus" : "installed",
          "productId" : "jedit"
          }
]

'ProductOnDepot' (depot specific package information)

Describes which product is installed in which version on a given depot..

Example of 'ProductOnDepot' objects:

 method productOnDepot_getObjects [] {"productId":"jedit"}
[
          {
          "ident" : "jedit;LocalbootProduct;4.4.1;2;depotserver.vmnat.local",
          "locked" : false,
          "productVersion" : "4.4.1",
          "productType" : "LocalbootProduct",
          "depotId" : "depotserver.vmnat.local",
          "type" : "ProductOnDepot",
          "packageVersion" : "2",
          "productId" : "jedit"
          },
          {
          "ident" : "jedit;LocalbootProduct;4.5;3;sepiolina.vmnat.local",
          "locked" : false,
          "productVersion" : "4.5",
          "productType" : "LocalbootProduct",
          "depotId" : "sepiolina.vmnat.local",
          "type" : "ProductOnDepot",
          "packageVersion" : "3",
          "productId" : "jedit"
          }
]

If you have multiple depot server, you may have different versions of one product.

'Config' (administration of configurations)

Describes the available configurations.

Example of a 'Config' object:

 method config_getObjects [] {"id":"opsiclientd.event_gui_startup.active"}
[
          {
          "ident" : "opsiclientd.event_gui_startup.active",
          "description" : "gui_startup active",
          "defaultValues" :
                    [
                    true
                    ],
          "editable" : false,
          "multiValue" : false,
          "possibleValues" :
                    [
                    false,
                    true
                    ],
          "type" : "BoolConfig",
          "id" : "opsiclientd.event_gui_startup.active"
          }
]

'ConfigState' (administration of client specific configurations)

Describes the client specific state of a configuration.

Example of an 'ConfigState' object:

 method configState_getObjects [] {"configId":"opsiclientd.event_gui_startup.active"}
[
          {
          "configId" : "opsiclientd.event_gui_startup.active",
          "ident" : "opsiclientd.event_gui_startup.active;wanclient.vmnat.local",
          "values" :
                    [
                    false
                    ],
          "objectId" : "wanclient.vmnat.local",
          "type" : "ConfigState"
          }
]

A 'ConfigState' object can’t be created without an existing 'Config' object to refer to.

'AuditHardwareOnHost' (client specific hardware information)

Describes the detected hardware types (including the client specific values). The idea is that you can see here the client specific data and in auditHardware only one entry for a network card which is used in all your computers.
Unfortunately in reality this doesn’t work as you might expect.

The attribute 'state' describes if this is current (value = '1') or historic (value = '0') data.

Example of 'AuditHardwareOnHost' objects:

 method auditHardwareOnHost_getObjects [] {"hostId":"xpclient.vmnat.local","hardwareClass":"NETWORK_CONTROLLER","ipAddress":"172.16.166.101"}
[
          {
          "vendorId" : "1022",
          "macAddress" : "00:0C:29:35:70:A7",
          "hardwareClass" : "NETWORK_CONTROLLER",
          "state" : 1,
          "deviceType" : "PCI",
          "subsystemVendorId" : "2000",
          "ipEnabled" : "True",
          "type" : "AuditHardwareOnHost",
          "firstseen" : "2012-03-30 15:48:15",
          "revision" : "10",
          "hostId" : "xpclient.vmnat.local",
          "vendor" : "Advanced Micro Devices (AMD)",
          "description" : "Ethernetadapter der AMD-PCNET-Familie",
          "subsystemDeviceId" : "1022",
          "deviceId" : "2000",
          "autoSense" : null,
          "netConnectionStatus" : "Connected",
          "maxSpeed" : null,
          "name" : "Ethernetadapter der AMD-PCNET-Familie",
          "serialNumber" : null,
          "lastseen" : "2012-03-30 15:48:15",
          "model" : null,
          "ipAddress" : "172.16.166.101",
          "adapterType" : "Ethernet 802.3"
          },
          {
          "vendorId" : "1022",
          "macAddress" : "00:0C:29:35:70:A7",
          "hardwareClass" : "NETWORK_CONTROLLER",
          "state" : 0,
          "deviceType" : "PCI",
          "subsystemVendorId" : "2000",
          "ipEnabled" : "True",
          "type" : "AuditHardwareOnHost",
          "firstseen" : "2012-03-08 14:26:14",
          "revision" : "10",
          "hostId" : "xpclient.vmnat.local",
          "vendor" : "VMware, Inc.",
          "description" : "VMware Accelerated AMD PCNet Adapter",
          "subsystemDeviceId" : "1022",
          "deviceId" : "2000",
          "autoSense" : null,
          "netConnectionStatus" : "Connected",
          "maxSpeed" : null,
          "name" : "VMware Accelerated AMD PCNet Adapter",
          "serialNumber" : null,
          "lastseen" : "2012-03-10 14:47:15",
          "model" : null,
          "ipAddress" : "172.16.166.101",
          "adapterType" : "Ethernet 802.3"
          },
   {
          "vendorId" : "1022",
          "macAddress" : "00:0c:29:35:70:a7",
          "hardwareClass" : "NETWORK_CONTROLLER",
          "state" : 0,
          "deviceType" : null,
          "subsystemVendorId" : "1022",
          "ipEnabled" : null,
          "type" : "AuditHardwareOnHost",
          "firstseen" : "2012-02-29 15:43:21",
          "revision" : "10",
          "hostId" : "xpclient.vmnat.local",
          "vendor" : "Advanced Micro Devices [AMD]",
          "description" : "Ethernet interface",
          "subsystemDeviceId" : "2000",
          "deviceId" : "2000",
          "autoSense" : "",
          "netConnectionStatus" : "yes",
          "maxSpeed" : null,
          "name" : "79c970 [PCnet32 LANCE]",
          "serialNumber" : "00:0c:29:35:70:a7",
          "lastseen" : "2012-03-30 14:58:30",
          "model" : "79c970 [PCnet32 LANCE]",
          "ipAddress" : "172.16.166.101",
          "adapterType" : ""
          }
]

'AuditHardware' (client independent hardware information)

Describes the detected hardware types (independent from client specific values). The idea in this object is to see client specific data and in AuditHardware only the generic. That way, for example, you can see here only one entry for a network card, which is used in all your computers.
Unfortunately in reality this idea doesn’t work as you might expect.

Example of 'AuditHardware' objects:

 method auditHardware_getObjects [] {"hardwareClass":"NETWORK_CONTROLLER","vendorId":"1022"}
[
          {
          "vendorId" : "1022",
          "deviceId" : "2000",
          "maxSpeed" : null,
          "vendor" : "Advanced Micro Devices [AMD]",
          "name" : "79c970 [PCnet32 LANCE]",
          "subsystemDeviceId" : "2000",
          "deviceType" : null,
          "subsystemVendorId" : "1022",
          "autoSense" : "",
          "model" : "79c970 [PCnet32 LANCE]",
          "revision" : "10",
          "type" : "AuditHardware",
          "hardwareClass" : "NETWORK_CONTROLLER",
          "adapterType" : "",
          "description" : "Ethernet interface"
          },
          {
          "vendorId" : "1022",
          "deviceId" : "2000",
          "maxSpeed" : null,
          "vendor" : "VMware, Inc.",
          "name" : "VMware Accelerated AMD PCNet Adapter",
          "subsystemDeviceId" : "1022",
          "deviceType" : "PCI",
          "subsystemVendorId" : "2000",
          "autoSense" : null,
          "model" : null,
          "revision" : "10",
          "type" : "AuditHardware",
          "hardwareClass" : "NETWORK_CONTROLLER",
          "adapterType" : "Ethernet 802.3",
          "description" : "VMware Accelerated AMD PCNet Adapter"
          },
          {
          "vendorId" : "1022",
          "deviceId" : "2000",
          "maxSpeed" : null,
          "vendor" : "Advanced Micro Devices (AMD)",
          "name" : "Ethernetadapter der AMD-PCNET-Familie",
          "subsystemDeviceId" : "1022",
          "deviceType" : "PCI",
          "subsystemVendorId" : "2000",
          "autoSense" : null,
          "model" : null,
          "revision" : "10",
          "type" : "AuditHardware",
          "hardwareClass" : "NETWORK_CONTROLLER",
          "adapterType" : "Ethernet 802.3",
          "description" : "Ethernetadapter der AMD-PCNET-Familie"
          },
  {
          "vendorId" : "1022",
          "deviceId" : "2000",
          "maxSpeed" : null,
          "vendor" : "Advanced Micro Devices (AMD)",
          "name" : "Ethernetadapter der AMD-PCNET-Familie",
          "subsystemDeviceId" : "1022",
          "deviceType" : "PCI",
          "subsystemVendorId" : "2000",
          "autoSense" : null,
          "model" : null,
          "revision" : "10",
          "type" : "AuditHardware",
          "hardwareClass" : "NETWORK_CONTROLLER",
          "adapterType" : "Ethernet 802.3",
          "description" : "Ethernetadapter der AMD-PCNET-Familie"
          },
          {
          "vendorId" : "1022",
          "deviceId" : "2000",
          "maxSpeed" : null,
          "vendor" : "Advanced Micro Devices (AMD)",
          "name" : null,
          "subsystemDeviceId" : "2000",
          "deviceType" : "PCI",
          "subsystemVendorId" : "1022",
          "autoSense" : null,
          "model" : "",
          "revision" : null,
          "type" : "AuditHardware",
          "hardwareClass" : "NETWORK_CONTROLLER",
          "adapterType" : null,
          "description" : "Ethernetadapter der AMD-PCNET-Familie"
          },
(....)
[

'AuditSoftwareOnClient' (client specific software information)

Describes the detected software types (including the client specific values). The idea is that you will see here the client specific data and in auditSoftware only one entry for a office software which is used in all your computers.

Example of 'AuditSoftwareOnClient' objects:

 method auditSoftwareOnClient_getObjects  [] {"name":"jEdit 4.5.0","clientId":"xpclient.vmnat.local"}
[
          {
          "ident" : "jEdit 4.5.0;4.5.0;;;x86;xpclient.vmnat.local",
          "licenseKey" : "",
          "name" : "jEdit 4.5.0",
          "uninstallString" : "\\\"C:\\\\Programme\\\\jEdit\\\\unins000.exe\\\"",
          "usageFrequency" : -1,
          "clientId" : "xpclient.vmnat.local",
          "lastUsed" : "0000-00-00 00:00:00",
          "subVersion" : "",
          "language" : "",
          "state" : 1,
          "version" : "4.5.0",
          "lastseen" : "2012-03-30 16:19:55",
          "binaryName" : "",
          "type" : "AuditSoftwareOnClient",
          "firstseen" : "2012-03-30 16:19:55",
          "architecture" : "x86"
          }
]

'AuditSoftware' (client independent software information)

Describes the detected software types (independent from the client specific values). The idea is that you will see here only one entry for a office software which is used in all your computers.

Example of 'AuditSoftware' objects:

 method auditSoftware_getObjects  [] {"name":"jEdit 4.5.0"}
[
          {
          "windowsDisplayVersion" : "4.5.0",
          "ident" : "jEdit 4.5.0;4.5.0;;;x64",
          "name" : "jEdit 4.5.0",
          "windowsSoftwareId" : "jedit_is1",
          "windowsDisplayName" : "jEdit 4.5.0",
          "installSize" : -1,
          "subVersion" : "",
          "language" : "",
          "version" : "4.5.0",
          "architecture" : "x64",
          "type" : "AuditSoftware"
          },
          {
          "windowsDisplayVersion" : "4.5.0",
          "ident" : "jEdit 4.5.0;4.5.0;;;x86",
          "name" : "jEdit 4.5.0",
          "windowsSoftwareId" : "jedit_is1",
          "windowsDisplayName" : "jEdit 4.5.0",
          "installSize" : -1,
          "subVersion" : "",
          "language" : "",
          "version" : "4.5.0",
          "architecture" : "x86",
          "type" : "AuditSoftware"
          }
]

'AuditSoftwareToLicensePool' (license management)

Describes which license pools are assingned to which 'AuditSoftware' patterns.

Example of 'AuditSoftwareToLicensePool' objects:

 method auditSoftwareToLicensePool_getObjects [] {"licensePoolId":"win7-msdn-prof"}
[
          {
          "ident" : "Windows 7 Professional N;6.1;00376-165;de-DE;x64;win7-msdn-prof",
          "name" : "Windows 7 Professional N",
          "language" : "de-DE",
          "subVersion" : "00376-165",
          "licensePoolId" : "win7-msdn-prof",
          "version" : "6.1",
          "architecture" : "x64",
          "type" : "AuditSoftwareToLicensePool"
          },
          {
          "ident" : "Windows 7 Professional N;6.1;00376-165;de-DE;x86;win7-msdn-prof",
          "name" : "Windows 7 Professional N",
          "language" : "de-DE",
          "subVersion" : "00376-165",
          "licensePoolId" : "win7-msdn-prof",
          "version" : "6.1",
          "architecture" : "x86",
          "type" : "AuditSoftwareToLicensePool"
          }
]

'SoftwareLicenseToLicensePool' (license management)

Describes which 'softwareLicenseId' is assingned to which 'licensePoolId'.

Example of a 'SoftwareLicenseToLicensePool' object:

method softwareLicenseToLicensePool_getObjects [] {"licensePoolId":"win7-msdn-prof"}
[
          {
          "licensePoolId" : "win7-msdn-prof",
          "softwareLicenseId" : "uib-msdn-win7-vol",
          "ident" : "uib-msdn-win7-vol;win7-msdn-prof",
          "licenseKey" : "12345-12345-12345-12345-3dbv6",
          "type" : "SoftwareLicenseToLicensePool"
          }
]

'SoftwareLicense' (license management)

Describes the existing software licenses and their meta data.

Example of a 'softwareLicense' object:S

 method softwareLicense_getObjects [] {"id":"uib-msdn-win7-vol"}
[
          {
          "ident" : "uib-msdn-win7-vol;msdn-uib",
          "maxInstallations" : 0,
          "boundToHost" : null,
          "expirationDate" : "0000-00-00 00:00:00",
          "licenseContractId" : "msdn-uib",
          "type" : "VolumeSoftwareLicense",
          "id" : "uib-msdn-win7-vol"
          }
]

'LicenseContract' (license management)

Describes the existing licenses contracts and their meta data.

Example of a 'LicenseContract' object:

 method licenseContract_getObjects [] {"id":"msdn-uib"}
[
          {
          "ident" : "msdn-uib",
          "description" : "",
          "conclusionDate" : "2011-04-22 00:00:00",
          "notificationDate" : "0000-00-00 00:00:00",
          "notes" : "",
          "expirationDate" : "0000-00-00 00:00:00",
          "partner" : "Microsoft",
          "type" : "LicenseContract",
          "id" : "msdn-uib"
          }
]

'LicenseOnClient' (license management)

Describes which license is used by which client.

Example of a 'LicenseOnClient' object:

 method licenseOnClient_getObjects  [] {"clientId":"win7client.vmnat.local"}
[
          {
          "softwareLicenseId" : "uib-msdn-win7-vol",
          "ident" : "uib-msdn-win7-vol;win7-msdn-prof;win7client.vmnat.local",
          "licenseKey" : "12345-12345-12345-12345-3dbv6",
          "notes" : "",
          "clientId" : "win7client.vmnat.local",
          "licensePoolId" : "win7-msdn-prof",
          "type" : "LicenseOnClient"
          }
]

'LicensePool' (license management)

Describes the license pool and to which opsi product the license pool is assigned.

Example of a 'LicensePool' object:

 method licensePool_getObjects [] {"id":"win7-msdn-prof"}
[
          {
          "ident" : "win7-msdn-prof",
          "type" : "LicensePool",
          "description" : "MSDN Keys",
          "productIds" :
                    [
                    "win7",
                    "win7-x64"
                    ],
          "id" : "win7-msdn-prof"
          }
]

Special methods

Opsi has some special methods. This chapter will introduce some of the more important ones.

'configState_getClientToDepotserver'

This is in fact also a storage object, but it’s a little aside of the standard. It tells us to which depot a client is currently assigned.

The syntax is

 method configState_getClientToDepotserver *depotIds *clientIds
*masterOnly *productIds

Example:

method configState_getClientToDepotserver [] "pcbon4.uib.local"
[
          {
          "depotId" : "bonifax.uib.local",
          "alternativeDepotIds" :
                    [

                    ],
          "clientId" : "pcbon4.uib.local"
          }
]

Communication with hosts

The 'hostControl' methods are used to communicate and control the clients. Since opsi 4.0.3 we strongly recommend to use the 'hostControlSafe' methods. All 'hostControlSafe' or 'hostControl' Methods have as last parameter the hostIds. The hostIds are the list of clients this method should work on. In all 'hostControlSafe' methods this parameter is not optional, if you want to send a method to all clients you have to give a "*". In the older 'hostControl' methods it is allowed to omit this parameter, which means 'send to all'. This has caused some trouble to people which tried this with methods like 'hostControl_reboot'. So with opsi 4.0.3 we broke the backward compatibility and now an empty hostIds is not any more allowed for the 'hostControl_reboot' and 'hostControl_shutdown' methods.

hostControlSafe_execute
Excute a command on the client.
Connect to the opsiclientd of the given hostIds and tell them to start command.
Parameters: command hostIds
hostControlSafe_fireEvent
Starts a opsiclientd event on the client.
Connect the opsiclientd of the given hostIds and tell them to start the event.
In case the client is currently processing another event which is in a cancelable state, it will cancel this event execution and instead fire the new event. A cancelable state is a state where either no data was changed and no actions were executed, or it is a waiting state of an event which has processActions = False (e.g. sync, sync_completed).

Parameters: event hostIds

hostControlSafe_getActiveSessions
Get information of the logged on users on the client.
Connect the opsiclientd of the given hostIds and ask for the active sessions.
Parameters: hostIds
hostControlSafe_opsiclientdRpc
Run the web service method of the opsiclientd.
Connect the opsiclientd of the given hostIds and tell them to run the web service method using the given parameters. This is the most generic 'hostControlSafe' method, because you may start any possible method. The best way to find out what is possible, is to have a look at control interface https://<clientId>:4441
Parameters: method *params hostIds
hostControlSafe_reachable
Checks if the opsiclientd is reachable.
Connect the opsiclientd of the given hostIds but do not login.
Parameters: hostIds
hostControlSafe_reboot
Reboot the clients.
Connect the opsiclientd of the given hostIds and starts a reboot.
Parameters: hostIds
hostControlSafe_showPopup
Shows a pop up message on the clients.
Connect the opsiclientd of the given hostIds and starts a pop up windows with the message.
Parameters: message hostIds
hostControlSafe_shutdown
Shutdown the clients.
Connect the opsiclientd of the given hostIds and starts a shutdown.
Parameters: hostIds
hostControlSafe_start
Sends a 'wakeOnLan' signal the clients.
This is the only 'hostControlSafe' method that is not use by the opsiclientd from a client.
Parameters: hostIds
hostControlSafe_uptime
Asks for the clients uptime.
Connect the opsiclientd of the given hostIds and get the clients uptime in seconds.
Parameters: hostIds

'log_read' / 'log_write'

log_read
Reads a opsi log file from the server.
Parameters: logType *objectId *maxSize
Possible logTypes are 'instlog' (opsi-winst), 'clientconnect' (opsiclientd), 'userlogin', 'bootimage', 'opsiconfd'. The 'objectId' is normally the 'clientId' to which the log belongs.
log_write
Writes a opsi log file to the server.
Parameters: logType data *objectId *append
Logtypes and objectId see above, append (true/false) (Default = false) should the log be appended to an existing log.

Tutorial: Working with groups

The following tutorial will show how to use the opsi interface from the commandline and work with groups of hosts in opsi.

We want to work with group objects and therefore need to work with those functions whose names start with 'group'. Opsi does distinguish between groups of the type 'ProductGroup' and 'HostGroup'. The first is used for product groupings and the last is used for grouping hosts.

Creating a group of hosts is possible through the method group_createHostGroup. The parameters of the method are 'id', a 'description', 'notes' and the 'parentGroupId' (ID of the parent group). Only the ID is required - everything else is optional. The ID is also the name of the group.

In opsi 4.0 groups are identified by their ID. This ID must be unique throughout the opsi groups.

To create a first group from the commandline we can now issue the following command:

opsi-admin -d method group_createHostGroup rechner_wenselowski "Nikos computer"

To check if our group was created we use group_getObjects.

opsi-admin -d method group_getObjects '' '{"id": "rechner_*", "type": "HostGroup"}'

To create some hierarchy we need to also specify the ID of the parent group.

opsi-admin -d method group_createHostGroup "rechner_wenselowski2" "Undergroup" "" "rechner_wenselowski"

We can use the call to group_getObjects from earlier to see that our group was indeed created.

Opsi has a default group that behaves like a directory service - i.e. OpenLDAP - that means, that a client can only be member of one group. There is a root group with the ID clientdirectory that assumes that exact behavior for any group / client inside. Any client not in a subgroup of clientdirectory will be moved to another special group with the ID NOT_ASSIGNED. Anyone working with that groups is responsible that clients are not member of multiple subgroups of clientdirectory.

Working with the clients is easy now. You probably have noticed that our earlier query to opsi did not show us any signs of clients. That is because the assignment from a client to a group is taken care of another type of object: objectToGroup.

To have a client at hand we will first create one:

opsi-admin -d method host_createOpsiClient "wenselowski-test.uib.local"

This client we now want to add to the group we created previously.

opsi-admin -d method objectToGroup_create "HostGroup" "rechner_wenselowski2" "wenselowski-test.uib.local"

Noticed the HostGroup as the first parameter? That is again our group type. To check if the creation was successful we can execute the following command:

opsi-admin -d method objectToGroup_getObjects '' '{"groupType": "HostGroup", "groupId": "rechner_wenselowski2"}'

If for some reason we want to remove a client we can do this as well. Just execute the following:

opsi-admin -d method objectToGroup_delete "HostGroup" "rechner_wenselowski2" "wenselowski-test.uib.local"

Finally you may want to clean up the groups we created earlier. The following statements will do this for you:

opsi-admin -d method group_delete "rechner_wenselowski"

Action oriented methods

The action oriented methods where introduced in opsi 3. These methods are still available and will still be maintained. Technically methods are mapped to the 'object oriented' methods internally.

Here comes a short list of some methods with a short description. This is meant mainly for orientation and not as a complete reference. The short description does not necessarily provide all information you need to use this method.

method authenticated

Check whether the authentication on the server was successful or not.

method createClient clientName domain

Creates a new client.

method createGroup groupId, members = [], description = ""

Creates a group of clients (as used by the opsi-Configed).

method createLicenseKey productId licenseKey

Assigns an (additional) license key to the product 'productId'.

method createLocalBootProduct productId name productVersion packageVersion licenseRequired=0 setupScript="" uninstallScript="" updateScript="" alwaysScript="" onceScript="" priority=10 description="" advice="" productClassNames=('localBoot')

Creates a new localBoot product (opsi-winst product).

method createNetBootProduct productId name productVersion packageVersion licenseRequired=0 setupScript="" uninstallScript="" updateScript="" alwaysScript="" onceScript="" priority=10 description="" advice="" productClassNames=('netboot')

Creates a new netBoot (boot image) product.

method createProduct productType productId name productVersion packageVersion licenseRequired=0 setupScript="" uninstallScript="" updateScript="" alwaysScript="" onceScript="" priority=10 description="" advice="" productClassNames=""

Creates a new product.

method createProductDependency productId action requiredProductId="" requiredProductClassId="" requiredAction="" requiredInstallationStatus="" requirementType=""

Creates product dependencies.

method createProductPropertyDefinition productId name description=None defaultValue=None possibleValues=[]

Creates product properties.

method deleteClient clientId

Deletes a client.

method deleteGeneralConfig objectId

Deletes a client configuration or domain configuration.

method deleteGroup groupId

Deletes a client group.

method deleteHardwareInformation hostId

Deletes all hardware information for the computer <hostid>.

method deleteLicenseKey productId licenseKey

Deletes a license key for product <productId>.

method deleteProduct productId

Deletes a product from the data base.

method deleteProductDependency productId action requiredProductId="" requiredProductClassId="" requirementType=""

Deletes product dependencies.

method deleteProductPropertyDefinition productId name
method deleteProductPropertyDefinitions productId

Deletes a single property or all properties from the product <productId>.

method deleteServer serverId

Deletes a server configuration

method exit

Quit 'opsi-admin'.

method getBackendInfos_listOfHashes

Supplies information about the available backends of the opsi depot server and which of them are activated.

method getClientIds_list

Supplies a list of clients which meet the assigned criteria.

method getClients_listOfHashes

Supplies an extended list of clients which meet the assigned criteria (with description, notes and 'last seen' for each client).

method getDomain hostId

Supplies the computer domain.

method getGeneralConfig_hash objectId

Supplies the general configuration of a client or a domain.

method getGroupIds_list

Supplies the list of saved client groups.

method auditHardwareOnHost_getObjects '[]' '{"hostId":"<hostId>"}'

Supplies the hardware information of the specified computer.

method getHostId hostname

Supplies the hostid of the specified host name.

method getHost_hash hostId

List of properties of the specified computer.

method getHostname hostId

Supplies the host name of the specified host id.

method getInstallableLocalBootProductIds_list clientId

Supplies a list of all localBoot products that could be installed on the client.

method getInstallableNetBootProductIds_list clientId

Supplies a list of all netBoot products that could be installed on the client.

method getInstallableProductIds_list clientId

Supplies a list of all products that could be installed on the client.

method getInstalledLocalBootProductIds_list hostId

Supplies a list of all localBoot products that are installed on the client.

method getInstalledNetBootProductIds_list hostId

Supplies a list of the installed netBoot products of a client or server.

method getInstalledProductIds_list hostId

Supplies a list of the installed products for a client or server.

method getIpAddress hostId

Supplies the IP address of a host.

method getLicenseKey productId, clientId

Supplies an available license key of the specified product or the product license key which is assigned to the client.

method getLicenseKeys_listOfHashes productId

Supplies a list of all license keys for the specified product.

method getLocalBootProductIds_list

Supplies a list of all known localBoot products.

method getLocalBootProductStates_hash clientIds = []

Supplies for all clients the installation status and action request of all localBoot products.

method getMacAddresses_list hostId

Supplies the MAC address of the specified computer.

method getNetBootProductIds_list

Supplies a list of all NetBoot products.

method getNetBootProductStates_hash clientIds = []

Supplies for all clients the installation status and action request of all netBoot products.

method getNetworkConfig_hash objectId

Supplies the network specific configurations of a client or a domain.

method getOpsiHostKey hostId

Supplies the pckey of the specified hostid.

method getPcpatchPassword hostId

Supplies the password of 'pcpatch' (encrypted with the 'pckey' of 'hostId').

method getPossibleMethods_listOfHashes

Supplies the list of callable methods (approximately like in this chapter).

method getPossibleProductActionRequests_list

Lists the available action requests of opsi.

method getPossibleProductActions_hash

Supplies the available actions for each product ('setup', 'uninstall' , ….).

method getPossibleProductActions_list productId=softprod

Supplies the list of all actions ('setup', 'uninstall',….).

method getPossibleProductInstallationStatus_list

Supplies the list of all installation states ('installed', 'not_installed',… )

method getPossibleRequirementTypes_list

Supplies the list of types of product requirement ('before', 'after', … )

method getProductActionRequests_listOfHashes clientId

Supplies the list of upcoming actions of the specified client.

method getProductDependencies_listOfHashes

Supplies the list of product dependencies of all or the specified product.

method getProductIds_list

Supplies a list of products which meet the specified criteria.

method getProductInstallationStatus_hash productId hostId

Supplies the installation status for the specified client and product.

method getProductInstallationStatus_listOfHashes hostId

Supplies the installation status of the specified client.

method getProductProperties_hash productId

Supplies the product properties of the specified product and client.

method getProductPropertyDefinitions_hash

Supplies all known product properties with description, allowed values,…

method getProductPropertyDefinitions_listOfHashes productId

Supplies the product properties of the specified product with description, allowed values,… .

method getProductStates_hash clientIds = []

Supplies installation status and action requests of all products (for the specified clients).

method getProduct_hash productId

Supplies the meta data (description, version, …) of the product

method getProvidedLocalBootProductIds_list serverId

Supplies a list of available localBoot products on the specified server.

method getProvidedNetBootProductIds_list serverId

Supplies a list of available netBoot products on the specified server.

method getServerId clientId

Supplies the opsi-configserver in charge of the specified client.

method getServerIds_list

Supplies a list of the known opsi-configserver.

method powerOnHost mac

Send a WakeOnLan signal to the specified MAC address.

method setGeneralConfig config

Set for client or domain the generalConfig

method setHostDescription hostId

Set a description for a client.

method setHostLastSeen hostId timestamp

Set the 'last seen' time stamp of a client.

method setHostNotes hostId notes

Set the notes for a client.

method setMacAddresses hostId macs

Set the client MAC address in the data base.

method setOpsiHostKey hostId opsiHostKey

Set the 'pckey' for a computer.

method setPcpatchPassword hostId password

Set the encrypted (!) 'password' for 'hostId'

method setProductActionRequest productId clientId actionRequest

Set an action request for the specified client and product.

method setProductInstallationStatus productId hostId installationStatus policyId="" licenseKey=""

Set an installation status for the specified client and product.

method setProductProperties productId properties

Set the product properties for the specified product (and the specified client).

method unsetProductActionRequest productId clientId

Set the Action-Request to 'none'.

Backend extensions

opsi 4 brings the feature of a backend extender that allows to extend to core functionality through additional methods that will be served as an extension to the API.

The set of standard API methods will be created through 'opsiconfd' by overlaying the in the .conf-files in '/etc/opsi/backendManager/extend.d' defined methods.

Backend extensions can be used to implement specific tasks for additional features.

These extensions have to be written as Python code. Extensions are loaded "on to" an BackendManager-instance and can reference it with self.

Accessing the API

The API uses JSON-RPC 1.0 over HTTP for communication. We use basic authentication.

To use this interface POST your calls to the path rpc of your opsi server, i.e. https://opsiserver.domain.tld:4447/rpc.