ACC SHELL
<HTML>
<HEAD>
<TITLE>Ldap agent description</TITLE>
<!-- $Id: ldap.html 45136 2008-02-29 13:19:13Z jsuchome $ -->
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
</HEAD>
<BODY>
<H1>Ldap agent description</H1>
<HR>
<H2>Purpose</H2>
The Ldap agent (<tt>ag_ldap</tt>) is used to access LDAP directory.
It is part of YaST2 SCR, the system configuration repository,
used to access configuration data on the target system. The general
SCR API allows <tt>Read()</tt>, <tt>Write()</tt> and <tt>Execute()</tt>
access to get and change data.
<P>
<H2>Implementation</H2>
Agent uses c++ library (<tt>ldapcpplib</tt>) for all LDAP operations.<br>
During initialization (<tt>Execute (.ldap)</tt> call), new object of type
<tt>LDAPConnection</tt> is created and all further actions with LDAP contens
are called as the methods of this object.
<P>
The methods of ldapcpp library are described in
<a href="/usr/share/doc/packages/ldapcpplib/html/annotated.html">
ldapcpplib package documentation</a>.
<p>
<I>The complete development documentation is available in the
<A HREF="autodocs/index.html"><tt>autodocs/</tt></A> directory.</I>
<P>
<H2>Interface for ldap-agent</H2>
The interface is implemented as a SCR agent with the usual <tt>Read()</tt>,
<tt>Write()</tt> and <tt>Execute()</tt> interface. The path prefix used is
<tt>.ldap</tt>. For more see the paths tables.
<P>
<H2>Restrictions, limits and future enhancements</H2>
If you want to use agent, don't forget to call <tt>Execute(.ldap)</tt> at first
to initialize it.
<P>
See the <A HREF="TODO.txt">TODO.txt</A> file for the current status of support
and also for the list of possible future enhancements.
<P>
<H2>Complete Read paths table</H2>
<TABLE border=3>
<tr><th WIDth="20%" ALIGN="left">Path</th>
<th width="10%" align="left">Argument</th>
<th WIDth="10%" ALIGN="left">Type of Result</th>
<th ALIGN="left">Result</th>
</tr>
<tr><td><tt>.ldap.error</tt></td>
<td></td>
<td align="left">YCPMap</td>
<td>Map with last error message and code number.<br>
<b>Example of result:</b>
<pre>
$[
"msg" : "Can't contact LDAP server",
"code" : 81,
"server_msg": "Some additional error info from LDAP server"
]
</pre>
</td>
</tr>
<tr><td><tt>.ldap.search</tt></td>
<td align="left">YCPMap</td>
<td align="left">YCPMap or YCPList</td>
<td>Generic search command. Return value is list of objects (as default)
or map of type <tt>$[ dn: object ]</tt> (when the value of <tt>map</tt> argument is <tt>true</tt>).<br>
<b>Example of argument map</b>:
<pre>
$[
"base_dn" : "dc=suse,dc=cz",
"filter" : "(objectClass=posixGroup)",
"scope" : 0, //0:base, 1:one, 2:sub
"attrsOnly" : false,
// true: return map instead of the list
"map" : true,
// true: one-item values are
// returned as string, not as list with one value
"single_values" : false,
// true: return only list of DN's
"dn_only" : false,
// true: no error message is written when
// object was not found (empty list/map is returned)
"not_found_ok" : true,
// true: "dn" key is included in a map of each entry
"include_dn" : true,
// which attrinbutes do we search for
"attrs" : [ "objectClass", "cn", "gidNumber" ]
]</pre>
<b>Example of result map</b>:
<pre>
$[
"cn=users,dc=suse,dc=cz" : $[
"objectClass" : [ "posixGroup"],
"cn" : "users",
"gidNumber" : 500
],
"cn=group,dc=suse,dc=cz" : $[
"objectClass" : [ "posixGroup"],
"cn" : "group",
"gidNumber" : 501
]
]</pre>
</td>
</tr>
<tr><td><tt>.ldap.schema.object_class</tt></td>
<td>YCPMap</td>
<td>YCPMap</td>
<td>Get the map of object class with given name. Argument map
has to contain <tt>name</tt> entry.<br>
<b>Example of argument map</b>:
<pre>
$[ "name": "userTemplate"]</pre>
<b>Result map</b> contains entries <tt>oid, desc, must, may, sup</tt>.
<tt>"sup"</tt> is a name of superior class.
</td>
</tr>
<tr><td><tt>.ldap.schema.attr_types</tt></td>
<td>YCPMap</td>
<td>YCPMap</td>
<td>Get the map of attribute type with given name. Argument map
has to contain <tt>name</tt> entry.<br>
<b>Example of argument map</b>:
<pre>
$[ "name": "uidNumber"]
</pre>
<b>Result map</b> contains entries <tt>oid, desc, single, usage</tt>.
When <tt>single</tt> is true, only single value is allowed for
this attribute type. <tt>usage</tt> defines the attribute usage in these operations:
0=userApplications, 1=directoryOperation, 2=distributedOperation, 3=dSAOperation
</td>
</tr>
<tr><td><tt>.ldap.users</tt></td>
<td></td>
<td>YCPMap</td>
<td>Return map of users, generated by
<tt>Execute (.ldap.users.search)</tt> call.<br>
For the special use of yast2-users module.
</td>
</tr>
<tr><td><tt>.ldap.users.by_uidnumber</tt></td>
<td></td>
<td>YCPMap</td>
<td>Return mapping of UID's to user names. Map was generated by
<tt>Execute (.ldap.users.search)</tt> call.<br>
For the special use of yast2-users module.
</td>
</tr>
<tr><td><tt>.ldap.users.homes</tt></td>
<td></td>
<td>YCPList</td>
<td>Return list of home directories, previously generated by
<tt>Execute (.ldap.users.search)</tt> call.<br>
For the special use of yast2-users module.
</td>
</tr>
<tr><td><tt>.ldap.users.uids</tt></td>
<td></td>
<td>YCPList</td>
<td>Return list of UID's, previously generated by
<tt>Execute (.ldap.users.search)</tt> call.<br>
For the special use of yast2-users module.
</td>
</tr>
<tr><td><tt>.ldap.users.usernames</tt></td>
<td></td>
<td>YCPList</td>
<td>Return list of user names, previously generated by
<tt>Execute (.ldap.users.search)</tt> call.<br>
For the special use of yast2-users module.
</td>
</tr>
<tr><td><tt>.ldap.users.userdns</tt></td>
<td></td>
<td>YCPList</td>
<td>Return list of user DN's, previously generated by
<tt>Execute (.ldap.users.search)</tt> call.<br>
For the special use of yast2-users module.
</td>
</tr>
<!--
<tr><td><tt>.ldap.users.itemlist</tt></td>
<td></td>
<td>YCPList</td>
<td>Return list of items for user table, previously generated by
<tt>Execute (.ldap.users.search)</tt> call.<br>
For the special use of yast2-users module. Currently not used.
</td>
</tr>
-->
<tr><td><tt>.ldap.groups</tt></td>
<td></td>
<td>YCPMap</td>
<td>Return map of groups (indexed by cn attribute), generated by
<tt>Execute (.ldap.groups.search)</tt> call.<br>
For the special use of yast2-users module.
</td>
</tr>
<tr><td><tt>.ldap.groups.by_gidnumber</tt></td>
<td></td>
<td>YCPMap</td>
<td>Return map of group names, indexed by gidnumber attribute.
Map was generated by
<tt>Execute (.ldap.groups.search)</tt> call.<br>
For the special use of yast2-users module.
</td>
</tr>
<tr><td><tt>.ldap.groups.gids</tt></td>
<td></td>
<td>YCPList</td>
<td>Return list of GID's, previously generated by
<tt>Execute (.ldap.groups.search)</tt> call.<br>
For the special use of yast2-users module.
</td>
</tr>
<tr><td><tt>.ldap.groups.groupnames</tt></td>
<td></td>
<td>YCPList</td>
<td>Return list of group names, previously generated by
<tt>Execute (.ldap.groups.search)</tt> call.<br>
For the special use of yast2-users module.
</td>
</tr>
<!--
<tr><td><tt>.ldap.groups.itemlist</tt></td>
<td></td>
<td>YCPList</td>
<td>Return list of items for group table, previously generated by
<tt>Execute (.ldap.groups.search)</tt> call.<br>
For the special use of yast2-users module. Currently not used.
</td>
</tr>
-->
</TABLE>
<P>
<H2>Complete Write paths table</H2>
Return value is YCPBoolean (usually the success of the object method call).
<p>
Generaly, 1st argument is a map, containing value of DN (of modified object) and
possibly other values. (e.g.<tt>$[ "dn" : "ou=Groups,dc=suse,dc=cz" ]</tt>)
<TABLE border=3>
<tr><th width="20%" align="left">Path</th>
<th width="10%" align="left">1st argument</th>
<th width="10%" align="left">2nd argument</th>
<th align="left">Result</th>
</tr>
<tr><td><tt>.ldap.add</tt></td>
<td align="left">YCPMap</td>
<td align="left">YCPMap</td>
<td>Add a new LDAP object. Second argument is map of its attributes.<br>
<b>Example of attributes map:</b>
<pre>
$[
"objectClass" : [ "organizationalUnit"],
"ou" : "Groups"
]</pre>
</td>
</tr>
<tr><td><tt>.ldap.modify</tt></td>
<td align="left">YCPMap</td>
<td align="left">YCPMap</td>
<td>Modifies an existing LDAP object.<br>
Second argument is map of
attributes (and its values) which should be changed/added/deleted.
To remove some attribute, use empty value ("" or []) for it.<br>
<!--
If 1st argument map contains <tt>"rdn"</tt> key, object will be
renamed using the value of <tt>"rdn"</tt> as a new Relative
Distinguished Name.<br>
-->
Parameter <tt>"new_dn"</tt> (DN of new object) is necessary for
renaming.<br>
For moving the object, use additionaly <tt>"newParentDN"</tt> value
for new parent DN of object.<br>
If argument map contains <tt>"check_attrs"</tt> key with <tt>true
</tt> value, there will be done a search for current object's
attributes before modify. When some attribute in attributes map
(2nd argument) has an empty value it will be ignored, if the object
currently has not such attribute. Otherwise (<tt>"check_attrs"</tt>
is false as default), this situation leads to error message,
because non-existent attribute is set for deletion.<br>
If you want to rename or move an entry, which is not a leaf of LDAP
tree, you must include <tt>"subtree"</tt> key (with true as a value)
in argument map. In
such a case, the modify operation could take more time, according
to the subtree size, because all subtree items must be copied to new
location and deleted from the old one.<br>
<b>Example of argument map:</b>
<pre>
$[
"dn" : "ou=people,dc=suse,dc=cz",
"new_dn" : "ou=lide,dc=suse,dc=cz",
"deleteOldRDN" : true,
"subtree" : true
]
</pre>
<b>Example of attributes map:</b>
<pre>
$[
"ou": "lide"
]
</pre>
</td>
</tr>
<tr><td><tt>.ldap.delete</tt></td>
<td align="left">YCPMap</td>
<td align="left">YCPMap</td>
<td>Deletes LDAP object. With "subtree" set to true, it will
delete the whole subtree of the given entry. <b>Use carefully!</b><br>
<b>Example of argument map:</b>
<pre>
$[
"dn" : "ou=people,dc=suse,dc=cz",
"subtree" : true
]</pre>
</td>
</tr>
</TABLE>
<P>
<H2>Complete Execute paths table</H2>
Return value is YCPBoolean (usually the success of the object method call).
<p>
<table border=3>
<tr><th width="15%" align="left">Path</th>
<th width="15%" align="left">Argument</th>
<th align="left">Result</th>
</tr>
<tr><td><tt>.ldap</td>
<td align="left">YCPMap</td>
<td>Initialization. Input map has to contain hostname and may contain
port number and "use_tls" entry. "use_tls" could have these values:
<ul>
<li>"no": Do not start TLS (same when "use_tls" is missing).</li>
<li>"try": Start TLS. If it was not successful, fall back to unencrypted LDAP.</li>
<li>"yes": Start TLS. If it fails, return false (check its value with ldap.error read call).</li>
</ul>
<b>Example of SCR call:</b>
<pre>
Execute(.ldap, $[
"hostname" : "localhost",
"port" : 389,
"use_tls" : "try"
])
</pre>
</td>
</tr>
<tr><td><tt>.ldap.ping</td>
<td align="left">YCPMap</td>
<td>Checks if it is possible to run a search query on the server.
Return value is boolean; in case false is returned, it is possible
that server is not running - check the error value via error read
call.
Input map has to contain hostname and may contain port number.
<br>
<b>Example of SCR call:</b><br>
<pre>
Execute (.ldap.ping, $[ "hostname" : "localhost",])
</pre>
</td>
</tr>
<tr><td><tt>.ldap.ppolicy</td>
<td align="left">YCPMap</td>
<td>Checks if server supports Password Policy.
Return value is boolean.
Input map has to contain hostname, bind DN and may contain port number.
For bind DN, use base DN of the LDAP Database or a child of it.
<br>
<b>Example of SCR call:</b><br>
<pre>
Execute (.ldap.ppolicy, $[
"hostname" : "localhost",
"bind_dn" : "dc=suse,dc=cz"
])
</pre>
</td>
</tr>
<tr><td><tt>.ldap.bind</td>
<td align="left">YCPMap</td>
<td>Bind to server. Items of input map should be <tt>"bind_dn"</tt>
and <tt>"bind_pw"</tt>. For anonymous acess, let input map empty.
<br>
<b>Example of SCR call:</b><br>
<pre>
Execute (.ldap.bind, $[ "bind_dn": "uid=manager,dc=suse,dc=cz", "bind_pw": "heslo"])
</pre>
</td>
</tr>
<tr><td><tt>.ldap.start_tls</td>
<td align="left">none</td>
<td>Starts TLS on current connection. Returns false when operation
failed (check error via ldap.error then).
<b>Example of SCR call:</b><br>
<pre>
Execute (.ldap.start_tls)
</pre>
</td>
</tr>
<tr><td><tt>.ldap.schema</td>
<td align="left">YCPMap</td>
<td>Initialize LDAP schema: read it (defined by <tt>"schmema_dn"</tt>),
parse it and save lists of its object classes and attribute types
to internal structures. From now, they are available for
<tt>Read(.ldap.schema.*)</tt> calls.<br>
<b>Example of SCR call:</b><br>
<pre>
Execute (.ldap.schema, $[ "schema_dn": "cn=Subschema"])
</pre>
</td>
</tr>
<tr><td><tt>.ldap.users.search</td>
<td align="left">YCPMap</td>
<td>LDAP search command for users and groups. Specialized call for the
use of yast2-users module. Additionaly to normal search, it builds
many helper structures - they are read by the calls of type
<tt>Read(.ldap.users.*)</tt> and <tt>Read(.ldap.groups.*)</tt>.<br>
<b>Example of SCR call:</b><br>
<pre>
Execute (.ldap.users.search,
$[
"user_base" : "dc=suse,dc=cz",
"group_base" : "dc=suse,dc=cz",
"user_filter" : "objectClass=posixAccount",
"user_attrs" : [ "objectClass", "cn", "uid", "uidNumber", "gidNumber"],
"group_filter" : "objectClass=posixGroup",
"group_attrs" : [ "objectClass", "cn", "gidNumber", "uniqueMember" ],
"group_scope" : 1,
"member_attribute" : "uniquemember",
])
</pre>
</td>
</tr>
<tr><td><tt>.ldap.unbind</td>
<td align="left">none</td>
<td>Performs the UNBIND-operation on the current server.<br>
<pre>
Execute (.ldap.unbind)
</pre>
</td>
</tr>
</table>
<P>
<ADDRESS>
Jiří Suchomel <jsuchome@suse.cz><BR>
</ADDRESS>
</BODY>
</HTML>
ACC SHELL 2018