COMPONENT
devel
)
+
+add_subdirectory(doc)
-UID wrapper library
-====================
+UID_WRAPPER
+===========
-Privilege separation - Some projects like a file server need privilege
-separation to be able to switch to the connnection user and do file operations.
-uid_wrapper convincingly lies to the application letting it believe it is
-operating as root and even switching betwen uids and gids as needed.
+This is a wrapper for the user, group and hosts NSS API.
-More precise this library intercepts seteuid and related calls, and simulates
-them in a manner similar to the nss_wrapper and socket_wrapper libraries.
+DESCRIPTION
+-----------
-This allows you to do user switching when testing e.g. file servers.
+More details can be found in the manpage:
-To use it set the following environment variables:
+ man -l ./doc/uid_wrapper.1
-LD_PRELOAD=libuid_wrapper.so
-UID_WRAPPER=1
+or the raw text version:
-If you unset the variable or set it to 0 you can disable uwrap even if it is
-loaded. If you need the application to think it is root at startup you can set:
+ less ./doc/uid_wrapper.1.txt
-UID_WRAPPER_ROOT=1
+For installation instructions please take a look at the README.install file.
-If you set the environment variable to UID_WRAPPER_MYUID=1 before you call
-geteuid() then it will return the real uid.
+MAILINGLIST
+-----------
-To find out if uid_wrapper is enabled, we suggest to implment the following
-function in a library your application loads:
+As the mailing list samba-technical is used and can be found here:
-int uid_wrapper_enabled(void)
-{
- return 0;
-}
-
-Then you can use:
-
-if (uid_wrapper_enabled()) {
- /* special uid_wrapper handling code */
-}
-
-uid_wrapper implements this funciton too and it will be loaded before your
-library gets loaded.
+https://lists.samba.org/mailman/listinfo/samba-technical
--- /dev/null
+install(FILES
+ uid_wrapper.1
+ DESTINATION
+ ${MAN_INSTALL_DIR}/man1)
--- /dev/null
+The manpage is written with asciidoc. To generate the manpage use:
+
+a2x --doctype manpage --format manpage doc/uid_wrapper.1.txt
--- /dev/null
+'\" t
+.\" Title: uid_wrapper
+.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\" Date: 07/11/2014
+.\" Manual: \ \&
+.\" Source: \ \&
+.\" Language: English
+.\"
+.TH "UID_WRAPPER" "1" "07/11/2014" "\ \&" "\ \&"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+uid_wrapper \- A wrapper to fake privilege separation
+.SH "SYNOPSIS"
+.sp
+LD_PRELOAD=libuid_wrapper\&.so UID_WRAPPER=1 UID_WRAPPER_ROOT=1 \fB\&./myapplication\fR
+.SH "DESCRIPTION"
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Allows uid switching as a normal user\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Start any application making it believe it is running as root\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Support for user/group changing in the local thread using the syscalls (like glibc)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+More precisely this library intercepts seteuid and related calls, and simulates them in a manner similar to the nss_wrapper and socket_wrapper libraries\&.
+.RE
+.sp
+Some projects like a file server need privilege separation to be able to switch to the connection user and do file operations\&. uid_wrapper convincingly lies to the application letting it believe it is operating as root and even switching between UIDs and GIDs as needed\&.
+.SH "ENVIRONMENT VARIABLES"
+.PP
+\fBUID_WRAPPER\fR
+.RS 4
+If you load the uid_wrapper and enable it with setting UID_WRAPPER=1 all setuid and setgid will work, even as a normal user\&.
+.RE
+.PP
+\fBUID_WRAPPER_ROOT\fR
+.RS 4
+It is possible to start your application as fake root with setting UID_WRAPPER_ROOT=1\&.
+.RE
+.PP
+\fBUID_WRAPPER_DEBUGLEVEL\fR
+.RS 4
+If you need to see what is going on in uid_wrapper itself or try to find a bug, you can enable logging support in uid_wrapper if you built it with debug symbols\&.
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+0 = ERROR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+1 = WARNING
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+2 = DEBUG
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+3 = TRACE
+.RE
+.RE
+.SH "EXAMPLE"
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ LD_PRELOAD=libuid_wrapper\&.so UID_WRAPPER=1 UID_WRAPPER_ROOT=1 id
+uid=0(root) gid=0(root) groups=100(users),0(root)
+.fi
+.if n \{\
+.RE
+.\}
--- /dev/null
+uid_wrapper(1)
+==============
+
+NAME
+----
+
+uid_wrapper - A wrapper to fake privilege separation
+
+SYNOPSIS
+--------
+
+LD_PRELOAD=libuid_wrapper.so UID_WRAPPER=1 UID_WRAPPER_ROOT=1 *./myapplication*
+
+DESCRIPTION
+-----------
+
+- Allows uid switching as a normal user.
+- Start any application making it believe it is running as root.
+- Support for user/group changing in the local thread using the syscalls (like glibc).
+- More precisely this library intercepts seteuid and related calls, and simulates
+ them in a manner similar to the nss_wrapper and socket_wrapper libraries.
+
+Some projects like a file server need privilege separation to be able to switch
+to the connection user and do file operations. uid_wrapper convincingly lies to
+the application letting it believe it is operating as root and even switching
+between UIDs and GIDs as needed.
+
+ENVIRONMENT VARIABLES
+---------------------
+
+*UID_WRAPPER*::
+
+If you load the uid_wrapper and enable it with setting UID_WRAPPER=1 all setuid
+and setgid will work, even as a normal user.
+
+*UID_WRAPPER_ROOT*::
+
+It is possible to start your application as fake root with setting
+UID_WRAPPER_ROOT=1.
+
+*UID_WRAPPER_DEBUGLEVEL*::
+
+If you need to see what is going on in uid_wrapper itself or try to find a
+bug, you can enable logging support in uid_wrapper if you built it with
+debug symbols.
+
+- 0 = ERROR
+- 1 = WARNING
+- 2 = DEBUG
+- 3 = TRACE
+
+EXAMPLE
+-------
+
+ $ LD_PRELOAD=libuid_wrapper.so UID_WRAPPER=1 UID_WRAPPER_ROOT=1 id
+ uid=0(root) gid=0(root) groups=100(users),0(root)
git.samba.org / uid_wrapper.git / commitdiff