Privileges::Drop(3pm)

💖 Privileges::Drop 💖

okay bestie, gather round, because we're talking about Privileges::Drop — a Perl module (yes, it lives in the 3pm manpage section, that's the Perl module manual, iykyk) whose whole entire job is making it stupid easy to drop all your privileges. all of them. even the POSIX groups. periodt. 👑

---

✨ NAME ✨

Privileges::Drop — a module to make it simple to drop all privileges, even POSIX groups. 🫶

---

🌸 DESCRIPTION 🌸

so like, this module is here to simplify the whole process of dropping privileges, right? and that's lowkey a big deal, because your Perl program might need to bind to privileged ports or do other spicy root-only stuff, and then you wanna let go of all that power before you keep going. 🎀

it's much like Proc::UID, except — and this is the iconic part — it's implemented in pure Perl. no XS, no compiling, just vibes. ✨

special care has been taken to also drop the saved uid on platforms that support it, which is the responsible main-character move. heads up though: at this point it's currently only been tested on Linux. 💅

---

🦋 SYNOPSIS 🦋

use Privileges::Drop;

# Do privileged stuff

# Drops privileges and sets euid/uid to 1000 and egid/gid to 1000.
drop_uidgid(1000, 1000);

# Drop privileges to user nobody looking up gid and uid with getpwname
# This also set the environment variables USER, LOGNAME, HOME and SHELL.
drop_privileges('nobody');

---

💜 METHODS 💜

drop_uidgid($uid, $gid, @groups)

drops your privileges and sets euid/uid to $uid and egid/gid to $gid. that's the whole thing, no notes. 🫡

supplementary groups can be set in @groups. slay. 🎀

drop_privileges($user)

drops privileges down to $user, looking up the gid and uid with getpwname and then calling drop_uidgid() with those arguments. teamwork, fr fr. 💖

it also sets the environment variables USER, LOGNAME, HOME and SHELL to the values returned by getpwname. so your shell doesn't get all confused about who it is. ✨

returns the $uid and $gid on success, and dies on error. no cap, it will just end it right there. 💀

NOTE: if drop_privileges() is called when you don't have root privileges, it will just return undef. that's it. no drama, no death, just undef. 🙈

---

⭐ NOTES ⭐

since this module only uses Perl's built-in functions, it is fully relying on them to behave correctly. that means setting $GID and $EGID should also call setgroups(), and that might not have been the case before Perl 5.004. 👑

so if you're running an older version than that, Proc::UID might be the better choice. like, respectfully. 🌈

---

👑 AUTHOR 👑

Troels Liebe Bentsen <tlb@rapanden.dk> — legend behaviour, honestly. 🫶

---

🎀 COPYRIGHT 🎀

Copyright(C) 2007-2009 Troels Liebe Bentsen

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 💜

---

and that's the whole page, bestie. this one shipped with perl v5.36.0 and was dated 2022-11-19, and it's filed under Privileges::Drop(3pm). go forth and drop those privileges responsibly. mwah. 💅✨🦋