ACC SHELL
<html><head><title>YaST2 Users module</title></head>
<body>
<h1>YaST2: Users configuration module</h1>
<h2>Features (SL 9.3)</h2>
<p>
Basic module abilities:
<ul>
<li>add, remove and edit local users and groups
<li>add, remove and edit LDAP users and groups
<li>read NIS users and groups
<li>configure password encryption type
<li>configure authentication type
<li>edit defaults from /etc/defaults/useradd
</ul>
User attributes:
<ul>
<li>name
<li>password
<li>uid
<li>GECOS (fullname and other attributes)
<li>default group, additional group membership
<li>shell
<li>home directory
<li>password settings (warning limits, expiration date etc.)
<li>special attributes for LDAP users
</ul>
Group attributes:
<ul>
<li>name
<li>gid
<li>users
<li>password access
<li>special attributes for LDAP groups
</ul>
<a href="Todo.txt">TODO file</a>
<hr>
<h2>Implementation</h2>
YaST Users module consists from following subcomponents:
<ul>
<li>Perl modules
<ul>
<li>Users.pm
<li>UsersLDAP.pm
<li>UsersCache.pm
<li>UsersLDAP.pm
<li>YaPI/USERS.pm
</ul>
<li>SCR agents
<ul>
<li>SCR agent for reading and writing the main user/group config files
(e.g. /etc/passwd)
<li>SCR agent for reading and writing /etc/default/useradd config file
li>SCR agent for testing the password strength ("agent-crack")
<li>SCR agent for testing if the UIDs/usernames are unique ("agent-uid")
</ul>
<li>User interface files (dialog behaviour definition and implementation)
</ul>
<h3>Users.pm data structures and functions</h3>
<h4>Purpose of this module</h4>
<ul>
<li>Read and write the settings using agents
<li>Store the settings in module variables
<li>Provide functions required by other components
<li>Provide functions tightly bound to the data it stores
<li>Provide other functions required by user interface
</ul>
<h4>Data structures</h4>
<h5>map users</h5>
This structure gatheres informations of all users in the system.
(To be more precise, information of NIS and LDAP users could be
read later on demand, so just after Users::Read call, the map
describes the content of /etc/passwd config file). The map is
indexed by user type (local,system etc.), values are maps of each
type. The inner maps are indexed by UID, values are maps of users.
Such user map has the keys (user attributes, like 'uid' (= login name)
or 'home') and its values describing that user (see <i>user_in_work</i>
map).
<p>
Here is the example of 'users' structure, written in YCP:
<pre>
$[
"local":$[
500: $[
"cn" :"Ha Ha Herman",
"uid" :"hh",
"uidNumber" :500,
"gidNumber" :100,
"homeDirectory" :"/home/hh",
"userPassword" :"x",
"loginShell" :"/bin/bash",
"type" : "local",
"grouplist" : $[
"audio" : 1,
"video" : 1,
],
"modified" : "added",
"what" : "add_user",
],
],
"ldap": $[
5000: $[
"cn" :"LDAP user",
"givenName" : "LDAP",
"sn" : "user",
"dn" : "uid=ldap1,ou=people,dc=suse,dc=cz",
"uid" : "ldap1",
"uidNumber" : 5000,
"gidNumber" : 100,
"homeDirectory" : "/ldap_homes/ldap1",
"userPassword" : "x",
"loginShell" : "/bin/bash",
"shadowExpire" : "0",
"shadowInactive" : "-1",
"shadowLastChange" : "11984",
"shadowMax" : "99999",
"shadowMin" : "0",
"shadowWarning" : "7",
"type" : "ldap",
"grouplist" : $[
"audio" : 1,
"video" : 1,
"lgroup": 1
],
]
]
]
</pre>
<p>
<h5>map groups</h5>
<p>
This structure describes all the groups (which means - as default
- the content of /etc/group config file). The map is indexed by
group type (local,system etc.), values are maps of each type. The
inner maps are indexed by GID, values are maps of groups.
<p>
Example of structure:
<p>
<pre>
$[
"local":$[
500 :$[
"cn" : "users",
"gid" : 500,
"type" : "local"
"userlist" : $[],
"more_users" : $[
"hh": 1
],
]
],
"system": $[
1: $[
"cn" : "bin",
"gid" : 1,
"type" : "system"
"userlist" : $[
"daemon": 1
],
"more_users" : $[
"bin" : 1
],
],
]
]
</pre>
<p>
<h5>map shadow</h5>
<p>
This is the map indexed by user type (local,system etc.), values
are maps of each type. The inner maps are indexed by username,
values are maps of user shadow settings. This map describes the
content of /etc/shadow file.
<p>
<h5>map useradd_defaults</h5>
<p>
This map contains information about default values, used for new
users. It describes /etc/default/useradd config file.
<p>
Example of structure:
<p>
<pre>
$[
"group" : "500",
"home" : "/home",
"inactive" : "-1",
"expire" : "",
"shell" : "/bin/bash",
"skel" : "/etc/skel",
"groups" : "dialout,uucp,video,audio",
]
</pre>
<p>
<h5>map user_in_work</h5>
<p>
Map of current user. The maps with the same structure are saved in
global "users" map as the values for UID keys. The map contains:
<p>
<ul>
<li>real data entries
<p>
these which were read from the config file (/etc/passwd) or
other user repository (LDAP directory) and will be written
there at the end, like "gidNumber", "uidNumber", or "username".
<li>helper structures
<p>
these were generated from the "real" data and are stored in
the user map just as in some cache, like "grouplist"
(generated from "group" map), "org_home" (necessary for
moving home directory to new location), "type", etc.
</ul>
<p>
Example of <i>user_in_work</i> structure:
<pre>
$[
"cn" : "LDAP user",
"givenName" : "LDAP",
"sn" : "user",
"dn" : "uid=ldap1,ou=people,dc=suse,dc=cz",
"uid" : "ldap1",
"uidNumber" : 5000,
"gidNumber" : 100,
"homeDirectory" : "/ldap_homes/ldap1",
"userPassword" : "x",
"loginShell" : "/bin/bash",
"shadowExpire" : "0",
"shadowInactive" : "-1",
"shadowLastChange" : "11984",
"shadowMax" : "99999",
"shadowMin" : "0",
"shadowWarning" : "7",
"type" : "ldap",
"grouplist" : $[
"audio" : 1,
"video" : 1,
"lgroup": 1
],
]
</pre>
<h4>Functions</h4>
<h5>boolean Users::ReadNewSet (string type)</h5>
Local and system users (groups) are always read as default in
Users::Read() function. ReadNewSet () function provides reading of
non-standard user (group) set (this currently means NIS or LDAP)
on demand. Function gets the connection to server where the sets
are stored (it could require user interaction) and generates
appropriate ("nis" or "ldap") structures for both users and groups.
<h5>boolean Users::AddUser (map data)</h5>
Initialize data structure for new user. As a parameter, gets
data for new user - the map can be empty (just to fill in
defaults) or almost complete (for example after user added the
details via UI) - in this case use the map of <i>user_in_work</i>
format. Function chooses new UID
(if not given), fills defaults (from useradd structure), and
copies given data to new user map.
<h5>boolean Users::SelectUser (integer uid)</h5>
Finds the user identified by its UID and copies its data from
global <i>users</i> map to current user map (<i>user_in_work</i>).
<h5>boolean Users::SelectUserByName (string username)</h5>
Finds the user identified by its name and copies its data to
current user map.
<h5>boolean Users::EditUser (map data)</h5>
Initializes current user map (<i>user_in_work</i>) for editing. Copies
the original (not yet edited) data to 'org_user' submap.
Additionaly, loads the data not yet contained in current user map
(like "shadow" values or additional groups for NIS/LDAP users)
from the global structures to the <i>user_in_work</i> map. Initialization
is the one type of usage of Edit function, in such case its
parameter could be an empty map.
<p>
In the second type of usage, function updates current user map
using the values in the given parameter, which is a map with the
same format as the <i>user_in_work</i>, but
containing only the entries with the changed values.
<h5>string Users::CheckUser ()</h5>
Function does all necessary checks to ensure that new or just
edited user can be written (for example the checks for possible
UID/username duplicates, home directory existence etc.). Returns
error message of the first check that failed.
<h5>boolean Users::CommitUser ()</h5>
Saves the current user map to global structures and updates all
affected structures. Adapts the (cache) lists of all usernames,
uid's, home directories; adapts the affected groups. Cache
structures are adapted in UsersCache::CommitUser() function.
<p>
Takes care of special cases, e.g. when username or uid is changed,
because both are used as the indexes in some global structures.
<p>
All possible problems should be resolved in check functions before
CommitUser is called, so theoreticaly this function should never
fail.
<h3>The workflow</h3>
<p>
<img src="workflow.png">
<p>
<h2>The files</h2>
For more, see <a href="autodocs/index.html">developer's documentation</a>.
</body></html>
ACC SHELL 2018