1
<!doctype linuxdoc system>
4
<title>libuser 0.52.2</title>
5
<author>Nalin Dahyabhai <tt/<nalin@redhat.com>/
6
<date>28 September 2004
7
<abstract>This is the libuser administrator and programmer's guide. It
8
first describes the motivation for the existence of this library, and
9
then delves into the library interface used by both libuser modules and
10
applications.</abstract>
14
<p>This section describes libuser: why it was written, and how it works. How
15
the library is to be used will be described later.
19
<p>When proper nsswitch functionality was introduced into glibc 2.0, it
20
became possible to supply third-party facilities which would allow the
21
standard C library (and by extension, all of a system's binaries) to pull
22
information about users, protocols, and services from a variety of sources
23
the glibc authors might not have anticipated.
25
<p>The most common use for a new nsswitch module is supplementing the user
26
and group databases, extending the data sources accessed over a network
27
to a centrally-managed information store. This, along with the ability to
28
authenticate users using networked servers (functionality provided by the
29
increasingly-ubiquitous Linux-PAM library) and an enterprise-class
30
networked filesystem, allows a properly-configured Linux workstation to
31
participate as a full-fledged client in a large-scale network.
33
<p>The facilities provided by PAM allow a user to log in and change her
34
authentication tokens. The nsswitch interface allows any user (even
35
unprivileged users like <bf>nobody</bf>) to look up information needed
38
<p>However, there are certain functions supplied by traditional isolated
39
systems which such a networked workstation can't provide. Users have no
40
method for modifying their non-essential information (<bf>chfn</bf> is broken),
41
and the system administrator who previously had total power over the user and
42
group databases must now perform all administration at the server using
43
tools which are designed for general modification of the information
44
store (hand-editing zone files for hesiod databases, <bf>ldapmodify</bf>,
45
<bf>kadmin</bf>) instead of the traditionally-used tools.
49
<sect1>Alternative Solutions
51
<p>The software which comes closest to meeting these needs is
52
<bf>pwdb</bf>. However, the pwdb library has a few design limitations
53
which make it unsuitable for this purpose. Like the standard files-based
54
mechanisms, pwdb assumes that the superuser wields full power over the
55
databases it interfaces with. The current version of pwdb provides no
56
facilities for managing groups(?). The current version of pwdb can not be
57
extended easily by third parties due to its reliance on static linking.
61
<sect1>The libuser Library
63
<p>The libuser library implements a fully-modular system for reading,
64
modifying, creating, and removing user and group accounts and account
65
information. Modules which provide access to information stores can
66
request information from the accessing user in order to authenticate to
67
the information store.
73
<sect>System Administration
75
<p>This section describes libuser's configuration file and bundled
76
applications which may be of use to system administrators.
80
<p>The libuser configuration file is named <bf>libuser.conf</bf> and
81
usually lives in <bf>/etc</bf>. Its format is the common format used
82
by numerous other programs. Sections are marked by the section name
83
enclosed in square brackets (<bf>[section]</bf>), and configuration
84
directives within these sections are of the form <bf>key = value</bf>.
86
<p>The <bf>defaults</bf>, <bf>userdefaults</bf>, and <bf>groupdefaults</bf>
87
sections are used by the library itself. The <bf>defaults</bf> section
88
specifies the directory where modules can be found (<bf>moduledir</bf>) and
89
lists the modules to be consulted when looking up user information.
91
<p>There are two lists of modules because <bf>libuser</bf> separates an
92
account's authentication information from other information. This is done
93
to allow different information stores to be used for these functions, and
94
because some information stores can only hold authentication data (for
95
example, shadow and krb5).
97
<p>For the <bf>info_modules</bf> and <bf>auth_modules</bf> lists, order
98
is only important for account creation -- the library will attempt to
99
create a data entry for the user in each of the modules until one of them
100
succeeds (so if you prefer new accounts to be created in your LDAP
101
directory, then you'd make sure "ldap" was listed <it>before</it>
102
"files"). For looking up account information, the order determines
103
precedence because the library stops searching after a module returns success
104
(so again, you'd want "ldap" listed before "files").
105
Account modifications and deletions go straight to the information store which
106
is known to hold the user's information.
112
<p>Specific modules implement access to specific information stores. The
113
modules included in the source distribution are the <bf>files</bf> and
114
<bf>shadow</bf> modules. Modules can supply and manipulate either (or both)
115
of two distinct types of data about a user: generic user information (the
116
UID, home directory, etc.), and authentication-related information.
120
<p>The files module implements both information and authentication data
121
stores using the standard <bf>passwd</bf> and <bf>group</bf> files.
123
<p>This module uses the <bf>files</bf> section of the configuration file
124
to store configuration data. It presently recognizes these flags:
127
<item>directory - the directory the <bf>passwd</bf> and <bf>group</bf> files
135
<p>The shadow module implements only an authentication data store using
136
the <bf>shadow</bf> and the <bf>gshadow</bf> files. While the format of
137
these files (and even the existence of the <bf>gshadow</bf> file) varies
138
between OSs, this module supports the same file formats used by the shadow
141
<p>This module uses the <bf>shadow</bf> section of the configuration file
142
to store configuration data. It presently recognizes these flags:
145
<item>directory - the directory the <bf>shadow</bf> and <bf>gshadow</bf>
146
files are to be stored in.
153
<p>The krb5 module implements only an authentication data store using
154
a connection to the Kerberos realm's administrative server and the kadmin
157
<p>This module uses the <bf>krb5</bf> section of the configuration file
158
to store configuration data. It presently recognizes these flags:
161
<item>realm - the default realm to administer accounts in. If not specified,
162
the value is taken from <bf>krb5.conf</bf> by the Kerberos libraries the
170
<p>The ldap module implements both information and authentication data stores
171
using an LDAP directory and a schema which (should) conform to RFC2307. The
172
module expects the client and server to support access using LDAPv3 with TLS;
173
TLS is not required if the server is specified by URI.
175
<p>This module uses the <bf>ldap</bf> section of the configuration file
176
to store configuration data. It presently recognizes these flags:
179
<item>server - the hostname or URI of the LDAP server
180
<item>basedn - the distinguished name which is the root of your tree
181
<item>user - the user name with which to perform SASL binds
182
<item>authuser - the authorization user name with which to perform SASL binds
183
<item>binddn - the distinguished name to connect as for administrative access
184
<item>userBranch - the distinguished name (relative to the basedn) under which
185
user account data is kept
186
<item>groupBranch - the distinguished name (relative to the basedn) under which
187
group account data is kept
196
<p>Sample testbed applications which mimic the behavior of certain parts
197
of the shadow password suite are included in the libuser distribution.
198
To allow them to be used alongside existing utilities, their names have
199
been prefixed with the letter 'l'.
201
<p>As of this writing (version 0.7), this list of tools includes
202
workalikes for <bf>useradd</bf>, <bf>usermod</bf>, <bf>userdel</bf>,
203
<bf>groupadd</bf>, <bf>groupmod</bf>, <bf>groupdel</bf>, and <bf>chage</bf>.
204
It should be noted that none of these tools provide a means for modifying
205
the defaults they use, and no functions for creating, populating, moving, or
206
deleting user home directories are implemented.
added
removed
docs/sgml/libuser.sgml
