Introduction to LCFG : Part 6a

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

This tutorial follows on from IntroductoryTutorialPart6a. In the following examples we will work on the task of managing the nginx web server. 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.

The examples below use the LCFG buildtools, documentation is available for the tools on the LCFG website.

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.

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.

Generating a new component

The first step is to create a skeleton project directory for the new component. The LCFG build tools provide an lcfg-skeleton tool which can be used to generate a reasonable starting point. As the non-root user run the lcfg-skeleton command in a terminal and respond to the questions as below:

Name of the component/project: nginx
Is this an LCFG component? (yes/no) [yes]: 
Short description of the project [The LCFG nginx component]: 
Name of the author [Guest User,,,]: Example User
Email address for the author:
Type of component (perl/shell/file/virtual) [perl]: 
Version Control System (SVN/CVS/None) [SVN]: None
Supported platforms: UbuntuFocal
Distribution license [GPLv2]: 
Restart component on RPM update (yes/no) [yes]: 
Use the CMake build system (yes/no) [yes]: 
Check all changes are committed before a release? (yes/no) [yes]: 
Generate the ChangeLog from the Revision-Control log? (yes/no) [no]: yes


  • Mostly the defaults will be sensible and you can just accept them.
  • You must specify None for the version control system, that will create an lcfg-nginx project in the current directory.
  • You must provide a valid email address.

This should result in output which looks like this:

Stored LCFG build metadata
Generating /tmp/RMylXJNeeb/CMakeLists.txt
Generating /tmp/RMylXJNeeb/nginx.def.cin
Generating /tmp/RMylXJNeeb/ChangeLog
Generating /tmp/RMylXJNeeb/templates/README
Generating /tmp/RMylXJNeeb/nagios/README
Generating /tmp/RMylXJNeeb/lib/LCFG/Component/
Generating /tmp/RMylXJNeeb/README
Generating /tmp/RMylXJNeeb/README.BUILD
Generating /tmp/RMylXJNeeb/nginx.pod.cin
Generating /tmp/RMylXJNeeb/nginx.cin
Generating /tmp/RMylXJNeeb/specfile
Successfully imported your project into your version-control system.

You will now have an lcfg-nginx directory which contains various files:

  • ChangeLog - A list of changes for each release. When using svn or git this may be auto-generated.
  • CMakeLists.txt - The CMake build script
  • lcfg.yml - LCFG build tools metadata, controls parts of the package building process
  • lib/LCFG/Component/ - The LCFG component Perl module
  • nagios/README - Explanatory notes about the optional LCFG nagios translator module
  • nginx.cin - The LCFG component script
  • nginx.def.cin - The LCFG component schema
  • nginx.pod.cin - The LCFG component documentation (used to generate the man page)
  • README - Explanatory notes about the project
  • README.BUILD - Explanatory notes on how to build the project
  • specfile - RPM build script
  • templates/README - Explanatory notes about the optional templates for the LCFG component

Adding Debian/Ubuntu support

As the virtual appliance for this tutorial is based on Ubuntu the project needs to be able to generate a Debian (.deb) package. By default the project only has support for building RPM packages.

Add support for building debian packages to your project using the gendeb command like this:

cd lcfg-nginx
lcfg-reltool gendeb

You will see output like this:

Failed to detect version-control and nothing explicitly specified.
LCFG: Creating debian/lcfg-nginx-defaults.install metadata file
LCFG: Creating debian/lcfg-nginx.install metadata file
LCFG: Creating debian/lcfg-nginx.lintian-overrides metadata file
LCFG: Creating debian/lcfg-nginx.manpages metadata file
LCFG: Creating debian/lcfg-nginx.postinst metadata file
LCFG: Creating debian/lcfg-nginx.postrm metadata file
LCFG: Creating debian/lcfg-nginx.prerm metadata file
LCFG: Creating debian/lcfg-nginx.service metadata file
LCFG: Creating debian/lcfg-nginx.triggers metadata file
LCFG: Removing debian/lcfg-nginx.triggers as it is empty
LCFG: Creating debian/lcfg-nginx-doc.install metadata file
LCFG: Creating debian/compat metadata file
LCFG: Creating debian/control metadata file
LCFG: Creating debian/copyright metadata file
LCFG: Creating debian/docs metadata file
LCFG: Creating debian/rules metadata file
LCFG: Creating debian/source/format metadata file
LCFG: Creating debian directory 'debian'
LCFG: Please review the debian directory for this project

These files serve the same purpose as the specfile for building RPMs, the main difference is that the build config is split into many small files.

The most important files are:

  • debian/control - controls what packages are built and this is where dependencies must be specified
  • debian/rules - drives the building of the packages

Making a Release

The LCFG build tools expect a project to have a 3-part version string like major.minor.micro and support making 3 types of releases. In terms of revision control systems the releases are usually done as tags or copies into a separate directory.

  • micro - A very small change, no modification to behaviour, e.g. a bug fix or documentation improvements.
  • minor - A change in functionality which is backwards compatible, e.g. the addition of new resources.
  • major - Changes which are not backwards compatible or very significant (e.g. major code refactoring).

Try making the first release for your project:

lcfg-reltool micro

The output will look like this:

Failed to detect version-control and nothing explicitly specified.
LCFG: Updating debian/changelog

As this project is not being stored in a revision control system the tags are placed into a directory in your home directory.

Examine the contents of ~/lcfgbuild/tags/

find ~/lcfgbuild/tags

This should show a couple of tags for the lcfg-nginx project

Building Packages

The LCFG build tools support two modes of building packages. You can either build a development version of a package which includes all the latest changes in the working directory or you can build a tagged version (as already created with one of the major, minor or micro commands).

Build a development version of your project like this:

lcfg-reltool devdeb

If you were on a Redhat based machine you would instead use the devrpm command.

You should see a whole load of output from the build process and it will end like this:

LCFG: Successfully built source package for lcfg-nginx
LCFG: Source: /afs/
LCFG: Successfully built packages for lcfg-nginx
LCFG: Package: /afs/
LCFG: Package: /afs/
LCFG: Package: /afs/

Those are your packages ready to be installed using the dpkg tool.

To build a tagged version of a package use the deb and rpm commands. Those will build the version in the lcfg.yml file (in this case 0.0.2), to build a package from a different tag (e.g. 0.0.1) switch to that tag directory and run the command there.

If there are no local changes since the last release was tagged then the two commands may produce packages with the same contents but they will have different versions, a development build always contains an extra dev part (e.g. .dev2)

The package should now be installed (as the root user) like this:

dpkg -i /afs/

The defaults and doc packages are not essential, the main lcfg-nginx package (without any extension to the name) contains everything necessary for client side LCFG component support.

-- squinney - 2021-04-22

This topic: LCFG > DocsForLCFGUsers > IntroductoryTutorial > IntroductoryTutorialPart6a
Topic revision: r2 - 2021-04-23 - 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