path: root/os-plugins/OpenSLX/OSPlugin/Base.pm

# 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 B<OS-plugin>s.

This API can be separated into different parts:

=over

=item - L</Declarative Interface> (provide info about a plugin)

=item - L</Vendor-OS Interface> (installing or removing a plugin into/from a 
vendor-OS)

=item - L</Initramfs Interface> (integrating a plugin into an initramfs)

=back

=head1 MORE INFO

Please read the user-level introduction on plugins in the OpenSLX-wiki:
L<http://openslx.org/trac/de/openslx/wiki/PluginKonzept> (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<slxconfig>.

The returned hash-ref must include at least the following entries:

=over

=item B<I<plugin-name>::active>

Indicates whether or not this plugin is active (1 for active, 0 for inactive).

=item B<I<plugin-name>::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;