'\" 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: 2015-09-12

.\"    Manual: \ \&

.\"    Source: \ \&

.\"  Language: English

.\"

.TH "NSS_WRAPPER" "1" "2015\-09\-12" "\ \&" "\ \&"

.\" -----------------------------------------------------------------

.\" * 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 "LIMITATIONS"

.sp

Some calls in nss_wrapper will only work if uid_wrapper is loaded and active\&. One of this functions is initgroups() which needs to run setgroups() to set the groups for the user\&. setgroups() is wrapped by uid_wrapper\&.

.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

.\}