To simplify the process of distributing large numbers of packages, especially entire channels, ZENworks Linux Management includes the rcmirror command. You can use it to move software from a server hosted outside your network ("the remote server") to your local server, so that you can redistribute the software to all your client machines.
The command creates a duplicate of full or partial channel contents from a remote server. The most obvious use is to create a duplicate of a channel on one of the servers hosted by Ximian, moving it from the Internet to your ZENworks Linux Management server. The server that is mirrored may be a ZENworks Linux Management, Red Hat Network, or YaST server.
The rcmirror usage process typically works in the following fashion:
For a complete example of how to use rcmirror, see An Example rcmirror Deployment.
You will note that during this process, rcmirror must authenticate itself twice. When logging in to a ZENworks Linux Management machine, it uses the same sort of authentication as an rcd client. For rcman, it will use the email address and password of a ZENworks Linux Management administrator.
The rcmirror command uses the same identification strings as rcd when downloading packages and package information. However, it is not actually an rcd client, and does not use any of the settings in rcd.conf.
ZENworks Linux Management comes with a Red Carpet Express activation key. We suggest that you use rcmirror as a Red Carpet Express client for access to dedicated high-bandwidth servers.
You can also use a staging server to download software from Ximian or other distributors on the Internet; this allows for thorough testing and a more complete separation of the production environment from the Internet at large. You can do this easily using rcmirror: first mirror from the Internet to your staging server, then, from the staging server to your production server.
rcmirror accepts no arguments, and draws the vast majority of its information from its configuration file, covered in Configuration File Format for rcmirror.
By default, only root users can run rcmirror. To grant rcmirror access to a non-root user, give permissions to rcmirror.conf and the rcmirror cache location (var/cache/rcmirror).
The command accepts the following option flags:
Use the configuration file [filename] instead of the default ( /etc/ximian/rcmirror.conf).
Print help information and quit.
Display actions that would be performed with this command, but do not actually perform any actions.
List the channels available on the remote server.
List the packages available in the specified channel.
List the patches available in the specified channel.
Narrow the channel or package listing (-l or -p) to the specified distribution target.
Log the rcmirror output to syslogd.
Send the rcmirror output to the specified email address.
The default configuration file for rcmirror is /etc/ximian/rcmirror.conf, although you can use the -c or --conf flags to specify another file if you wish. The file format is that of GNOME applications, which should also be familiar to Windows users who know INI files: sections are named in square brackets, and each section contains one or more token/value pairs, one definition to a line.
You can find example rcmirror.conf files in /usr/share/doc/packages/rcmirror/(for SUSE systems) or /usr/share/doc/rcmirror/(for Red Hat systems). The files are named rcmirror-full-example.conf, rcmirror-rhn-example.conf, rcmirror-yast-example.conf, and rcmirror-ximian-example.conf. Respectively, they demonstrate a variety of mirroring options, and focused mirroring of RHN, YaST, and Ximian servers.
Before running rcmirror, you will need to edit the default rcmirror.conf file, which provides several suggested templates as examples.
There are four types of section you may create:
There can be only one [rcmirror] section per configuration file. It supports a single token: cachedir.
The cachedir token is the path to a directory you wish to use for downloaded files. This directory must exist, and it must be writable by the user that is running rcmirror.
If the [rcmirror] section is absent or cachedir is not set, rcmirror uses a temporary directory in /var/tmp for all downloaded files. That directory is completely removed on exit, regardless of the success of the rcmirror run.
If cachedir is set, its contents will only be removed on the success of the mirroring run. Anything that is already in that directory will not be downloaded on the next mirroring run.
Note that this behavior is only relevant when mirroring fails - in general, rcmirror only downloads files that are missing from your local server.
There can be only one [remote] section per configuration file. The section can have the following tokens:
base
The base token is the path to the server you wish to mirror from.
Mirroring from servers hosted by Ximian: Set the value to the URL of the RCX server, beginning with https://. If you are running as root, you do not need to provide the username or password tokens, as these are read directly from files in /etc/ximian.
From the free YaST Service: Set this value to the mirror of your choice, beginning with http:// or ftp://. SUSE maintains a list of update mirrors on its Web site.
From SUSE Maintenance Web (authenticated YaST updates for SUSE enterprise products): Set the value to your SUSE update server.
In some cases, usually in development or testing, base may be a path to a file, or an http URL.
proxy
If you use an HTTP proxy, set the proxy token to that server's name and port. For example:
proxy=http://proxy.location.corp.com:3182
Proxies that require authentication are supported in ZENworks Linux Management.
type
If you are mirroring from authenticated Ximian servers (Red Carpet Express or ZENworks Linux Management): You do not need to set this token.
From Red Hat Network: Set the value to rhn. If you wish to mirror anything other than the operating system running on your server, you must also set the systemid token. The proxy and base tokens are not set when using RHN.
From Red Carpet basic servers: Set the value to basic. You will also need to set the base token, but not user or password.
From YaST: Set the value to yast. For SUSE Maintenance Web you will need to set the base token as well.
systemid
This token is used only for mirroring from Red Hat Network. Its default value is /etc/sysconfig/rhn/systemid. If you are running ZENworks Linux Management on a Red Hat Linux operating system, and wish to mirror that same operating system from RHN, you do not need to set this token.
To mirror anything other than the operating system actually running on your local server, you must use a different systemid file, and set this value as the path to that file.
RHN will only grant access to one operating system per systemid file, so if you want to mirror another OS, you need another systemid file. In addition, there can be only one [remote] section per rcmirror configuration file, so you will need a second configuration configuration file as well.
Using two configuration files and two systemid files is only moderately complicated: the files will be nearly identical, and you can use the --conf flag to specify which configuration file you wish to use when executing rcmirror. It may help to run the mirror actions at different times, to avoid saturating your bandwidth.
To get a systemid file, copy it from a registered RHN client that is running the operating system you wish to mirror. The file is found at /etc/sysconfig/rhn/systemid.
The proxy setting in rcmirror does not work with RHN: you must set the proxy with up2date, or edit the systemid file, changing the value "httpProxy" to your proxy and port, and the value "enableProxy" to 1.
user and password
Mirroring from RHN: Neither user nor password are required when mirroring from RHN.
Mirroring from SUSE Maintenance Web: rcmirror can read the user and password values from the /etc/sysconfig/onlineupdate file generated by YaST. If you have not run and registered YaST Online Update on your ZENworks Linux Management server, set the user token to your SUSE product registration code, and password to the password you set when registering the product. The public YaST service does not require authentication.
Mirroring from Ximian servers: If you are running as root, rcmirror can discover these values automatically. If you are not, you can find the user value in /etc/ximian/mcookie, and the password value in /etc/ximian/partnernet. These two tokens identify the machine to the remote server. If you have ever used rug or rcd on this machine, the files will already exist. However, you must make sure that the machine has permission to access the channels you wish to mirror. You must do this regardless of whether you put the user and password values into the file. To do so, do the following:
rug service-add https://update.novell.com/data
This will make the Red Carpet client access the Ximian Red Carpet Express server (if it is not already pointed there). If you wish to use a different remote server, substitute it for the one in the example.
To apply ZENworks Linux Management 6.6.2 Hot Patches, see TID 3998128 at Novell Support Web site.
rug activate -s [remote-server] [key] [email@address]
You may specify the remote server by URL, name, or number. Use rug service-list to determine which values to enter. If you are using only one server, you can omit the -s [servicename] portion entirely.
[local]
The [local] section describes the machine which is running rcmirror. It may have the following tokens:
type
Sets the type of server, which may be rce (ZENworks Linux Management) or static (plain directories of files). If you do not set this token, it is assumed to be rce.
If the value is static, rcmirror will produce a simple directory tree of package files. If the value is rce or the token is unset, rcmirror will insert the packages into the server noted in the base value.
rcmanuser and rcmanpassword
The username and password for an rcman administrator. The account must have control over the channel or channels being mirrored. It's a good idea to use an md5 hash instead of putting your password directly into a configuration file:
echo -n "password" | md5sum
[channel]
The [channel] section is the description of a single remote channel that is to be mirrored. There may be multiple channel sections per file. There is one required token, name. You may also use the tokens localname, target, excludetarget, package, excludepackage, patch, exclude patch.
name specifies the channel you will be mirroring from the remote server. For example, "ximian-gnome", "redhat-73-i386", and "openoffice" are all channel names.
localname gives the channel a different name on your server than it does on the remote server. For example, if you were mirroring a channel called "mono-software-devel-kit-redhat-80-i386" and wanted a more convenient name you could enter localname=mono.
target token limits the mirroring to the specified distribution target. This is matched with a shell-like globbing function, so you can specify redhat-73-* to get Red Hat Linux 7.3 for all supported architectures, or redhat-* for all versions of Red Hat Linux. You can specify multiple target tokens in one [channel] section. Any target matched by any of the targettokens will be marked as eligible for mirroring. If no target token is specified, all supported targets will be mirrored.
excludetarget excludes a target from the list to be mirrored. This is matched with a shell-like globbing function, so you can specify redhat-* to exclude all variants of Red Hat Linux. You can specify multiple "excludetarget" tags in one [channel] section. All target exclusions are performed after target tags have been processed.
package token limits the mirroring to a specified set of package names. Semantics are the same as with the target token. Globbing is allowed, and multiple package tags result in all matching packages being mirrored.
excludepackage excludes a package from the list to be mirrored. Globbing is allowed, as are multiple excludepackage tags. All package exclusions are performed after package tags have been processed.
patch token limits the mirroring to a specified set of patch names. Semantics are the same as with the target token. Globbing is allowed, and multiple patch tags result in all matching packages being mirrored.
For example, many administrators choose to create a separate channel for kernel modules and patches. This example sets rcmirror up to exclude mirroring kernel patches from the main SUSE 9.1 channel, and instead mirrors them from a kernel specific channel:
[channel]
name=suse-91-i586
excludepatch=kernel*
[channel]
name=suse-91-i586
localname=suse-91-i586-kernel
patch=kernel*
excludepatch excludes a patch from the list to be mirrored. Globbing is allowed, as are multiple excludepatch tags. All package exclusions are performed after package tags have been processed.
[product]
The [product] section allows you to mirror specific pre-arranged sets of software from Ximian. It was designed to provide an easy method of installing Ximian Desktop or Ximian Evolution on a large number of systems. Each "product" consists of a set of "components," each of which represents a set of packages. A component is roughly analogous to a package set, or one of the "task" packages from the Debian distribution.
WARNING: Mirroring More than you Bargained For
rcmirror will also pull in the operating system for any given product mirrored. If you have mirrored the operating system under a different name, rcmirror will download it again. If you do not specify a target when mirroring a product, rcmirror will fetch the product, plus the entire operating system, for all available targets. To avoid downloading more than you wanted, be sure to set target or excludetarget token.
As in other rcmirror operations, the [product] section causes rcmirror to fetch software from Ximian servers and add it to the local server. If you use the [product] section, rcmirror will also fetch the XML files used by the Ximian installer, making it possible to use the Ximian installer with your local server.
rcmirror will also create a package set for each component of the product mirrored, containing the individual packages for the component. These package sets make it more convenient to install the large bundles of software contained in products. The naming scheme for the package sets created in this manner is "product-component-pkgset." For example, when mirroring the "ximian-evolution" product, the package set "ximian-evolution-pilot-pkgset" is created on the local server, containing a set of PalmOS synchronization packages.
The [product] section uses the name token, followed by target and excludetarget as in the [channel] section.
NOTE: Mcookie, Partnernet, and Identity
The mcookie and partnernet files define the identity of a Red Carpet client machine, and do not normally change. Copying those files copies the identity of the client. You may use the values created on a different machine if you wish, although there is no good reason to do so.
This section will demonstrate using rcmirror to copy software from Ximian servers to your ZENworks Linux Management server.
As with a ZENworks Linux Management deployment, the first step in using rcmirror is planning: you need to decide what software to mirror, and where to get it. After that, it's a matter of writing a configuration file, testing, and scheduling a repeated rcmirror job with cron.
As a rule, you should mirror the complete distribution for all operating systems you support, the Ximian Red Carpet tools, and additional Ximian products you plan to use, such as Ximian Desktop or Ximian Evolution. Most operating systems and all Ximian products can be mirrored directly from Ximian. However, the "Enterprise" versions of many operating systems have redistribution restrictions that mean you must download from the vendor directly.
To mirror from an OS vendor as well as from Ximian, you will need an additional configuration file and mirror action. You will need one file per source; for Red Hat Enterprise offerings you will need one file per version of the operating system.
Writing a configuration file is not as difficult as it sounds, but it's a little complicated.
Before anything else, make a working copy of the rcmirror.conf file, and keep a backup of the default, just to be safe. The default file consists almost entirely of examples, so you can just go through the file and remove the comment symbols (#) from the lines you want to use. Also, check the additional example files ( rcmirror-yast-example.conf, rcmirror-full-example.conf, and so forth) for more information.
NOTE: Permissions and Activation
Because rcmirror logs in to two services, it must have two sets of access permissions. At the remote server it logs in to download packages and package information; at the local server it logs in again as an rcman administrator to add packages.
If you installed from CD, it is likely that you have not yet activated your local machine against the servers hosted at Ximian.Your sales or support representative will provide you with an activation key, and you can run the following activation commands as described in the network install instructions:
rug service-add https://update.novell.com/data rug activate -s https://update.novell.com/data [key] [email@address]
Section one is [rcmirror] and the suggested contents for the section are cachedir=/var/cache/rcmirror. That's simple: we want a cache directory in case something fails. Make sure that the directory /var/cache/rcmirror exists and is writeable.
The next section is [remote], controlling the connection to the remote server. For this example, we'll be mirroring from the Ximian Red Carpet Express server:
[remote]
base=https://update.novell.com/data/
NOTE: Other Types of Remote Servers
See Configuration File Format for rcmirror , the rcmirror.conf man page, or Red Hat Network and rcmirror for information about using Red Carpet basic, YaST, or Red Hat Network servers and the type token.
Note that ZENworks Linux Management version 2.0 clients, including rcmirror and rcd, will not work with 1.4 servers.
The [local] section defines access to the local ZENworks Linux Management server. In this case, we only need to define the rcmanuser and rcmanpassword values. Everything else can be left at its default.
For the rcmanuser value, enter a login name for the ZENworks Linux Management server. For rcmanpassword, use your password or the output of the command:
echo -n "password" | md5sum.
Our [local] section looks like this:
[local]
rcmanuser=email@address.company.com
rcmanpassword=5f4dcc3b5aa765d61d8327deb882cf99
The last section is easy enough: defining the software we will mirror:
[channel]
name=redhat-80-i386
The first test is checking to see if the channels are listed properly:
rcmirror -l
You should see only one channel listed: redhat-80-i386
To perform a full run of the program, type:
rcmirror -c /path/to/my-rcmirror.conf
When you are sure that it works, copy the new rcmirror.conf file into the /etc/ximian/ directory and add rcmirror to the server's crontab for nightly execution (see man cron or man anacron for more information about scheduling events).
Now, any new packages added to the Red Hat 8.0 channel will appear on your ZENworks Linux Management server overnight. If you have set up a recurring update transaction for that channel, the packages will be automatically installed on your client machines as well.
ZENworks Linux Management has the ability to mirror SUSE patch files and apply them to your SUSE 9 machines. These patch files are created and distributed by SUSE using the YaST Online Update (YOU) system, and are usually applied using YaST.
ZENworks Linux Management has incorporated the ability to download and install these patches, enabling you to use a single server to distribute you software as well as SUSE patches.
When you mirror a ZENworks Linux Management server, patches are mirrored automatically. New options are included in the rcmirror.conf file to select and exclude patches much like you would packages. If the server you are mirroring provides patches, you do not need to do anything to enable patches, they are mirrored automatically, given that there are patches which meet the criteria specified by the patch and excludepatch flags.
You can also mirror a SUSE YaST Online Update server, though you will receive only patches, rather than patches and packages as you would if you mirrored a ZENworks Linux Management server.
Rcmirror can download packages from RHN and add them to a ZENworks Linux Management server for distribution within your organization.
Mirroring Red Hat Enterprise Linux from a Red Hat Network server differs only slightly from the example contained in An Example rcmirror Deployment. This section shows you how to check your RHN registration, add the appropriate channels to your ZENworks Linux Management server, and create an rcmirror.conf file for RHN.
NOTE: As of ZENworks 6.6 Linux Management, up2date is no longer used to contact the Red Hat Network, as rcmirror can now contact the Red Hat Network directly.
If you are mirroring from Red Hat Network, check your registration and channel availability with the command:
up2date --nox --show-channels
If you are registered, you will see the list of channels available, such as:
[root@10-0-0-233 ximian]# up2date --nox --show-channels redhat-advanced-server-i386 redhat-stronghold-i386 bea-weblogic-jrockit-i386-7.0
If you are not registered, do so with the rhn_register command.
After registration, add channels to your RHN subscription by doing the following:
Once you have ensured that you can access the software on your remote server, you will need to prepare the local server to receive it. First, select a ZENworks Linux Management administration account that will manage the mirroring procedures. You may use an existing administrator or create your own. If you create a new one, make sure that the account has full organization privileges, rather than just channel or group privileges.
The rcmirror process will create channels for the mirrored software, so you do not need to create them beforehand. However, you may wish to create groups of clients at this time. Here's how:
rcman group-add "Red Hat Enterprise Clients" rhel-clients --desc="Machines updating RHEL" rcman ga "Stronghold Clients" stronghold-clients --desc="Machines with Stronghold" rcman ga "JRockit Group" jrockit-group --desc="Machines with JRockit"
rcman act-add --key=rhel-activation-key rcman act-addgroup rhel-activation-key rhel-clients
The client machines can now activate and will be easily grouped when you wish to ship software to them.
Finally, you are ready to create your /etc/ximian/rcmirror.conf file. Open a text editor and begin:
The resulting file will look like this:
[remote]
type=rhn
[local]
rcmanuser=my-rce-admin@ximian.com
rcmanpassword=md5sum-of-my-password
[channel]
name=redhat-advanced-server-i386
[channel]
name=redhat-stronghold-i386
[channel] name=bea-weblogic-jrockit-i386-7.0
Once you have completed setup, you should run a few tests to make sure everything will go according to plan. First, list the channels your file will mirror, using the command:
rcmirror --list-channels --conf=[my-rcmirror-file]
You should see all the channels for which you have created a [channel] section in the configuration file.
If that list of channels is indeed the one you wish to mirror, use the -n or --dry-run flag, to perform a test, checking the servers and get package information, but not downloading packages or adding them to the server:
rcmirror --dry-run --conf=[my-rcmirror-file]
If you are satisfied, run without the --dry-run flag: rcmirror --conf=[my-rcmirror-file]. The download may take quite awhile, especially the first time you run it, depending upon the number of packages you are downloading.
When you are ready to ship the software, create a transaction as described in Transactions: Making Things Happen.