* added support for --help, --man and --version

git-svn-id: http://svn.openslx.org/svn/openslx/trunk@426 95ad53e4-c205-0410-b2fa-d234c58c8868

1 files changed, 273 insertions, 1 deletions

diff --git a/config-db/slxconfig-demuxer.pl b/config-db/slxconfig-demuxer.pl
index 2c469ded..8221ebf9 100755
--- a/config-db/slxconfig-demuxer.pl
+++ b/config-db/slxconfig-demuxer.pl
@@ -8,6 +8,7 @@ use lib $FindBin::Bin;
 use Fcntl qw(:DEFAULT :flock);
 use File::Basename;
 use Getopt::Long qw(:config pass_through);
+use Pod::Usage;
 
 use OpenSLX::Basics;
 use OpenSLX::ConfigDB qw(:access :aggregation :support);
@@ -30,13 +31,25 @@ my (
 		# number of system configurations written
 	$clientSystemConfCount,
 		# number of (system-specific) client configurations written
+	$helpReq,
+	$manReq,
+	$versionReq,
 );
 
 GetOptions(
 	'dry-run' => \$dryRun,
 		# dry-run doesn't write anything, just prints statistic about what
 		# would have been written
-);
+	'help|?' => \$helpReq,
+	'man' => \$manReq,
+	'version' => \$versionReq,
+) or pod2usage(2);
+pod2usage(1) if $helpReq;
+pod2usage(-verbose => 2) if $manReq;
+if ($versionReq) {
+	system('slxversion');
+	exit 1;
+}
 
 openslxInit();
 
@@ -339,3 +352,262 @@ sub writeConfigurations
 	writePXEMenus();
 }
 
+__END__
+
+=head1 NAME
+
+slxconfig-demuxer.pl - OpenSLX configuration demultiplexer
+
+=head1 SYNOPSIS
+
+slxconfig-demuxer.pl [options]
+
+  Script Options:
+      --dry-run           avoids writing anything, for testing
+
+  OpenSLX Options:
+      --db-basepath=s     basic path to openslx database
+      --db-datadir=s      data folder created under db-basepath
+      --db-spec=s         full DBI-specification of database
+      --db-name=s         name of database
+      --db-type=s         type of database to connect to (CSV, SQLite, ...)
+      --locale=s          locale to use for translations
+      --logfile=s         file to write logging output to
+      --bin-path=s        path to binaries and scripts
+      --config-path=s     path to configuration files
+      --base-path=s       basic path to project files
+      --export-path=s     path to root of all exported filesystems
+      --private-path=s    path to private data
+      --public-path=s     path to public (client-accesible) data
+      --share-path=s      path to sharable data
+      --temp-path=s       path to temporary data
+      --tftpboot-path=s   path to root of tftp-server
+      --verbose-level=i   level of logging verbosity (0-3)
+
+  General Options:
+      --help              brief help message
+      --man               full documentation
+
+=head1 OPTIONS
+
+=head2 Script Options
+
+=over 8
+
+=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
+
+=head2 OpenSLX Options
+
+=over 8
+
+=item B<--base-path=s>
+
+Sets basic path to project files.
+
+Default is $SLX_BASE_PATH (usually F</opt/openslx>).
+
+=item B<--bin-path=s>
+
+Sets path to binaries and scripts.
+
+Default is $SLX_BASE_PATH/bin (usually F</opt/openslx/bin>).
+
+=item B<--config-path=s>
+
+Sets path to configuration files.
+
+Default is $SLX_CONFIG_PATH (usually F</etc/opt/openslx>).
+
+=item B<--db-basepath=s>
+
+Sets basic path to openslx database.
+
+Default is $SLX_DB_PATH (usually F</var/opt/openslx/db>).
+
+=item B<--db-datadir=s>
+
+Sets data folder created under db-basepath.
+
+Default is $SLX_DB_DATADIR (usually empty as it depends on db-type
+whether or not such a directory is required at all).
+
+=item B<--db-name=s>
+
+Gives the name of the database to connect to.
+
+Default is $SLX_DB_NAME (usually C<openslx>).
+
+=item B<--db-spec=s>
+
+Gives the full DBI-specification of database to connect to. Content depends
+on the db-type.
+
+Default is $SLX_DB_SPEC (usually empty as it will be built automatically).
+
+=item B<--db-type=s>
+
+Sets the type of database to connect to (CSV, SQLite, mysql, ...).
+
+Default $SLX_DB_TYPE (usually C<CSV>).
+
+=item B<--export-path=s>
+
+Sets path to root of all exported filesystems. For each type of export (NFS,
+NBD, ...) a separate folder will be created in here.
+
+Default is $SLX_EXPORT_PATH (usually F</srv/openslx/export>.
+
+=item B<--locale=s>
+
+Sets the locale to use for translations.
+
+Defaults to the system's standard locale.
+
+=item B<--logfile=s>
+
+Specifies a file where logging output will be written to.
+
+Default is to log to STDERR.
+
+=item B<--private-path=s>
+
+Sets path to private data, where the config-db, vendor_oses and configurational
+extensions will be stored.
+
+Default is $SLX_PRIVATE_PATH (usually F</var/opt/openslx>.
+
+=item B<--public-path=s>
+
+Sets path to public (client-accesible) data.
+
+Default is $SLX_PUBLIC_PATH (usually F</srv/openslx>.
+
+=item B<--share-path=s>
+
+Sets path to sharable data, where distro-specs and functionality templates
+will be stored.
+
+Default is $SLX_SHARE_PATH (usually F</opt/openslx/share>.
+
+=item B<--temp-path=s>
+
+Sets path to temporary data.
+
+Default is $SLX_TEMP_PATH (usually F</tmp>.
+
+=item B<--tftpboot-path=s>
+
+Sets path to root of tftp-server from which clients will access their files.
+
+Default is $SLX_TFTPBOOT_PATH (usually F</srv/openslx/tftpboot>.
+
+=item B<--verbose-level=i>
+
+Sets the level of logging verbosity (0-3).
+
+Default is $SLX_VERBOSE_LEVEL (usually 0, no logging).
+
+=back
+
+=head2 General Options
+
+=over 8
+
+=item B<--help>
+
+Prints a brief help message and exits.
+
+=item B<--man>
+
+Prints the manual page and exits.
+
+=back
+
+=head1 DESCRIPTION
+
+B<slxconfig-demuxer.pl> 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 (you can use the
+option B<--tftpboot-path> to override the default taken from the OpenSLX
+default settings).
+
+=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_TFTPBOOT_PATH/pxe> 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_TFTPBOOT_PATH/pxe/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).
+
+=item B<System Kernels and Initialram-Filesystems>
+
+For each bootable system, that system's kernel will be copied to
+F<$SLX_TFTPBOOT_PATH/pxe/<system-name>/kernel and an OpenSLX-specific initramfs
+required for booting that particular system is generated (by means of
+slxmkramfs) and put into F<$SLX_TFTPBOOT_PATH/pxe/<system-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 combination of system and client, an OpenSLX configuration archive
+will be generated and written to
+F<$SLX_TFTPBOOT_PATH/client-config/<system-name>/01-<MAC-of-client>.tgz>.
+This archive will contain the file F<initramfs/machine-setup>, specifying all
+the attributes of that particular client (e.g. whether or not it should start
+the X-server).
+
+Furthermore, the archive may contain additional system files that are
+required for the client (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>>.
+
+=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.
+
+=cut