Configuration Management CLI Tools

The mgr-cfg package has three components as subpackages with CLI tools:

Table 1. Configuration Management CLI Tool Components
Package name Tool name Installed on Use for

mgr-cfg-client

mgrcfg-client

Client

Managing client configuration

mgr-cfg-managemnet

mgrcfg-manager

Client

Managing server configuration

mgr-actions-control

mgr-actions-control

Client

Administer configuration settings

Clients do not have configuration management enabled by default. To get started, install the mgr-actions-control tool on the SUSE Manager Server, and use it to enable configuration management for your organization.

1. Actions Control (mgr-actions-control)

Use the mgr-actions-control tool to enable and disable configuration management on a client. Actions that can be performed with mgr-actions-control include:

  • Deploy a configuration file on a client

  • Upload a file from the client

  • Compare the configuration tools available on a client, with what is being used

  • Run remote commands

You must be logged in to SUSE Manager with an administrator account to use mgr-actions-control.

This tool works by adding or removing files and directories on the client in the /etc/sysconfig/rhn/allowed-actions/ directory. By default, this directory requires root permissions.

The available options for mgr-actions-control are listed in this table. Use this syntax for mgr-actions-control commands:

mgr-actions-control [-h] [--version] [-v] [--option]
Table 2. Action Control Options
Option Abbreviated Option Description

enable-all

Enable all options

disable-all

Disable all options.

enable-deploy

Allow mgrcfg-client to deploy files.

enable-diff

Allow mgrcfg-client to diff files.

enable-upload

Allow mgrcfg-client to upload files.

enable-mtime-upload

Allow mgrcfg-client to upload file modification time.

enable-run

Enable running scripts.

disable-deploy

Disable deployment.

disable-diff

Disable diff use.

disable-upload

Disable file uploads.

disable-mtime-upload

Disable modification time upload.

disable-run

Disable running scripts.

report

Report whether modes are enabled or disabled.

force

f

Force the operation without asking first.

help

h

Show help message and exit.

For more information about the available options for the mgr-actions-control tool, see the man page:

man mgr-actions-control

2. Client Configuration (mgrcfg-client)

Use the mgrcfg-client tool to manage configuration on a client. The mgrcfg-client has these primary modes:

  • list

  • get

  • channels

  • diff

  • verify

The available commands and arguments for mgrcfg-client are listed in this section. Use this syntax for mgrcfg-client commands:

mgrcfg-client [-h] [--version] [-v] [--option] [mode]

2.1. List Configuration Files

The list mode lists the configuration files for the client, including the labels of the configuration channels containing them. To see a complete list of all the configuration files that are currently applied to the client, use this command:

mgrcfg-client list

The output looks like this:

DoFoS   Config Channel      File
F      config-channel-17   /etc/config-file
F      config-channel-17   /var/spool/aalib.rpm
F      config-channel-14   /etc/rhn/rhn.conf

In this output, DoFoS means Directory, File, or Something else. Each entry in the output will be marked with D, F, or S. These configuration files apply to the client.

Get more detail about a channel by specifying the channel name:

mgrcfg-client list config-channel-14

The output looks like this:

Files in config channel 'config-channel-14'
/etc/config-file /etc/rhn/rhn.conf

It is possible that there are duplicate configuration files in different channels. In this case, the file listing for the channel shows files that are not present when listing channels applied to the client. This is a result of file ranking, which means that channels can contain files that are not applied to the client, because they are outranked by a different file from a different channel.

2.2. Get Configuration Files

The get mode displays the contents of the primary configuration file for the client. To see the configuration file with the highest rank within the channel, use this command:

mgrcfg-client get

To see a specific configuration file, use this command:

mgrcfg-client get <FILENAME>

The available options for mgrcfg-client get are listed in this table.

Table 3. Client Get Mode Options
Option Abbreviated Option Description

topdir=TOPDIR

Make all file operations relative to this string.

exclude=EXCLUDE

Exclude a file from being deployed with get. Can be used multiple times.

help

h

Show help message and exit.

2.3. Channels

The channels mode lists the configuration channels for the client. To see a complete list of all the configuration channels that are currently applied to the client, use this command:

mgrcfg-client channels

The output looks like this:

Config channels:
Label                   Name
-----                   ----
config-channel-17       config chan 2
config-channel-14       config chan 1

2.4. Differentiating Configuration Files

The diff mode shows the differences between the configuration files deployed on the client and those stored by SUSE Manager. Use this command:

mgrcfg-client diff

The output looks like this:

rhncfg-client diff
--- /etc/test
+++ /etc/test 2020-08-28 00:14:49.405152824 +1000
@@ -1 +1,2 @@
This is the first line
+This is the second line added

You can use the --topdir option to compare configuration files with those located in an arbitrary unused location on the client, like this:

# mgrcfg-client diff --topdir /home/test/example/

2.5. Verify Configuration Files

The verify mode checks if the configuration file on the client is different to the configuration associated with it. Use this command:

mgrcfg-client verify

The output looks like this:

modified /etc/config-file /var/spool/aalib.rpm

The file config-file is locally modified, while aalib.rpm is not.

The available options for mgrcfg-client verify are listed in this table.

Table 4. Client Verify Mode Options
Option Abbreviated Option Description

verbose

v

Increase the amount of output detail.

only

o

Only show differing files.

help

h

Show help message and exit.

3. Server Configuration (mgrcfg-manager)

Use the mgrcfg-manager tool to manage the configuration files and channels on the SUSE Manager Server. It does not manage configuration on a client.

The mgrcfg-manager tool has these primary modes:

  • add

  • create-channel

  • diff

  • diff-revisions

  • download-channel

  • get

  • list

  • list-channels

  • remove

  • remove-channel

  • revisions

  • update

  • upload-channel

Each mode has further options. See the available options using this syntax:

mgrcfg-manager <MODE> --help

The available commands and arguments for mgrcfg-manager are listed in this section. Use this syntax for mgrcfg-manager commands:

mgrcfg-manager [-h] [--version] [-v] [mode] [--option]

By default, the mgrcfg-manager tool times out after thirty minutes. You can change this value in the /etc/rhn/rhn.conf configuration file by adding or adjusting this line, with a value in minutes:

server.session_lifetime = <MINUTES>

3.1. Add Files to a Configuration Channel

The add mode adds a configuration file from your local filesystem to an existing channel. Use this command:

mgrcfg-manager add --channel=<channel-label> <local/path/to/file>

You can use options to modify the file during addition. For example, to change the path or file name, use this command:

mgrcfg-manager add --channel=<channel-label> \
  --dest-file=</new/path/to/file> <local/path/to/file>

The output looks like this:

Pushing to channel <channel-label>
Local file <local/path/to/file> -> remote file </new/path/to/file>

The available options for mgrcfg-manager add are listed in this table.

Table 5. Manager Add Mode Options
Option Abbreviated Option Description

channel

c

Upload files to this configuration channel.

dest-file

d

Upload the file to this path.

delim-start

Start delimiter for variable interpolation.

delim-end

End delimiter for variable interpolation.

ignore-missing

i

Ignore missing local files.

help

h

Show help message and exit.

By default, the maximum file size for configuration files is 128 KB. For information about changing the maximum file size value, see Files.

3.2. Create a Configuration Channel

The create-channel mode creates a new configuration channel. Use this command:

mgrcfg-manager create-channel <channel-label>

When you have created a configuration channel, you can add configuration files to it with the add mode.

3.3. Differentiate Between Configuration Files

The diff mode shows the differences between the stored configuration files and the latest revisions in the associated channel. Use this command:

mgrcfg-manager diff --channel=<channel-label>
  --dest-file=</path/to/file> </local/path/to/file>

The output looks like this:

--- </path/to/file> config_channel: <channel-label> revision: 1
+++ /home/test/example/hello_world.txt 2020-12-14 19:08:59.000000000 -0500
@@ -1 +1 @@
-example
+hello, world

The available options for mgrcfg-manager diff are listed in this table.

Table 6. Manager Diff Mode Options
Option Abbreviated Option Description

channel

c

Get files from this configuration channel.

dest-file

d

Upload the file to this path.

revision

r

Use this revision.

topdir

t

Make all files relative to this string.

help

h

Show help message and exit.

3.4. Differentiate between Revisions

The diff-revisions mode shows the differences between the revisions of configuration files.

This command can compare revisions across different channels. Use the -r option to indicate which revision of the file should be compared and the -n option to indicate the two channels to be checked. In this case, specify only one file name, because the file is being compared to a different revision of itself. Use this command:

mgrcfg-manager diff-revisions -n=<channel-label-1> -r=1 \
  -n=<channel-label-2> -r=1 </path/to/file>

The output looks like this:

--- </path/to/file> 2020-01-13 14:36:41 \
config channel: <example-channel-1> revision: 1
--- </path/to/file> 2020-01-13 14:42:42 \
config channel: <example-channel-2> revision: 1
@@ -1 +1,20 @@
-example
+hello, world

The available options for mgrcfg-manager diff-revision are listed in this table.

Table 7. Manager Diff Revision Mode Options
Option Abbreviated Option Description

channel

c

Get files from this configuration channel.

revision

r

Use this revision.

help

h

Show help message and exit.

3.5. Download All Files in a Channel

The download-channel mode downloads all configuration files in a channel to local directory. Use this command:

mgrcfg-manager download-channel <channel-label> --topdir <local/directory/>

The output looks like this:

Copying </config-file> -> <local/directory/config-file>

The available options for mgrcfg-manager download-channel are listed in this table.

Table 8. Manager Download Channel Mode Options
Option Abbreviated Option Description

topdir

t

Make all files relative to this string.

help

h

Show help message and exit.

3.6. Get the Contents of a File

The get mode displays the contents of a configuration file. Use this command:

mgrcfg-manager get --channel=<channel-label> <config-file>

3.7. List All Files in a Channel

The list mode lists the configuration files contained in a channel. Use this command:

mgrcfg-manager list <channel-label>

The output looks like this:

Files in config channel <channel-label>:
/tmp/dest_path/config-file

The available options for mgrcfg-manager list are listed in this table.

Table 9. Manager List Mode Options
Option Abbreviated Option Description

channel

c

Get files from this configuration channel.

topdir

t

Make all files relative to this string.

revision

r

Use this revision.

help

h

Show help message and exit.

3.8. List All Configuration Channels

The list mode lists the configuration channels available in your organization. Use this command:

mgrcfg-manager list-channels

The output looks like this:

Available config channels:
example-channel example-channel2 example-channel3 config-channel-14 config-channel-17

The output of this command does not include local_override or server_import channels.

3.9. Remove Files From a Channel

The remove mode removes configuration files from a channel. Use this command:

mgrcfg-manager remove --channel=<channel-label> <config-file>

The available options for mgrcfg-manager remove are listed in this table.

Table 10. Manager Remove Mode Options
Option Abbreviated Option Description

channel

c

Get files from this configuration channel.

topdir

t

Make all files relative to this string.

help

h

Show help message and exit.

3.10. Delete a Config Channel

The remove-channel mode removes configuration channels from your organization. Use this command:

mgrcfg-manager remove-channel <channel-label>

The output looks like this:

Removing config channel example-channel
Config channel example-channel removed

3.11. Determine the Number of File Revisions

The revisions mode shows how many revisions of a configuration file exist in a channel. Use this command:

mgrcfg-manager revisions <channel-label> <config-file>

The output looks like this:

Analyzing files in config channel example-channel \
/tmp/dest_path/config-file: 1

3.12. Update a File in a Channel

The update mode creates a new revision of a configuration file. The new revision is added within the existing channel. Use this command:

mgrcfg-manager update --channel=<channel-label> \
--dest-file=</path/to/file.txt> </local/path/to/file>

The output looks like this:

Pushing to channel example-channel:
Local file example-channel /tmp/local/config-file -> \
remote file /tmp/dest_path/config-file

The available options for mgrcfg-manager update are listed in this table.

Table 11. Manager Update Mode Options
Option Abbreviated Option Description

channel

c

Upload the file to this configuration channel.

dest-file

d

Upload the file to this path.

topdir

t

Make all files relative to this string.

delim-start

Start delimiter for variable interpolation.

delim-end

End delimiter for variable interpolation.

help

h

Show help message and exit.

3.13. Upload Multiple Files

The upload-channel mode allows you to upload multiple configuration files to a channel. Use this command:

mgrcfg-manager upload-channel --topdir=<topdir> <channel-label>

The output looks like this:

Using config channel example-channel4
Uploading config-file from /tmp/dest_path/

The available options for mgrcfg-manager upload-channel are listed in this table.

Table 12. Manager Upload Channel Mode Options
Option Abbreviated Option Description

channel

c

Upload the files to this configuration channel.

topdir

t

Directory containing the files to be uploaded.

help

h

Show help message and exit.