doc/users.html

<html><head><title>YaST2 Users module</title></head>
<body>
<h1>YaST2: Users configuration module</h1>

<p>
    Note this document has not been revisited since the year 2005.
    Thus, it may contain outdated information, specially since many
    components are been totally or partially rewritten in Ruby (under
    the namespace <tt>Y2Users</tt>) following a completely different
    approach.
</p>

<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>

<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 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"
]
</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.

<h2>The files</h2>

For more, see <a href="autodocs/index.html">developer's documentation</a>.
</body></html>