Ground Control

The Spacewalk management framework has been featured in a previous ADMIN issue [1]; so, in this article, I will depart from the familiar web interface and instead show script-based solutions for handling tasks. The Spacewalk API offers a very comprehensive approach to performing every imaginable task on the server. However, admins do need to design fairly complex script constructs when it comes to handling extensive tasks on the server. The language you use for this purpose is not initially important, as long as it supports XML-RPC calls. What you will mostly find here is Perl and Python scripts.

The spacecmd tool also relies on the Spacewalk server's XML-RPC-based API, but it abstracts its calls in handy options. The tool is either started in interactive mode and then waits for your instructions, or you can pass all the necessary options in at the command line. Thus, you can use the tool in your own Bash scripts. Some admins prefer to use Bash rather than a mile-long Python or Perl program. In this article, I compare and contrast the two variants.

Spacewalk API

Typically, any script that wants to talk to the Spacewalk API requires a client and a session object. The session object is used for authentication against the server and must be specified for each method call. To avoid the need to specify username and password for accessing the server in every single script, it makes sense to write a module and integrate this into your scripts.

Listing 1 shows an example of such a module for the Perl scripting language. You need to save the module either in the folder with the API scripts or preferably in the directory with your Perl modules. A call to perl -V shows you where this is. The module requires an /etc/sysconfig/spacewalk_api.conf configuration file, in which the Spacewalk server and the username and password for accessing the server are separated by blanks. You can add Use RHNSession to the header of an API script to access this module.

01 package RHNSession;
02
03 use strict;
04 use Exporter;
05 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
06
07 $VERSION     = 1.0;
08 @ISA         = qw(Exporter);
09 @EXPORT      = ();
10 @EXPORT_OK   = qw(Session);
11 %EXPORT_TAGS = ( DEFAULT => [qw(&Session)] );
12
13 sub Session {
14   open(IN, "/etc/sysconfig/spacewalk_api.conf") or die "Spacewalk API config not found: $!";
15   $_ = <IN>;
16   my ($server, $user, $pass) = (split);
17   close(IN);
18
19   my $client = new Frontier::Client(url => "http://$server/rpc/api");
20   my $session = $client->call('auth.login', $user, $pass);
21
22   return ($client, $session);
23 }

The script in Listing 2 shows a simple example that binds the module you just created and calls the channel.listSoftwareChannels method on the Spacewalk server, which then returns a list of available software channels onscreen  – admittedly, a very simple script.

01 #!/usr/bin/perl
02
03 use strict;
04 use Frontier::Client;
05 use RHNSession;
06
07 my ($client, $session) = RHNSession::Session;
08
09 my $channels = $client->call('channel.listSoftwareChannels', $session);
10
11 foreach my $channel (@$channels) {
12   print $channel->{'label'} . "\n";
13 }
14
15 $client->call('auth.logout', $session);

The Spacewalk API naturally also lets you handle more complex tasks, such as creating or modifying software and configuration channels, Kickstart files, or system groups. A list of the available methods can be found in the Spacewalk documentation [2] (Figure 1). You will also find some examples of Perl and Python scripts that rely on the Spacewalk API.

Spacecmd

The script requirements can be quite extensive, depending on the task at hand. The spacecmd tool hides this complexity and allows Spacewalk newcomers to automate complex tasks easily with simple Bash scripts. The tool is now part of the official Spacewalk source and is thus available from the website  [3].

When you call spacecmd, the two configuration files /etc/spacecmd.conf and ~/.spacecmd/config are evaluated. You can define server and authentication information in them:

[spacecmd]
server=sat.virt.tuxgeek.de
username=admin
password=pw
nossl=0

In interactive mode, the tool supports tab completion, which is very helpful if you are looking for a method whose name you can't quite remember.

To implement the example in Listing 2 with the Spacewalk tool, you simply need to enter the softwarechannel_list command in interactive mode. The result will be identical to that of the Perl script, but the effort involved in developing the script is far less.

For more complex tasks, you can group the spacecmd calls in a Bash script. Listing 3 shows a simple example that figures out which systems access what software channels on the Spacewalk server. The result of the first spacecmd call stored is in the CHANNELS environmental variable. Then, it iterates through the list and passes each element – stored in the variable c – to the second spacecmd call. Everything else is just cosmetics.

01 #!/bin/sh
02
03 CHANNELS=$(spacecmd -- softwarechannel_list  2>/dev/null)
04
05 for c in $CHANNELS
06 do
07  echo "Systems that access channel $c:"
08  spacecmd -- softwarechannel_listsystems $c 2>/dev/null
09  echo
10 done

Conclusions

Almost all of the Spacewalk server's tasks can be automated with the two variants presented here. If you prefer less complex scripts, you will probably want to use spacecmd. I would only recommend direct access to the Spacewalk API using Perl or Python if you need to handle large-scale jobs.

If an API method is available but not yet implemented in the spacecmd tool, then either a friendly request on the project mailing list [4] or a spot of DIY will do the trick. You can drag the sources for the Spacewalk server onto your own computer using git clone git://git.fedorahosted.org/spacewalk.git. The spacecmd/src/lib subdirectory contains the modules that implement the API methods.