summaryrefslogtreecommitdiff
path: root/nss_wrapper.html
blob: 2e902fa09a795941ae81efa94650f6123e003682 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
<!DOCTYPE html>
<html lang="en"><head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="">
    <meta name="author" content="">
    <link rel="shortcut icon" href="/favicon.png">

    <title>cwrap - nss_wrapper</title>

    <!-- Bootstrap core CSS -->
    <link href="assets/css/bootstrap.min.css" rel="stylesheet">

    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
    <!--[if lt IE 9]>
      <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
      <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
    <![endif]-->
    <link href="assets/cwrap.css" type="text/css" rel="stylesheet"></head>

  <body>
    <div class="container subpage-header">
      <div class="">
        <a href="/">cwrap</a>
      </div>
    </div>

    <div class="container subpage">
        <h1>The nss_wrapper library</h1>
        <!-- Example row of columns -->
        <div class="row">
            <div class="col-md-12">
                <p>A wrapper for the user, group and hosts NSS API</p>

                <br />

                <p align="center">
                    <a class="btn btn-warning btn-lg" role="button" href="./download.html#nss_wrapper"><span class="glyphicon glyphicon-random"></span> Clone with git</a> ·
                    <a class="btn btn-danger btn-lg" role="button" href="https://bugzilla.samba.org/enter_bug.cgi?product=cwrap"><span class="glyphicon glyphicon-send"></span> Report a bug</a>
                </p>

                <br />

                <p>
                There are projects that need to be able to create,
                modify, and delete Unix users. Others just switch user
                IDs to interact with the system on behalf of another user
                (e.g. a user space file server). To be able to test
                applications like these, you need to grant privileges
                to modify the passwd and group files. With nss_wrapper it
                is possible to define your own passwd and group files
                to be used the software while it is under test. The nss_wrapper
                also allows you to create a hosts file to set up name
                resolution for the addresses you use with socket_wrapper.
                </p>

                <h2>Features</h2>
                <ul>
                    <li>Provides information for user and group accounts.</li>
                    <li>Network name resolution using a hosts file.</li>
                    <li>Loading and testing of NSS modules.</li>
                </ul>

                <h2>Detailed descriptions</h2>
                <ul>
                    <li>
                    The user, group, and hosts functionality are all defined
                    as wrappers around the Name Service Switch (NSS) API.
                    </li>

                    <li>For user and group accounts you need to create two
                    files: 'passwd' and 'group'. The format of the passwd file
                    is described in <code>man 5 passwd</code> and the group file
                    in <code>man 5 group</code>. So you can fill these files with
                    made up accounts.
                    You point nss_wrapper to them using the two variables
                    <code>NSS_WRAPPER_PASSWD=/path/to/your/passwd</code> and
                    <code>NSS_WRAPPER_GROUP=/path/to/your/group</code>.</li>

                    <li>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 <code>man 5
                    hosts</code>. Then you can point nss_wrapper to your hosts file
                    using: <code>NSS_WRAPPER_HOSTS=/path/to/your/hosts</code>
                    </li>

                    <li>If you need to return a hostname which is different
                    from the one of your machine is using you can use:
                    <code>NSS_WRAPPER_HOSTNAME=test.example.org</code></li>

                    <li>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
                    <code>NSS_WRAPPER_MODULE_SO_PATH=/path/to/libnss_yourmodule.so.</code>
                    As each nss module has a special prefix like
                    <code>_nss_winbind_getpwnam()</code> you need to set the prefix too so
                    nss_wrapper can load the functions with
                    <code>NSS_WRAPPER_MODULE_FN_PREFIX=&lt;prefix&gt;</code>.</li>

                </ul>

                <h2>Example</h2>
<pre>$ 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
$ echo "fd00::5357:5faa test.cwrap.org" > hosts
$ echo "127.0.0.20 test.cwrap.org" >> hosts
# Now query ahostsv6 which returns only IPv6 addresses and
# calls getaddrinfo() for each the entry.
$ LD_PRELOAD="libnss_wrapper.so" NSS_WRAPPER_HOSTS=hosts \
getent ahostsv6 test.cwrap.org
fd00::5357:5faa DGRAM  test.cwrap.org
fd00::5357:5faa STREAM test.cwrap.org
</pre>

            </div> <!-- /col -->
        </div>

    </div> <!-- /container -->

    <div class="container footer-line">
      <footer>
      <div class="row footer">
        <div class="col-md-6">
          <h3>Contact</h3>
          <p><a href="https://lists.samba.org/mailman/listinfo/samba-technical" target="_blank">samba-technical@lists.samba.org</a></p>
        </div>

        <div class="col-md-3 col-md-offset-3">
          <h3>Credits</h3>
          <p>Stefan Metzmacher<br />
          Günther Deschner<br />
          Andreas Schneider</p>
        </div>
      </div>
      </footer>
    </div> <!-- /container -->

   <!-- Bootstrap core JavaScript
        ================================================== -->
   <!-- Placed at the end of the document so the pages load faster -->
   <script src="assets/js/jquery-1.js"></script>
   <script src="assets/js/bootstrap.min.js"></script>

<!-- Piwik -->
<script type="text/javascript">
  var _paq = _paq || [];
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="//stats.cryptomilk.org/";
    _paq.push(['setTrackerUrl', u+'piwik.php']);
    _paq.push(['setSiteId', 3]);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s);
  })();
</script>
<noscript><p><img src="//stats.cryptomilk.org/piwik.php?idsite=3" style="border:0;" alt="" /></p></noscript>
<!-- End Piwik Code -->

</body></html>