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 togetObjects
, this operation delivers unchecked raw data directly from the backend. It is more efficient thangetObjects
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 thereturnType
parameter, with possible values beingunicode
,list
, andhash
. -
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 valuenull
) are set tonull
in the backend. -
updateObject
: Updates an object. Attributes not provided (or provided with the valuenull
) 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 theinsertObject
operation. -
updateObjects
: This function accepts either a single object or a list of objects. Each object is internally routed toinsertObject
if it doesn’t exist yet, or toupdateObject
if it does. -
create
: Creates a new object and accepts all possible attributes as individual parameters. This function internally usescreateObjects
, 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 anOpsiDepotserver
)
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 commandcommand
on the clients.
Parameters:command
,hostIds
-
hostControlSafe_fireEvent
Executes anopsiclientd
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 setprocessActions = 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 theopsiclientd
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 areinstlog
(opsi-script
logs),clientconnect
(opsiclientd
logs),userlogin
,bootimage
, andopsiconfd
.
TheclientId
of a client is specified as theobjectId
parameter. -
log_write
Writes a logfile on the server.
Parameters:logType
,data
,objectId
,append
Logfile types andobjectId
are the same as described underlog_read
.
Theappend
(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