NAME
    Process::DropPrivs - carefully drop root privileges

SYNOPSIS
            use Process::DropPrivs;

            if ( $> != 0 ) {
                    die "Run this as root!\n";
            }
        
            # do something with root privileges

            drop_privs('nobody');

            # do stuff without root privileges

DESCRIPTION
    Dropping privileges is something that needs to be done right and can
    easily be done wrong. Even if you know how to do it right, it takes a
    lot of booring code.

USAGE
    drop_privs(*new_user*, [*primary_group*] , [*supplimental_group* ... ]);

    This is the only function provided by Process::DropPrivs. It is exported
    by default.

    drop_privs() switches the uid, euid, gid, egid and reduces the
    supplimental groups to those specified if any.

    *new_user* is the user name or numeric user id of the user whom you wish
    the process to run as.

    *primary_group* is the group name or numeric group id of the primary
    group. If undefined, the primary group of the user *new_user* is used.

    *supplimental_group* is any group which you'd like the process to be a
    member of. If undefined, all supplimental group memberships are dropped.

    All names and groups are assumed to be numeric uids and numeric gids if
    they are integers. Otherwize they are assumed to be user names or group
    names.

EXAMPLES
    *   drop_privs('jdoe');

        Switch the uid and euid to 'jdoe'. Switch the gid and egid to jdoe's
        primary group (probably 'jdoe' or 'users' but maybe not.) Drop
        membership in any other groups.

    *   drop_privs('jdoe','users,'tape');

        Switch the uid and euid to 'jdoe'. Switch the gid and egid to
        'users'. Add membership in the 'tape' group and drop membership in
        any other groups.

    *   drop_privs('jdoe',undef,'tape');

        Switch the uid and euid to 'jdoe'. Switch the gid and egid to jdoe's
        primary group (probably 'jdoe' or 'users' but maybe not.) Add
        membership in the 'tape' group and drop membership in any other
        groups.

DIAGNOSTICS
    drop_privs() returns undef on succss and croaks on failure.

DISCUSSION
    I've written code that drops privileges many times and here's some of
    things I've forgotten to do at one time or another. Hence this module.

    Make sure you drop group membership as well as changing user id.
    Handle supplimental groups as well as the users primary group.
    Check to make sure uids/gids really did change.
    Check group membership without getting hung up about the order the
    groups are listed in.
BUGS AND LIMITATIONS
    This has only been tested on Linux.

    I assume you want euid == uid and egid == gid. If you don't I'd love to
    know why.

    Please report any bugs or feature requests to
    `bug-process-dropprivs@rt.cpan.org', or through the web interface at
    http://rt.cpan.org.

AUTHOR
    Dylan Martin `<dmartin@cpan.org>'

LICENCE AND COPYRIGHT
    Copyright (c) 2008, Dylan Martin & Seattle Central Community College
    `<dmartin@cpan.org>'.

    Permission to use, copy, modify, and distribute this software for any
    purpose with or without fee is hereby granted, provided that the above
    copyright notice and this permission notice appear in all copies.

DISCLAIMER
    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
    WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
    MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
    ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
    ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.