Design

Die Architektur entspricht der klassischen Schicht-Architektur, wie sie viele andere Anwendungen auch zeigen. Zuunterst liegt die Datenbasis in Form des opsi-Servers, darauf eine vergleichsweise dünne Abstraktionsschicht, die die die…

Server

Das server-Modul kapselt die Kommunikation mit opsi-Servern.

Die Kommunikation über das JSON-RPC-Backend übernimmt die Klasse opus.server.Server, sie agiert quasi als DB-Schicht.

class opus.server.Server(url: str, username: str, password: str)

Server-Verbindung.

Eine Server-Instanz hält die Zugangsdaten für einen JSONRPC-Aufruf, öffnet allerdings keine Verbindung. Dies erfolgt in den jeweiligen Methoden, die eine Payload vorbereiten und an __rpc_request übergeben.

server = Server(url, username, password)
client_ids = server.clients()

addClientToGroup(client_id, group_id)

add a client to a group

Parameter:

• client_id (str) – client id

• group_id (str) – group id

Rückgabe:

JSONRPC result

clientGroupMembers(group_id)

return a list with clients in a group

Parameter:

group_id (str) – group id

Rückgabe:

list of ObjectToGroup instances (these a Client instances)

Relevant attributes:

• objectId: id of the Client instance

clientGroups(group_id='')

return a list of client groups

Parameter:

group_id (str) – group id

Rückgabe:

list of HostGroup instances

Relevant attributes/methods:

• id: id of the group; index 0 is the main clientdirectory

• description: group description

clients()

return a list with all client ids

Rückgabe:

list with opsi client infos

fireEvent(client_ids, event='on_demand')

fire the given event for given clients

Parameter:

• client_ids (list) – list with client ids

• event (str) – event (default: on_demand); values are: panic, software_on_demand, sync_completed, on_shutdown, silent_install, gui_startup

Rückgabe:

JSONRPC result

installProductOnClient(client_id, product_id)

install a product on a client

Parameter:

• client_id (str) – client id

• product_id (str) – product id

Rückgabe:

JSONRPC result

productGroupMembers(group_id='')

return a list with products of a group

Parameter:

group_id (str) – product group name

Rückgabe:

list with product ids

productGroups()

return a list of known product groups

Rückgabe:

list with ProductGroup instances

products()

return a list of all available products

Rückgabe:

list of LocalbootProduct products

productsOnClient(client_id='')

return a list with all products installed on client(s)

Parameter:

client_id (str) – client id; leave empty for all clients

Rückgabe:

list with ProductOnClient instances

Helpful attributes:

• productId: product id, needed for installProductOnClient

• version: product version with packet version

• productVersion: product version alone

productsOnDepot()

list with available products

Rückgabe:

list with available products in depot

reboot(client_ids)

reboot clients

Parameter:

client_ids (list) – list with client ids

Rückgabe:

JSONRPC result

setProductOnClientStatus(client_id, product_id, status='installed')

set the product status on a client; default: installed

Parameter:

• client_id (str) – client id

• product_id (str) – product id

• status (str) – status to set

Rückgabe:

JSONRPC result

shutdown(client_ids)

shutdown clients

Parameter:

client_ids – list with client ids

Rückgabe:

JSONRPC result

softwareOnClient(client_id)

get all installed products on given client

Parameter:

client_id (str) – client id

Rückgabe:

JSONRPC result

uninstallProductOnClient(client_id, product_id)

remove a product from a client

Parameter:

• client_id (str) – client id

• product_id (str) – product id

Rückgabe:

JSONRPC result

Backend

Das backend-Modul definiert mit der Klasse Backend die grundlegenden Methoden für die Anwendung, ist dabei aber eine vergleichsweise dünne Abstraktionsschicht, die sich die Funktionalität von opus.server.Server zunutze macht.

class opus.backend.Backend(url, username, password)

Die Backend-Klasse hält die Verbindungsdaten zum Server vor und stellt die grundlegenden Methoden für die Arbeit mit opsi-Clients bereit.

Anwendungsbeispiel:

backend = Backend(url, username, password)

# known clients
clients = backend.clients
# installed products on client 'x'
products_on_client_x = client["x"].products

addClientsToGroup(client_ids, group_id)

add client(s) to the given group

Parameter:

• client_ids (list) – client ids

• group_id (str) – group id

clientGroupMembers(group_id)

get members of the given client group

Parameter:

group_id (str) – group id

Rückgabe:

list with client ids

clientGroups(group_id='')

get client groups

Parameter:

group_id (str) – group id

Rückgabe:

dictionary with (group) id and description

property clients

get clients

Rückgabe:

dictionary with client id:data; data is a dictionary with products:[(productId, productVersion, packageVersion, installationStatus, lastAction, actionResult)]

install(client_id, product_id)

install product on client

Parameter:

• client_id (str) – client id

• product_id (str) – product id

ondemand(client_ids)

trigger ondemand event on client(s)

Parameter:

client_ids (list) – list with client ids

productGroupMembers(group_id)

get list of members of the given product group

Parameter:

group_id (str) – group id

Rückgabe:

list of group member ids

productGroups()

get list of known product groups

Rückgabe:

dictionary with product group ids and descriptions

property products

get available products

Rückgabe:

list of products (dictionaries)

reboot(client_ids)

reboot client(s)

Parameter:

client_ids (list) – list with client ids

setInstalled(client_id, product_id)

install product on client

Parameter:

• client_id (str) – client id

• product_id (str) – product id

setSetup(client_id, product_id)

set product on client to setup

Parameter:

• client_id (str) – client id

• product_id (str) – product id

setUninstalled(client_id, product_id)

set product status to ‚uninstalled on client(s)install product on client

Parameter:

• client_id (str) – client id

• product_id (str) – product id

shutdown(client_ids)

shutdown clienti(s)

Parameter:

client_ids (list) – list with client ids

softwareOnClient(client)

get list of installed software (not only by opsi, but all software) on a client.

Warning: This requires a run swaudit beforehand!

Parameter:

client (str) – client id

Rückgabe:

list with dicts

uninstall(client_id, product_id)

remove product from client

Parameter:

• client_id (str) – client id

• product_id (str) – product id

App

Das app-Modul mit der Klasse Opus ist der Kern von opus.

class opus.app.Opus(url, username, password)

Die Klasse Opus stellt die API für alle Frontends von opus bereit.

Beispiel:

app = Opus(url, username, password)

# get a list of all known clients (instances of Client)
clients = app.clients()
# get a list of all installable products
products = app.products()

addClientsToGroup(client_ids, group_id)

Add Client to a group.

Parameter:

• client_ids (list) – list with client ids

• group_id (str) – group id

clientGroupMembers(group_id)

Get all members of a client group.

Parameter:

group_id (str) – group id

Rückgabe:

list with client ids

clientGroups(group_id='')

Get all client group names.

Rückgabe:

dictionary with group ids and descriptions

clients()

Get all clients.

Rückgabe:

dictionary with client id:data; data is a dictionary with products:[(productId, productVersion, packageVersion, installationStatus, lastAction, actionResult)]

evaluate_targets(target_string)

Filter clients with given string and return the resulting list. der Liste der bekannten Clients.

Parameter:

target_string (str) – filter string

Rückgabe:

list with clients (dictionaries)

failedClients(client_ids)

Get list of failed clients.

A failed client is a client with a failed un-/install action.

Parameter:

client_ids (list) – client ids

Rückgabe:

dictionary with client id:[failed products]

install(clients, packages, force, now)

Install given package(s) on client(s).

Installation will be done if:

• package is not installed

• older version of the package installed

Parameter:

• clients (dict) – client dict with name:data

• packages (list) – list with package ids

• force (bool) – force installation even if package is installed

• now (bool) – trigger ondemand to install immediately

install_updates_on_depot_(ssh_cmd)

Installiert für das Depot verfügbare Paket-Updates

is_failed(product_tuple)

Get a list with failed products on a client.

Parameter:

product_tuple (tuple) – product data as a tupel

Rückgabe:

True if failed, False otherwise

is_fresh(client_json)

Check if client is a fresh installed machine.

Parameter:

client_json (dict) – client data (dict)

Rückgabe:

True if fresh, False otherwise

list_migratable(client, json)

Get a list of installed software with available opsi packages for a given client.

Parameter:

• client (string) – client id

• json (dict) – client json data

Rückgabe:

not installed available packages in depot, missing packages

migrate(clients, masked_pkgs)

Mark software that has an opsi package as ‚installed‘.

Parameter:

clients (list) – list of client ids

ondemand(clients)

Trigger ondemand event on clients.

Parameter:

clients (dict) – client dict with name

os_version(client)

Get OS version info for a given client.

This requires a software audit beforehand.

Parameter:

client – client id

Rückgabe:

string with version info or None

productGroupMembers(group_id)

Get a list of products of a product group

Parameter:

group_id (str) – group id

Rückgabe:

list with product ids and version

productGroups()

Get a list with known product groups.

Rückgabe:

dictionary with product group ids and description

products()

Get a list all available products in the depot.

Example for product data:

product_data = {
    'name': 'Microsoft Visual C++ 2017', 'licenseRequired': False,
    'setupScript': 'setup3264.opsiscript', 'uninstallScript': '',
    'updateScript': '', 'alwaysScript': '', 'onceScript': '',
    'customScript': '', 'userLoginScript': '', 'priority': 0,
    'description': 'Microsoft Visual C++ 2017 redistributable',
    'advice': '', 'changelog': '', 'productClassIds': [],
    'windowsSoftwareIds': [], 'id': 'visualcpp-2017',
    'productVersion': '14.12.25810.0', 'packageVersion': '1',
    'type': 'LocalbootProduct',
    'ident': 'visualcpp-2017;14.12.25810.0;1'
    }

Rückgabe:

dictionary with product id: product data

reboot(clients)

Reboot clients.

Parameter:

clients (dict) – client dict with name

set_installed(clients, packages, installed=True)

Set packages to ‚installed‘ state on given clients.

Parameter:

• clients (list) – client ids

• packages (list) – package ids

set_setup(clients, packages)

Set packages to ‚setup‘ state on given clients.

Parameter:

• clients (list) – client ids

• packages (list) – package ids

shutdown(targets)

Shutdown clients.

Parameter:

clients (dict) – client dict with name

uninstall(clients, packages, now)

Remove package(s) from client(s).

Deinstallation only takes place if the package is installed.

Parameter:

• clients (dict) – clients with name:data

• packages (list) – list with package ids

• now (bool) – trigger ondemand to uninstall immediately

unpackaged(client, json)

Get a list of installed, but unpackaged software on a client.

This is a somewhat manual approach as it requires a custom list of software names (‚_mapping‘). Helpful for migration into opsi.

Parameter:

• client (str) – client id

• json (dict) – client json data

Rückgabe:

dictionary with name:list of unpackaged software

updatable(product_triple, products_in_depot)

Check if a product can be updated.

Parameter:

product_triple (tuple) – triple of product data

Rückgabe:

new version (package version incl.) if available, otherwise False

update(clients, packages, now)

Update package(s) on client(s).

Warning: windomain can break AD joins, if Rejoin is forbidden!

Parameter:

• clients (dict) – dict with name:data

• packages (list) – list with package names. If this is empty, then all possible updates will be installed.

• now (bool) – trigger ondemand on clients

updates_(ssh_cmd)

Listet für das Depot verfügbare Paket-Updates auf