Chapter 1. Red Hat Satellite Information

This section covers various topics on Red Hat Satellite advanced configuration.

1.1. Command Line Configuration Management Tools

In addition to the options provided in the Red Hat Satellite website, there are two command line tools for managing a system's configuration files: the Red Hat Network Configuration Client and the Red Hat Network Configuration Manager. There is a complementary Red Hat Network Actions Control tool that is used to enable and disable configuration management on client systems. If you do not yet have these these tools installed, they can be found within the Red Hat Network Tools child channel for your operating system.

Note

Whenever a configuration file is deployed via the website, a backup of the previous file including its full path is made in the /var/lib/rhncfg/backups/ directory on the affected system. The backup retains its filename but has a .rhn-cfg-backup extension appended.

1.1.1. Red Hat Network Actions Control

The Red Hat Network Actions Control (rhn-actions-control) application is used to enable and disable configuration management of a system. Client systems cannot be managed in this fashion by default. This tool allows System Administrators to enable or disable specific modes of allowable actions such as: deploying a configuration file onto the system, uploading a file from the system, using diff to find out what is currently managed on a system and what is available, or allowing running arbitrary remote commands. These various modes are enabled/disabled by placing/removing files and directories in the /etc/sysconfig/rhn/allowed-actions/ directory. Due to the default permissions on the /etc/sysconfig/rhn/ directory, Red Hat Network Actions Control have to be run by someone with root access.

1.1.1.1. General command line options

There is a man page available, as there are for most command line tools. Simply decide what Red Hat Network scheduled actions should be enabled for use by system administrators. These options enable the various scheduled action modes:

Table 1.1. rhn-actions-control options

Option Description
--enable-deploy Allow rhncfg-client to deploy files.
--enable-diff Allow rhncfg-client to diff files.
--enable-upload Allow rhncfg-client to upload files.
--enable-mtime-upload Allow rhncfg-client to upload mtime.
--enable-all Allow rhncfg-client to do everything.
--enable-run Enable script.run
--disable-deploy Disable deployment.
--disable-diff Disable diff
--disable-upload Disable upload
--disable-mtime-upload Disable mtime upload
--disable-all Disable all options
--disable-run Disable script.run
--report Report whether the modes are enabled or disabled
-f, --force Force the operation without asking first
-h, --help show help message and exit
Once a mode is set, your system is now ready for config management through Red Hat Satellite. rhn-actions-control --enable-all is a common option.

1.1.2. Red Hat Network Configuration Client

As the name implies, the Red Hat Network Configuration Client (rhncfg-client) is installed and run from an individual client system. From there you may use it to gain knowledge about how Red Hat Network deploys configuration files to the client.
The Red Hat Network Configuration Client offers these primary modes: list, get, channels, diff, and verify.

1.1.2.1. Listing Config Files

To list the configuration files for the machine and the labels of the config channels containing them, issue the command: 
rhncfg-client list
The output resembles the following list: 
Config Channel      File
config-channel-17   /etc/example-config.txt
config-channel-17   /var/spool/aalib.rpm
config-channel-14   /etc/rhn/rhn.conf
These are the configuration files that apply to your system. However, there may be duplicate files present in the other channels. For example, issue the following command: 
rhncfg-manager list config-channel-14
and observe the following output: 
Files in config channel 'config-channel-14' /etc/example-config.txt /etc/rhn/rhn.conf
You may then wonder where the second version of /etc/example-config.txt went. The rank of the /etc/example-config.txt file in config-channel-17 was higher than that of the same file in config-channel-14. As a result, the version of the configuration file in config-channel-14 is not deployed for this system, although the file still resides in the channel. The rhncfg-client command does not list the file because it will not be deployed on this system.

1.1.2.2. Getting a Config File

To download the most relevant configuration file for the machine, issue the command: 
rhncfg-client get /etc/example-config.txt
You should see output resembling: 
Deploying /etc/example-config.txt
View the contents of the file with less or another pager. Note that the file is selected as the most relevant based upon the rank of the config channel containing it. This is accomplished within the Configuration tab of the System Details page.

1.1.2.3. Viewing Config Channels

To view the labels and names of the config channels that apply to the system, issue the command: 
rhncfg-client channels
You should see output resembling: 
Config channels: Label Name ----- ---- config-channel-17 config chan 2 config-channel-14 config chan 1
The following table lists the options available for rhncfg-client get:

Table 1.2. rhncfg-client get options

Option Description
--topdir=TOPDIR Make all file operations relative to this string.
--exclude=EXCLUDE Excludes a file from being deployed with 'get'/ May be used multiple times.
-h, --help Show help message and exit

1.1.2.4. Differentiating between Config Files

To view the differences between the config files deployed on the system and those stored by Red Hat Network, issue the command: 
rhncfg-client diff
The output resembles the following: 
[root@testsatellite root]# rhncfg-client diff
--- /etc/test
+++ /etc/test	2013-08-28 00:14:49.405152824 +1000
@@ -1 +1,2 @@
 This is the first line
+This is the second line added
In addition, you may include the --topdir option to compare config files in Red Hat Network with those located in an arbitrary (and unused) location on the client system, like so: 
[root@ root]# rhncfg-client diff --topdir /home/test/blah/ /usr/bin/diff: /home/test/blah/etc/example-config.txt: No such file or directory /usr/bin/diff: /home/test/blah/var/spool/aalib.rpm: No such file or directory

1.1.2.5. Verifying Config Files

To quickly determine if client configuration files are different than those associated with it via Red Hat Network, issue the command: 
rhncfg-client verify
The output resembles the following: 
modified /etc/example-config.txt /var/spool/aalib.rpm
The file example-config.txt is locally modified, while aalib.rpm is not.
The following table lists the options available for rhncfg-client verify:

Table 1.3. rhncfg-client verify options

Option Description
-v, --verbose Increase the amount of output detail. Displays differences in the mode, owner, and group permissions for the specified config file.
-o, --only Only show files that differ.
-h, --help Show help message and exit

1.1.3. Red Hat Network Configuration Manager

Unlike the Red Hat Network Configuration Client, the Red Hat Network Configuration Manager (rhncfg-manager) is designed to maintain Red Hat Network's central repository of config files and channels, not those located on client systems. This tool offers a command line alternative to the configuration management features within the Red Hat Network website, as well as the ability to script some or all of the related maintenance.
It is intended for use by Config Administrators and requires an Red Hat Network username and password that has the appropriate permission set. The username may be specified in /etc/sysconfig/rhn/rhncfg-manager.conf or in the [rhncfg-manager] section of ~/.rhncfgrc.
When the Red Hat Network Configuration Manager is run as root, it attempts to pull in needed configuration values from the Red Hat Update Agent. When run as a user other than root, you may have to make configuration changes within the ~/.rhncfgrc file. The session file is cached in ~/.rhncfg-manager-session to prevent logging in for every command.
The default timeout for the Red Hat Network Configuration Manager is 30 minutes. To alter this, add the server.session_lifetime option and new value to the /etc/rhn/rhn.conf file on the server running the manager, like so: 
server.session_lifetime = 120
The Red Hat Network Configuration Manager offers these primary modes: add, create-channel, diff, diff-revisions, download-channel, get, list, list-channels, remove, remove-channel, revisions, update, and upload-channel.
Each mode offers its own set of options, which can be seen by issuing the following command: 
rhncfg-manager mode --help
Replace mode with the name of the mode to be inspected: 
rhncfg-manager diff-revisions --help
You can see such a list of options for the add mode at Table 1.4, “rhncfg-manager add options”.

1.1.3.1. Creating a Config Channel

To create a config channel for your organization, issue the command: 
rhncfg-manager create-channel channel-label
If prompted for your Red Hat Satellite username and password, provide them. The output resembles the following: 
Red Hat Network username: rhn-user
Password:
Creating config channel channel-label Config channel channel-label created
Once you have created a config channel, use the remaining modes listed above to populate and maintain that channel.

1.1.3.2. Adding Files to a Config Channel

To add a file to a config channel, specify the channel label as well as the local file to be uploaded, such as: 
rhncfg-manager add --channel=channel-label /path/to/file
In addition to the required channel label and the path to the file, you may use the available options for modifying the file during its addition. For instance, you may alter the path and file name by including the --dest-file option in the command, like: 
rhncfg-manager add --channel=channel-label --dest-file=/new/path/to/file.txt/path/to/file
The output resembles the following: 
Pushing to channel example-channel
Local file >/path/to/file -> remote file /new/path/to/file.txt
The following table lists the options available for rhncfg-manager add:

Table 1.4. rhncfg-manager add options

Option Description
-c CHANNEL --channel=CHANNEL Upload files in this config channel
-d DEST_FILE --dest-file=DEST_FILE Upload the file as this path
--delim-start=DELIM_START Start delimiter for variable interpolation
--delim-end=DELIM_END End delimiter for variable interpolation
-i, --ignore-missing Ignore missing local files
--selinux-context=SELINUX_CONTEXT Overwrite the SELinux context
-h, --help show help message and exit

Note

By default, the maximum file size for configuration files is 128KB. If you need to change that value, find or create the following line in the /etc/rhn/rhn.conf file: 
web.maximum_config_file_size=128
Additionally, find or create the following line in the /etc/rhn/rhn.conf file: 
maximum_config_file_size=128
In both locations, change the value from 128 to whatever limit you want in bytes.

1.1.3.3. Differentiating between Latest Config Files

To view the differences between the config files on disk and the latest revisions in a channel, issue the command: 
rhncfg-manager diff --channel=channel-label --dest-file=/path/to/file.txt \ /local/path/to/file
You should see output resembling: 
--- /tmp/dest_path/example-config.txt config_channel: example-channel revision: 1
+++ /home/test/blah/hello_world.txt 2003-12-14 19:08:59.000000000 -0500
@@ -1 +1 @@
-foo
+hello, world
The following table lists the options available for rhncfg-manager diff:

Table 1.5. rhncfg-manager diff options

Option Description
-c CHANNEL, --channel=CHANNEL Get file(s) from this config channel
-r REVISION, --revision=REVISION Use this revision
-d DEST_FILE, --dest-file=DEST_FILE Upload the file as this path
-t TOPDIR, --topdir=TOPDIR Make all files relative to this string
-h, --help Show help message and exit

1.1.3.4. Differentiating between Various Versions

To compare different versions of a file across channels and revisions, use the -r flag to indicate which revision of the file should be compared and the -n flag to identify the two channels to be checked. See Section 1.1.3.11, “Determining the Number of File Revisions” for related instructions. Specify only one file name here, since you are comparing the file against another version of itself. For example: 
rhncfg-manager diff-revisions -n=channel-label1 -r=1 -n=channel-label2 -r=1 /path/to/file.txt
The output resembles the following: 
--- /tmp/dest_path/example-config.txt 2004-01-13 14:36:41 \ config channel: example-channel2 revision: 1
--- /tmp/dest_path/example-config.txt 2004-01-13 14:42:42 \ config channel: example-channel3 revision: 1
@@ -1 +1,20 @@
-foo
+blah
+-----BEGIN PGP SIGNATURE-----
+Version: GnuPG v1.0.6 (GNU/Linux)
+Comment: For info see http://www.gnupg.org
+
+iD8DBQA9ZY6vse4XmfJPGwgRAsHcAJ9ud9dabUcdscdcqB8AZP7e0Fua0NmKsdhQCeOWHX +VsDTfen2NWdwwPaTM+S+Cow=
+=Ltp2
+-----END PGP SIGNATURE-----
The following table lists the options available for rhncfg-manager diff-revisions:

Table 1.6. rhncfg-manager diff-revisions options

Option Description
-c CHANNEL, --channel=CHANNEL Use this config channel
-r REVISION, --revision=REVISION Use this revision
-h, --help Show help message and exit

1.1.3.5. Downloading All Files in a Channel

To download all the files in a channel to disk, create a directory and issue the following command: 
rhncfg-manager download-channel channel-label --topdir .
The output resembles the following: 
Copying /tmp/dest_path/example-config.txt -> \ blah2/tmp/dest_path/example-config.txt
The following table lists the options available for rhncfg-manager download-channel:

Table 1.7. rhncfg-manager download-channel options

Option Description
-t TOPDIR, --topdir=TOPDIR Directory all the file paths are relative to. This option must be set.
-h, --help Show help message and exit

1.1.3.6. Getting the Contents of a File

To direct the contents of a particular file to stdout, issue the command: 
rhncfg-manager get --channel=channel-label \ /tmp/dest_path/example-config.txt
You should see the contents of the file as output.

1.1.3.7. Listing All Files in a Channel

To list all the files in a channel, issue the command: 
rhncfg-manager list channel-label
You should see output resembling: 
Files in config channel `example-channel3': /tmp/dest_path/example-config.txt
The following table lists the options available for rhncfg-manager get:

Table 1.8. rhncfg-manager get options

Option Description
-c CHANNEL, --channel=CHANNEL Get file(s) from this config channel
-t TOPDIR, --topdir=TOPDIR Make all files relative to this string
-r REVISION, --revision=REVISION Get this file revision
-h, --help Show help message and exit

1.1.3.8. Listing All Config Channels

To list all of your organization's configuration channels, issue the command: 
rhncfg-manager list-channels
The output resembles the following: 
Available config channels: example-channel example-channel2 example-channel3 config-channel-14 config-channel-17
Note that this does not list local_override or server_import channels.

1.1.3.9. Removing a File from a Channel

To remove a file from a channel, issue the command: 
rhncfg-manager remove --channel=channel-label /tmp/dest_path/example-config.txt
If prompted for your Red Hat Network username and password, provide them. You should see output resembling: 
Red Hat Network username: rhn-user Password: Removing from config channel example-channel3 /tmp/dest_path/example-config.txt removed
The following table lists the options available for rhncfg-manager remove:

Table 1.9. rhncfg-manager remove options

Option Description
-c CHANNEL, --channel=CHANNEL Remove files from this config channel
-t TOPDIR, --topdir=TOPDIR Make all files relative to this string
-h, --help Show help message and exit

1.1.3.10. Deleting a Config Channel

To destroy a config channel in your organization, issue the command: 
rhncfg-manager remove-channel channel-label
The output resembles the following: 
Removing config channel example-channel Config channel example-channel removed

1.1.3.11. Determining the Number of File Revisions

To find out how many revisions (revisions go from 1 to N where N is an integer greater than 0) of a file/path are in a channel, issue the following command: 
rhncfg-manager revisions channel-label /tmp/dest_path/example-config.txt
The output resembles the following: 
Analyzing files in config channel example-channel \ /tmp/dest_path/example-config.txt: 1

1.1.3.12. Updating a File in a Channel

To create a new revision of a file in a channel (or add the first revision to that channel if none existed before for the given path), issue the following command: 
rhncfg-manager update \ --channel=channel-label --dest-file=/path/to/file.txt /local/path/to/file
The output resembles the following: 
Pushing to channel example-channel: Local file example-channel/tmp/dest_path/example-config.txt -> \ remote file /tmp/dest_path/example-config.txt
The following table lists the options available for rhncfg-manager update:

Table 1.10. rhncfg-manager update options

Option Description
-c CHANNEL, --channel=CHANNEL Upload files in this config channel
-d DEST_FILE, --dest-file=DEST_FILE Upload the file as this path
-t TOPDIR, --topdir=TOPDIR Make all files relative to this string
--delim-start=DELIM_START Start delimiter for variable interpolation
--delim-end=DELIM_END End delimiter for variable interpolation
-h, --help Show help message and exit

1.1.3.13. Uploading Multiple Files at Once

To upload multiple files to a config channel from local disk at once, issue the command: 
rhncfg-manager upload-channel --topdir=topdir channel-label
The output resembles the following: 
Using config channel example-channel4 Uploading /tmp/ola_world.txt from blah4/tmp/ola_world.txt
The following table lists the options available for rhncfg-manager upload-channel:

Table 1.11. rhncfg-manager upload-channel options

Option Description
-t TOPDIR, --topdir=TOPDIR Directory all the file paths are relative to
-c CHANNEL, --channel=CHANNEL List of channels the config info will be uploaded into. Channels delimited by ','. Example: --channel=foo,bar,baz
-h, --help Show help message and exit