Getting Started with MetaConfig
Please note, that this is a re-write of an older guide. The re-write is not yet complete. The old document is available in PDF.
This guide will show you how to use MetaConfig to configure a simple Debian GNU/Linux server. The guide will assume that a freshly installed Debian GNU/Linux operating system has been installed on the target host.
We recommend that you use a virtual machine for this tutorial. You can download a VirtualBox image with a fresh Debian installation with MetaConfig installed from our download section.
Normally MetaConfig is used in a client-server infrastructure. However, to keep things simple this guide will use MetaConfig in stand alone mode.
Obtaining MetaConfig
Instructions for obtaining MetaConfig can be found in the Download section.
MetaConfig structure
The main configuration directory for MetaConfig is /etc/metaconfig. The directory is organized as follows:
| Path | Description |
|---|---|
| /etc/metaconfig/ | Main configuration directory |
| /etc/metaconfig/node/ | Contains configuration definition for this node (the local node) |
| /etc/metaconfig/node/config | This is the main configuration definition file for this node |
| /etc/metaconfig/files/ | File templates used in this node's configuration definition |
| /etc/metaconfig/res/ | Contains external resources such as definition components that are shared among multiple nodes. |
| /etc/metaconfig/triggers/ | This is a MetaConfig system directory that contains files to indicate if specific single-shot triggers has been run on this node |
When you install MetaConfig, an example configuration definition for your node is created in /etc/metaconfig/node/config.dist. Use this file as inspiration or rename this file to /etc/metaconfig/node/config in order to use it as configuration definition for your node.
Creating your first configuration definition
A configuration definition is needed in order to let MetaConfig know how the host should be configured. The node's configuration definition is located in /etc/metaconfig/node. This folder will usually be a Subversion or Git checkout.
The configuration definition’s main file is called 'config' and located in /etc/metaconfig/node/config. In the following we will refer to /etc/metaconfig/node/config as the node config.
The node config is specified using the XCL configuration definition language. The file is organized in sections. A section is a block of code that contains configuration definition relevant to a specific subject. E.g. a specific handler or component. More on handlers and components in later tutorials. For now, we will concentrate on defining configuration for a single node.
MetaConfig supports file templates. File templates are specified in /etc/metaconfig/node/files. We will return to this subject later. For now, we will concentrate on the main configuration definition.
Managing software
Installing software packages
In Debian, Ubuntu and other Debian derived operating systems, software is managed through the dpkg package manager. The Advanced Package Tool (APT) is used to install and remove software packages. RedHat Enterprise Linux, SuSE, and others use RPM packages and Yum to manage software packages.
In this guide we will assume that the node is running a Debian derivative, thus, the APT handler will be used in the following.
The APT handler is configured in the [apt] section of the node config. In order to manage which software packages will be installed, the APT handler operates on two lists: 'install' and 'remove'. 'install' is a list of packages that must be installed on the host. 'remove' is a list of packages that must not be installed on the system, thus, they will be removed if they are present. The former is used most frequently.
We start out by specifying that a few packages must be installed. We will need an editor and SSH access. So we add the packages 'vim' and 'ssh' to the list of packages to install. This is done by adding the following lines to the node config. Open /etc/metaconfig/node/config in an editor and add these lines:
[apt] install += "vim" install += "ssh"
Save the file and exit editor.
Now we will run a test to see how MetaConfig configures the system. First, a dry run is done to see what MetaConfig plans to do. Run the following in a root shell.
metaconfig
The expected output is this:
[*] Would change file [/etc/apt/sources.list.d/metaconfig.list]: -deb http://debian.sikkerhed.org/ stable main +## ------------------------------------------ +## Generated by MetaConfig +## +## THIS FILE IS AUTOMATICALLY GENERATED. +## DO NOT EDIT. ALL CHANGES WILL BE LOST. +## ------------------------------------------ [*] Would have updated apt-get database [*] Would apt-get install [vim ssh] [*] Plan finished
This output is a human readable description of the execution plan. It describes which operations MetaConfig would perform and in what order.
The first 8 lines means that MetaConfig would have overwritten the file /etc/apt/sources.list.d/metaconfig.list with an empty file containing a comment header. The indented lines show the difference between the current version of the file and the version that MetaConfig would have written. The format is the common unified diff format. Remember that when we installed MetaConfig, we wrote the file /etc/apt/sources.list.d/metaconfig.list by echoing the string 'deb http://debian.sikkerhed.org/ stable main' into it. This was just in order to be able to install MetaConfig. It is no longer needed, as we shall see how to manage software repositories with MetaConfig in a minute. So for now, it is safe to let MetaConfig overwrite it.
In the next line of output MetaConfig tells you that it will update the software database by running apt-get update.
Next line tells that it will install the packages ssh and vim (e.g. apt-get install ssh vim.
This is reasonable, so we will run the same command again with the -aa switch to indicate that all changes should be accepted. Run:
metaconfig -aa
The expected output is:
[*] Writing file [/etc/apt/sources.list.d/metaconfig.list] [*] Updating apt database.. [*] Going to apt-get install [ssh vim] Reading package lists... Done Building dependency tree Reading state information... Done The following extra packages will be installed: openssh-server vim-runtime Suggested packages: ssh-askpass rssh molly-guard ctags vim-doc vim-scripts The following NEW packages will be installed: openssh-server ssh vim vim-runtime 0 upgraded, 4 newly installed, 0 to remove and 0 not upgraded. Need to get 296kB/6668kB of archives. After this operation, 25,7MB of additional disk space will be used. Get:1 http://mirrors.telianet.dk lenny/main openssh-server 1:5.1p1-5 [295kB] Get:2 http://mirrors.telianet.dk lenny/main ssh 1:5.1p1-5 [1202B] Fetched 296kB in 0s (626kB/s) Preconfiguring packages ... Selecting previously deselected package openssh-server. (Reading database ... 21342 files and directories currently installed.) Unpacking openssh-server (from .../openssh-server_1%3a5.1p1-5_i386.deb) ... Selecting previously deselected package vim-runtime. Unpacking vim-runtime (from .../vim-runtime_1%3a7.1.314-3+lenny2_all.deb) ... Adding ‘diversion of /usr/share/vim/vim71/doc/help.txt to /usr/share/vim/vim71/doc/help.txt. vim-tiny by vim-runtime’ Adding ‘diversion of /usr/share/vim/vim71/doc/tags to /usr/share/vim/vim71/doc/tags.vim-tiny by vim-runtime’ Selecting previously deselected package vim. Unpacking vim (from .../vim_1%3a7.1.314-3+lenny2_i386.deb) ... Selecting previously deselected package ssh. Unpacking ssh (from .../ssh_1%3a5.1p1-5_all.deb) ... Processing triggers for man-db ... Setting up openssh-server (1:5.1p1-5) ... Restarting OpenBSD Secure Shell server: sshd. Setting up vim-runtime (1:7.1.314-3+lenny2) ... Processing /usr/share/vim/addons/doc Setting up vim (1:7.1.314-3+lenny2) ... Setting up ssh (1:5.1p1-5) ... [*] Metaconfiguration done
The packages for Vim and OpenSSH are now installed on the system.
MetaConfig is idempotent. This means, that it is safe to run the command multiple times. Run the command again and verify that the output is:
[*] Metaconfiguration done
MetaConfig did not change the system this time because the system was already in compliance with the desired state as specified in the configuration definition.