The Hub XMLRPC API helps to operate SUSE Manager or Uyuni infrastructures with one Server, called a Hub, managing several Servers. The typical architecture is represented below:
Servers are registered and can be managed from the Hub just like normal SUSE Manager or Uyuni clients. In addition to that, the Hub XMLRPC API provides a more convenient way to access all Servers' XMLRPC APIs from one only endpoint in the Hub.
- one central SUSE Manager/Uyuni Server (hereinafter: "Hub")
- two or more peripheral Servers registered to the Hub as Salt clients
- any number of end clients registered to peripheral Servers
- a host that can connect to all the peripheral Server's XMLRPC APIs (it can be the Hub itself)
- credentials to all Server XMLRPC APIs, including the Hub's
Install the package hub-xmlrpc-api, available from SUSE Manager 4.1 and Uyuni repos, either on the Hub itself or on a host that has access to all Servers' XMLRPC APIs.
If you are installing hub-xmlrpc-api on the Hub then no further configuration is necessary. The daemon can be started via systemd as a hub-xmlrpc-api.service file is provided by the package.
If you are installing hub-xmlrpc-api on a separate host then you should make sure that the URL to the Hub XMLRPC API is correctly configured in the /etc/hub/hub.conf file.
/etc/hub/hub.conf contains the following configuration parameters:
HUB_API_URL: URL to the Hub XMLRPC API endpointHUB_CONNECT_TIMEOUT: maximum number of seconds to wait for a response when connecting to a ServerHUB_REQUEST_TIMEOUT: maximum number of seconds to wait for a response when calling a Server methodHUB_CONNECT_USING_SSL: use https instead of plain http for communicating with peripheral Servers
Default values should suffice in most settings.
In order to use https to connect to peripheral Servers, in addition to setting HUB_CONNECT_USING_SSL flag to true, SSL certificates for all the peripheral Servers need to be installed on the machine where the hub-xmlrpc-api service runs. This can be achieved by copying the RHN-ORG-TRUSTED-SSL-CERT certificate file from each peripheral Server's pub directory (http://<server-url>/pub/) to /etc/pki/trust/anchors/ and then running the update-ca-certificates command.
Once the hub-xmlrpc-api service is running, you can connect to it at port 2830 via any XMLRPC compliant client library (see examples below).
The Hub API supports 3 different namespaces.
hub→ to target the Hub itself:- example:
hubSessionKey = client.hub.login(username, password)
- example:
unicast→ to target a single Server registered in the Hub:- example:
systems = client.unicast.system.list_systems(hubSessionKey, serverID)
- example:
multicast→ to target multiple Servers- example:
systemsPerServer = client.multicast.system.listUserSystems(hubSessionKey, [serverID_1, serverID_2], [], [])
- example:
Note that:
- all XMLRPC API methods available in a single Server are exposed by the namespaces above. Generally speaking, they accept the same parameters and return the same values with the exceptions described below
- the
hubSessionKeycan be obtained via theclient.hub.login(username, password)method - individual Server IDs can be obtained via
client.hub.listServerIds(hubSessionKey)(see example below) - the
unicastnamespace assumes all methods receivehubSessionKeyandserverIDas their first two parameters, then any other parameter as specified by the regular Server API - the
multicastnamespace assumes all methods receivehubSessionKey, a list of Server IDs, then lists of per-Server parameters as specified by the regular Server API. Return value will be an array, indexed per Server, of the results of individual Server calls
Hub supports 3 different authentication modes.
- manual mode (default): user needs to provide API credentials for each Server explicitly
- relay mode: the same credentials used to authenticate against the Hub will be re-used to authenticate Servers. The list of Servers to connect to will still be provided by the user
- auto connect mode: Hub credentials will be reused for Servers and any Server the user has access to will be automatically connected
#!/usr/bin/python
import xmlrpclib
import itertools
HUB_URL = "http://localhost:2830/hub/rpc/api"
HUB_LOGIN = "admin"
HUB_PASSWORD = "admin"
client = xmlrpclib.Server(HUB_URL, verbose=0)
# Login (uncomment only one line)
#hubSessionKey = client.hub.login(HUB_LOGIN, HUB_PASSWORD)
#hubSessionKey = client.hub.loginWithAuthRelayMode(HUB_LOGIN, HUB_PASSWORD)
#hubSessionKey = client.hub.loginWithAutoconnectMode(HUB_LOGIN, HUB_PASSWORD)
# get list of Server IDs registered to the Hub
serverIDs = client.hub.listServerIds(hubSessionKey)
# Manual authentication mode example. Uncomment if `client.hub.login` was uncommented above
#usernames = ["admin" for s in serverIDs]
#passwords = ["admin" for s in serverIDs]
#client.hub.attachToServers(hubSessionKey, serverIDs, usernames, passwords)
# Relay authentication mode example. Uncomment if `client.hub.loginWithAuthRelayMode` was uncommented above
#client.hub.attachToServers(hubSessionKey, serverIDs)
# Nothing has to be done if `client.hub.loginWithAutoconnectMode` was uncommented above
# Execute call
systemsPerServer = client.multicast.system.listSystems(hubSessionKey, serverIDs)
for system in itertools.chain.from_iterable(systemsPerServer):
print system.get('name')
#logout
client.hub.logout(hubSessionKey)For a normal build, just run go install (you will need at least go 1.11).
To rebuild the project's RPM package:
- branch this Open Build Service project: https://build.opensuse.org/package/show/systemsmanagement:Uyuni:Master/hub-xmlrpc-api
- grab the latest sources: possibly edit the _service file for the right revision, then
osc service disabledrun - run
osc build <distro>
Submit Requests are appreciated for changes related to packaging.
We use SemVer for versioning. For the versions available, see the tags on this repository.
See the list of contributors who participated in this project.
This project is licensed under the MIT License - see the LICENSE.md file for details.