Initial commit

author: Laurent Bercot <ska-skaware@skarnet.org> 2018-06-26 00:25:28 +0000
committer: Laurent Bercot <ska-skaware@skarnet.org> 2018-06-26 00:25:28 +0000
commit: 633445be1a9be37ae727c044417f5607706cf4ae (patch)
tree: 3c037459f5249e5c18ee5b9e41802c5964364f95 /doc
download: nsss-633445be1a9be37ae727c044417f5607706cf4ae.tar.xz
4 files changed, 323 insertions, 0 deletions
diff --git a/doc/index.html b/doc/index.html
new file mode 100644
index 0000000..49cf697
--- /dev/null
+++ b/doc/index.html
@@ -0,0 +1,163 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>nsss - a secure NSS-like implementation for small libcs</title>
+    <meta name="Description" content="utmps - a secure NSS-like implementation for small libcs" />
+    <meta name="Keywords" content="nsss NSS musl libc unix passwd grp shadow laurent bercot skarnet" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> nsss </h1>
+
+<h2> What is it&nbsp;? </h2>
+
+<p>
+ nsss is an implementation of a subset of the <tt>pwd.h</tt>,
+<tt>group.h</tt> and <tt>shadow.h</tt> family of functions,
+performing user database access on Unix systems.
+</p>
+
+<p>
+ Usually, user database access via <tt>getpwnam()</tt> and similar
+function is provided by the system's libc. However, not all libcs implement
+a configurable backend for the user/group database. For instance the
+<a href="https://musl-libc.org/">musl</a> libc, on Linux, only supports
+the standard <tt>/etc/passwd</tt> mechanism; it also supports the
+<tt>nscd</tt> protocol but this is not quite enough to implement the
+full set of database access functions with certain backends (such as a
+LDAP server).
+</p>
+
+<p>
+ <tt>nsss</tt> is a secure implementation of configurable user/group/shadow
+database access, providing <tt>getpwnam()</tt> et al. functionality
+by communicating over a Unix domain socket with a daemon; the daemon
+can perform lookups in any database it chooses.
+</p>
+
+<p>
+ Unlike NSS, <tt>nsss</tt> does not perform dynamic module
+loading, only adds a small footprint to the application's binary,
+and does not add any complex decision engine into the client's address
+space. Applications can be statically linked against the <tt>nsss</tt>
+library, and still benefit from configurable user database access
+functions.
+</p>
+
+<hr />
+
+<ul>
+ <li> <a href="overview.html">An overview of nsss</a> </li>
+</ul>
+
+<hr />
+
+<h2> Installation </h2>
+
+<h3> Requirements </h3>
+
+<ul>
+ <li> A POSIX-compliant system with a standard C development environment </li>
+ <li> GNU make, version 3.81 or later </li>
+ <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> version
+2.6.5.0 or later. It's a build-time requirement. It's also a run-time
+requirement if you link against the shared version of the skalibs
+library. </li>
+</ul>
+
+<h3> Licensing </h3>
+
+<p>
+ nsss is free software. It is available under the
+<a href="http://opensource.org/licenses/ISC">ISC license</a>.
+</p>
+
+<h3> Download </h3>
+
+<ul>
+ <li> The current released version of nsss is <a href="nsss-0.0.1.0.tar.gz">0.0.1.0</a>. </li>
+ <li> Alternatively, you can checkout a copy of the
+<a href="//git.skarnet.org/cgi-bin/cgit.cgi/nsss/">nsss
+git repository</a>:
+<pre> git clone git://git.skarnet.org/nsss </pre> </li>
+ <li> There's also a
+<a href="https://github.com/skarnet/nsss">GitHub mirror</a>
+of the nsss git repository. </li>
+</ul>
+
+<h3> Compilation </h3>
+
+<ul>
+ <li> See the enclosed INSTALL file for installation details. </li>
+</ul>
+
+<h3> Upgrade notes </h3>
+
+<ul>
+ <li> <a href="upgrade.html">This page</a> lists the differences to be aware of between
+the previous versions of nsss and the current one. </li>
+</ul>
+
+<hr />
+
+<h2> Reference </h2>
+
+<h3> Commands </h3>
+
+<ul>
+</ul>
+
+<h3> Libraries </h3>
+
+<ul>
+ <li> <a href="libnsss/">The <tt>nsss</tt> library interface</a> </li>
+ <li> The following primitives are also implemented:
+  <ul>
+   <li> endpwent() </li>
+   <li> setpwent() </li>
+   <li> getpwent() </li>
+   <li> getpwent_r() </li>
+   <li> getpwuid() </li>
+   <li> getpwuid_r() </li>
+   <li> getpwnam() </li>
+   <li> getpwnam_r() </li>
+   <li> endgrent() </li>
+   <li> setgrent() </li>
+   <li> getgrent() </li>
+   <li> getgrent_r() </li>
+   <li> getgrgid() </li>
+   <li> getgrgid_r() </li>
+   <li> getgrnam() </li>
+   <li> getgrnam_r() </li>
+   <li> endspent() </li>
+   <li> setspent() </li>
+   <li> getspent() </li>
+   <li> getspent_r() </li>
+   <li> getspnam() </li>
+   <li> getspnam_r() </li>
+  </ul> </li>
+</ul>
+
+<hr />
+
+<a name="related">
+<h2> Related resources </h2>
+</a>
+
+<h3> nsss discussion </h3>
+
+<ul>
+ <li> <tt>nsss</tt> is discussed on the
+<a href="//skarnet.org/lists.html#skaware">skaware</a> mailing-list. </li>
+</ul>
+
+</body>
+</html>
diff --git a/doc/libnsss/index.html b/doc/libnsss/index.html
new file mode 100644
index 0000000..0307725
--- /dev/null
+++ b/doc/libnsss/index.html
@@ -0,0 +1,97 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>nsss: the nsss library interface</title>
+    <meta name="Description" content="nsss: the nsss library interface" />
+    <meta name="Keywords" content="NSS pwd group shadow library libnsss skarnet" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="../">nsss</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>nsss</tt> library interface </h1>
+
+<h2> General information </h2>
+
+<p>
+ <tt>libnsss</tt> is a client library meant to be used by client
+programs needing utmp functionality. It interacts with various
+server-side daemons such as
+<a href="../nsssd-unix.html">nsssd-unix</a>.
+</p>
+
+<p>
+ Application programs can use it directly, but most existing programs
+simply use the standard
+<a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pwd.h.html">pwd.h</a>,
+<a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/grp.h.html">grp.h</a> or
+<a href="http://man7.org/linux/man-pages/man3/getspnam.3.html">shadow.h</a>
+interfaces, which in nsss are implemented as a series of thin wrappers
+around the nsss library.
+</p>
+
+<h2> Compiling </h2>
+
+<ul>
+ <li> Make sure the nsss headers, as well as the skalibs headers,
+are visible in your header search path. </li>
+ <li> Use <tt>#include &lt;nsss/nsss.h&gt;</tt> </li>
+ <li> To use the standard <tt>pwd.h</tt> interface, you can
+just <tt>#include &lt;pwd.h&gt;</tt>, which will work as long
+as the <tt>nsss/pwd.h</tt> header is accessible in your header
+search path. </li>
+ <li> Same thing for <tt>grp.h</tt> and <tt>shadow.h</tt>. </li>
+</ul>
+
+<h2> Linking </h2>
+
+<ul>
+ <li> Make sure the nsss library, as well as the skalibs library,
+are visible in your library search path. </li>
+ <li> Link against <tt>-lnsss</tt>, <tt>-lskarnet</tt>, </li>
+<tt>`cat $SYSDEPS/socket.lib`</tt> and
+<tt>`cat $SYSDEPS/tainnow.lib`</tt>, $SYSDEPS being your skalibs
+sysdeps directory. </li>
+</ul>
+
+<h2> Programming </h2>
+
+<p>
+ The <tt>nsss/nsss.h</tt> header is actually a collection of headers:
+</p>
+
+<ul>
+ <li> <tt>nsss/nsss-unix.h</tt> implements basic access to the
+<tt>/etc/passwd</tt>, <tt>/etc/group</tt> and <tt>/etc/shadow</tt>
+database. </li>
+ <li> <tt>nsss/nsss-switch.h</tt> implements connection via a Unix
+domain socket to a listening <tt>nsssd</tt> daemon, implementing an
+authentication backend based on what implementation of
+the daemon is listening. </li>
+ <li> <tt>nsss/nsss-all.h</tt> implements a safe policy: first a
+connection via <tt>nsss-switch</tt> is attempted, and if no daemon
+is listening, the safe <tt>nsss-unix</tt> backend is used. </li>
+</ul>
+
+<p>
+ By default, the <tt>getpwnam()</tt> et al. functions are aliased
+to their <tt>nsss-all</tt> implementations. You can disable the
+<tt>nsss-unix</tt> fallback by compiling with the NSSS_DISABLE_UNIX
+macro defined (-DNSSS_DISABLE_UNIX). Or you can disable any
+attempt to connect to a daemon by compiling with the
+NSSS_DISABLE_SWITCH macro defined (-DNSSS_DISABLE_SWITCH).
+</p>
+
+<p>
+ (To be completed.)
+</p>
+
+</body>
+</html>
diff --git a/doc/overview.html b/doc/overview.html
new file mode 100644
index 0000000..222e296
--- /dev/null
+++ b/doc/overview.html
@@ -0,0 +1,35 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>nsss: an overview</title>
+    <meta name="Description" content="nsss: an overview" />
+    <meta name="Keywords" content="nsss overview pwd grp shadow password group authentication unix ldap" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">nsss</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> An overview of nsss </h1>
+
+<p>
+ nsss is a secure implementation of a subset of the
+<tt>pwd.h</tt>, <tt>grp.h</tt> and <tt>shadow.h</tt> functionality, i.e.
+user authentication on Unix systems. It includes full POSIX
+functionality, a few GNU extensions, and an underlying
+<a href="libnsss/">C client library</a> with better error reporting
+than the POSIX interface specifies.
+</p>
+
+<p>
+ To be completed.
+</p>
+
+</body>
+</html>
diff --git a/doc/upgrade.html b/doc/upgrade.html
new file mode 100644
index 0000000..5ff9e3b
--- /dev/null
+++ b/doc/upgrade.html
@@ -0,0 +1,28 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>How to upgrade nsss</title>
+    <meta name="Description" content="How to upgrade nsss" />
+    <meta name="Keywords" content="nsss installation upgrade" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">nsss</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> What has changed in nsss </h1>
+
+<h2> in 0.0.1.0 </h2>
+
+<p>
+ Initial release.
+</p>
+
+</body>
+</html>
author	Laurent Bercot <ska-skaware@skarnet.org>	2018-06-26 00:25:28 +0000
committer	Laurent Bercot <ska-skaware@skarnet.org>	2018-06-26 00:25:28 +0000
commit	633445be1a9be37ae727c044417f5607706cf4ae (patch)
tree	3c037459f5249e5c18ee5b9e41802c5964364f95 /doc
download	nsss-633445be1a9be37ae727c044417f5607706cf4ae.tar.xz