NAME

    Linux::LXC - Manage your LXC containers.

VERSION

    1.0000

SYNOPSYS

      use Linux::LXC qw(ALLOW_UNDEF);
    
      my $c = Linux::LXC->new(
        utsname => 'web',
        template => 'download -- -d debian -r wheezy -a amd64'
      );
      my ($uid_start, $uid_map) =
        $c->get_config('lxc.id_map', qr/^u 0 (\d+) (\d+)$/, ALLOW_UNDEF);
      $c->stop if $c->is_running;
      $c->destroy if $c->is_existing;
      $c->deploy;
      $c->set_config('lxc.network.ipv4', '10.0.3.2');
      $c->start;
      my @cmd = (
        'route add default gw 10.0.0.3 eth0',
        'echo "nameserver 8.8.8.8" > /etc/resolv.conf',
        'apt-get update -y',
        'apt-get install -y lighttpd'
      );
      map {
        my ($res, $stdout, $stderr) = $c->exec($_);
        die $stderr if $stderr ne '';
      } @cmd;
      $c->put('lighttpd.conf', '/etc/lighttpd/lighttpd.conf');
      $c->put('www', '/var/www');

DESCRIPTION

    This module helps you to manage LXC container. Each container will be
    represented by an object of this module. Some module subroutine are
    also usable without any object instance.

 Module subroutines

  get_existing_containers()

    Will return an array with the name of all LXC containers existing on
    the system.

  get_running_containers()

    Will return an array with the name of all LXC containers currently
    running on the system.

  get_stopped_containers()

    Will return an array with the name of all LXC containers currently
    stopped on the system.

 Object methods

  new(%params)

    Instanciate a new Linux::LXC object. Params that can be initialized:

    utsname

      Mandatory parameter. Set the utsname of the container.

    template

      Mandatory only if you planned to deploy the container. Set the LXC
      template to use for deploying the container.

    return

      A Linux::LXC object.

  deploy()

    Will deploy the container. Concretly, this method will check that the
    container is not existing, and after execute `lxc-deploy -n <utsname>
    -t <template>` shell command.

    return

      The previous Linux::LXC object.

  del_config($attribute, $filter)

    Will delete all LXC configuration container attributes that respect the
    $filter pattern.

    $attribute

      The attribute to delete.

    $filter

      A regex or undef. It will be compared with all $attribute values. The
      ones that match will be removed. If undef, all values will be
      removed.

    return

      The number of elements deleted.

  destroy()

    Will stop the container if it's existing and destroy it with the shell
    `lxc-destroy -n <utsname>` shell command.

    return

      The previous Linux::LXC object.

  exec($cmd)

    Will execute the $cmd command in the container. This method use the
    IPC::Run method, that allow us to don't think at all about priorities
    between shell operators. Eg: exec('echo "Hello" >> ~/file.txt') will
    write the file on the container, and not on the instance that actually
    runs the commnand.

    return (if want array)

      ($result, $stdout, $stderr); $result true if shell command return 0
      (it usually means that the command was a success), false otherwise.
      $stdout and $stderr are self-explaining.

    return (if want scalar)

      True if shell command return 0 (it usually means that the command was
      a success), false otherwise.

  get_config($paramater, $filter, $flag)

    Get an array of values corresponding to all data that match the LXC
    container configuration.

    $parameter

      The parameter to match.

    $filter

      An regex, or undef. Values corresponding of the parameter to keep. If
      undef, we will keep all of them.

    $flags

      ALLOW_EMPTY: don't croak if the parameter asked was not found.

    return

      An array with all matched results.

  get_lxc_path()

    Return the path to the LXC instance of the container. By default it's
    /var/lib/lxc/<utsname>/. The path is the folder that contains rootfs
    and config file.

  get_template()

    Get the template of the LXC instance.

  get_utsname()

    Will return the utsname of the container.

  is_existing()

    Retrun true if the container with the given utsname exists. False
    otherwise.

  is_running()

    Retrun true if the container with the given utsname is running. False
    otherwise.

  is_stopped()

    Return true if the container with the given utsname is stopped. False
    otherwise.

  put($input, $destination)

    Will copy the $input file or folder on the $destination path in the
    container instance. This method also takes care of ownership and will
    chown $destination to the container root uid.

    $input

      String corresponding to a relative or absolute path of a folder or a
      file we want to copy on the container root fs. This path should be
      readable by the user executing this script.

    $output

      Location on the container to put the file or folder. This path has to
      be absolute.

  set_config($attribute, $value, $flag)

    Will set a LXC attribute in container configuration. The update can
    occurs in two modes: addition or erasing. In the first one, a new
    attribute with the given value will always be created. In the second
    case, the first previous value already existing of $attribute will be
    updated with the new $value. If none is found, the atribute will also
    be created.

    $attribute

      Attribute to set.

    $value

      Value to give to the attribute.

    $flag

      Can be ADDITION_MODE, ERASING_MODE or undef. If undef, ERASING_MODE
      will occur.

  set_template($template)

    Will set the $template name to the given container. Note that this
    action should be done before the deployment.

  start()

    Start the container.

  stop()

    Stop the container.

AUTHOR

    Spydemon <jsaipakoimetr@spyzone.fr>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2017 by Spydemon.

    This program is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation, either version 3 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
    General Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program. If not, see <http://www.gnu.org/licenses/>.