# 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/ # ----------------------------------------------------------------------------- # Base.pm # - provides empty base of the OpenSLX OSPlugin API. # ----------------------------------------------------------------------------- package OpenSLX::OSPlugin::Base; use strict; use warnings; our $VERSION = 1.01; # API-version . implementation-version =head1 NAME OpenSLX::OSPlugin::Base - the base class for all OpenSLX OS-plugins. =head1 DESCRIPTION This class defines the OpenSLX API for OS-plugins. The general idea behind OS-plugins is to extend any installed vendor-OS with a specific features. Each feature is implemented as a separate, small software component in order to make them easy to understand and maintain. Since all of these software components are plugged into the OpenSLX system by means of a common API, we call them Bs. This API can be separated into different parts: =over =item - L (provide info about a plugin) =item - L (installing or removing a plugin into/from a vendor-OS) =item - L (integrating a plugin into an initramfs) =back =head1 MORE INFO Please read the user-level introduction on plugins in the OpenSLX-wiki: L (in German). If you'd like to know how a plugin is implemented, please have a look at the 'example' plugin, which contains some explainations and useful hints. If you have any questions regarding the concept of OS-plugins and their implementation, please drop a mail to: ot@openslx.com, or join the IRC-channel '#openslx' (on freenode). =cut use OpenSLX::Basics; =head1 PLUGIN API =head2 Declarative Interface =over =item new() Every plugin should provide a new-method and provide it's own name in the 'name' entry of $self. Please note that by convention, plugin names are all lowercase! =cut sub new { confess "Creating OpenSLX::OSPlugin::Base-objects directly makes no sense!"; } =item initialize() Initializes basic context for this plugin (esp. a reference to the OSPlugin engine that drives this plugin. =cut sub initialize { my $self = shift; $self->{'os-plugin-engine'} = shift; $self->{'distro'} = shift; return; } =item getInfo() Returns a hash-ref with administrative information about this plugin (what does it do and how does it relate to other plugins). Every plugin needs to provide this method and return the information about itself. =cut sub getInfo { my $self = shift; return { # a short (one-liner) description of this plugin description => '', }; } =item getAttrInfo() Returns a hash-ref with information about all attributes supported by this specific plugin. This default configuration will be added as attributes to the default system, such that it can be overruled for any specific system by means of B. The returned hash-ref must include at least the following entries: =over =item B::active> Indicates whether or not this plugin is active (1 for active, 0 for inactive). =item B::precedence> Specifies the execution precedence of this plugin with respect to all other plugins (plugins with lower precedences will be started before the ones with a higher precedence). Valid values range from 0-99. If your plugin does not have any requirements in this context, just specify the default value '50'. =back =cut sub getAttrInfo { my $self = shift; # This default configuration will be added as attributes to the default # system, such that it can be overruled for any specific system by means # of slxconfig. return { # attribute 'active' is mandatory for all plugins # attribute 'precedence' is mandatory for all plugins }; } =item getDefaultAttrsForVendorOS() Returns a hash-ref with the default attribute values for the given vendor-OS. =cut sub getDefaultAttrsForVendorOS { my $self = shift; # the default implementation does not change the default values at all: return $self->getAttrInfo(); } =back =head2 Vendor-OS Interface =over =item installationPhase() In this method, the plugin should install itself into the given vendor-OS. What "installation" means is up to the plugin. Some plugins may just copy a file from the OpenSLX host installation into the vendor-OS, while others may need to download files from the internet and/or install packages through the vendor-OS' meta packager. N.B.: This method is invoked while chrooted into the vendor-OS root. In order to make the OpenSLX files from the host available, the OpenSLX base folder (normally /opt/openslx) will be mounted to /mnt/openslx. So if you have to copy any files from the host, fetch them from there. =cut sub installationPhase { my $self = shift; my $pluginRepositoryPath = shift; # the repository folder, relative to the vendor-OS root my $pluginTempPath = shift; # the temporary folder, relative to the vendor-OS root my $openslxPath = shift; # the openslx base path bind-mounted into the chroot (/mnt/openslx) return; } =item removalPhase() In this method, the plugin should remove itself from the given vendor-OS. What "removal" means is up to the plugin. Some plugins may just delete a file from the vendor-OS, while others may need to uninstall packages through the vendor-OS' meta packager. N.B.: This method is invoked while chrooted into the vendor-OS root. =cut sub removalPhase { my $self = shift; my $pluginRepositoryPath = shift; # the repository folder, relative to the vendor-OS root my $pluginTempPath = shift; # the temporary folder, relative to the vendor-OS root my $openslxPath = shift; # the openslx base path bind-mounted into the chroot (/mnt/openslx) return; } =back =head2 Initramfs Interface All of the following methods are invoked by the config demuxer when it makes an initramfs for a system that has this plugin activated. Through these methods, each plugin can integrate itself into that initramfs. =over =item suggestAdditionalKernelParams() Called in order to give the plugin a chance to add any kernel params it requires. In order to do so, the plugin should return a list of additional kernel params that it would like to see added. =cut sub suggestAdditionalKernelParams { my $self = shift; my $makeInitRamFSEngine = shift; return; } =item suggestAdditionalKernelModules() Called in order to give the plugin a chance to add any kernel modules it requires. In order to do so, the plugin should return the names of additional kernel modules that it would like to see added. =cut sub suggestAdditionalKernelModules { my $self = shift; my $makeInitRamFSEngine = shift; return; } =item copyRequiredFilesIntoInitramfs() Called in order to give the plugin a chance to copy all required files from the vendor-OS into the initramfs. N.B.: Only files that are indeed required by the initramfs should be copied here, i.e. files that are needed *before* the root-fs has been mounted. All other files should be taken from the root-fs instead! =cut sub copyRequiredFilesIntoInitramfs { my $self = shift; my $targetPath = shift; my $attrs = shift; my $makeInitRamFSEngine = shift; return; } =item setupPluginInInitramfs() Called in order to let the plugin setup all the files it requires in the initramfs. Normally, you don't need to override this method in your own plugin, as it is usually enough to override suggestAdditionalKernelParams(), suggestAdditionalKernelModules() and maybe copyRequiredFilesIntoInitramfs(). =cut sub setupPluginInInitramfs { my $self = shift; my $attrs = shift; my $makeInitRamFSEngine = shift; my $pluginName = $self->{name}; my $pluginSrcPath = "$openslxConfig{'base-path'}/lib/plugins"; my $buildPath = $makeInitRamFSEngine->{'build-path'}; my $pluginInitdPath = "$buildPath/etc/plugin-init.d"; my $initHooksPath = "$buildPath/etc/init-hooks"; # copy runlevel script my $precedence = sprintf('%02d', $attrs->{"${pluginName}::precedence"}); my $scriptName = "$pluginSrcPath/$pluginName/XX_${pluginName}.sh"; my $targetName = "$pluginInitdPath/${precedence}_${pluginName}.sh"; if (-e $scriptName) { $makeInitRamFSEngine->addCMD("cp $scriptName $targetName"); $makeInitRamFSEngine->addCMD("chmod a+x $targetName"); } # copy init hook scripts, if any if (-d "$pluginSrcPath/$pluginName/init-hooks") { my $hookSrcPath = "$pluginSrcPath/$pluginName/init-hooks"; $makeInitRamFSEngine->addCMD( "cp -r $hookSrcPath/* $buildPath/etc/init-hooks/" ); } # invoke hook methods to suggest additional kernel params ... my @suggestedParams = $self->suggestAdditionalKernelParams($makeInitRamFSEngine); if (@suggestedParams) { my $params = join ' ', @suggestedParams; vlog(1, "plugin $pluginName suggests these kernel params: $params"); $makeInitRamFSEngine->addKernelParams(@suggestedParams); } # ... and kernel modules my @suggestedModules = $self->suggestAdditionalKernelModules($makeInitRamFSEngine); if (@suggestedModules) { my $modules = join(',', @suggestedModules); vlog(1, "plugin $pluginName suggests these kernel modules: $modules"); $makeInitRamFSEngine->addKernelModules(@suggestedModules); } # invoke hook method to copy any further files that are required in stage3 # before the root-fs has been mounted $self->copyRequiredFilesIntoInitramfs( $buildPath, $attrs, $makeInitRamFSEngine ); return 1; } =back 1;