ACC SHELL
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>YaPI__USERS</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:feedback@suse.de" />
</head>
<body style="background-color: white">
<!-- INDEX BEGIN -->
<div name="index">
<p><a name="__index__"></a></p>
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#preface">PREFACE</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
</ul>
<hr name="index" />
</div>
<!-- INDEX END -->
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>YaPI::USERS</p>
<p>
</p>
<hr />
<h1><a name="preface">PREFACE</a></h1>
<p>This package is the public YaST2 API for Users/Groups management</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p>use YaPI::USERS</p>
<p>$error = UserAdd ($config_hash, $data_hash)</p>
<pre>
Creates new user, described in $data_hash.
Returns an error message if operation failed or empty string otherwise.</pre>
<p>$error = UserModify ($config_hash, $data_hash)</p>
<pre>
Modifies the data of given user.
Returns an error message if operation failed or empty string otherwise.</pre>
<p>$error = UserFeatureAdd ($config_hash)</p>
<pre>
Adds a new feature (plugin) to the given user.
Returns an error message if operation failed or empty string otherwise.</pre>
<p>$error = UserFeatureDelete ($config_hash)</p>
<pre>
Removes a feature (plugin) from the given user.
Returns an error message if operation failed or empty string otherwise.</pre>
<p>$error = UserDelete ($config_hash)</p>
<pre>
Deletes an existing user.
Returns an error message if operation failed or empty string otherwise.</pre>
<p>$error = UserDisable ($config_hash)</p>
<pre>
Disable user to log in.
Returns an error message if operation failed or empty string otherwise.</pre>
<p>$error = UserEnable ($config_hash)</p>
<pre>
Enable disabled user to log in again.
Returns an error message if operation failed or empty string otherwise.</pre>
<p>$data_hash = UserGet ($config_hash)</p>
<pre>
Returns data hash decribing user.</pre>
<p>$users_hash = UsersGet ($config_hash)</p>
<pre>
Returns hash of users. The resulting set is defined in $config hash.</pre>
<p>$error = GroupAdd ($config_hash, $data_hash)</p>
<pre>
Creates new group, described in $data_hash.
Returns an error message if operation failed or empty string otherwise.</pre>
<p>$error = GroupModify ($config_hash, $data_hash)</p>
<pre>
Modifies the data of given group.
Returns an error message if operation failed or empty string otherwise.</pre>
<p>$error = GroupMemberAdd ($config_hash, $user_hash)</p>
<pre>
Adds a new member (user) to the given group.
Returns an error message if operation failed or empty string otherwise.</pre>
<p>$error = GroupMemberDelete ($config_hash, $user_hash)</p>
<pre>
Removes a member from the given group.
Returns an error message if operation failed or empty string otherwise.</pre>
<p>$error = GroupDelete ($config_hash)</p>
<pre>
Deletes an existing group.
Returns an error message if operation failed or empty string otherwise.</pre>
<p>$data_hash = GroupGet ($config_hash)</p>
<pre>
Returns data hash decribing group.</pre>
<p>$groups_hash = GroupsGet ($config_hash)</p>
<pre>
Returns hash of groups. The resulting set is defined in $config hash.</pre>
<p>$groups_hash = GroupsGetByUser ($config_hash, $user_hash)</p>
<pre>
Returns hash of groups given user is member of.
The resulting set is defined in $config hash.</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<ul>
<li><strong><a name="useradd" class="item"><code>$error = UserAdd ($config_hash, $data_hash)</code></a></strong>
<p>Creates new user. User attributes are described in $data_hash,
$config_hash describes special configuration data.</p>
<p>Returns an error message if operation failed or empty string otherwise.</p>
<p>PARAMETERS:</p>
<pre>
Possible parameters for $config hash:</pre>
<pre>
"type" Type of user (string). Possible values:
"local","system","ldap","nis". ("nis" is not available
for adding)</pre>
<pre>
Specific parameters of $config hash, related to LDAP users (all keys
are optional, there should exist reasonable default values based on
current LDAP configuration):</pre>
<pre>
"bind_dn"
DN of LDAP administrator, used to bind to LDAP server
(string)
"bind_pw"
Password for LDAP administrator (string)
"anonymous_bind"
If this key is present, there will be done created an
anonymous connection to LDAP server (if it is allowed).
"member_attribute"
Name of LDAP attribute, defining the membership in LDAP
groups (possible values: "member", "uniquemember"). The
default value is in /etc/ldap.conf (nss_map_attribute).</pre>
<pre>
"user_attributes"
List of attributes to be returned by an LDAP search for
user (list of strings). If empty, all non-empty
attributes will be returned as a result of search.</pre>
<pre>
"user_filter"
Filter for restricting LDAP searches (string).
The default value is stored as "suseSearchFilter" in
LDAP configuration.</pre>
<pre>
"user_base"
DN of LDAP base where the users are stored (string). By
default, the value of "suseDefaultBase" stored in LDAP
configuration is used.</pre>
<pre>
"user_scope"
The scope used for LDAP searches for users. Possible
values are 0 (base), 1(one), 2(sub). Default is 2.
"plugins"
List of plugins which should be applied for user
(list of strings). General plugin for LDAP users,
("UsersPluginLDAPAll") is always available, others are
part of modules which has to be installed before their
usage (yast2-samba-server, yast2-mail-server).</pre>
<pre>
"user_plugins"
Same as "plugins".</pre>
<pre>
Values mentioned above are common for all $config hashes in the
functions for handling user. Additionally, there is a special value
which is defined only for UserAdd:</pre>
<pre>
"create_home"
If this is set to 0, the home directory for new user
won't be created.</pre>
<pre>
Possible parameters for $data hash:</pre>
<pre>
"uid" Login name
"cn" Full name
"userPassword" User's password
"homeDirectory" Users's home directory
"loginShell" User's login shell
"gidNumber" GID of user's default group
"groupname" name of user's default group; YaST itself will look for GID
"grouplist" Hash (of type { <group_name> => 1 }) with groups
this user should be member of.
"shadowinactive" Days after password expires that account is disabled
"shadowexpire" Days since Jan 1, 1970 that account is disabled
"shadowwarning" Days before password is to expire that user is warned
"shadowmin" Days before password may be changed
"shadowmax" Days after which password must be changed
"shadowflag" (last value at line in /etc/shadow)
"shadowlastchange" Days since Jan 1, 1970 that password was last changed</pre>
<pre>
<ldap_attribute> For LDAP users, any attribute supported by
users's object class can be here.</pre>
<p>EXAMPLE:</p>
<pre>
my $config = { "type" => "ldap",
"plugins" => [ "UsersPluginLDAPAll" ],
"bind_dn" => "uid=admin,dc=example,dc=com",
};
my $data = { "uid" => "ll",
"uidNumber" => 1111,
"userPassword" => "qqqqq"
"givenName" => "l",
"cn" => [ "ll" ]
"description" => [ "first", "second" ],
};
# create new LDAP user
my $error = UserAdd ($config, $data);</pre>
<pre>
# create new local user 'hh'; use all available defaults
UserAdd ({}, { "uid" => "hh" });</pre>
<p>NOTE</p>
<pre>
You can see on example that LDAP attributes could be passed either
as list of value or as strings, which is just the same case as a list
with one value.</pre>
</li>
<li><strong><a name="usermodify" class="item"><code>$error = UserModify ($config_hash, $data_hash)</code></a></strong>
<p>Modifies existing user. User attributes which should be changed
are described in $data_hash,
$config_hash describes special configuration data, especially user
identification.</p>
<p>Returns an error message if operation failed or empty string otherwise.</p>
<p>PARAMETERS:</p>
<pre>
Special values for $config hash: additinally to the values always
available (see L<UserAdd>), $config must contains one of the key
used to identify the user which should be modified:</pre>
<pre>
"dn" Distinguished name (DN) - only for LDAP user
"uid" User name (which is value of "uid" for LDAP user)
"uidNumber" UID number ("uidNumber" value for LDAP user)</pre>
<pre>
For values in $data hash, see L<UserAdd>.</pre>
<p>EXAMPLE:</p>
<pre>
my $config = { "type" => "ldap",
"uidNumber" => 500
};
my $data = { "userPassword" => "wwwww"
};
# changes a password of LDAP user (identified with id)
my $error = UserModify ($config, $data);</pre>
<pre>
# change GID value of local user (identified with name)
$error = UserModify ({ "uid" => "hh" }, { "gidNumber" => 5555 });</pre>
</li>
<li><strong><a name="userfeatureadd" class="item"><code>$error UserFeatureAdd ($config_hash);</code></a></strong>
<p>Adds a new feature (plugin) to the given user.</p>
<p>Returns an error message if operation failed or empty string otherwise.</p>
<p>PARAMETERS:</p>
<pre>
$config hash can contain data always available (see L<UserAdd>)
and the data used for user identification (see L<UserModify>).
Additionally, it has to contain the value for</pre>
<pre>
"plugins" List of plugins which should be added to the user.</pre>
<p>EXAMPLE:</p>
<pre>
my $config = { "type" => "ldap",
"plugins" => [ "UsersPluginSambaAccount" ],
"bind_dn" => "uid=admin,dc=example,dc=com",
"uid" => "ll"
};
# adds 'SambaAccount' plugin to the user
my $error = UserFeatureAdd ($config);</pre>
</li>
<li><strong><a name="userfeaturedelete" class="item"><code>$error UserFeatureDelete ($config_hash);</code></a></strong>
<p>Deletes a new feature (plugin) to the given user.</p>
<p>Returns an error message if operation failed or empty string otherwise.</p>
<p>PARAMETERS:</p>
<pre>
See L<UserFeatureAdd>.
"plugins" contains the list of plugins to be removed.</pre>
<p>EXAMPLE:</p>
<pre>
my $config = { "type" => "ldap",
"plugins" => [
"UsersPluginSambaAccount",
"UsersPluginMail"
],
"uid" => "ll"
};
# removes 'SambaAccount' and 'Mail' plugin from the user
my $error = UserFeatureDelete ($config);</pre>
</li>
<li><strong><a name="userdelete" class="item"><code>$error UserDelete ($config_hash);</code></a></strong>
<p>Deletes existing user. Identification of user selected for delete is
stored in $config_hash.</p>
<p>Returns an error message if operation failed or empty string otherwise.</p>
<p>PARAMETERS:</p>
<pre>
For general values of $config hash, see L<UserAdd>.
For parameters necessary to identify the user, see L<UserModify>.
Additinally, there is special parameter for</pre>
<pre>
"delete_home" Integer: For 1, home directory of selected user
will be deleted. Default value is 0 (false).</pre>
<p>EXAMPLE:</p>
<pre>
my $config = { "type" => "ldap",
"dn" => "uid=ll,dc=example,dc=com",
"delete_home" => YaST::YCP::Boolean (1)
};
# deletes LDAP user together with its home directory
my $error = UserDelete ($config);</pre>
<pre>
$error = UserDelete ({ "uid" => "hh", "type" => "local" });</pre>
</li>
<li><strong><a name="userdisable" class="item"><code>$error UserDisable ($config_hash);</code></a></strong>
<p>Disables existing user to log in. Identification of user selected for delete is
stored in $config_hash.</p>
<p>Returns an error message if operation failed or empty string otherwise.</p>
<p>PARAMETERS:</p>
<pre>
For general values of $config hash, see L<UserAdd>.
For parameters necessary to identify the user, see L<UserModify>.</pre>
<p>EXAMPLE:</p>
<pre>
my $config = { "type" => "ldap",
"uidNumber" => 500,
};
# disables LDAP user (as it is defined its plugins)
my $error = UserDisable ($config);</pre>
</li>
<li><strong><a name="userenable" class="item"><code>$error UserEnable ($config_hash);</code></a></strong>
<p>Enables existing user to log in. Identification of user selected for delete is
stored in $config_hash.</p>
<p>Returns an error message if operation failed or empty string otherwise.</p>
<p>PARAMETERS:</p>
<pre>
For general values of $config hash, see L<UserAdd>.
For parameters necessary to identify the user, see L<UserModify>.</pre>
<p>EXAMPLE:</p>
<pre>
my $config = { "type" => "ldap",
"uidNumber" => 500,
};
# enables LDAP user (in a default way, defined for LDAP users)
my $error = UserEnable ($config);</pre>
</li>
<li><strong><a name="userget" class="item"><code>$data_hash UserGet ($config_hash);</code></a></strong>
<p>Returns a map describing selected user.</p>
<p>PARAMETERS:</p>
<pre>
For general values of $config hash, see L<UserAdd>.
For parameters necessary to identify the user, see L<UserModify>.</pre>
<p>EXAMPLE:</p>
<pre>
my $config = { "type" => "ldap",
"user_attributes" => [ "uid", "uidNumber", "cn" ],
"uidNumber" => 500
};
# searches for LDAP user with uidNumber 500 and returns the hash with given
# attributes
my $user = UserGet ($config);</pre>
<pre>
$config = { "type" => "ldap",
"uid" => "my_user",
"user_base" => "ou=people,dc=example,dc=com",
"bind_dn" => "uid=admin,dc=example,dc=com",
};
# searches for LDAP user with uid "my_user" in given search base and
# returns the hash with all user's non-empty attributes
$user = UserGet ($config);</pre>
</li>
<li><strong><a name="usersget" class="item"><code>$users_hash = UsersGet ($config_hash);</code></a></strong>
<p>Returns a hash describing the set of users. By default, the hash is indexed
by UID number, unless statet otherwise in $config_hash.</p>
<p>PARAMETERS:</p>
<pre>
For general values of $config hash, see L<UserAdd>.
Additionally, there is a special key</pre>
<pre>
"index" The name of the key, which should be used as a index
in the return hash.</pre>
<p>EXAMPLE:</p>
<pre>
my $config = { "type" => "ldap",
"user_attributes" => [ "uid", "uidNumber", "cn" ],
"user_base" => "ou=people,dc=example,dc=com",
"user_scope" => YaST::YCP::Integer (2),
"user_filter" => [ "objectClass=posixAccount" ]
"index" => "dn"
};
# searches for LDAP users in given search base and returns the hash
# indexed by DN's with the hash values containing users with given attributes
my $users = UsersGet ($config);</pre>
</li>
<li><strong><a name="groupadd" class="item"><code>$error GroupAdd ($config_hash, $data_hash);</code></a></strong>
<p>Creates new group. Group attributes are described in $data_hash,
$config_hash describes special configuration data.</p>
<p>Returns an error message if operation failed or empty string otherwise.</p>
<p>PARAMETERS:</p>
<pre>
Possible parameters for $config hash:</pre>
<pre>
"type" Type of group (string). Possible values:
"local","system","ldap","nis". ("nis" is not available
for adding)</pre>
<pre>
Specific parameters of $config hash, related to LDAP groups (all keys
are optional, there should exist reasonable default values based on
current LDAP configuration):</pre>
<pre>
"bind_dn"
DN of LDAP administrator, used to bind to LDAP server
(string)
"bind_pw"
Password for LDAP administrator (string)
"anonymous_bind"
If this key is present, there will be done created an
anonymous connection to LDAP server (if it is allowed).
"member_attribute"
Name of LDAP attribute, defining the membership in LDAP
groups (possible values: "member", "uniquemember"). The
default value is in /etc/ldap.conf (nss_map_attribute).</pre>
<pre>
"group_attributes"
List of attributes to be returned by an LDAP search for
group (list of strings). If empty, all non-empty
attributes will be returned as a result of search.</pre>
<pre>
"group_base"
DN of LDAP base where the groups are stored (string). By
default, the value of "suseDefaultBase" stored in LDAP
configuration is used.</pre>
<pre>
"group_filter"
Filter for restricting LDAP searches (string).
The default value is stored as "suseSearchFilter" in
LDAP configuration.</pre>
<pre>
"group_scope"
The scope used for LDAP searches for groups. Possible
values are 0 (base), 1(one), 2(sub). Default is 2.</pre>
<pre>
"group_plugins"
List of plugins which should be applied for group
(list of strings). General plugin for LDAP groups,
("UsersPluginLDAPAll") is always available, others are
part of modules which has to be installed before their
usage (yast2-samba-server, yast2-mail-server).</pre>
<pre>
Possible parameters for $data hash:</pre>
<pre>
"gidNumber" GID number of the group
"cn" Group name
"userPassword" Password for the group.
"userlist" Hash (of type { <username> => 1 }) with
the users that should be members of this group.
Optionally, this could be also the list of
user names.</pre>
<pre>
<member_attribute> For LDAP groups, correct member attribute (
"member"/"uniquemember") has to be used instead
of "userlist". It could be list of user names or
hash with DN's of the members.</pre>
<pre>
<ldap_attribute> Any LDAP attribute supported by groups's object class</pre>
<p>EXAMPLE:</p>
<pre>
my $config = { "type" => "ldap",
"group_plugins" => [ "GroupsPluginsLDAPAll" ],
"bind_dn" => "uid=admin,dc=example,dc=com",
"group_base" => "ou=groups,dc=example,dc=com"
};
my $data = { "gidNumber" => 5555,
"cn" => "lgroup",
"member" => {
"uid=test,ou=people,dc=example,dc=com" => 1,
"uid=ll,ou=people,dc=example,dc=com" => 1
}
};
# create new LDAP group</pre>
<pre>
my $error = GroupAdd ($config, $data);</pre>
<pre>
# create new system group
GroupAdd ({ "type" => "system" }, {
"cn" => "ggg",
"userlist" => {
"root" => 1,
"hh" => 1
}
);</pre>
</li>
<li><strong><a name="groupmodify" class="item"><code>$error GroupModify ($config_hash, $data_hash);</code></a></strong>
<p>Modifies existing group. Group attributes which should be changed
are described in $data_hash,
$config_hash describes special configuration data, especially group
identification.</p>
<p>Returns an error message if operation failed or empty string otherwise.</p>
<p>PARAMETERS:</p>
<pre>
For general values of $config hash, see L<GroupAdd>.
Additinally, $config must contain one of the key used to identify
the group which should be modified:</pre>
<pre>
"dn" Distingueshed name (only for of LDAP group)
"cn" Group name (or value of "cn" attribute for LDAP group).
"gidNumber" GID number (value of "gidNumber" for LDAP group).</pre>
<p>EXAMPLE</p>
<pre>
# change GID value of local group (identified with name)
my $error = GroupModify ({ "cn" => "users" }, { "gidNumber" => 101 });</pre>
<pre>
my $config = { "type" => "ldap",
"gidNumber" => 5555
};
my $data = { "member" => [
"uid=test,ou=people,dc=example,dc=com",
"uid=ll,ou=people,dc=example,dc=com",
"uid=admin,dc=example,dc=com"
]
};
# changes a member attribute of LDAP group (identified with id)
$error = GroupModify ($config, $data);</pre>
<pre>
NOTE</pre>
<pre>
You can see on example that "member" attribute could be passed either
as an array (which could one expect for LDAP attribute) or as hash,
(which is used by YaST for internal representation) as shown in example
for GroupAdd () function. YaST always takes care of it and does the
necessary conversions.</pre>
</li>
<li><strong><a name="groupmemberadd" class="item"><code>$error GroupMemberAdd ($config_hash, $user_hash);</code></a></strong>
<p>Adds a new member to the given group. User is described in $user_hash,
group identification is passwd in $config_hash. User must exist.</p>
<p>Returns an error message if operation failed or empty string otherwise.</p>
<p>PARAMETERS:</p>
<pre>
For general values of $config hash, see L<GroupAdd>.
For parameters necessary to identify the group, see L<GroupModify>.
$user_hash must include the information necessary to identify the
user. This has to be one of these keys:</pre>
<pre>
"dn" Distinguished name (DN) [only for LDAP users]
"uid" User name (which is "uid" attribute for LDAP user)
"uidNumber" UID (which is "uidNumber" attribute for LDAP user)</pre>
<p>EXAMPLE:</p>
<pre>
my $config = { "type" => "ldap",
"bind_dn" => "uid=admin,dc=example,dc=com",
"gidNumber" => 5555
};
my $user = { "uid" => "my_user" }
};</pre>
<pre>
my $error = GroupMemberAdd ($config, $user);</pre>
</li>
<li><strong><a name="groupmemberdelete" class="item"><code>$error GroupMemberDelete ($config_hash, $user_hash);</code></a></strong>
<p>Deletes a member from the group.</p>
<p>Returns an error message if operation failed or empty string otherwise.</p>
<p>PARAMETERS:</p>
<pre>
For general values of $config hash, see L<GroupAdd>.
For parameters necessary to identify the group, see L<GroupModify>.
$user_hash must include the information necessary to identify the
user - see L<GroupMemberAdd></pre>
<p>EXAMPLE:</p>
<pre>
my $config = { "type" => "ldap",
"dn" => "cn=lgroup,dc=example,dc=com"
};
my $user = { "uidNumber" => 1000 }</pre>
<pre>
# removes user with given uidNumber from group with given DN
my $error = GroupMemberDelete ($config, $user);</pre>
</li>
<li><strong><a name="groupdelete" class="item"><code>$error GroupDelete ($config_hash);</code></a></strong>
<p>Deletes existing group. Identification of group is stored in $config_hash.</p>
<p>Returns an error message if operation failed or empty string otherwise.</p>
<p>PARAMETERS:</p>
<pre>
For general values of $config hash, see L<GroupAdd>.
For parameters necessary to identify the group, see L<GroupModify>.</pre>
<pre>
EXAMPLE:</pre>
<pre>
my $config = { "type" => "local",
"uid" => "users"
};
my $error = GroupDelete ($config);</pre>
</li>
<li><strong><a name="groupget" class="item"><code>$data_hash GroupGet ($config_hash);</code></a></strong>
<p>Returns a map describing selected group.</p>
<p>PARAMETERS:</p>
<pre>
For general values of $config hash, see L<GroupAdd>.
For parameters necessary to identify the group, see L<GroupModify>.</pre>
<pre>
EXAMPLE:</pre>
<pre>
my $config = { "type" => "ldap",
"group_attributes" => [ "cn", "gidNumber", "member" ],
"gidNumber" => 500
};
# searches for LDAP group with gidNumber 500 and returns the hash
# with given attributes
my $group = GroupGet ($config);</pre>
</li>
<li><strong><a name="groupsget" class="item"><code>$groups_hash GroupsGet ($config_hash);</code></a></strong>
<p>Returns a hash describing the set of groups. By default, the hash is indexed
by GID number, unless statet otherwise in $config_hash.</p>
<p>PARAMETERS:</p>
<pre>
For general values of $config hash, see L<GroupAdd>.
Additionally, there is a special key</pre>
<pre>
"index" The name of the key, which should be used as a index
in the return hash (default value is "gidNumber").</pre>
<p>EXAMPLE:</p>
<pre>
# searches for LDAP groups in default base and returns the hash
# indexed by GID's with the hash values containing groups with all
# non-empty attributes
my $groups = GroupsGet ({ "type" => "ldap" });</pre>
<pre>
# returns hash with all NIS groups
$groups = GroupsGet ({ "type" => "nis" });</pre>
</li>
<li><strong><a name="groupsgetbyuser" class="item"><code>$groups_hash GroupsGetByUser ($config_hash, $user_hash);</code></a></strong>
<p>Returns a hash describing the set of groups. By default, the hash is indexed
by GID number, unless stated differently in $config_hash.</p>
<p>PARAMETERS:</p>
<pre>
For general values of $config hash, see L<GroupAdd>.
$user_hash must include the information necessary to identify the
user - see L<GroupMemberAdd>.
Additionally, there is a special key</pre>
<pre>
"index" The name of the key, which should be used as a index
in the return hash.</pre>
<p>EXAMPLE:</p>
<pre>
my $config = { "type" => "ldap",
"index" => "dn"
"group_scope" => YaST::YCP::Integer (2),
};
my $user = { "dn" => "uid=ll,ou=people,dc=example,dc=com" };</pre>
<pre>
# searches for LDAP groups in default base and returns the hash
# indexed by DN's with the hash values containing groups with all
# non-empty attributes
my $groups = GroupsGetByUser ($config, $user);</pre>
</li>
</ul>
</body>
</html>
ACC SHELL 2018