Dylan Djos Martin > Unix-SavedIDs-0.4.1 > Unix::SetUser

Download:
Unix-SavedIDs-0.4.1.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.4.0   Source  

NAME ^

Unix::SetUser - carefully drop root privileges

SYNOPSIS ^

        use Unix::SetUser;

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

        set_user('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 boring code.

About Saved IDs ^

Most modern unices have saved ids. This is a 3rd id type, so you have real user id, effective user id and now saved user id. (The same applies to groups). This means if you don't set your saved id, you really haven't dropped root privileges. Please see Unix::SavedIDs, the module used in Unix::SetUser to handle saved ids, for more information.

USAGE ^

set_user(new_user, [primary_group] , [supplemental_group ... ]);

This is the only function provided by Unix::SetUser. It is exported by default.

set_user() switches the uid, euid, suid, gid, egid, sgid and reduces the supplemental 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.

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

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

EXAMPLES ^

DIAGNOSTICS ^

set_user() returns undef on success and croaks on failure.

DISCUSSION ^

Here's some of the gotchas involved in dropping privileges. These are all taken care of by Unix::SetUser

Make sure you drop group membership as well as changing user id.
Handle supplemental groups as well as the users primary group.
Set saved ids as well as real and effective ids.
Check to make sure ids really did change.
Check group membership without getting hung up about the order the groups are listed in.

PORTABILITY ^

This module will only work on unix-like systems which support saved ids. That is the vast majority of unices. I would like to add support for unices without saved ids and Windows, but I don't use those systems so I can't justify the time spent.

ACKNOWLEDGMENTS ^

After I wrote version 0.1, I discovered Proc::UID by Paul Fenwick. It does everything that this module does plus more. Sadly, its unmaintained since 2004 and the author specifically states that it is not for production code.

BUGS AND LIMITATIONS ^

This has only been tested on Linux and OpenBSD.

I assume you want uid == euid == suid and gid == euid == suid. If you don't Unix::SavedIds will let you manipulate all 3.

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>

LICENSE 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.

syntax highlighting: