A simple README, explaining how the whole thing works

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..a6e2031
--- /dev/null
+++ b/README
@@ -0,0 +1,47 @@
+================================================================================
+
+This package contains the suidgw utility
+
+Copyright (c) 2013 Martin Mares <mj@ucw.cz>
+
+All files in this package can be freely distributed and used according
+to the terms of the GNU General Public License, either version 2 or
+(at your opinion) any newer version. This is the same distribution
+policy as for the Linux kernel itself -- see /usr/src/linux/COPYING
+for details.
+
+================================================================================
+
+
+For many years, I have been happily using suidperl to let ordinary users run
+various scripts with elevated privileges. However, suidperl is not supported
+on current systems any longer. Therefore I have written a simple wrapper,
+which can be used to emulate setuid/setgid on scripts written in any language.
+
+
+Theory of operation
+~~~~~~~~~~~~~~~~~~~
+
+  o  /usr/bin/suidgw is the gateway binary, installed setuid root.
+
+  o  /usr/lib/suidgw/$SCRIPT is the script to be run, installed with
+     an appropriate combination of setuid/setgid bits (as if it were
+     a binary program). Note that Linux kernel ignores setuid/setgid
+     on scripts, so running the scripts manually does no harm.
+     [Alternatively, /usr/local/lib/suidgw/$SCRIPT can be used.]
+
+  o  /usr/bin/$SCRIPT is a symlink to /usr/bin/suidgw.
+     [Or use any other directory accessible to ordinary users.]
+
+  o  When a user executes suidgw via the symlink, it parses argv[0],
+     determines which $SCRIPT was called and checks that the name looks sane.
+
+  o  The suidgw finds /usr/lib/suidgw/$SCRIPT and checks that the current
+     (real) user is allowed to run it.
+
+  o  Then it switches the effective and saved UID and runs the script.
+     Environment variables are sanitized (currently, the whole environment
+     is reset; in the future, we may propagate some variables if needed)
+     and so are file descriptors (we make sure that fd's 0 to 2 exist).
+
+  o  The action is logged to the syslog (facility auth, level info).