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

UI

Das ui-Modul stellt eine Konsolen-Schnittstelle zu opus bereit. Es nutzt das click-Paket, um die auf der Befehlszeile übergebenen Parameter auszuwerten.