The branch, master has been updated
via bb8a492 doc: Add nss_wrapper manpage.
from 6ab6a09 nss_wrapper: Fix some "discarding const" warnings
http://gitweb.samba.org/?p=nss_wrapper.git;a=shortlog;h=master
- Log -----------------------------------------------------------------
commit bb8a492e467d154b11ac19230e63cd5e13ab8577
Author: Andreas Schneider <a...@samba.org>
Date: Wed Jul 9 17:29:12 2014 +0200
doc: Add nss_wrapper manpage.
Signed-off-by: Andreas Schneider <a...@samba.org>
Reviewed-by: Michael Adam <ob...@samba.org>
-----------------------------------------------------------------------
Summary of changes:
CMakeLists.txt | 1 +
README | 58 ++++------------
doc/CMakeLists.txt | 4 +
doc/README | 3 +
doc/nss_wrapper.1 | 180 +++++++++++++++++++++++++++++++++++++++++++++++++
doc/nss_wrapper.1.txt | 96 ++++++++++++++++++++++++++
6 files changed, 298 insertions(+), 44 deletions(-)
create mode 100644 doc/CMakeLists.txt
create mode 100644 doc/README
create mode 100644 doc/nss_wrapper.1
create mode 100644 doc/nss_wrapper.1.txt
Changeset truncated at 500 lines:
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 40d6595..094d620 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -88,3 +88,4 @@ install(
devel
)
+add_subdirectory(doc)
diff --git a/README b/README
index 2ffa564..2d26237 100644
--- a/README
+++ b/README
@@ -1,54 +1,24 @@
-NSS wrapper library
-====================
+NSS_WRAPPER
+===========
-There are projects which provide daemons needing to be able to create, modify
-and delete unix users. Or just switch user ids to interact with the system e.g.
-a user space file server. To be able to test that you need the privilege to
-modify the passwd and groups file. With nss_wrapper it is possible to define
-your own passwd and groups file which will be used by software to act correctly
-while under test.
+This is a wrapper for the user, group and hosts NSS API.
-If you have a client and server under test they normally use functions to
-resolve network names to addresses (dns) or vice versa. The nss_wrappers allow
-you to create a hosts file to setup name resolution for the addresses you use
-with socket_wrapper.
+DESCRIPTION
+-----------
-The first environment variable you need to set is:
+More details can be found in the manpage:
-LD_PRELOAD=libnss_wrapper.so
+ man -l ./doc/nss_wrapper.1
-For user and group accounts you need to create two files: 'passwd' and 'group'.
-The format of the passwd file is described in 'man 5 passwd' and the group file
-in 'man 5 group'. So you can fill these files with made up accounts. You point
-nss_wrapper to them using the two variables:
+or the raw text version:
-NSS_WRAPPER_PASSWD=/path/to/your/passwd and
-NSS_WRAPPER_GROUP=/path/to/your/group.
+ less ./doc/nss_wrapper.1.txt
-If you also need to emulate network name resolution in your enviornment,
-especially with socket_wrapper, you can write a hosts file. The format is
-described in 'man 5 hosts'. Then you can point nss_wrapper to your hosts
-file using:
+For installation instructions please take a look at the README.install file.
-NSS_WRAPPER_HOSTS=/path/to/your/hosts
+MAILINGLIST
+-----------
-If you need to return a hostname which is different from the one of your
-machine is using you can use:
+As the mailing list samba-technical is used and can be found here:
-NSS_WRAPPER_HOSTNAME=test.example.org
-
-If you have a project which also provides user and group information out of a
-database, you normally write your own nss modules. nss_wrapper is able to load
-nss modules and ask them first before looking into the faked passwd and group
-file. To point nss_wrapper to the module you can do that using
-
-NSS_WRAPPER_MODULE_SO_PATH=/path/to/libnss_yourmodule.so
-
-As each nss module has a special prefix like _nss_winbind_getpwnam() you need
-to set the prefix too so nss_wrapper can load the functions with:
-
-NSS_WRAPPER_MODULE_FN_PREFIX=<prefix>
-
-For _nss_winbind_getpwnam() this would be:
-
-NSS_WRAPPER_MODULE_FN_PREFIX=winbind
+https://lists.samba.org/mailman/listinfo/samba-technical
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
new file mode 100644
index 0000000..353168a
--- /dev/null
+++ b/doc/CMakeLists.txt
@@ -0,0 +1,4 @@
+install(FILES
+ nss_wrapper.1
+ DESTINATION
+ ${MAN_INSTALL_DIR}/man1)
diff --git a/doc/README b/doc/README
new file mode 100644
index 0000000..7217244
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,3 @@
+The manpage is written with asciidoc. To generate the manpage use:
+
+a2x --doctype manpage --format manpage doc/nss_wrapper.1.txt
diff --git a/doc/nss_wrapper.1 b/doc/nss_wrapper.1
new file mode 100644
index 0000000..0224f83
--- /dev/null
+++ b/doc/nss_wrapper.1
@@ -0,0 +1,180 @@
+'\" t
+.\" Title: nss_wrapper
+.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\" Date: 07/09/2014
+.\" Manual: \ \&
+.\" Source: \ \&
+.\" Language: English
+.\"
+.TH "NSS_WRAPPER" "1" "07/09/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"
+nss_wrapper \- A wrapper for the user, group and hosts NSS API
+.SH "SYNOPSIS"
+.sp
+LD_PRELOAD=libnss_wrapper\&.so NSS_WRAPPER_PASSWD=/path/to/passwd
NSS_WRAPPER_GROUP=/path/to/group NSS_WRAPPER_HOSTS=/path/to/host
\fB\&./myapplication\fR
+.SH "DESCRIPTION"
+.sp
+There are projects which provide daemons needing to be able to create, modify
and delete Unix users\&. Or just switch user ids to interact with the system
e\&.g\&. a user space file server\&. To be able to test that you need the
privilege to modify the passwd and groups file\&. With nss_wrapper it is
possible to define your own passwd and groups file which will be used by
software to act correctly while under test\&.
+.sp
+If you have a client and server under test they normally use functions to
resolve network names to addresses (dns) or vice versa\&. The nss_wrappers
allow you to create a hosts file to setup name resolution for the addresses you
use with socket_wrapper\&.
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Provides information for user and group accounts\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Network name resolution using a hosts file\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Loading and testing of NSS modules\&.
+.RE
+.SH "ENVIRONMENT VARIABLES"
+.PP
+\fBNSS_WRAPPER_PASSWD\fR, \fBNSS_WRAPPER_GROUP\fR
+.RS 4
+For user and group accounts you need to create two files:
+\fIpasswd\fR
+and
+\fIgroup\fR\&. The format of the passwd file is described in
+\fIman 5 passwd\fR
+and the group file in
+\fIman 5 group\fR\&. So you can fill these files with made up accounts\&. You
point nss_wrapper to them using the two variables
NSS_WRAPPER_PASSWD=/path/to/your/passwd and
NSS_WRAPPER_GROUP=/path/to/your/group\&.
+.RE
+.PP
+\fBNSS_WRAPPER_HOSTS\fR
+.RS 4
+If you also need to emulate network name resolution in your enviornment,
especially with socket_wrapper, you can write a hosts file\&. The format is
described in
+\fIman 5 hosts\fR\&. Then you can point nss_wrapper to your hosts file using:
NSS_WRAPPER_HOSTS=/path/to/your/hosts
+.RE
+.PP
+\fBNSS_WRAPPER_HOSTNAME\fR
+.RS 4
+If you need to return a hostname which is different from the one of your
machine is using you can use: NSS_WRAPPER_HOSTNAME=test\&.example\&.org
+.RE
+.PP
+\fBNSS_WRAPPER_MODULE_SO_PATH\fR, \fBNSS_WRAPPER_MODULE_FN_PREFIX\fR
+.RS 4
+If you have a project which also provides user and group information out of a
database, you normally write your own nss modules\&. nss_wrapper is able to
load nss modules and ask them first before looking into the faked passwd and
group file\&. To point nss_wrapper to the module you can do that using
NSS_WRAPPER_MODULE_SO_PATH=/path/to/libnss_yourmodule\&.so\&. As each nss
module has a special prefix like _nss_winbind_getpwnam() you need to set the
prefix too so nss_wrapper can load the functions with
NSS_WRAPPER_MODULE_FN_PREFIX=<prefix>\&.
+.RE
+.sp
+For _nss_winbind_getpwnam() this would be:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+NSS_WRAPPER_MODULE_FN_PREFIX=winbind
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBNSS_WRAPPER_DEBUGLEVEL\fR
+.RS 4
+If you need to see what is going on in nss_wrapper itself or try to find a
bug, you can enable logging support in nss_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
+$ echo "bob:x:1000:1000:bob gecos:/home/test/bob:/bin/false" > passwd
+$ echo "root:x:65534:65532:root gecos:/home/test/root:/bin/false" >> passwd
+$ echo "users:x:1000:" > group
+$ echo "root:x:65532:" >> group
+$ LD_PRELOAD=libnss_wrapper\&.so NSS_WRAPPER_PASSWD=passwd \e
+ NSS_WRAPPER_GROUP=group getent passwd bob
+bob:x:1000:1000:bob gecos:/home/test/bob:/bin/false
+$ LD_PRELOAD=libnss_wrapper\&.so NSS_WRAPPER_HOSTNAME=test\&.example\&.org
hostname
+test\&.example\&.org
+.fi
+.if n \{\
+.RE
+.\}
diff --git a/doc/nss_wrapper.1.txt b/doc/nss_wrapper.1.txt
new file mode 100644
index 0000000..1e5e929
--- /dev/null
+++ b/doc/nss_wrapper.1.txt
@@ -0,0 +1,96 @@
+nss_wrapper(1)
+==============
+
+NAME
+----
+
+nss_wrapper - A wrapper for the user, group and hosts NSS API
+
+SYNOPSIS
+--------
+
+LD_PRELOAD=libnss_wrapper.so NSS_WRAPPER_PASSWD=/path/to/passwd
NSS_WRAPPER_GROUP=/path/to/group NSS_WRAPPER_HOSTS=/path/to/host
*./myapplication*
+
+DESCRIPTION
+-----------
+
+There are projects which provide daemons needing to be able to create, modify
+and delete Unix users. Or just switch user ids to interact with the system e.g.
+a user space file server. To be able to test that you need the privilege to
+modify the passwd and groups file. With nss_wrapper it is possible to define
+your own passwd and groups file which will be used by software to act correctly
+while under test.
+
+If you have a client and server under test they normally use functions to
+resolve network names to addresses (dns) or vice versa. The nss_wrappers allow
+you to create a hosts file to setup name resolution for the addresses you use
+with socket_wrapper.
+
+- Provides information for user and group accounts.
+- Network name resolution using a hosts file.
+- Loading and testing of NSS modules.
+
+ENVIRONMENT VARIABLES
+---------------------
+
+*NSS_WRAPPER_PASSWD*::
+*NSS_WRAPPER_GROUP*::
+
+For user and group accounts you need to create two files: 'passwd' and 'group'.
+The format of the passwd file is described in 'man 5 passwd' and the group file
+in 'man 5 group'. So you can fill these files with made up accounts. You point
+nss_wrapper to them using the two variables
+NSS_WRAPPER_PASSWD=/path/to/your/passwd and
+NSS_WRAPPER_GROUP=/path/to/your/group.
+
+*NSS_WRAPPER_HOSTS*::
+
+If you also need to emulate network name resolution in your enviornment,
+especially with socket_wrapper, you can write a hosts file. The format is
+described in 'man 5 hosts'. Then you can point nss_wrapper to your hosts
+file using: NSS_WRAPPER_HOSTS=/path/to/your/hosts
+
+*NSS_WRAPPER_HOSTNAME*::
+
+If you need to return a hostname which is different from the one of your
+machine is using you can use: NSS_WRAPPER_HOSTNAME=test.example.org
+
+*NSS_WRAPPER_MODULE_SO_PATH*::
+*NSS_WRAPPER_MODULE_FN_PREFIX*::
+
+If you have a project which also provides user and group information out of a
+database, you normally write your own nss modules. nss_wrapper is able to load
+nss modules and ask them first before looking into the faked passwd and group
+file. To point nss_wrapper to the module you can do that using
+NSS_WRAPPER_MODULE_SO_PATH=/path/to/libnss_yourmodule.so. As each nss module
+has a special prefix like _nss_winbind_getpwnam() you need to set the prefix
+too so nss_wrapper can load the functions with
+NSS_WRAPPER_MODULE_FN_PREFIX=<prefix>.
+
+For _nss_winbind_getpwnam() this would be:
+
+ NSS_WRAPPER_MODULE_FN_PREFIX=winbind
+
+*NSS_WRAPPER_DEBUGLEVEL*::
+
+If you need to see what is going on in nss_wrapper itself or try to find a
+bug, you can enable logging support in nss_wrapper if you built it with
+debug symbols.
+
+- 0 = ERROR
+- 1 = WARNING
+- 2 = DEBUG
+- 3 = TRACE
+
+EXAMPLE
+-------
+
+ $ echo "bob:x:1000:1000:bob gecos:/home/test/bob:/bin/false" > passwd
+ $ echo "root:x:65534:65532:root gecos:/home/test/root:/bin/false" >> passwd
+ $ echo "users:x:1000:" > group
+ $ echo "root:x:65532:" >> group
+ $ LD_PRELOAD=libnss_wrapper.so NSS_WRAPPER_PASSWD=passwd \
+ NSS_WRAPPER_GROUP=group getent passwd bob
+ bob:x:1000:1000:bob gecos:/home/test/bob:/bin/false
+ $ LD_PRELOAD=libnss_wrapper.so NSS_WRAPPER_HOSTNAME=test.example.org hostname
+ test.example.org
--
NSS Wrapper Repository
