This chapter will help you to identify and solve problems that you encounter with ZENworks Linux Management. The main tools at your disposal are configuration and log files, data and package caches, PHP and Apache configuration files, and your support representatives.
The best way to deal with problems is to prevent them, and the second best is to be prepared for them. This section will help you work with the backup, failover, optomizing, and database replication features of ZENworks Linux Management, so that you can be ready for disk failure, power outage, natural disaster or other inconveniences.
To create an XML backup of the server database, use the command rce-dump. It accepts no arguments or flags and outputs two files ending in .dump. The first file contains the database information and the second file contains log information.
To restore your server from those files, use the command rce-restore with the main and log files as arguments.
You can use rce-dump on a regular basis for scheduled backups, but you should definitely use it before upgrading to a new version of ZENworks Linux Management.
The package repository, typically stored in /ximian, can be backed up and restored with standard filesystem backup tools. Be sure to run all the backup processes at the same time, so that your database matches the package repository contents.
To improve performance, use the rce-pgsql-vacuum example script, found in the /usr/share/rcserver directory on the ZENworks Server.
You must log in as Root before running the rce-pgsql-vacuum script.
The rce-pgsql-vacuum script runs the vacuumdb command, which has a significant impact on database performance. For optimal performance, run the script once a week on a lightly loaded server and once a day on a heavily loaded server.
Upgrading to Red Hat Enterprise Linux AS version 3 by performing a minimal install using ZENworks Linux Management may cause the Red Carpet Daemon to crash when you restart the system or the daemon. Before restarting the daemon, to remedy this problem, delete the __db.001, __db.002, and __db.003 files in the /var/lib/rpm directory, run rpm --rebuilddb, and then restart the daemon.
Software dependencies can get incredibly complicated. Each individual package can have an arbitrary number of "provides," "conflicts," and "requires," and after a few packages, you end up with an intimidating list of packages, libraries, functional equivalents, and filenames.
There are several tools you can use to work with dependencies and simplify the process of shipping a coherent channel of software. The first and most obvious are those from rug:
This command takes no arguments and no options. It simply goes to the server and checks to see if anything you ship requires something that you don't. As a general rule, it is best to minimize the number of dangling requirements.
Given a package, display a list of software that conflicts with it. For example, "httpd" conflicts with "thttpd."
List the libraries and functionality that a package provides. For example, the package rug provides:
/usr/bin/rug rug = 2.0.1-0.ximian.8.0 ximian_unmarshaller.so ximian-rug = 2.0.1-0
List a package's requirements, the package that provides them, and the channel from which the required packages come. For example, rug lists its own requirements as:
! | Requirement | Provided By | Channel
--+-------------------------+-------------+-------------
| libc.so.6(GLIBC_2.2) | glibc | (none)
| libc.so.6(GLIBC_2.1.3) | glibc | (none)
| libc.so.6(GLIBC_2.1.2) | glibc | (none)
| libc.so.6(GLIBC_2.1) | glibc | (none)
| libc.so.6(GLIBC_2.0) | glibc | (none)
| libc.so.6 | glibc | (none)
| /usr/bin/env | sh-utils | (none)
| rcd >= 2.0 | rcd | Red Carpet 2
| python >= 2.2 | python | (none)
Resolve dependencies for libraries, installing packages as necessary. This command can be used with version numbers and comparison operators. ZENworks Linux Management Server, for example, requires libgobject-2.0.so.0 and postgresql-server >= 7.2.1. To install whatever packages provide those two things, you could run the command:
rug solvedeps libgobject-2.0.so.0 postgresql-server >= 7.2.1
to install glib2 and some version of postgresql-server later than 7.2.1.
Display the conflicts for a library or functionality (rather than a package, as in info-conflicts).
List packages that provide the library you specify. If, in the solvedeps example above, you wanted to know what package provided libgobject-2.0.so.0, you might use the command:
rug wp libgobject-2.0.so.0
and get the response:
S | Channel | Package | Version --+--------------------------+---------+-------- i | Red Hat Linux 8.0 | glib2 | 2.0.6-2
List packages that require the library you specify (rather than a package you specify, as in info-requirements).
The dump command outputs the current state of the rcddaemon. To troubleshoot someone else's daemon problems, stop your daemon and run the command:
/usr/sbin/rcd --undump=[filename].
You may also use the various tools provided directly by rpm:
The rpm --rebuilddb command rebuilds the database from the headers of the installed packages.
The rpm --verify command checks to see if a particular package has been installed properly. Some of the checks performed during the verification process confirm the size, MD5sum, permissions, and type of each file installed with the package. This can be useful if you suspect that files may have been damaged, or that an unauthorized update has occurred.
HINT: Specify the Channel
If you're doing an installation and you can't figure out why a package, usually of a lower version, is being pulled in, try explicitly choosing the package using the channel:package notation (ie, "rug in xd2-pro:acroread"). Chances are there's a dependency problem that prevents it from being a valid solution.
Finally, it may be helpful to set a few environment variables for rcd:
When set to true, displays additional information in the rcd logs.
Set to true to display the entire resolution process. This should not be necessary in most cases, and will produce extremely large log files.
Set to a number of seconds to provide an approximate maximum for dependency resolution. This should not normally be necessary unless you have a very large number of channels providing many possible solutions to a given request.
When something goes wrong, the first place to look for a cause is in the log files:
This is a list of messages from rcd, describing actions taken with the date, time, pid of the rcd process, and the status of the action. For example, a segment might look like this:
Dec 23 02:22:39 [19021] Running heartbeat at Mon Dec 23 02:22:39 2003 Dec 23 02:22:39 [19021] id=468 BEGIN 'Downloading https://hostname.server.com/channels.php?distro_target=redhat-80-i386' (running) Dec 23 02:22:40 [19021] id=468 COMPLETE 'Downloading https://hostname.server.com/channels.php?distro_target=redhat-80-i386' time=1s (finished) Dec 23 02:22:41 [19021] Can't subscribe to non-existent channel 'channelname'
Be sure to check this file after rug or red-carpet failures, especially if you see "ximian_xmlrpclib.py" in the traceback.
This file describes the actions taken by rcd, one action per line, with data fields demarcated by pipe (|) characters, with an empty field represented by the underscore (_). Each line describes a single transaction. The first half of the line lists the date, a hex number identifying the transaction, whether the transaction was remote or local, the name of the user taking the action, and the action taken (upgrade, remove, or install). The last eight fields display the name, epoch, version, and build number of the package before and after the action. For example, an upgrade would look like this:
Fri Aug 16 19:10:10 2002 |3d5b2|local|root|upgrade|gtk+|1|1.2|ximian.0|gtk+|1|1.2.1|ximian.3
Be sure to check both locations for Web server logs, which will be placed differently depending on your operating system and the version or versions of Apache you have installed. If the ZENworks Linux Management server runs into problems, you are likely to find them described here. Check the Apache 2 documentation for more information.
The rcman error message ERROR: Invalid server response appears only when the server does not respond. That is most likely due to a PHP error, and the exact reason is likely to be found in the file /var/log/httpd/ssl_error_log or /var/log/apache2/ssl_error_log.
ZENworks Linux Management uses flat files or XML files for configuration, mostly stored in /etc/ximian/ and subdirectories.
The ZENworks Linux Management Server configuration files are kept in /etc/ximian/rcserver/. The most important one is rcserver.conf, which sets a number of variables for the system. For the most part, you should not need to change this file, or the "configured" file in the same directory.
NOTE: You can change the ZENworks Linux Management Server service name by adding the following line to the rcserver.conf file:
servername = new_name
After editing the rcserver.conf file, run rce-refresh -s to refresh the change in the rcserver.conf file.
Client configuration files are kept in /etc/ximian as well. The most important is rcd.conf. The rcd.conf file format is described in its own manual page; to read it, use the man rcd.conf command.
The /etc/ximian/mcookie file is a system identifier, and /etc/ximian/partnernet is the key used to log in to ZENworks Linux Management servers. Except at setup time, you should not need to touch these files, and even then, they are more likely to be manipulated by the software than edited or created by hand.
If packages refuse to upgrade properly, or if you have trouble with software package locks, check the file /etc/ximian/rcd-package-locks
In the vast majority of cases, you will not need to alter the configuration files for Apache, PHP, or the SQL database. However, if you do wish to customize them, check the documentation associated with the individual products; you may also wish to speak with your support representative.
The files most directly customized by the ZENworks Linux Management server are php.ini and httpd.conf.
If transactions are failing inexplicably, your clients may not be connecting properly with the server. First, make sure that your ZENworks Linux Management server recognizes the machine, by seeing that it appears in the output of the rcman machine-list command. The output will display the name, IP address, and last contact time for each machine (use group-listmachines if you wish to list only the machines in a given group).
If machines do not contact the server, add services, or activate properly, check to be sure:
rug set require-verified-certificates false
to turn off SSL checking.)
If, during activation or the addition of a service, the client machine displays the error message:
Unable to download service info: IO error - Soup error: SSL handshake failed (8)
it is likely that you need to turn off SSL certificate checking.
If you get the error message "Server could not contact client" during a transaction, check the following:
The wwwrun process must have proper file access to the folders containing any packages or packagesets. If you receive errors when you attempt to create a package or packageset in the Web interface, ensure that the wwwrun process has proper access to the files.
Your software purchase includes support. Your sales representative will provide you with instructions for contacting the support team.
Support representatives can help you best when they have a clear understanding of your problem, so for best results please include as much as possible of the following information:
If you have trouble during a transaction, let us know whether it was initiated by the server or by the client.
For server-initiated transactions and issues involving client information conveyed to the server, be sure that rcd-modules is installed on the client.
We may ask you to attach files or portions of files to your incident:
rug dump>system.xml; gzip -9 system.xml
and any relevant information from /var/log/rcd/rcd-messages.
rce-dump>db.xml; gzip -9 db.xml.
You may also want information from /var/log/httpd/error_log and /var/log/httpd/access_log.