Site administration with omd

In some cases it is also desirable to specify the user/group ID of the new user to be created. This is performed with the -u and -g options, e.g.:

An overview of the further options can be shown with omd create --help. The most important options are:

By default, the home directory of a new site is created at /omd/sites/ and filled with default files. However, you can also have an empty home directory created, for example to mount an external volume at this location. This is done by the --no-init option:

This option also omits integration with the system apache, leaving /omd/apache/mysite.conf empty. You could then mount any directory or volume and continue the setup:

omd init then catches up with the two omitted steps, so it adds the default files and creates the Apache configuration.

As the site user you can simply call the interactive mode with:

As soon as you change a setting while the site is running, OMD will inform you that your site must be stopped first and does this as needed:

Don’t forget to restart the site following the completion of the work. omd config will not do this for you automatically.

Those who don’t like the interactive mode, or prefer to work with scripts, can set the individual settings as variables via the command line. For this there is the omd config set command. The following example sets the AUTOSTART variable to off:

This can be also performed as root if the site’s name is added as an argument:

The current assignment of all variables shows as root the command omd config mysite show and as site user omd config show:

The command output above is abbreviated for clarity and shows only the first entries.

There are numerous settings in omd config. The most important are:

Note: You can also see these variables under the same names in the interactive mode.

It is sometimes useful to create a copy of a site for testing purposes or when preparing for an update. Of course one could simply copy the /omd/sites/mysite_old directory to /omd/sites/mysite_new. That will however not work as desired, because:

To simplify copying a site, there is instead the omd cp command, which takes all of this into account. Run the command as root and simply enter the name of the existing site followed by the name of the new one. For example:

The copy can only work if:

Both of these ensure that the site is in a consistent state at the time of copying and does not change during the operation.

OMD could originally only handle the files that were actually created during the creation of the site with omd create, and which also contained the site’s ID ($OMD_SITE). These files can be found in the site directory ~/etc with this command:

Previously, OMD could not do anything with configuration files that were created later via work with the Checkmk site (the configurations of hosts that had been added at a later date, for example). From a purely technical point of view, this behavior corresponds exactly to the scope of OMD. However, the expectation of most users is that an omd cp creates a completely new site that can continue to be used productively — including its own monitoring configuration.

From Checkmk version 2.1.0 OMD can now also customize the most important elements of the Checkmk configuration. By the way, you don’t have to do anything, the whole migration described below takes place automatically.

A typical example: In a host’s properties you can use the Monitored on site attribute to manually specify which site this host should be monitored on, for example mysite_old. After an omd cp mysite_old mysite_new the value will change to mysite_new accordingly. (Previously this procedure would have resulted in the entry Unknown site (mysite_old)).

The actual technical implementation of this migration is as follows: OMD detects changes to the site ID and then executes the post-rename-site -v -o mysite_new command. The individual migration steps are subsequently processed completely automatically via the so-called rename actions plugins, which you can find at cmk/post_rename_site/plugins/actions in the Git repository.

Migration also includes informing you about anything that cannot be migrated automatically.

Here’s a concrete example: you are using distributed monitoring and rename both the central site and a remote site.

Central site: The sites.py plug-in detects that this is a central site and updates, among other things, the URL prefix value, which can be found in the connection settings of the local site under Setup > General > Distributed Monitoring.

Remote site: The warn_remote_site.py plug-in recognizes that it is a remote site and accordingly indicates that the central site must be checked and manually customized if necessary. This in turn means that in the distributed monitoring settings on the central site, the remote site’s new name must be entered in the connection settings to the renamed remote site — OMD of course cannot do this from a remote computer.

OMD itself informs you in detail about the whole procedure in the terminal. Here you can see an example of the migration messages from the omd cp output when renaming a central site — separated into success and warning messages. The processed rename action plugins are numbered individually. First the output from the automatically performed migration tasks (shortened here):

The second part of the output now contains tips regarding settings you may need to configure manually (here heavily abbreviated):

The Warn about configurations to review…​ item includes general notes on individual aspects that will generally need to be reviewed manually during a migration, such as hard coded filters for views:

Here is an overview of the six currently active plug-ins — the order here corresponds to the numbering in the above output:

If you are monitoring a large number of hosts with the site, the volume of data to be copied can be quite substantial. Most of this is produced by the measured values stored in the Round Robin Databases (RRD). But the log files containing historic events can also produce larger data volumes.

If the history is not required (for example, because you just want to test something quickly), these can be omitted from the copy. In such cases the following options can be added to omd cp:

The order of the option(s) is important:

Renaming a site is performed with the omd mv command. This is done similarly to copying a site, has the same prerequisites and is also done including configuration migration. The options to restrict the data volume are not available since the data is only being moved to another directory and is not being duplicated.

Example:

As with creating a site, copying and renaming each creates a new Linux user. Therefore omd cp and omd mv also have some of the same options as omd create, e.g. to specify user and group IDs. For more detailed information, use the omd cp --help and omd mv --help commands.

The site management in Checkmk has a built-in mechanism for backing up and restoring Checkmk sites. The omd backup and omd restore commands are the basics for packing all of the site’s data into a tar archive, and respectively, extracting that data for a restore.

Note: Checkmk also offers the possibility of performing backups and restores without using the command line, via the GUI under Setup > Maintenance > Backups. There you can also create encrypted backups and scheduled backup jobs. See the Backups article to learn how to do this.

Backing up a site with omd backup does not require root permissions. A site user can perform this. Simply enter as an argument the name of the backup file to be created:

Note that:

If the backup’s target directory is not writable for a site user, you can also do the backup as root. In this case an additional argument is required, as always, specifying the site name to be backed up:

The backup contains all of the site’s data — except for the volatile data under ~/tmp/. With the tar tzf command one can easily have a look at the file’s contents:

The lion’s share of the data to be moved during a site backup are the measured values and the log files with historical events. This is just as true when backing up as when copying a site. If you do not absolutely need this data, you can omit it and thus make the backup much faster and the resulting output file much smaller.

omd backup provides the same options to omit this data as omd cp does when copying. In the following example, the backup is created without measurement data and without the history stored in the log files:

A backup can also be created from a running site. To ensure a consistent state of the Round Robin Databases (RRD) used for recording the measurement data, the omd backup command automatically alters the Round Robin cache to a mode with which the running updates are written only to the journal, and no longer to the RRDs. The journal files are the last to be backed up — thus it can be achieved that as much as possible of the measurement data that has been generated during the backup is also included in the backup.

Restoring a backup is as simple as creating a backup. The omd restore command restores a site from a backup — in the Checkmk version that was used to backup the site. Therefore, for the restore to work, this same version must be installed on the server.

The site is completely emptied and refilled. Before omd restore the site must be stopped and afterwards it must be restarted:

A restore can also be performed by a root user. Unlike when called by the site user, the site will be recreated with the backup.

So if there is still a site with the same name, you will need to delete it before the restore. This can be performed either with an omd rm, or by simply including the --reuse option with the omd restore. A --kill additionally ensures that the already existing site is stopped before the restore proceeds. You do not need to specify the site name in the command, because it is contained in the backup:

As root, you can also restore a site with a different name from that in the backup. To do this, specify the desired name as an argument after the word restore:

The long list of conversions that happen here has the same function as for copying and renaming sites described earlier. The site name is included in numerous configuration files, and with this procedure any such occurrences will be replaced automatically by the new name.

The omd backup and omd restore commands can — in good old Unix tradition — also work via standard input/output instead of files. Instead of a path for the tar file, simply enter a hyphen (-).

In this way a pipe can be constructed and the data ‘streamed’ directly to another computer without requiring intermediate files. The larger the backup, the more advantageous this will be since no temporary space in the backed up server’s file system will be needed.

The following command backs up a site to another computer using SSH:

If you want to reverse the SSH access, i.e. prefer to connect from the backup server to the Checkmk site, this is also possible, as the following example shows. For this, first an SSH login as a site user must be permitted.

If you are clever, and combine the above with an omd restore which reads the data from the standard input, you can copy a complete, running site from one server to another — and without needing any additional space for a backup file:

And now again the whole thing with reversed SSH access — this time again from the source system to the target system: