create new tag
view all tags

Introductory Tutorial

This LCFG tutorial is based around using a virtual appliance which is preloaded with a self-hosting LCFG client/server environment. Although it is possible to follow the instructions on a fully-fledged LCFG service we don't recommend it in case you break something...

Get the Virtual Machine

The virtual appliance is provided as a .ova file, approximately 5.2GB in size. It was produced using VirtualBox version 6.1. It should work with older versions, and might also work with VMWare - please let us know how you get on.

It can be downloaded from the web at https://www.lcfg.org/vbox/lcfg_tutorial.ova or via rsync at rsync.lcfg.org::vbox/lcfg_tutorial.ova. If you have access to AFS you can fetch the image from /afs/inf.ed.ac.uk/group/mp-unit/virtual_dice/images/lcfg_tutorial.ova To verify your download is correct an MD5 checksum is provided at https://www.lcfg.org/vbox/lcfg_tutorial.md5sum

Importing the appliance into VirtualBox is very straightforward, just use the Import Appliance item in the File menu. Full instructions and screenshots are provided on the Oracle docs website. You may need to install the extension pack as the appliance requires USB 2.0 support, that's not something we need for this tutorial and is probably just due to the extension pack being installed on the machine where the appliance was created.

It also seems to be possible to import the VM into KVM:

tar xfv lcfg_tutorial.ova
qemu-img convert -O qcow2 lcfg_tutorial-disk001.vmdk lcfg_tutorial-disk001.qcow2

Move the image to wherever your libvirtd storage pool is (probably /var/lib/libvirt/images) and chown it to root. Create a new VM in virt-manager by importing the newly created disk image and set it to have 1 cpu, 2048M RAM and an e1000 network card.

The General Environment

The VM is based on Ubuntu 20.04.2 (Focal Fossa) and uses the Gnome desktop environment.

Extra packages can be installed using the apt tool. This comes pre-configured with the Informatics LCFG package repository - but note that that will only be accessible within the ed.ac.uk network, so you will need to connect via a VPN if you're at home.

On boot the VM will autologin to the desktop environment. It's configured with the guest user and the password is also guest. To get root access use sudo, e.g. run sudo bash.

You will regularly be automatically prompted to apply any updates. Please do that, to ensure that you always have the latest version of the tutorial files. It's also worth giving it a manual prod at boot-time by starting a terminal and running these commands:

sudo apt update
sudo apt upgrade

Some basic knowledge of Linux is assumed but we do not expect people to have any specific Debian/Ubuntu knowledge.

The LCFG Environment

If you are only accustomed to the SL7 LCFG environment, you will notice that things are slightly different on Ubuntu. An effort has been made to adhere more closely to the Filesystem Hierarchy Standard FHS.

Log files are stored in /var/log/lcfg. In particular you will be interested in the client and server logs. You can follow the changes to the files like this: tail -f /var/log/lcfg/server

Component configuration is stored in the /var/lib/lcfg/conf directory. For these tutorials most files of interest will be in the server directory - /var/lib/lcfg/conf/server. This contains the following sub-directories of interest:

  • defaults - the schema files for components
  • include - the configuration header files
  • packages - the package list files
  • source - the source profiles
  • web - the XML profiles generated by the server

Don't worry if you don't initially know what all these files are used for, that's the whole reason we're following this tutorial!

The LCFG server watches the files in these directories for changes, and it will rebuild dependent profiles as soon as any file changes. If you want to make big modifications we recommend copying the file to somewhere else, making your changes, and then copying it back into place.

The client daemon is rdxprof (think "read XML profile"), it is managed using Systemd, so you can prod the daemon using systemctl like this:

systemctl restart rdxprof

The LCFG server daemon is also managed using Systemd, and it's called mkxprof (think "make XML profile"), e.g.:

systemctl status mkxprof

Users familiar with LCFG should note that, for simplicity, the server component is NOT installed. Changes to the way the daemon runs may be made by editing the /etc/lcfg/server.args file and restarting the service manually (using the command systemctl restart mkxprof).


The examples are based around a source profile named lcfg-tutorial (which matches the hostname of the VM). The site is named local which is chosen to not clash with any LCFG sites in UoE (e.g. dice, phys, see, geos)

Examples are provided in the /usr/share/lcfg/tutorial directory, and there is a sub-directory for the specific platform (e.g. /usr/share/lcfg/tutorial/examples/focal). During the tutorial we will copy various files into the locations in /var/lib/lcfg/conf/server (see above) to discover what happens.

The original pristine state of the source profile can be restored using the file named original in the examples source directory.


The following tutorials are available:

-- squinney - 2021-03-18

Topic revision: r6 - 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