Appendix B. SUSE Manager API Access

Contents

B.1. Using the auth Class and Getting the Session
B.2. Obtaining the system_id
B.3. Determining the sid
B.4. Viewing the cid
B.5. Getting the sgid
B.6. Channel Labels
B.7. Sample API Script

In an effort to provide customers with added flexibility, SUSE Manager makes an application programming interface (API) available. This interface can be found by clicking Help at the top-right corner of the SUSE Manager website, then clicking API in the left navigation bar.

The SUSE Manager API is based upon XML-RPC, which allows distinct pieces of software on disparate systems to make remote procedure calls using XML over HTTP. For this reason, any calls you make are expected to meet the constraints of XML-RPC. You can find out more at http://www.xmlrpc.com/.

This section bypasses a list of available methods and classes in favor of tips for using the API efficiently. These include steps for determining required values and a sample script that makes some of the calls.

B.1. Using the auth Class and Getting the Session

It is worth noting that you will almost invariably use the auth class first. This class offers a single method, login. Use this to establish an SUSE Manager session. It requires values for three parameters: username, password, and duration. The first two come directly from your SUSE Manager account, while the third is the length of time the session should last in seconds, typically 1200. It returns a session string than can be used in all other methods.

B.2. Obtaining the system_id

Many of the methods require a value for the system_id parameter. This is the unique alphanumeric value assigned to each system when registered to SUSE Manager. It can be found within the /etc/sysconfig/rhn/systemid file on each machine. In addition, you may use the download_system_id method within the system class to obtain the value.

B.3. Determining the sid

Several methods require a value for the sid, or server ID, parameter. Note that this is different from the system_id. You may determine the sid of a machine in two different ways. First, you can log into the SUSE Manager website, click the name of a system, and view the sid at the end of the URL in the location bar. It follows the = symbol and is part of a string that resembles the following: index.pxt?sid=1003486534 . Second, you may use the list_user_systems method within the system class to obtain a list of systems available to the user that contains the associated sids.

B.4. Viewing the cid

Like servers, channels have their own IDs. This value, the cid, is a required parameter for some methods, including set_base_channel and set_child_channels. Also like the sid, the cid can be obtained through the SUSE Manager website. Just click on the name of a channel and view the end of the URL. It follows the = symbol, as part of a string that resembles the following: details.pxt?cid=54 .

B.5. Getting the sgid

System groups also have their own IDs. This value, the sgid, is a required parameter for the set_group_membership method, for instance. Like the sid and cid, the sgid can be obtained through the SUSE Manager website. Just click on the name of a system group and view the end of the URL. It follows the = symbol, as part of a string that resembles the following: details.pxt?sgid=334958 . Note that the member parameter within the set_group_membership method requires only yes or no as input to make the association.

B.6. Channel Labels

The architecture of a channel is not always clear from the channel label. Below is a list that shows the correspondence between channel labels and the official title of the architecture they serve.

Table B.1. Channel Labels

Channel LabelPlatform
channel-i386-sun-solarisi386 Solaris
channel-ia32IA-32
channel-ia64IA-64
channel-sparcSparc
channel-alphaAlpha
channel-s390IBM S/390
channel-s390xIBM System z
channel-iSeriesIBM eServer System i
channel-pSeriesIBM eServer System p
channel-x86_64AMD64 and Intel EM64T
channel-ppcPPC
channel-sparc-sun-solarisSparc Solaris

This is particularly necessary to know for the channel.software.create method.

B.7. Sample API Script

The following sample script depicts how to construct an SUSE Manager API client. Review the comments and links for a full discussion of the calls made.

#!/usr/bin/perl -w

use strict;
use Frontier::Client;
use Data::Dumper;

############################################################################
# This is a sample script for use of the experimental Management APIs.     #
# The API is currently available using XMLRPC only, which is described in  #
# depth at:                                                                #
#                                                                          #
# http://www.xmlrpc.com/                                                   #
#                                                                          #
# We use the Frontier modules, available from:                             #
#                                                                          #
# http://theoryx5.uwinnipeg.ca/mod_perl/cpan-search?dist=Frontier-RPC      #
#                                                                          #
############################################################################


############################################################################
#   Defining an XMLRPC session.                                            #
############################################################################

# Define the host first.  This will be the FQDN of your SUSE Manager system.
my $HOST = '.yourdomain.com';

# Now we create the client object that will be used throughout the session.

my $client = new Frontier::Client(url => "http://$HOST/rpc/api");

# Next, we execute a login call, which returns a session identifier that will
# be passed in all subsequent calls.  The syntax of this call is described at:
#
#   http://$HOST/rpc/api/auth/login/

my $session = $client->call('auth.login', 'username', 'password');

############################################################################
#   System calls.                                                          #
############################################################################

# This next call returns a list of systems available to the user.  The 
# syntax of this call is described at:
#
#   http://$HOST/rpc/api/system/list_user_systems/
#
# In the code snippet below, we dump data about our systems, and we 
# capture the ID of the first system we find for future operations.

my $systems = $client->call('system.list_user_systems', $session);
for my $system (@$systems) {
  print Dumper($system);
}
print "\n\nCapturing ID of system @$systems[0]->{name}\n\n";
my $systemid = @$systems[0]->{id};

# This next call returns a list of packages present on this system.  The
# syntax of this call is described at:
#
#   http://$HOST/rpc/api/system/list_packages/
#
# This will probably be a pretty long list.

my $packages = $client->call('system.list_packages', $session, $systemid);
for my $package (@$packages) {
  print Dumper($package);
}

# Additional system calls are described at:
#   http://$HOST/rpc/api/system/