create new tag
view all tags

Introduction to LCFG : Part 4a

The following examples assume you are using the virtual appliance described in IntroductoryTutorial.

In the following examples we will work on the simple but realistic task of managing the "message of the day" for a system. This is a task that most system administrators have probably needed to do at some time. Although in this tutorial we're only configuring this for a single machine keep in mind that this could be something you need to do for a large collection of machines. Once you go beyond a small number of machines doing this manually will be inefficient, tedious and there's the potential to miss out some of them.

Getting Started

As with the previous tutorial start by opening several terminal windows. To see the entire process of a change to an LCFG source profile being applied tail the server and client log files - /var/log/lcfg/server and /var/log/lcfg/client. You will also need root access in one terminal so you can modify the source profile, that can be acquired using sudo bash with the password being the same as the username.

For all these examples we will be using the LCFG file component, this is well suited to the task of managing a single file but once things become more complicated (e.g. you also need to manage services) you will want to look for another more specific component that supports that service.

All the files for this tutorial are provided in the lcfg-tutorial package, for Focal they are stored in the /usr/share/lcfg/tutorial/examples/focal/. To ensure you have the latest version run apt update and apt upgrade before starting.

Example 1 - Basics

In our first example we're going to create the /etc/motd file which is used to display a message of the day when users login to a system (e.g. using ssh).

This is available in source/example1, either copy that file to overwrite your lcfg-tutorial profile (in /var/lib/lcfg/conf/server/source/) like:

cp /usr/share/lcfg/tutorial/examples/focal/source/example1 /var/lib/lcfg/conf/server/source/lcfg-tutorial

Or directly edit the lcfg-tutorial source profile to add the following:

!file.files         mADD(example)
file.file_example   /etc/motd
file.type_example   literal
file.tmpl_example    Welcome to the LCFG Hands On tutorial.

The management of the file is done using the file component which is a standard part of all LCFG installations. To manage a particular file a tag must be added to the files tag list resource for that component (i.e. file.files). In this case the example tag is added and that tag is then used as part of the name of the associated resources. There are various possible resources available, in this example only these are used:

  • The absolute path for the managed file is specified using the file_ resource.
  • The type of the file is specified using the type_ resource (there are quite a few possibilities for this, we'll examine a couple more in later examples).
  • The template which should be used to create the file (i.e. what the contents should look like) is specified using the tmpl_ resource. This is used in different ways depending on the file type.

Once you have modified the profile check the server and client logs. Once the change has reached the client you should see that it has accepted the new profile and that the change has been applied.

Depending on what you've previously done with your workshop virtual machine, at this stage you might well notice that nothing happened and the file has not been created. This is because an LCFG component needs to be activated before it will begin managing files. On a fully managed system this would be done automatically but in the minimal environment it needs to be done manually the first time. Each LCFG component comes with a Systemd service file which should be used for this task, doing the following will ensure it is always automatically activated for subsequent reboots.

systemctl enable lcfg-file
systemctl start lcfg-file

You can then check the status of a component like this:

systemctl status lcfg-file

You should see output like this:

 lcfg-file.service - The LCFG file component
     Loaded: loaded (/lib/systemd/system/lcfg-file.service; enabled; vendor preset: enabled)
     Active: active (exited) since Fri 2021-03-26 09:43:52 GMT; 1min 55s ago
       Docs: man:lcfg-file(8)
    Process: 2594 ExecStart=/usr/bin/om file start (code=exited, status=0/SUCCESS)
   Main PID: 2594 (code=exited, status=0/SUCCESS)

Mar 26 09:43:52 lcfg-tutorial.localdomain systemd[1]: Starting The LCFG file component...
Mar 26 09:43:52 lcfg-tutorial.localdomain om[2595]: [OK] file: Start
Mar 26 09:43:52 lcfg-tutorial.localdomain systemd[1]: Finished The LCFG file component.

Now check the log file for the component - /var/log/lcfg/file, has it changed the /etc/motd file?

Aside: It is possible to activate/deactivate a component using the om tool. This is done like: om file stop or om file start. Doing that will activate or deactivate the component until the next reboot. Deactivating a component like this can occasionally be useful if you need to prevent a component from interfering whilst you manually test some configuration changes.

If you activated the file component for the first time it may well have begun managing some other files which are included by default. You should examine all the resources using qxprof:

qxprof file

Finally, try modifying the message slightly (via the file.tmpl_example resource). Watch the logs again, does anything now appear in the client log? You should see something like:

26/03/21 09:55:26:    new profile: http://localhost.localdomain/profiles/localdomain/lcfg-tutorial/XML/profile.xml
26/03/21 09:55:26:    last modified Fri Mar 26 09:55:20 2021
26/03/21 09:55:26:    profile accepted: 39788b169c003c5baf1c7713d9868341
26/03/21 09:55:27:    reconfiguring component: file.configure
26/03/21 09:55:27:      [OK] file: Configure

The [OK] shows that the change was successfully applied, if any problems occur there will be an [ERROR] usually accompanied by a helpful explanatory message.

Aside: If resources change for multiple components the LCFG client will work out the best sequence in which to apply the changes, component authors can express opinions on that by using ngeneric resources.

Example 2 - Resource Reference

In our second example we're going to modify the previously created /etc/motd file to include some system-specific information stored in other resources.

This is available in source/example2, either copy that file to overwrite your lcfg-tutorial profile (in /var/lib/lcfg/conf/server/source/) like:

cp /usr/share/lcfg/tutorial/examples/focal/source/example2 /var/lib/lcfg/conf/server/source/lcfg-tutorial

Or directly edit the lcfg-tutorial source profile to change the file.tmpl_example resource to be the following:

file.tmpl_example    Welcome to the LCFG Hands On tutorial running on <%profile.node%> (<%profile.comment%>).

Again watch the change go through the server, client and file component logs. Once it has all finished check the contents of /etc/motd. It should now look like:

Welcome to the LCFG Hands On tutorial running on lcfg-tutorial (LCFG Hands On VM).

This shows the power of LCFG resources to deal with diversity, a single piece of shared configuration can be used to produce different system-specific configuration on all managed machines.

Example 3 - Directories

The file component can be used to manage various types of files, this example demonstrates how to create a directory and use resources to control the owner, group and mode.

This is available in source/example3, either copy that file to overwrite your lcfg-tutorial profile (in /var/lib/lcfg/conf/server/source/) like:

cp /usr/share/lcfg/tutorial/examples/focal/source/example3 /var/lib/lcfg/conf/server/source/lcfg-tutorial

Or directly edit the lcfg-tutorial source profile to remove the previous example and replace it with:

!file.files         mADD(example3)
file.file_example3  /etc/example3
file.type_example3  dir
file.owner_example3 root
file.group_example3 root
file.mode_example3 0755

The type here is dir, the owner and group may be either names or numeric IDs, the mode is expected to be an octal value.

Aside: Extra users and groups may be added using the LCFG auth component.

Once you have modified the profile check the server and client logs. Once the change has reached the client you should see that it has accepted the new profile and that the directory has been created.

Finally, what happened to the original /etc/motd file? Does it still exist? Use qxprof file.files to check that it is no longer in the list of managed files. This is a (sometimes surprising) disadvantage of using the file component, once any file has been created in this way it will remain on the system even after it becomes unmanaged. There is currently no support in the file component for automatically removing old files but we would like to make it a possibility in the future.

Example 4 - Using a header

So far we have been modifying a single source profile but what the configuration needs to be shared between multiple hosts? Configuration is shared using a header file which is included in each source profile.

Create a local/options directory and install the example motd.h file:

mkdir -p /var/lib/lcfg/conf/server/include/local/options
cp /usr/share/lcfg/tutorial/examples/focal/include/options/motd.h /var/lib/lcfg/conf/server/include/local/options

The local header is a very simple site-specific wrapper, it contains:


#include <lcfg/options/motd.h>


If you watch the server log you will see that it notices the new header. As nothing depends on that file (yet) no profiles will be rebuilt.

This is available in source/example4, either copy that file to overwrite your lcfg-tutorial profile (in /var/lib/lcfg/conf/server/source/) like:

cp /usr/share/lcfg/tutorial/examples/focal/source/example4 /var/lib/lcfg/conf/server/source/lcfg-tutorial

Or directly edit the lcfg-tutorial source profile to remove the previous example and replace it with:

#include <local/options/motd.h>

Once the profile is changed watch the server, client and file component logs. What does the contents of the /etc/motd file now look like?

This is lcfg-tutorial.localdomain running ubuntu 20.04 linux/amd64.
It is managed by 

Did any other files change?

Examine the contents of the local/options/motd.h header file. It wraps the lcfg-level equivalent, see if you can find that header and read through the contents. Note that there are is some missing information in the output, can you work out which resource you would need to set to deal with that issue?

Topic revision: r4 - 2021-03-29 - squinney
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback