JSON-RPC API

The core opsi API uses JSON-RPC (JavaScript Object Notation Remote Procedure Call) as its foundation.

This API includes a comprehensive interface description, detailing all RPC methods. You can access this interface description using the RPC method backend_getInterface.

Additionally, this list of methods is available on the opsiconfd Admin Page, specifically on the RPC interface tab.

The JSON-RPC-API operates on the principle of objects, each having a set of attributes.

For example, consider an object of the type Product, which represents an opsi product:

"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 in the system, there is a series of operations typically available, which are as follows:

getObjects: This function returns a list of objects that conform to a specified filter. If a list of attributes is provided, only these attributes are populated from the backend.
getHashes: Similar to getObjects, this operation delivers unchecked raw data directly from the backend. It is more efficient than getObjects but should be used cautiously.
getIdents: This returns a list of object IDs matching the specified filter. The format of the elements in the result can be selected through the returnType parameter, with possible values being unicode, list, and hash.
insertObject: This operation creates a new object. If the object already exists, it is entirely overwritten with the new values. Attributes not provided (or provided with the value null) are set to null in the backend.
updateObject: Updates an object. Attributes not provided (or provided with the value null) are not altered in the backend. If the object does not exist, no change is made, and no new object is created.
createObjects: Either a single object or a list of objects can be passed. Each object is internally handled by the insertObject operation.
updateObjects: This function accepts either a single object or a list of objects. Each object is internally routed to insertObject if it doesn’t exist yet, or to updateObject if it does.
create: Creates a new object and accepts all possible attributes as individual parameters. This function internally uses createObjects, which means existing objects are completely overwritten.
deleteObjects: Deletes a list of objects. Here, a list must be provided. Only the attributes that identify the object (type/id/ident) are used to select the objects for deletion.
delete: Removes the object identified by the specified parameters.

For updating an object, it is usually preferable to use the relevant method. For instance, the state of a package on a client can be updated using productOnClient_updateObjects. This approach is effective regardless of whether the object already exists.

The naming convention for these methods is structured as follows:

<object_type>_<operation>

The getObjects methods include two optional parameters:

attributes
filter

The attributes parameter is useful when you need to query only specific attributes of an object, which can lead to performance benefits. If a list of attributes is provided, only these are retrieved from the backend. The other attributes will be returned with their default values. However, attributes that are crucial for identifying the object (//) are always filled.

For instance, consider the method product_getObjects, parameterized with attributes: ["name"] for the 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

The filter parameter is designed to narrow down the list of objects based on specific criteria. For example, in the method product_getObjects, using the filter {"id": "javavm"} limits the results to only the object with the ID javavm. When multiple filter attributes are provided, they are combined in the query. If a list of values is passed for an attribute, it is interpreted as - link. You can also use the asterisk (*) as a wildcard character for string values. If you do not wish to apply any filters (which is the default behavior), you can either pass null or an empty object {} as the filter parameter.

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 methods where one or more objects are to be passed, this should be done using a JSON object or a list of JSON objects.

The most important objects include:

auditHardwareOnHost: Contains client-specific hardware information.
auditHardware: Holds client-independent hardware information.
auditSoftwareOnClient: Encompasses client-specific software information.
auditSoftware: Covers client-independent software information.
auditSoftwareToLicensePool: Used for license management.
configState: Manages additional configurations.
config: Manages new typed additional configurations.
group: Used for group management.
host: Pertains to servers and clients.
LicenseContract: Involved in license management.
licenseOnClient: Part of license management.
licensePool: Also used for license management.
objectToGroup: Used for group management.
productDependency: Manages product dependencies.
productOnClient: Provides information about a product in relation to a client.
productOnDepot: Contains information about a product in relation to a depot.
productPropertyState: Manages depot and client-related product property values.
productProperty: Defines the properties of a product.
product: Contains product metadata.
SoftwareLicenseToLicensePool: Involved in license management.
softwareLicense: Part of license management.

Additionally, there are several other objects with special operations that do not conform to this object schema, for example:

backend_getLicensingInfo
network_sendBroadcast
accessControl_userIsAdmin

There are also methods that lack the <object_type> prefix. Typically, these are older methods retained for the purpose of maintaining backward compatibility.

Host (Server and Clients)

Example for an opsi client:

 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 accessible on the Clients tab in opsi-configed.

OpsiClient
OpsiDepotserver
OpsiConfigserver (which also functions as an OpsiDepotserver)

OpsiDepotserver and OpsiConfigserver have more attributes than an OpsiClient.

Example of a OpsiConfigserver:

 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 accessible via the depot configuration in opsi-configed.

Group

Describes groups and their hierarchical structure, i.e. is used for group management. 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

Describes the membership of objects in groups, i.e. is used to manage group memberships.

Example 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

Describes a product’s metadata as it was defined when the product was created.

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 there are several depot servers in the opsi environment, different versions of a product may appear here.

The attributes productClassIds and windowsSoftwareIds are not used at the moment.

ProductProperty

Describes a product’s properties as they were defined when the package was created.

Example of a ProductProperty object:

 method productProperty_getObjects [] {"productId":"jedit","productVersion":"4.5"}
[
          {
          "ident" : "jedit;4.5;3;start_server",
          "description" : "Should the jedit derver 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 default values used for a client are not stored here, but are instead stored in productPropertyState objects on a depot-specific basis.

ProductPropertyState

Describes

the default values of a ProductProperty object on a depot
the client-specific settings of a ProductProperty object

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

Describes dependencies between packages as defined when the package was created.

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

Describes which products are installed in which versions 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

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

Example for 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 there are several depot servers in the opsi environment, different versions of a product may appear here.

Config

Describes the available configurations, i.e. manages the default values of the 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

Manages the client-specific configurations.

Example of a 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 cannot be created without the Config object that references it.

AuditHardwareOnHost

Describes the detected hardware including the client-specific data. AuditHardwareOnHost objects contain the hardware-specific and client-specific attributes, AuditHardware objects only contain hardware-specific attributes.

The attribute state no longer has any meaning.

Examples 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

Describes the detected hardware information without the client-specific data.

Examples 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

Describes the detected software information including the client-specific data.

Examples 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

Describes the detected software information without the client-specific data.

Example for 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

Describes the assignment of patterns from the software inventory (AuditSoftware) to individual license pools.

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

Describes the assignment of softwareLicenseIds to licensePoolIds.

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

Describes the existing software licenses and their metadata.

Example of a SoftwareLicense object:

 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

Describes the existing license contracts and their metadata.

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

Describes which client is using which license.

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

Describes a license pool and its assignment to products.

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"
          }
]

Example: Changing a Key in several Objects

This section explains how to modify an object. The host object is used as an example, which is restricted to the OpsiDepotserver type via the selection:

 method host_getObjects '[]' {"type":"OpsiDepotserver"}
[
          {
          "masterDepotId" : null,
          "ident" : "configserver.vmnat.local",
          "networkAddress" : "172.16.166.0/255.255.255.128",
          "description" : "",
          "inventoryNumber" : "",
          "ipAddress" : "172.16.166.1",
          "repositoryRemoteUrl" : "webdavs://configserver.vmnat.local:4447/repository",
          "depotLocalUrl" : "file:///var/lib/opsi/depot",
          "isMasterDepot" : true,
          "notes" : "",
          "hardwareAddress" : null,
          "maxBandwidth" : 0,
          "repositoryLocalUrl" : "file:///var/lib/opsi/repository",
          "opsiHostKey" : "17835c8d52170dcd06ba3c5089a74815",
          "type" : "OpsiConfigserver",
          "id" : "configserver.vmnat.local",
          "depotWebdavUrl" : "webdavs://configserver.vmnat.local:4447/depot",
          "depotRemoteUrl" : "smb://configserver/opsi_depot"
          },
          {
          "masterDepotId" : null,
          "ident" : "depotserver.vmnat.local",
          "networkAddress" : "172.16.166.128/25",
          "description" : "Depot Server",
          "inventoryNumber" : "",
          "ipAddress" : "172.16.166.150",
          "repositoryRemoteUrl" : "webdavs://depotserver.vmnat.local:4447/repository",
          "depotLocalUrl" : "file:///var/lib/opsi/depot",
          "isMasterDepot" : true,
          "notes" : "",
          "hardwareAddress" : "00:0c:29:7d:eb:55",
          "maxBandwidth" : 0,
          "repositoryLocalUrl" : "file:///var/lib/opsi/repository",
          "opsiHostKey" : "8284d506278667cb25cc2f9f992a024d",
          "type" : "OpsiDepotserver",
          "id" : "depotserver.vmnat.local",
          "depotWebdavUrl" : "webdavs://depotserver.vmnat.local:4447/depot",
          "depotRemoteUrl" : "smb://depotserver/opsi_depot"
          }
]

To change the values for the maxBandwidth key, this call would generate a file in which the maximum bandwidth on all depot servers is changed from 0 to 100. The file can also be changed manually.

opsi-admin -d method host_getObjects '[]' '{"type":"OpsiDepotserver"}' | sed  -e 's/"maxBandwidth"\s:\s0/"maxBandwidth" : 100/' > /tmp/maxBand.json

Use this command to apply the changed configuration to the opsi backend:

opsi-admin -d method host_createObjects < /tmp/maxBand.json

Special Methods

There are a number of special methods. Some of these are presented below.

configState_getClientToDepotserver

This method provides information about which depot a client is assigned to.

Example:

method configState_getClientToDepotserver [] "client1.company.internal"
[
          {
          "depotId" : "opsi.company.internal",
          "alternativeDepotIds" :
                    [

                    ],
          "clientId" : "client1.company.internal"
          }
]

Communicating with Hosts

The hostControl methods are used to communicate with and control the clients. In addition, there are hostControlSafe methods. Both variants have a parameter called hostIds. This is optional for hostControl. If the parameter is not specified, the actions are carried out on all clients. With hostControlSafe, the parameter is mandatory. If all clients are to be addressed, an asterisk (*) must be specified here.

Since opsi 4.3 the hostControl methods are preferably executed via the opsi message bus.

hostControlSafe_execute
Executes the command command on the clients.
Parameters: command, hostIds
hostControlSafe_fireEvent
Executes an opsiclientd event on the clients. If another event is currently in an interruptible phase, this is interrupted and the new event is started instead. A phase is interruptible if an event has either not yet changed any data or executed any actions or if it is a waiting phase for an event that has set processActions = False (e.g. sync, sync_completed).
Parameters: event, hostIds
hostControlSafe_getActiveSessions
Determines the user sessions that are active on the clients.
Parameter: hostIds
hostControlSafe_opsiclientdRpc
Executes the method (method) with the given parameters (params) on the opsiclientd service.
This is a generic method, as all methods can be executed via it.
The easiest way to determine the available methods is to connect to the control interface of the client (https://<client-address>:4441).
Parameters: method, params, hostIds
hostControlSafe_reachable
Checks if the opsi client is reachable. Since opsi 4.3, a client is considered connected if it is connected to the opsi message bus.
Parameter: hostIds
hostControlSafe_reboot
Reboots the clients.
Parameter: hostIds
hostControlSafe_showPopup
Shows a message in a pop-up window on the clients.
Parameter: message hostIds
hostControlSafe_shutdown
Shuts down the clients.
Parameter: hostIds
hostControlSafe_start
Sends a Wake-On-LAN signal to the MAC addresses of the clients.
Parameter: hostIds
hostControlSafe_uptime
Determines the clients' uptime in seconds.
Parameter: hostIds

Logfiles

The following methods for logfiles are available.

log_read
Reads an opsi log from the server.
Parameters: logType, objectId, maxSize
Possible logfile types are instlog (opsi-script logs), clientconnect (opsiclientd logs), userlogin, bootimage, and opsiconfd.
The clientId of a client is specified as the objectId parameter.
log_write
Writes a logfile on the server.
Parameters: logType, data, objectId, append
Logfile types and objectId are the same as described under log_read.
The append (Boolean) is used to control whether the new content is appended to any existing logfile.

Tutorial: Working with Groups

The methods' names start with group_, i.e. they work on groups. There are two types of groups: host groups (type = HostGroup) and product groups (type = ProductGroup).

Host groups can also be created using the group_createHostGroup method. The parameters are id, description (description), notes (notes), and parentGroupId (ID of the parent group). The id must be specified; it must be unique.

Groups are identified by their ID. This ID must be unique across all groups.

Example for creating a group:

opsi-admin -d method group_createHostGroup "windows-clients" "Windows clients"

Groups can be read via group_getObjects. Here is an example of reading the group that has just been created:

opsi-admin -d method group_getObjects [] '{"id": "windows-clients", "type": "HostGroup"}'

If you want to create subgroups, you must enter the ID of the parent group as parentGroupId. Here is an example of a subgroup for the group you have just created:

opsi-admin -d method group_createHostGroup "win10-clients" "Windows 10 clients" "" "windows-clients"

If you want to work with the directory, it is treated internally as a group with the ID clientdirectory. Clients may only ever be in one group in the directory. By default, they are assigned to the group with the ID NOT_ASSIGNED. If you use opsi in a different language, the name of the group may differ.

Administrators must make sure that the clients are always in only one group if they are to be in the directory. The backend does not intervene at this point.

Clients are assigned to the group via ObjectToGroup objects. To create a client, enter the following command:

opsi-admin -d method host_createOpsiClient "client1.company.internal"

Now add the new client to the subgroup you have just created:

opsi-admin -d method objectToGroup_create "HostGroup" "win10-clients" "client1.company.internal"

To check the result, query the assignment:

opsi-admin -d method objectToGroup_getObjects [] '{"groupType": "HostGroup", "groupId": "win10-clients"}'

To delete the client from the group, enter this:

opsi-admin -d method objectToGroup_delete "HostGroup" "win10-clients" "client1.company.internal"

You can also delete the group:

opsi-admin -d method group_delete "win10-clients"

Extending the API Methods

If required, you can define additional methods. To do this, create files in Python format; these have the extension .conf and are located in the directory /etc/opsi/backendManager/extend.d. All other API methods can be used in the custom method via the self object.

Example:

@rpc_method
def custom_create_client(self, name):
	client_id = f"{name}.company.internal"
	self.host_createOpsiClient(id=client_id, description="Created by custom method")
	return self.host_getObjects(id=client_id)[0]

Accessing the API

The API is based on JSON-RPC via HTTPS. The JSON-RPC requests are sent via POST to the endpoint /rpc (https://<server-address>:4447/rpc) of the opsi config server. Authentication usually takes place via basic authentication.

A curl example:

curl -k -X POST \
	-u "adminuser:secret" \
	-H 'Content-Type: application/json' \
	-d '{"jsonrpc":"2.0","id":"1","method":"host_getObjects","params":[[], {"type":"OpsiClient"}]}' \
	https://opsi.domain.internal:4447/rpc