Ldap agent description

Purpose

The Ldap agent (ag_ldap) 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 Read(), Write() and Execute() access to get and change data.

Implementation

Agent uses c++ library (ldapcpplib) for all LDAP operations.
During initialization (Execute (.ldap) call), new object of type LDAPConnection is created and all further actions with LDAP contens are called as the methods of this object.

The methods of ldapcpp library are described in ldapcpplib package documentation.

The complete development documentation is available in the autodocs/ directory.

Interface for ldap-agent

The interface is implemented as a SCR agent with the usual Read(), Write() and Execute() interface. The path prefix used is .ldap. For more see the paths tables.

Restrictions, limits and future enhancements

If you want to use agent, don't forget to call Execute(.ldap) at first to initialize it.

See the TODO.txt file for the current status of support and also for the list of possible future enhancements.

Complete Read paths table

Path	Argument	Type of Result	Result
`.ldap.error`		YCPMap	Map with last error message and code number. Example of result: `$[ "msg": "Can't contact LDAP server", "code": 81 ]`
`.ldap.search`	YCPMap	YCPMap or YCPList	Generic search command. Return value is list of objects (as default) or map of type `$[ dn: object ]` when `return_map` in argument map is `true`. Example of argument map: $[ "base_dn": "dc=suse,dc=cz", "filter" : "(objectClass=posixGroup)", "scope" : 0, //0:base, 1:one, 2:sub "attrsOnly": false, "return_map": true, // when true, return map not the list "single_values": false, // when true, one-item values are returned as string, not as list with one value "dn_only": false, // when true, only list of DN's will be returned "not_found_ok": true, // when true, no error message is written when object was not found (empty list/map is returned) "attrs": [ "objectClass", "cn", "gidNumber" ] // which attrinbutes do we search for ] Example of result map: `$[ "cn=users,dc=suse,dc=cz" : $[ "objectClass": [ "posixGroup"], "cn": "users", "gidNumber" : 500 ], "cn=group,dc=suse,dc=cz" : $[ "objectClass": [ "posixGroup"], "cn": "group", "gidNumber" : 501 ] ]`
`.ldap.schema.object_class`	YCPMap	YCPMap	Get the map of object class with given name. Argument map has to contain `name` entry. Example of argument map: `$[ "name": "userTemplate"]` Result map contains entries `oid, desc, must, may, sup`. `"sup"` is name of superior class.
`.ldap.schema.attr_types`	YCPMap	YCPMap	Get the map of attribute type with given name. Argument map has to contain `name` entry. Example of argument map: `$[ "name": "uidNumber"]` Result map contains entries `oid, desc, single`. When `"single"` is true, only single value is allowed for this attribute type.
`.ldap.users`		YCPMap	Return map of users, generated by `Execute (.ldap.users.search)` call. For the special use of yast2-users module.
`.ldap.users.by_name`		YCPMap	Return mapping of user names to UID's. Map was generated by `Execute (.ldap.users.search)` call. For the special use of yast2-users module.
`.ldap.users.homes`		YCPList	Return list of home directories, previously generated by `Execute (.ldap.users.search)` call. For the special use of yast2-users module.
`.ldap.users.uids`		YCPList	Return list of UID's, previously generated by `Execute (.ldap.users.search)` call. For the special use of yast2-users module.
`.ldap.users.usernames`		YCPList	Return list of user names, previously generated by `Execute (.ldap.users.search)` call. For the special use of yast2-users module.
`.ldap.users.userdns`		YCPList	Return list of user DN's, previously generated by `Execute (.ldap.users.search)` call. For the special use of yast2-users module.
`.ldap.users.itemlist`		YCPList	Return list of items for user table, previously generated by `Execute (.ldap.users.search)` call. For the special use of yast2-users module.
`.ldap.groups`		YCPMap	Return map of groups (indexed by GID's), generated by `Execute (.ldap.groups.search)` call. For the special use of yast2-users module.
`.ldap.groups.by_name`		YCPMap	Return map of groups, indexed by group names. Map was generated by `Execute (.ldap.groups.search)` call. For the special use of yast2-users module.
`.ldap.groups.gids`		YCPList	Return list of GID's, previously generated by `Execute (.ldap.groups.search)` call. For the special use of yast2-users module.
`.ldap.groups.groupnames`		YCPList	Return list of group names, previously generated by `Execute (.ldap.groups.search)` call. For the special use of yast2-users module.
`.ldap.groups.itemlist`		YCPList	Return list of items for group table, previously generated by `Execute (.ldap.groups.search)` call. For the special use of yast2-users module.

Complete Write paths table

Return value is YCPBoolean (usually the success of the object method call).

Generaly, 1st argument is a map, containing value of DN (of modified object) and possibly other values. (e.g.$[ "dn" : "ou=Groups,dc=suse,dc=cz" ])

Path 1st argument 2nd argument Result

.ldap.add YCPMap YCPMap Add a new LDAP object. Second argument is map of its attributes.
Example of attributes map:
$[ "objectClass": [ "organizationalUnit"], "ou": "Groups" ]

.ldap.modify YCPMap YCPMap Modifies an existing LDAP object. Second argument is map of attributes (and its values) which are to be changed/added/deleted. To remove some attribute, use empty value ("" or []) for it.
If 1st argument map contains "rdn" key, object will be renamed using the value of "rdn" as a new Relative Distinguished Name.
For moving the object, use additionaly "newParentDN" value for new parent DN of object.
If argument map contains "check_attrs" key with true 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 ("check_attrs" is false as default), this situation leads to error message, because non-existent attribute is set for deletion.
Example of argument map:
$[ "dn": "ou=people,dc=suse,dc=cz", "rdn": "ou=lide", "delOldRDN": true ] Example of attributes map:
$[ "ou": "lide" ]

.ldap.delete YCPMap YCPMap Deletes LDAP object.

Path	1st argument	2nd argument	Result
`.ldap.add`	YCPMap	YCPMap	Add a new LDAP object. Second argument is map of its attributes. Example of attributes map: `$[ "objectClass": [ "organizationalUnit"], "ou": "Groups" ]`
`.ldap.modify`	YCPMap	YCPMap	Modifies an existing LDAP object. Second argument is map of attributes (and its values) which are to be changed/added/deleted. To remove some attribute, use empty value ("" or []) for it. If 1st argument map contains `"rdn"` key, object will be renamed using the value of `"rdn"` as a new Relative Distinguished Name. For moving the object, use additionaly `"newParentDN"` value for new parent DN of object. If argument map contains `"check_attrs"` key with `true` 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 (`"check_attrs"` is false as default), this situation leads to error message, because non-existent attribute is set for deletion. Example of argument map: `$[ "dn": "ou=people,dc=suse,dc=cz", "rdn": "ou=lide", "delOldRDN": true ]` Example of attributes map: `$[ "ou": "lide" ]`
`.ldap.delete`	YCPMap	YCPMap	Deletes LDAP object.

Complete Execute paths table

Return value is YCPBoolean (usually the success of the object method call).

Path Argument Result

.ldap YCPMap Initialization. Input map has to contain hostname and may contain port number.
Example of SCR call:
Execute(.ldap, $[ "host": "localhost", "port": 389])

.ldap.bind YCPMap Bind to server. Items of input map should be "bind_dn" and "bindpw". For anonymous acess, let input map empty. Example of SCR call:
Execute(.ldap.bind, $[ "bind_dn": "uid=manager,dc=suse,dc=cz", "bind_pw": "heslo"])

.ldap.start_tls none Starts TLS on current connection. Returns false when operation failed (check error via ldap.error then). Example of SCR call:
Execute (.ldap.start_tls)

.ldap.schema YCPMap Initialize LDAP schema: read it (defined by "schmema_dn"), parse it and save lists of its object classes and attribute types to internal structures. From now, they are available for Read(.ldap.schema.*) calls.
Example of SCR call:
Execute(.ldap.schema, $[ "schema_dn": "cn=Subschema"])

.ldap.users.search YCPMap 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 Read(.ldap.users.*) and Read(.ldap.groups.*).
Example of SCR call:
Execute(.ldap.schema, $[ "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", ])

Path	Argument	Result
`.ldap`	YCPMap	Initialization. Input map has to contain hostname and may contain port number. Example of SCR call: `Execute(.ldap, $[ "host": "localhost", "port": 389])`
`.ldap.bind`	YCPMap	Bind to server. Items of input map should be `"bind_dn"` and `"bindpw"`. For anonymous acess, let input map empty. Example of SCR call: `Execute(.ldap.bind, $[ "bind_dn": "uid=manager,dc=suse,dc=cz", "bind_pw": "heslo"])`
`.ldap.start_tls`	none	Starts TLS on current connection. Returns false when operation failed (check error via ldap.error then). Example of SCR call: `Execute (.ldap.start_tls)`
`.ldap.schema`	YCPMap	Initialize LDAP schema: read it (defined by `"schmema_dn"`), parse it and save lists of its object classes and attribute types to internal structures. From now, they are available for `Read(.ldap.schema.)` calls. Example of SCR call:* `Execute(.ldap.schema, $[ "schema_dn": "cn=Subschema"])`
`.ldap.users.search`	YCPMap	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 `Read(.ldap.users.)` and `Read(.ldap.groups.)`. Example of SCR call: `Execute(.ldap.schema, $[ "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", ])`

Jiri Suchomel <jsuchome@suse.cz>