view release on metacpan or  search on metacpan

lib/Linux/Capabilities.pod  view on Meta::CPAN

=head1 NAME

Linux::Capabilities - a class to manage capabilies in linux written in C.

=head1 DESCRIPTION

Linux::Capabilities contains a number of very fast useful functions, written in C.

=head1 SYNOPSIS

    use Linux::Capabilities;
                       
    my $caps_self = Linux::Capabilities->new;# Creating capabilities list for self proccess
    my $caps_other = Linux::Capabilities->new(5432);# Creating capabilities list for proccess with pid 5432
    my $caps_by_text = Linux::Capabilities->new("all=epi cap_chown-p");# Creating capabilities list from text as in system call cap_from_text
    my $caps_empty = Linux::Capabilities->empty;# Creating empty capabilities set

    my $caps_from_file = Linux::Capabilities->from_file("./file");# Creating capabilities set from file

    print $caps_self->get_text;
    my $all_caps = $caps_self0->get_all;# Hash with capabilities
    my $cap_chown = $caps_self->get_value(CAP_CHOWN);
    my $cap_kill_effective = $caps_self->get_value(CAP_KILL, CAP_EFFECTIVE);

    $cap_self->raise;
    $cap_self->raise(CAP_CHOWN);
    $cap_self->raise([CAP_CHOWN, CAP_KILL]);
    $cap_self->raise(CAP_CHOWN, CAP_EFFECTIVE);
    $cap_self->raise(CAP_CHOWN, [CAP_EFFECTIVE, CAP_PERMITTED]);
    $cap_self->raise([CAP_CHOWN, CAP_KILL], [CAP_EFFECTIVE, CAP_PERMITTED]);

    $cap_self->drop;
    $cap_self->drop(CAP_CHOWN);
    $cap_self->drop([CAP_CHOWN, CAP_KILL]);
    $cap_self->drop(CAP_CHOWN, CAP_EFFECTIVE);
    $cap_self->drop(CAP_CHOWN, [CAP_EFFECTIVE, CAP_PERMITTED]);
    $cap_self->drop([CAP_CHOWN, CAP_KILL], [CAP_EFFECTIVE, CAP_PERMITTED]);

    $cap_self->submit;
    $cap_self->submit_to_file("./file");

=head1 PERL FUNCTIONS

Supposed usage: creating capabilities set with new, getting needed info with get_all, get_value, get_value_flag and is_supported, editing it with raise/drop, and then applying it with submit. 

=head2 is_supported

    $caps->is_supported(12);
    Linux::Capabilities::is_supported(12);

is_supported will return 1 if capability that you passed there is supported on your system and 0 otherwise.

=head2 get_name

    my $name1 = $caps->get_name(CAP_CHOWN); # $name1 = "cap_chown"
    my $name2 = Linux::Capabilities::get_name(CAP_NET_BIND_SERVICE); # $name2 = "cap_net_bind_service"

=head2 new

    my $cap = Linux::Capability->new;

returns object that is working with capability set

=over

=item new

Object is created with capability set from current proccess.

=item new(5432)

Object is created with capability set from procces with pid that you pass to new.

=item new("cap_chown=e")

Object is created with capability set made from input string, as in system call cap_from_text in Linux.

=back

=head2 from_file

    my $caps = Linux::Capabilities->from_file("./foo.pl");

Object is created with capability set from a file.

=head2 empty

Object is created with clear capability set.

=head2 get_text

Returns text made from capability set, same as system call cap_to_text in Linux.

    my $cap_text = Linux::Capabilities->new("cap_chown=p");

$cap_text will be set to "cap_chown=p"

=head2 get_all

Returns capability set as hash reference:

    my $caps = Linux::Capabilities->new("cap_chown=ep cap_kill=i");
    my $cap_all = $caps->get_all;

$cap_all will be set to:

    {
        cap_chown => {
            effective => 1,
            permitted => 1,
            inheritable => 0
        },
        cap_kill => {
            effective => 0,
            permitted => 0,
            inheritable => 1
        }
    }

=head2 get_value

Returns capability flags as hash reference:

    my $caps = Linux::Capabilities->new("cap_chown=ep cap_kill=i");
    my $cap_chown = $cap_all->get_value(CAP_CHOWN);

$cap_chown will be set to:

    {
        effective => 1,
        permitted => 1,
        inheritable => 0,
    }

=head2 get_value_flag

Returns value of a flag in capability(i.e. flag effective in CAP_CHOWN);

    my $caps = Linux::Capabilities->new("cap_chown=ep cap_kill=i");
    my $cap_chown_eff = $cap_all->get_value_flag(CAP_CHOWN, CAP_EFFECTIVE);

$cap_chown_eff will be set to 1

=head2 raise

raise is used to make flags state CAP_SET in your current capabilities set.

=over

=item raise

    $caps->raise;

this will raise all flags in all capabilities

=item raise($values)

    $caps->raise(CAP_CHOWN);
    $caps->raise([CAP_CHOWN, CAP_KILL]);

this will raise all flags in capability that you passed as an argument. Argument can be either single number(or constant from capabilities constants) or array of values.

=item raise($values, $flags)

    $caps->raise(CAP_CHOWN, CAP_EFFECTIVE);
    $caps->raise([CAP_CHOWN, CAP_KILL], CAP_EFFECTIVE);
    $caps->raise(CAP_CHOWN, [CAP_EFFECTIVE, CAP_PERMITTED]);
    $caps->raise([CAP_CHOWN, CAP_KILL], [CAP_EFFECTIVE, CAP_PERMITTED]);

this will raise a specific flag in capability that you passed as first argument, flag can be either single number(or constant from flag constants) or array of flags;

=back

=head2 drop

drop is used to make flags state CAP_CLEAR in your current capabilities set.

=over

=item drop

    $caps->drop;

this will drop all flags in all capabilities

=item drop($values)

    $caps->drop(CAP_CHOWN);
    $caps->drop([CAP_CHOWN, CAP_KILL]);

this will drop all flags in capability that you passed as an argument. Argument can be either single number(or constant from capabilities constants) or array of values.

=item drop($values, $flags)

    $caps->drop(CAP_CHOWN, CAP_EFFECTIVE);
    $caps->drop([CAP_CHOWN, CAP_KILL], CAP_EFFECTIVE);
    $caps->drop(CAP_CHOWN, [CAP_EFFECTIVE, CAP_PERMITTED]);
    $caps->drop([CAP_CHOWN, CAP_KILL], [CAP_EFFECTIVE, CAP_PERMITTED]);

this will drop a specific flag in capability that you passed as first argument, flag can be either single number(or constant from flag constants) or array of flags;

=back