The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
App-LXC-Container-0.20
River stage zero No dependents
++
/ App::LXC::Container::Data

NAME

App::LXC::Container::Data - provide OS-specific data for App::LXC::Container

SYNOPSIS

    # This module should never be used directly!
    # It is used indirectly via the following:
    use App::LXC::Container;

ABSTRACT

This module provides the general and OS-specific configuration data (meaning data specific to a subset of different Linux distributions) used by the main package App::LXC::Container. This can be both static data (like the basic LXC network configuration) as well as dynamic data (like the list of files of installed software packages).

DESCRIPTION

The documentation of this module is only intended for developers of the package itself. Data is provided using an object-oriented approach: Everything that behaves identically across all supported Linux distributions is defined in the module Data::common. This is included by a module for a basic distribution, e.g. the module Data::Debian. Those may extend, modify or overwrite the common configuration. Additional levels may be added by derived Linux distributions, e.g. with the module Data::Ubuntu. Data.pm itself then maps this internal OO-design into a functional one hiding the internal singleton object.

Development hint

During development everything not already clearly OS-specific is put into the common module first. When support for another distribution is added, the configuration is migrated into the appropriate OS-specific module(s).

EXPORT

All access functions are exported by default as that's the point of this module.

FUNCTIONS (general)

The Data module provides the following general functions (alphabetically, case-insensitive):

find_executable - find executable in PATH

    $dir = find_executable($exec);

parameters:

    $exec               executable to search for (must be a base-name)

description:

This function searches for an executable in the standard search path (as defined by the environment variable PATH) and returns the absolute path of the first one found. Note that only absolute paths are checked. Also note that the executable must be indeed executable for the current user.

returns:

    absolute path to the executable, C<undef> if not found

groups_of - get groups of account

    @groups = groups_of($user);

parameters:

    $user               account of user

description:

This function returns the list of all groups a user belongs to.

returns:

    list of groups, should never be empty

initial_network_list - return initial list of networks

    @output = initial_network_list();

description:

This function returns the initial list of containers using a network.

returns:

hard-coded header of network list

FUNCTIONS (OS-specific)

(We don't use general dynamic function as we want to add some minimal documentation for each one anyway and fail cleanly in case of missing ones. In addition this makes maintenance easier.)

The Data module provides the following OS-specific functions (alphabetically, case-insensitive):

content_audio_packages - return package configuration for audio

    @output = content_audio_packages();

description:

This function returns the additional package configuration needed to support audio within an application container. The content depends on the distribution used.

returns:

array of configuration lines

content_device_default - return default device configuration

    @output = content_device_default();

description:

This function returns the basic device configuration for the application containers (lxc. variables configuring the setup of the directory /dev).

returns:

array of configuration lines

content_default_filter - return default filter

    @output = content_default_filter();

description:

This function returns the default filter of directories that are never automatically derived from packages. The content depends on the distribution used.

returns:

array of configuration lines

content_default_mounts - return default mount configuration

    @output = content_default_mounts();

description:

This function returns the minimal mount configuration for the application containers. The content depends on the distribution used.

returns:

array of configuration lines

content_default_packages - return default packages

    @output = content_default_packages();

description:

This function returns the minimal list of packages that are always needed for application containers. The content depends on the distribution used.

returns:

array of configuration lines

content_network_default - return default network configuration

    @output = content_network_default();

description:

This function returns the basic network configuration for the application containers (lxc.net.0.*).

returns:

array of configuration lines

content_network_mounts - return mount configuration for network

    @output = content_network_mounts();

description:

This function returns the additional mount configuration needed to run applications having network access within the application container. The content depends on the distribution used.

returns:

array of configuration lines

content_network_packages - return package configuration for network

    @output = content_network_packages();

description:

This function returns the additional package configuration needed to run applications having network access within the application container. The content depends on the distribution used.

returns:

array of configuration lines

content_x11_mounts - return mount configuration for X11

    @output = content_x11_mounts();

description:

This function returns the additional mount configuration needed run X11 applications within the application container. The content depends on the distribution used.

returns:

array of configuration lines

content_x11_packages - return mount configuration for X11

    @output = content_x11_packages();

description:

This function returns the additional package configuration needed to support X11 within an application container. The content depends on the distribution used.

returns:

array of configuration lines

depends_on - find installed dependencies of package

    @packages = depends_on($package, $include);

parameters:

    $package            name of dependent package
    $include            types of dependencies to be used

description:

This function returns all installed dependencies of the given package (all packages that it depends on). This always includes mandatory dependencies. With a positive 2nd parameter recommended dependencies are included as well. Finally with a 2nd parameter greater than 1 optional (suggested) dependencies are also included.

Note that further calls for the same package will always return an empty list for performance reasons. The calling will not terminate if this is changed.

returns:

    all prerequisites of given package

package_of - find package of file

    $package = package_of($file);

parameters:

    $file               absolute path to file to search for

description:

This function searches for the given file in all installed packages and returns the first one containing it.

returns:

    name of first package containing given file, C<undef> if not found

paths_of - get list of paths of package

    @paths = paths_of($package);

parameters:

    $package            name of package

description:

This function returns a list of all absolute paths (files and maybe directories) installed by the given package.

returns:

    list of absolute paths

regular_users - return list of regular users

    @users = regular_users();

description:

This function returns a list of all users on the system having a home directory beneath a path beginning with /home.

returns:

    list of all regular users

INTRNAL FUNCTIONS

The following functions may only be used internally:

_singleton - return OS-specific singleton object

    $_ = _singleton();

description:

This function returns the OS-specific singleton object. If the object does not yet exist, the function checks the running OS by checking the variables ID and ID_LIKE of the file /etc/os-release. It then loads the matching internal data module (Data/OS.pm) providing the appropriate configuration.

returns:

OS-specific singleton

KNOWN BUGS

The current default configuration should work for Debian and probably also for Ubuntu. All other systems most likely require adaptions. Feedback for those is greatly appreciated!

SEE ALSO

App::LXC::Container

LICENSE

Copyright (C) Thomas Dorner.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See LICENSE file for more details.

AUTHOR

Thomas Dorner <dorner (at) cpan (dot) org>