path: root/config-db/slxconfig-demuxer

#! /usr/bin/perl -CLADS
# -----------------------------------------------------------------------------
# Copyright (c) 2006, 2007 - OpenSLX GmbH
#
# This program is free software distributed under the GPL version 2.
# See http://openslx.org/COPYING
#
# If you have any feedback please consult http://openslx.org/feedback and
# send your suggestions, praise, or complaints to feedback@openslx.org
#
# General information about OpenSLX can be found at http://openslx.org/
# -----------------------------------------------------------------------------
# slxconfig-demuxer
#	- OpenSLX configuration demultiplexer
# -----------------------------------------------------------------------------
use strict;
use warnings;

my $abstract = q[
slxconfig-demuxer
    This script will read information about all systems, clients and
    groups from the OpenSLX configuration database, mix & match the individual
    configurational attributes and then demultiplex the resulting information
    to a set of configuration files. These files are used by any OpenSLX-client
    during boot to find out which systems to offer for booting.

    The resulting files will be put into the OpenSLX-tftpboot-path.

    Please use the --man option in order to read the full manual.
];

use Fcntl qw(:DEFAULT :flock);
use File::Basename;
use File::Find;
use Getopt::Long qw(:config pass_through);
use Pod::Usage;

# add the lib-folder and the folder this script lives in to perl's search
# path for modules:
use FindBin;
use lib "$FindBin::RealBin/../lib";
use lib "$FindBin::RealBin";
# development path to config-db stuff

use OpenSLX::Basics;
use OpenSLX::ConfigDB qw(:support);
use OpenSLX::ConfigFolder;
use OpenSLX::OSPlugin::Engine;
use OpenSLX::Utils;

my $pxeDefaultTemplate = q[NOESCAPE 0
PROMPT 0
TIMEOUT 10
DEFAULT menu.c32
IMPLICIT 1
ALLOWOPTIONS 1
MENU TITLE Was möchten Sie tun (Auswahl mittels Cursortasten)?
MENU MASTER PASSWD secret
];

my (
	$dhcpType,
	# type of DHCP export format
	$dryRun,
	# dryRun won't touch any file
	$systemConfCount,
	# number of system configurations written
	$clientSystemConfCount,
	# number of (system-specific) client configurations written
	%vendorOSInitramfsMap,
	# keeping note of how many initramFSs have been created for a
	# specific vendor-OS.
	$helpReq,
	$manReq,
	$versionReq,
);

GetOptions(
	'dhcp-export-type=s' => \$dhcpType,
	'dry-run'            => \$dryRun,
	'help|?'             => \$helpReq,
	'man'                => \$manReq,
	'version'            => \$versionReq,
  )
  or pod2usage(2);
pod2usage(-msg => $abstract, -verbose => 0, -exitval => 1) if $helpReq;
if ($manReq) {
	$ENV{LANG} = 'en_EN';
	# avoid dubious problem with perldoc in combination with UTF-8 that
	# leads to strange dashes and single-quotes being used
	pod2usage(-verbose => 2);
}
if ($versionReq) {
	slxsystem('slxversion');
	exit 1;
}

my ($sec, $min, $hour, $day, $mon, $year) = (localtime);
$mon++;
$year += 1900;
my $callDate = sprintf('%04d-%02d-%02d', $year, $mon, $day);
my $callTime = sprintf('%02d:%02d:%02d', $hour, $min, $sec);

openslxInit();

my $openslxDB = OpenSLX::ConfigDB->new();
$openslxDB->connect();

my $clientConfigPath = "$openslxConfig{'private-path'}/config";
# make sure that the default config folders exist:
if (createConfigFolderForDefaultSystem()) {
	# this path should have been generated by earlier stage (slxsettings), so
	# we indicate that there is some kind of problem:
	warn _tr(
		"Completed client-config-folder '%s', since at least some parts of it didn't exist!",
		$clientConfigPath
	);
}

my $lockFile = "$openslxConfig{'private-path'}/config-demuxer.lock";
lockScript($lockFile);

END { unlockScript($lockFile); }

my $tempPath = "$openslxConfig{'temp-path'}/slxconfig-demuxer";
if (!$dryRun) {
	slxsystem("rm -rf $tempPath");
	slxsystem("mkdir -p $tempPath");
	if (!-d $tempPath) {
		die _tr("Unable to create or access temp-path '%s'!", $tempPath);
	}
}
my $tftpbootPath = "$openslxConfig{'public-path'}/tftpboot";
if (!$dryRun) {
	slxsystem("rm -rf $tftpbootPath/*");
	slxsystem("mkdir -p $tftpbootPath/client-config $tftpbootPath/pxelinux.cfg");
	if (!-d $tftpbootPath) {
		die _tr("Unable to create or access tftpboot-path '%s'!",
			$tftpbootPath);
	}
}

writeConfigurations();

my $wr = ($dryRun ? "would have written" : "wrote");
print
  "$wr $systemConfCount system- and $clientSystemConfCount client-specific configurations to $tftpbootPath/client-config\n";

$openslxDB->disconnect();

slxsystem("rm -rf $tempPath") unless $dryRun || length($tempPath) < 12;

exit;

################################################################################
###
################################################################################
sub lockScript
{
	my $lockFile = shift;

	return if $dryRun;

	# use a lock-file to singularize execution of this script:
	if (-e $lockFile) {
		my $ctime = (stat($lockFile))[10];
		my $now   = time();
		if ($now - $ctime > 15 * 60) {
			# existing lock file is older than 15 minutes, wipe it:
			unlink $lockFile;
		}
	}
	if (!sysopen(LOCKFILE, $lockFile, O_RDWR | O_CREAT | O_EXCL)) {
		if ($! == 13) {
			die _tr(qq[Unable to create lock-file <%s>, exiting!\n], $lockFile);
		} else {
			die _tr(
				qq[Lock-file <%s> exists, script is already running.
Please remove the logfile and try again if you are sure that no one else
is executing this script.\n], $lockFile
			);
		}
	}
}

sub unlockScript
{
	my $lockFile = shift;

	return if $dryRun;

	close(LOCKFILE);
	unlink $lockFile;

	return;
}

sub folderContainsFiles
{
	my $folder = shift;

	return 0 unless -d $folder;

	my $result = 0;
	my $wanted = sub {
		if ($result) {
			# skip anything else if we have found a file already
			$File::Find::prune = 1;
		}
		$result = 1 if -f;
	};
	find({wanted => $wanted, follow_fast => 1}, $folder);
	vlog(2, "result for folderContainsFiles($folder): $result\n");
	return $result;
}

sub digestAttributes
{    # returns a digest-string for the given attribute hash, in order to
	    # facilitate comparing different attribute hashes.
	my $attrs = shift;

	my $attrsAsString 
		=   join ';', 
			map { 
				my $val = $attrs->{$_} || '';
				"$_=$val";
			}
		    sort { $a cmp $b }
		    grep { isAttribute($_) } keys %$attrs;

	vlog(3, "Attribute-string: $attrsAsString");
	use Digest::MD5 qw(md5_hex);
	return md5_hex($attrsAsString);
}

sub writeAttributesToFile
{
	my $attrHash          = shift;
	my $fileName          = shift;
	my $grepForAttributes = shift;

	return if $dryRun;

	my $content = "# attributes set by slxconfig-demuxer:\n";
	my @attrs 
		= $grepForAttributes
			? grep { isAttribute($_) } sort keys %$attrHash
			: sort keys %$attrHash;
	foreach my $attr (@attrs) {
		my $attrVal = $attrHash->{$attr} || '';
		if (length($attrVal) > 0) {
			my $externalAttrName = externalAttrName($attr);
			$content .= qq[$externalAttrName="$attrVal"\n];
		}
	}
	# Overwrite attribute file even if it exists, to make sure that our users
	# will never again try to fiddle with machine-setup directly the
	# file-system. From now on the DB is the keeper of that info.
	spitFile($fileName, $content);
	if ($openslxConfig{'verbose-level'} > 2) {
		vlog(0, "--- START OF $fileName ---");
		vlog(0, $content);
		vlog(0, "--- END OF $fileName --- ");
	}
	return;
}

sub writeSlxConfigToFile
{
	my $slxConf  = shift;
	my $fileName = shift;

	return if $dryRun;

	my $content = '';
	foreach my $key (sort keys %$slxConf) {
		$content .= qq[$key="$slxConf->{$key}"\n];
	}
	spitFile($fileName, $content);
	return;
}

sub copyExternalSystemConfig
{   # copies local configuration extensions of given system from private
    # config folder (var/lib/openslx/config/...) into a temporary folder
	my $systemName = shift;
	my $targetPath = shift;
	my $clientName = shift;    # optional

	if ($targetPath !~ m[$tempPath]) {
		# bail if target-path isn't within temp folder, as we do not dare
		# executing 'rm -rf' in that case!
		die _tr("system-error: illegal target-path <%s>!", $targetPath);
	}
	return if $dryRun;

	slxsystem("rm -rf $targetPath");
	mkdir $targetPath;

	# first copy default files ...
	my $defaultConfigPath = "$clientConfigPath/default";
	vlog(2, "checking $defaultConfigPath for default config...");
	if (-d $defaultConfigPath) {
		slxsystem("cp -a $defaultConfigPath/* $targetPath");
	}
	# ... now pour system-specific configuration on top (if any):
	my $systemSpecConfigPath = "$clientConfigPath/$systemName/default";
	vlog(2, "checking $systemSpecConfigPath for system config...");
	if (folderContainsFiles($systemSpecConfigPath)) {
		slxsystem("cp -a $systemSpecConfigPath/* $targetPath");
	}
	if (defined $clientName) {
		# client has been given, so we finally pour client-specific
		# configuration on top (if any):
		my $clientSpecConfigPath = "$clientConfigPath/$systemName/$clientName";
		vlog(2, "checking $clientSpecConfigPath for client config...");
		if (folderContainsFiles($clientSpecConfigPath)) {
			slxsystem("cp -a $clientSpecConfigPath/* $targetPath");
		}
	}
	return;
}

sub createTarOfPath
{
	my $buildPath       = shift;
	my $tarName         = shift;
	my $destinationPath = shift;

	my $tarFile = "$destinationPath/$tarName";
	vlog(1, _tr('creating tar %s', $tarFile));
	return if $dryRun;

	mkdir $destinationPath;
	my $tarCmd = "cd $buildPath && tar czf $tarFile *";
	if (slxsystem("$tarCmd") != 0) {
		die _tr("unable to execute shell-command:\n\t%s \n\t(%s)", $tarCmd, $!);
	}
}

################################################################################
###
################################################################################
sub writePXEMenus
{
	my @infos = @_;

	my $pxePath       = "$tftpbootPath";
	my $pxeConfigPath = "$tftpbootPath/pxelinux.cfg";

	if (!-e "$pxePath/pxelinux.0") {
		my $pxelinux0Path =
		  "$openslxConfig{'base-path'}/share/tftpboot/pxelinux.0";
		slxsystem(qq[cp -p "$pxelinux0Path" $pxePath/]) unless $dryRun;
	}
	if (!-e "$pxePath/menu.c32") {
		my $menuc32Path = "$openslxConfig{'base-path'}/share/tftpboot/menu.c32";
		slxsystem(qq[cp -p "$menuc32Path" $pxePath/]) unless $dryRun;
	}
	if (!-e "$pxePath/vesamenu.c32") {
		my $vesamenuc32Path =
		  "$openslxConfig{'base-path'}/share/tftpboot/vesamenu.c32";
		slxsystem(qq[cp -p "$vesamenuc32Path" $pxePath/]) unless $dryRun;
	}

	# fetch PXE-template, if any:
	my $pxeTemplate =
	  "# generated by slxconfig-demuxer (on $callDate at $callTime)\n";
	my $pxeTemplateFile = "$openslxConfig{'config-path'}/PXE-template";
	if (-e $pxeTemplateFile) {
		$pxeTemplate .= slurpFile($pxeTemplateFile);
	} else {
		$pxeTemplate .= $pxeDefaultTemplate;
	}
	# PXE uses 'cp850' (codepage 850) but our string is in utf-8, we have
	# to convert in order to avoid showing gibberish on the client side...
	use Encode 'from_to';
	from_to($pxeTemplate, 'utf-8', 'cp850');

	my @clients = $openslxDB->fetchClientByFilter();
	foreach my $client (@clients) {
		my $externalClientID = externalIDForClient($client);
		my $pxeFile          = "$pxeConfigPath/$externalClientID";
		my $clientAppend     = $client->{kernel_params} || '';
		vlog(1, _tr("writing PXE-file %s", $pxeFile));
		next if $dryRun;
		my $pxeFH;
		open($pxeFH, '>', $pxeFile)
			or croak _tr("unable to create file '%s' (%s)\n", $pxeFile, $!);
		print $pxeFH $pxeTemplate;
		my %systemIDs;
		@systemIDs{$openslxDB->aggregatedSystemIDsOfClient($client)} = ();
		my @systemInfos = grep { exists $systemIDs{$_->{id}} } @infos;
		# now @systemInfos holds all infos relevant to this client
		foreach my $info (@systemInfos) {
			my $extID      = $info->{'vendor-os'}->{name};
			my $kernelName = basename($info->{'kernel-file'});
			my $append     = $info->{kernel_params};
			$append .= " initrd=$extID/$info->{'initramfs-name'}";
			$append .= " $clientAppend";
			print $pxeFH "LABEL openslx-$info->{'external-id'}\n";
			print $pxeFH "\tMENU LABEL ^$info->{label}\n";
			print $pxeFH "\tKERNEL $extID/$kernelName\n";
			print $pxeFH "\tAPPEND $append\n";
			print $pxeFH "\tIPAPPEND 1\n";
		}
		close($pxeFH)
			or croak _tr("unable to close file '%s' (%s)\n", $pxeFile, $!);
	}
	return;
}

sub generateInitalRamFS
{
	my $info            = shift;
	my $pxeVendorOSPath = shift;

	my $vendorOS = $info->{'vendor-os'};

	my $osExportEngine = instantiateClass("OpenSLX::OSExport::Engine");
	$osExportEngine->initializeFromExisting($info->{export}->{name});

	vlog(1, _tr('generating initialramfs %s/initramfs', $pxeVendorOSPath));
	my $cmd = "$openslxConfig{'base-path'}/bin/mkdxsinitrd ";
	if ($info->{attr_ramfs_nicmods}) {
		$cmd .= qq[-n "$info->{attr_ramfs_nicmods}" ];
	}
	my $fsMods = $info->{attr_ramfs_fsmods} || '';
	$fsMods .= ' ' . $osExportEngine->requiredFSMods();
	if ($fsMods) {
		$cmd .= qq[-f "$fsMods" ];
	}
	if ($info->{attr_ramfs_miscmods}) {
		$cmd .= qq[-m "$info->{attr_ramfs_miscmods}" ];
	}
	my $rootPath = "$openslxConfig{'private-path'}/stage1/$vendorOS->{name}";
	$cmd .= "-i $pxeVendorOSPath/$info->{'initramfs-name'} -r $rootPath ";

	# pass in system name:
	$cmd .= "-S $info->{name} ";

	# use theme 'openslx':
	$cmd .= "-s openslx ";

	# always use dhclient instead of the busybox-provided dhcp-client
	# (since the latter is unable to fetch NIS-stuff):
	$cmd .= "-d ";

	# generate initramfs-setup file (with settings relevant for initramfs only):
	my $initramfsAttrFile = "$tempPath/initramfs-setup";
	my $initramfsAttrs    = {
		'host_name'		=> 'slx-client', # silly default just to have something
		'ramfs_fsmods'  => $info->{'attr_ramfs_fsmods'} || '',
		'ramfs_nicmods' => $info->{'attr_ramfs_nicmods'} || '',
		'ramfs_screen'  => $info->{'attr_ramfs_screen'} || '',
		'rootfs'        => $info->{'export-uri'} || '',
	};
	writeAttributesToFile($initramfsAttrs, $initramfsAttrFile, 0);
	# and pass the generated initramfs-setup file to mkdxsinitrd:
	$cmd .= "-c $initramfsAttrFile ";

	# ... set kernel version ...
	my $kernelFile = basename(followLink($info->{'kernel-file'}));
	$kernelFile =~ m[-(.+)$];
	my $kernelVersion = $1;
	$cmd .= "-k $kernelVersion ";

	# ... add version info ...
	my $slxver = `slxversion`;
	chomp $slxver;
	$ENV{'SLX_VERSION'} = $slxver;

	# ... finally invoke mkdxsinitrd:
	slxsystem($cmd) unless $dryRun;
	return;
}

sub writeSystemPXEFiles
{
	my $info = shift;

	my $kernelFile = $info->{'kernel-file'};
	my $kernelName = basename($kernelFile);

	my $pxePath         = "$tftpbootPath";
	my $pxeVendorOSPath = "$pxePath/$info->{'vendor-os'}->{name}";
	mkdir $pxeVendorOSPath unless -e $pxeVendorOSPath || $dryRun;

	my $targetKernel = "$pxeVendorOSPath/$kernelName";
	if (!-e $targetKernel) {
		vlog(1, _tr('copying kernel %s to %s', $kernelFile, $targetKernel));
		slxsystem(qq[cp -p "$kernelFile" "$targetKernel"]) unless $dryRun;
	}
	$vendorOSInitramfsMap{$info->{'vendor-os'}->{id}}++;
	$info->{'initramfs-name'} =
	  sprintf("initramfs-%d",
		$vendorOSInitramfsMap{$info->{'vendor-os'}->{id}});
	generateInitalRamFS($info, $pxeVendorOSPath);
	return;
}

sub writeDhcpConfig
{
	vlog(0, _tr("sorry, exporting dhcp data is not implemented yet!"));
	my $dhcpModule = "OpenSLX::Export::DHCP::$dhcpType";
	if (!eval { require $dhcpModule } ) {
		die _tr("unable to load DHCP-Export backend '%s'! (%s)\n",
			$dhcpModule, $@);
	}
	my $dhcpBackend = $dhcpModule->new();
	my @clients     = $openslxDB->fetchClientByFilter();
	$dhcpBackend->execute(\@clients);
	return;
}

sub writeClientConfigurationsForSystem
{
	my $info      = shift;
	my $buildPath = shift;
	my $attrFile  = shift;

	my @clientIDs = $openslxDB->aggregatedClientIDsOfSystem($info);
	my @clients   = $openslxDB->fetchClientByID(\@clientIDs);
	foreach my $client (@clients) {
		next if $client->{name} eq '<<<default>>>';
			# skip default client, as it doesn't need any config-tgz

		my $externalSystemID   = externalIDForSystem($info);
		my $externalClientName = externalConfigNameForClient($client);
		my $clientConfigPath   =
		  "$clientConfigPath/$externalSystemID/$externalClientName";

		# merge configurations of client, it's groups, default client and
		# system and write the resulting attributes to a configuration file:
		$openslxDB->mergeDefaultAndGroupAttributesIntoClient($client);
		mergeAttributes($client, $info);

		my $clientAttrDigest = digestAttributes($client);
		vlog(
			2,
			_tr(
				"attribute-digest for client '%s' is '%s'", $client->{name},
				$clientAttrDigest
			)
		);
		# export client-specific config only if attributes are different
		# from system and/or a client-specific config-folder exists:
		if ($clientAttrDigest ne $info->{'attr-digest'}
			|| -d $clientConfigPath)
		{
			vlog(
				1,
				_tr(
					"creating config-tgz for client %d:%s", $client->{id},
					$client->{name}
				)
			);
			$clientSystemConfCount++;

			# merge default, system and client configuration files into
			# the system configuration for the current client:
			copyExternalSystemConfig($externalSystemID, $buildPath,
				$externalClientName);

			writeAttributesToFile($client, $attrFile, 1);

			# create tar containing external system configuration
			# and client attribute file, this time referring to the client
			# via its external ID (the PXE-style MAC), as the TGZ needs to
			# be accessed from the client-PC, which doesn't know about the
			# name it is referred to in the openslx-config-DB:
			my $externalClientID = externalIDForClient($client);
			createTarOfPath($buildPath, "${externalClientID}.tgz",
				"$tftpbootPath/client-config/$info->{'external-id'}");
		}
	}
	return;
}

sub writePluginConfigurationsForSystem
{
	my $info      = shift || confess 'need to pass in info-hash!';
	my $buildPath = shift || confess 'need to pass in build-path!';

	my $pluginConfPath = "$buildPath/initramfs/plugin-conf";
	slxsystem("mkdir -p $pluginConfPath") unless -d $pluginConfPath;

	my $pluginInitdPath = "$buildPath/initramfs/plugin-init.d";
	slxsystem("mkdir -p $pluginInitdPath") unless -d $pluginInitdPath;
	
	foreach my $pluginName (OpenSLX::OSPlugin::Engine->getAvailablePlugins()) {
		vlog(2, _tr("writing configuration file for plugin '%s'", $pluginName));

		# create plugin engine and fetch specific plugin module config hash:
		my $pluginEngine = OpenSLX::OSPlugin::Engine->new();
		$pluginEngine->initialize($pluginName, $info->{'vendor-os'}->{name});
		my $config = $pluginEngine->getPlugin()->getConfig();
		
		# skip inactive plugins
		next unless $config->{active};

		# write plugin configuration to a file:
		my $content;
		foreach my $attr (sort keys %$config) {
			my $attrVal = $config->{$attr} || '';
			if (length($attrVal) > 0) {
				my $externalAttrName = externalAttrName($attr);
				$content .= qq[$externalAttrName="$attrVal"\n];
			}
		}
		my $fileName = "$pluginConfPath/${pluginName}.conf";
		spitFile($fileName, $content);
		if ($openslxConfig{'verbose-level'} > 2) {
			vlog(0, "--- START OF $fileName ---");
			vlog(0, $content);
			vlog(0, "--- END OF $fileName --- ");
		}
		
		# copy runlevel script to be used in stage3:
		my $precedence = sprintf('%02d', $config->{precedence});
		my $scriptFolder 
			= "$openslxConfig{'base-path'}/lib/plugins/$pluginName";
		my $scriptName = "$scriptFolder/XX_${pluginName}.sh";
		my $targetName = "$pluginInitdPath/${precedence}_${pluginName}.sh";
		if (slxsystem("cp $scriptName $targetName && chmod a+x $targetName")) {
			die _tr(
				"unable to copy runlevel script '%s' to '%s'! (%s)",
				$scriptName, $targetName, $!
			);
		}
	}
	return;
}

sub writeSystemConfiguration
{
	my $info = shift;

	my $buildPath = "$tempPath/build";
	copyExternalSystemConfig(externalIDForSystem($info), $buildPath);

	$openslxDB->mergeDefaultAttributesIntoSystem($info);
	$info->{'attr-digest'} = digestAttributes($info);
	vlog(
		2,
		_tr(
			"attribute-digest for system '%s' is '%s'", $info->{name},
			$info->{'attr-digest'}
		)
	);
	my $attrFile = "$buildPath/initramfs/machine-setup";
	writeAttributesToFile($info, $attrFile, 1);
	
	writePluginConfigurationsForSystem($info, $buildPath);

	my $systemPath = "$tftpbootPath/client-config/$info->{'external-id'}";
	createTarOfPath($buildPath, "default.tgz", $systemPath);

	writeSystemPXEFiles($info);

	writeClientConfigurationsForSystem($info, $buildPath, $attrFile);

	slxsystem("rm -rf $buildPath") unless $dryRun;
	return;
}

sub writeConfigurations
{
	$systemConfCount = $clientSystemConfCount = 0;
	my @systems = $openslxDB->fetchSystemByFilter();
	my @infos;
	foreach my $system (@systems) {
		next if $system->{name} eq '<<<default>>>';

		vlog(
			0,	_tr('exporting system %d : %s', $system->{id}, $system->{name})
		);
		$systemConfCount++;

		my $info = $openslxDB->aggregatedSystemFileInfoFor($system);
		$info->{'external-id'} = externalIDForSystem($system);

		writeSystemConfiguration($info);

		push @infos, $info;
	}
	writePXEMenus(@infos);
	if (defined $dhcpType) {
		writeDhcpConfig();
	}
	return;
}

=head1 NAME

slxconfig-demuxer - OpenSLX configuration demultiplexer

=head1 SYNOPSIS

slxconfig-demuxer [options]

=head3 Script Options

    --dhcp-export-type=<string>  specifies the type of DHCP-server
                                 (ISC,...)
    --dry-run                    avoids writing anything, for testing

=head3 General Options

    --help                       brief help message
    --man                        full documentation
    --version                    show version

=head1 DESCRIPTION

B<slxconfig-demuxer> will read information about all systems, clients and
groups from the OpenSLX configuration database, mix & match the individual
configurational attributes and then demultiplex the resulting information
to a set of configuration files. These files are used by any OpenSLX-client
during boot to find out which systems to offer for booting.

The resulting files will be put into the OpenSLX-tftpboot-path.

=head2 FILE CREATION

The following set of files will be created:

=over 8

=item B<Basic PXE Setup>

The basic PXE files (F<menu.c32>, F<pxelinux.0>) will be copied into
F<$SLX_PUBLIC_PATH/tftpboot> to make them available to any PXE-client via tftp.

=item B<PXE Client Configurations>

For each client, a PXE configuration file will be generated and written to
F<$SLX_PUBLIC_PATH/tftpboot/pxelinux.cfg/01-<MAC-of-client>>. This file will
contain information about the systems this client shall offer for booting.
For each of these systems, the kernel cmdline options required for that
particular system setup is specified (via PXE's APPEND option).

Any client that is not known to OpenSLX (so it will not have a specific
configuration file) will use the configuration from the default client 
(appropriately named 'default').

=item B<System Kernels and Initialram-Filesystems>

For each bootable system, that system's kernel will be copied to
F<$SLX_PUBLIC_PATH/tftpboot/<vendor-os-name>/kernel and an OpenSLX-specific initramfs
required for booting that particular system is generated (by means of
slxmkramfs) and put into F<$SLX_PUBLIC_PATH/tftpboot/<vendor-os-name>/initramfs.

These two files (kernel & initramfs) will be referenced by the PXE client
configuration of all clients that offer this specific system for booting.

=item B<OpenSLX Client Configurations>

For each system, an OpenSLX configuration archive will be generated and written 
to F<$SLX_PUBLIC_PATH/tftpboot/client-config/<system-name>/default. Furthermore, 
every client of that system whose attributes differ from the system's default
will get its own configuration archive generated here, too (e.g. 
F<$SLX_PUBLIC_PATH/tftpboot/client-config/<system-name>/01-<MAC-of-client>.tgz>).

Each of these archives will contain the file F<initramfs/machine-setup>, 
specifying all the attributes of that particular system and/or client 
(e.g. whether or not it should start the X-server).

Furthermore, each system-specific archive may contain additional system files 
that are required for that system (e.g. a special PAM-module required for LDAP 
authentication). These files are copied from F<$SLX_PRIVATE_PATH/config/default>
and F<$SLX_PROVATE_PATH/config/<system-name>>.

On top of that, each client may have its own set of system files, too (e.g.
some config files required to install a special kind of hardware available only
on that client). These files are copied from 
F<< $SLX_PROVATE_PATH/config/<system-name>/01-<MAC-of-client> >>.
=back

=head2 MIXING & MATCHING (THE DEMUXER)

In the OpenSLX configuration database, each system, group and client may have
several configurational attributes set to a specific value that will cause
a client booting that system to behave in a certain way. The mixing of all
these different attributes into one set that is relevant for a specific client
booting one specific system is one important task of the slxconfig-demuxer.

As an example, let's assume one system setup that is configured to boot directly
into a special application that demands a rather low screen-resolution of
1024x768 pixels, as otherwise the text would be unreadable due to very small
fonts being used by that app. In order to achieve this, the administrator can
set the I<hw_monitor>-attribute of the B<system> to '1024x768'.
Let's say one of the clients, however, is connected to a very old monitor that
has problems with this resolution and only supports 800x600 pixels. In that
case, the administrator can set the I<hw_monitor>-attribute of that B<client> to
'800x600'. The mixing & matching process would make sure that this specific
client would run that system with a resolution of 800x600, while all other
clients would run that system in 1024x768.

So the slxconfig-demuxer demultiplexes the individual configurational attributes
into a concrete set of configuration settings for specific clients and their
offered systems, making sure that each client/system combination uses the
appropriate settings.

=head1 OPTIONS

=head3 Script Options

=over 8

=item B<<     --dhcp-export-type >>

Specifies the type of DHCP-export that shall be used. Currently, only 'ISC' is
supported.

=item B<<     --dry-run >>

Runs the script but avoids writing anything. This is useful for testing, as
you can learn from the logging output what would have been done.

=back

=head3 General Options

=over 8

=item B<<     --help >>

Prints a brief help message and exits.

=item B<<     --man >>

Prints the manual page and exits.

=item B<<     --version >>

Prints the version and exits.

=back

=head1 SEE ALSO

slxsettings, slxos-setup, slxos-export, slxconfig

=head1 GENERAL OPENSLX OPTIONS

Being a part of OpenSLX, this script supports several other options
which can be used to overrule the OpenSLX settings:

    --db-name=<string>         name of database
    --db-spec=<string>         full DBI-specification of database
    --db-type=<string>         type of database to connect to
    --locale=<string>          locale to use for translations
    --logfile=<string>         file to write logging output to
    --private-path=<string>    path to private data
    --public-path=<string>     path to public (client-accesible) data
    --temp-path=<string>       path to temporary data
    --verbose-level=<int>      level of logging verbosity (0-3)

Please refer to the C<slxsettings>-manpage for a more detailed description
of these options.

=cut