Welcome to metasphinx’s documentation!

This documentation is all about metaconfig

Control structure

Control structures and how they are used in data files

foreach

The minimal example

in _config_

1
2
[settings]
nameservers = ["192.168.1.1", "8.8.8.8"]

in an included file, say files/etc/resolv.conf

1
2
3
4
5
%header("##")

#foreach ns in nameservers
   nameservers = %(ns)
#end

A foreach example using a dictionary

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
crontab["example"] = dict(
             enabled = 0,
             min     = "0",
             hour    = "*",
             day     = "*",
             month   = "*",
             weekday = "*",
             user    = "nobody",
             command = "echo foo"
         )

using the variable

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
%header("##")
SHELL="%(shell)"
PATH="%(path)"
MAILTO="%(mailto)"
%# min  hour  day  month  weekday  user    command
#foreach ct in crontab
  #if crontab[ct]["enabled"]
      %(crontab[ct]["min"])    %(crontab[ct]["hour"])     %(crontab[ct]["day"])    %(crontab[ct]["month"])      %(crontab[ct]["weekday"])        %(crontab[ct]["user"])  %(crontab[ct]["command"])
  #end
#end

if and else

if-else branching is done like this

1
2
[settings]
enable_logging = 1

in an included file, say files/etc/resolv.conf

1
2
3
4
5
6
7
%header("##")

#if enable_logging
   logging = 1
#else
   logging = 0
#end

or, if _logging_ is default disabled, leave out the explicit _logging_ line.

1
2
3
4
5
%header("##")

#if enable_logging
   logging = 1
#end

To test if a dictionary contains a specific key

1
2
3
#if "max_days" in params
   SomethignWithDays = %(params["max_days"])
#end

Troubleshooting

1
2
3
# metaconfig
[E] Lexer error at (<some file name>: line n, column m): Command token expected but EOL found
[F] Too many errors, aborting compilation

Configuration files

As part of the configuration, it is possible to add files.

It must be place in the files subdirectory

example from the ntp package

1
2
3
4
5
6
$ tree ntp
ntp
├── config
└── files
    └── etc
        └── ntp.conf

in the files adding %header(“##”) adds the metaconfig warning header.

The “##” part is the comment signs to use. For some config files ”;” or “–” would be appropriate

Pound sign

To show the sign # in a file, use %#.

To have a comment in the file parsed by metaconfig, use ##

Defining variables

define a variable to be used later in the config

example usage

1
2
#define vname "drupal.example.org"
SomeVar = %(vname)

Commands

define, import, method

Config variables

In the config files different variable type are allowed.

example

1
2
3
4
5
[settings]
AnInteger = 12
AString = "This is a string"
AnArray = [1,2,3,4,5]
ADictionary = dict( a = 2, b = "C" )

in an included file, say files/etc/resolv.conf

1
2
3
4
5
%header("##")

#foreach ns in nameservers
   nameservers = %(ns)
#end

if and else

if-else branching is done like this

1
2
[settings]
enable_logging = 1

in an included file, say files/etc/resolv.conf

1
2
3
4
5
6
7
%header("##")

#if enable_logging
   logging = 1
#else
   logging = 0
#end

or, if _logging_ is default disabled, leave out the explicit _logging_ line.

1
2
3
4
5
%header("##")

#if enable_logging
   logging = 1
#end

Config files

As part of the configuration, for all nodes and modules, a file named _config_ is used.

import

Imports a module from /etc/metaconfig/res

Changing setting from e.g. config/network is done in the namespace [settings.config/network]

TODO: quick example

modify

TODO: quicl example and explanation

Special commands and variables

unix users

TDB

file ownership and permissions

(from profile/minimal)

Files permissions and ownership can be explicitly set.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
[files]
# Set executable permission for standard dirs for binaries
permission["/etc/initramfs-tools/hooks/*"] = "0755"
permission["/etc/init.d/*"] = "0755"
permission["/etc/cron.hourly/*"] = "0755"
permission["/etc/cron.daily/*"] = "0755"
permission["/etc/cron.weekly/*"] = "0755"
permission["/etc/cron.monthly/*"] = "0755"
permission["/usr/local/bin/*"] = "0755"
permission["/root"] = "0700"

Variables

Example of build-in variables

1
2
3
4
5
6
7
from profile/standard
if PLATFORM_OS_NAME in ["debian", "ubuntu"]
  import "public/config/debian-logrotate"
  import "public/config/kernel-img"
  import "public/config/hostname"
  import "public/config/locale"
end

TODO: which one are there and how to find out

Triggers

(from config/backup)

Triggers are used to run certain commands when metaconfig change files.

1
2
3
[trigger.generate-backup-keys]
command = "DIR=/etc/spye/backup/main/ssh; PRIV=$DIR/private.key; PUB=$DIR/public.key; mkdir -p $DIR; [ ! -r $PRIV ] && (echo \"Generating backup keys\" && ssh-keygen -P \"\" -C \"$(hostname -f)-backup-$(date +%Y-%m-%d)\" -t rsa -b 2048 -f $PRIV && mv $PRIV.pub $PUB) || true"
single = True

TODO: single = true? what does that mean?

1
2
3
4
[trigger.restart-exim]
command = ["service", "exim4", "restart"]
files += "/etc/exim4/*"
files += "/etc/exim4/conf.d/*/*"

Unix users and groups

(from mozrepo/config/sysuser)

Metaconfig can enforce uid and gid values, as well as the ohter paramteres for a given user.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
[unixuser.sysuser]
uid = 1500
gid = 1500
gecos = ",,,"
home = "/home/sysuser"
shell = "/bin/bash"

groups_include += "adm"
groups_include += "sudo"
groups_include += "sysuser"

[unixgroup.sysuser]
gid=1500

Apt

Apt is the pacakge handling system of debian and its derivatives, like ubuntu.

TODO: add ref

Adding and removing packages

In the config file, instruct metaconfig to install certain pacakages, and to remove certain packages (if they are installed).

1
2
3
4
5
6
[apt]
install += "somepackage"
install += ["a", "list", "of", "packages"]

remove += "Someotherpackage"
remove += ["a", "list", "of", "packages", "no", "to", "be", "on", "the", "system"]

If bad package names are used, metaconfig will return with an error.

Note that, before installing, metaconfig will update the repositories (as in run “apt-get update”)

Adding apt keys

Apt repositories has signing keys, and metaconfig will normalæy fail if packages cannot be validated.

1
2
3
4
5
[apt.source.debian_mozilla]
url = "http://mozilla.debian.net/"
dist = "wheezy-backports"
components = ["iceweasel-esr"]
keys += "A6AA8C72"

(from Metaconfig_mozrepo/service/iceweasel_latest_esr/config)

TODO: how to find these keys? or a link to some debian documentation related to this.

Howto

The follwing contains metaconfig snippets for doing specific things.

Setting static IP

The following will set a static IP on interface eth0.

1
2
3
4
import "mozrepo/config/networks"

[settings.mozrepo/config/network]
iface["eth0"] = dict( type="static", address="10.0.0.123", netmask="255.255.0.0", gateway="10.0.0.1" )

This is work-in-progress

Stuff missing

  • Examples/howtos

  • Adaptation of obsolete pdf

  • rundown of
    • Settings and template files
    • import/modify
    • apt
    • unixuser

  • contact info

  • FAQ

  • some sort of overview and proper introduction

  • installation instructions

  • Troubleshooting