config_base.rst

none

MMC base plugin configuration file

This document explains the content of the MMC base plugin configuration file.

Introduction

The « base » plugin is the main plugin of the MMC Python API. It features base operations like LDAP management (users, groups, etc), user authentication and provisioning.

The plugin configuration file is /etc/mmc/plugins/base.ini.

Like all MMC related configuration file, its file format is INI style. The file is made of sections, each one starting with a « [sectionname] » header. In each section options can be defined like this « option = value ».

For example: :

[section1]
option1 = 1
option2 = 2

[section2]
option1 = foo
option2 = plop

Obfuscated password support in configuration files

All the passwords contained in MMC-related configuration files can be obfuscated using a base64 encoding. This is not a security feature, but at least somebody won't be able to read accidentally a password.

To obfuscate a password, for example the word "secret", you can use the Python interpreter:

$ python -c 'print "secret".encode("base64")'
c2VjcmV0

The base64-encoded password is the word "c2VjcmV0". Now to use it in a configuration file:

[section]
password = {base64}c2VjcmV0

The {base64} prefix warns the configuration parser that the following word is a base64-encoded word, and so needs to be decoded before being used.

Configuration file sections

Here are all the base.ini available sections:

Section name	Description	Optional
ldap	LDAP access definition	no
backup-tools	Backup tools configuration	no
audit	MMC audit framework configuration	yes
hooks	Hooks for scripts that interacts with the MMC	yes
userdefault	Attributes and Objectclass values that are added or deleted when adding a new user into the LDAP	yes
authentication	Defines how a user is authenticated when logging into the MMC web interface. For example, another LDAP server can be use to perform the authentication.	yes
provisioning	User accounts can be created or updated automatically when logging in to the MMC web interface.	yes
subscription	This section is used to declare what has been subscribed, and to give some important information to the end user.	yes

Section « ldap »

This section defines how the main LDAP is accessed, where are located the users organization units, etc.

Available options for the "ldap" section

Option name	Description	Optional	Default value
host (deprecated by ldapurl) ldapurl network_timeout	IP address or hostname of the LDAP server LDAP URL to connect to the LDAP server, for example: ldap://127.0.0.1:389. If ldapurl starts with "ldaps://", use LDAP over SSL on the LDAPS port. LDAPS is deprecated, and you should use StartTLS. If ldapverifypeer = demand, always use the server hostname instead of its IP address in the LDAP URL. This hostname must match the CN field of the server certificate. Network timeout in seconds for LDAP operations. No default timeout set.	no no yes
start_tls	TLS connection parameters when LDAPS is not used. "off": never use TLS. "start_tls": use the LDAPv3 StartTLS extended operation (recommended).	yes	off
ldapverifypeer cacertdir cacert localcert localkey	If start_tls != off or LDAPS, specify check to perform on server certificate. "never": don't ask certificate. "demand": request certificate. If none or bad certificate provided, stop the connection (recommended). Client certicates to use (default are empty) for LDAPS or TLS connections. For example: /etc/ssl/certs Certificate Authority file. For example: /etc/mmc/certs/demoCA/cacert.pem Local SSL certificate file. For example: /etc/mmc/certs/client.cert Local SSL public key. For example: /etc/mmc/certs/client.key	yes yes yes yes yes	demand
ciphersuites	Accepted ciphers from the LDAP server.	yes	TLSv1:!NULL
ldapdebuglevel baseDN rootName password baseUsersDN baseGroupsDN	set this to 255 to debug LDAP connection problems. Details of all LDAP operations will be written to stdout LDAP base Distinguished Name (DN) LDAP administrator DN LDAP administrator password LDAP organisational unit DN where the users are located LDAP organisational unit DN where the groups are located	yes no no no no no	0
gpoDN userHomeAction defaultUserGroup	LDAP organisational unit DN where the GPO are located If set to 1, create and delete user directory when creating/deleting one When creating an user, set this group as the primary user group	yes no yes	ou=System,baseDN
skelDir	Use the specified directory when creating a user home directory	yes	/etc/skel
defaultHomeDir	Use this directory as a base directory when creating a user without specifying a home directory. If the creater user is called "foo", his/her homeDirectory will be "defaultHomeDir/foo"	yes	/home
defaultShellEnable	the default shell for enabled users	no	/bin/bash
defaultShellDisable	the default shell for disabled users	no	/bin/false
authorizedHomeDir	a list of directory where user home directory can be put	yes	defaultHomeDir
uidStart	starting uid number for user accounts	yes	10000
gidStart	starting gid number for groups	yes	10000
logViewModule logfile	enable/disable the logview module LDAP log file path	yes no	no
passwordscheme	LDAP user password scheme. Possible values are "ssha", "crypt" and "passmod". "passmod" uses the LDAP Password Modify Extended Operations to change password. The password encryption is done by the LDAP server.	no	passmod

Section « backup-tools »

This section defines where are located the backup tools. The backup tools are used when backuping a home directory or a SAMBA share from the MMC.

Available options for the "backup-tools" section:

Option name	Description	Optional
path	Where are located the executable needed by the backup tools	no
destpath	Where the backup are located once done	no

Section « audit »

This section defines the audit framework behaviour. By default the audit framework is disabled.

Available options for the "audit" section:

Option name	Description	Optional
method	Method used to record all audit data. Only the "database" method is supported.	no
dbhost	Host to connect to the SGBD that stores the audit database	no
dbdriver	Database driver to use. "mysql" and "postgres" drivers are supported.	no
dbport	Port to connect to the SGBD that stores the audit database.	no
dbuser	User login to connect to the SGBD that stores the audit database.	no
dbpassword	User password to connect to the SGBD that stores the audit database.	no
dbname	Name of the audit database.	no

Section « hooks »

The hooks system allow you to run external script when doing some operations with the MMC.

The script will be run as root user, with as only argument the path to a temporary file containing the full LDIF export of the LDAP user.

For the « adduser » and « changeuserpassword » hooks, the LDIF file will contain the userPassword attribute in cleartext.

For the « usertoken » hook the userPassword attribute will contain the authentication token for the user. This token is valid for 15 minutes. Using this token a link can be send to the user (email, sms...) so that he can login in the MMC interface and change his password trough the "Reset password page". The link is in the form: http://SERVER/mmc/token.php?token=<TOKEN>.

The executable bit must be set on the script to run. The temporary LDIF file is removed once the script has been executed.

Available options for the "hooks" section:

Option name	Description	Optional
adduser	path to the script launched when a user has been added into the LDAP directory	yes
changeuserpassword	path to the script launched when a user has been changed into the LDAP directory	yes
deluser	path to the script launched when a user is going to be removed from the LDAP directory	yes
usertoken	path to the script launched when an authentication token has been created for a user	yes

Here is a hook example written in BASH for « adduser »:

#!/bin/sh
# Get the uid of the new user
VALUE=`cat $1 | grep ^uid: | sed "s/uid: //"`
# Log new user event
echo "New user $VALUE created" >> /var/log/newuser.log
exit 0

The same hook, written in Python:

#!/usr/bin/env python
import sys
# ldif is a Python package of the python-ldap extension
import ldif
LOGFILE = "/var/log/newuser.log"

class MyParser(ldif.LDIFParser):

    def handle(self, dn, entry):
        uid = entry["uid"][0]
        f = file(LOGFILE, "a")
        f.write("New user %s created\\n" % uid)
        f.close()

parser = MyParser(file(sys.argv[1]))
parser.parse()

Section « userdefault »

This section allows to set default attributes to a user, or remove them, only at user creation.

Each option of this section is corresponding to the attribute you want to act on.

If you want to remove the « displayName » attribute of each newly added user:

[userdefault]
displayName = DELETE

Substitution is done on the value of an option if a string between '%' is found. For example, if you want that all new user have a default email address containing their uid:

[userdefault]
mail = %uid%@mandriva.com

If you want to add a value to a multi-valuated LDAP attribute, do this:

[userdefault]
objectClass = +corporateUser

Since version 1.1.0, you can add modifiers that interact with the substitution. This modifiers are put between square bracket at the beginning os the string to substitute.

Available modifiers for substitution

modifier character	Description
/	Remove diacritics (accents mark) from the substitution string
_	Set substitution string to lower case
|	Set substitution string to upper case

For example, you want that all new created users have a default mail address made this way: « firstname.lastname@mandriva.com ». But your user firstname/lastname have accent marks, that are forbidden for email address. You do it like this:

[userdefault]
mail = [_/]%givenName%.%sn%@mandriva.com

User authentication

The default configuration authenticates users using the LDAP directory specified in the [ldap] section.

But it is also possible to set up authentication using an external LDAP server.

Section « authentication »

This optional section tells the MMC agent authentication manager how to authenticate a user. Each Python plugin can register "authenticator" objects to the authentication manager, that then can be used to authenticate users.

The authentication manager tries each authenticator with the supplied login and password until one successfully authenticate the user.

Please note that the user won't be able to log in to the MMC web interface if she/he doesn't have an account in the LDAP directory configured in the [ldap] section of the base plugin. The provisioning system will allow you to automatically create this account.

The base plugin registers two authenticators:

• baseldap: this authenticator uses the LDAP directory configured in the [ldap] section of the base plugin to authenticate the user,
• externalldap: this authenticator uses an external LDAP directory to authenticate the user.

Available options for the "authentication" section

Option name	Description	Optional	Default value
method	space-separated list of authenticators to try to authenticate a user	yes	baseldap

The default configuration is:

[authentication]
method = baseldap

authentication_baseldap

This section defines some configuration directives for the baseldap authenticator.

Available options for the "authentication_baseldap" section:

Option name	Description	Optional	Default value
authonly	space-separated list of login that will be authentified using this authenticator. Others will be skipped.	yes

For example, to make the "baseldap" authenticator only authenticate the virtual MMC "root" user:

[authentication_baseldap]
authonly = root

authentication_externalldap

This section defines some configuration directives for the baseldap authenticator.

Available options for the "authentication_externalldap" section:

Option name	Description	Optional	Default value
exclude authonly	space-separated list of login that won't be authenticated using this authenticator. If set, only the logins from the specified space-separated list of login will be authenticated using this authenticator, other login will be skipped.	yes yes
mandatory network_timeout ldapurl suffix bindname bindpasswd	Set whether this authenticator is mandatory. If it is mandatory and can't be validated during the mmc-agent activation phase, the mmc-agent exits with an error. LDAP connection timeout in seconds. If the LDAP connection failed after this timeout, we try the next LDAP server in the list or give up if it the last. LDAP URL of the LDAP directory to connect to to authenticate user. You can specify multiple LDAP URLs, separated by spaces. Each LDAP server is tried until one successfully accepts a connection. DN of the LDAP directory where to search users DN of the LDAP directory account that must be used to bind to the LDAP directory and to perform the user search. If empty, an anonymous bind is done. Password of the LDAP directory account given by the bindname option. Not needed if bindname is empty.	yes yes no no no no	True
filter attr	LDAP filter to use to search the user in the LDAP directory Name of the LDAP attribute that will allow to match a user entry with a LDAP search	yes no	objectClass=*

For example, to authenticate a user using an Active Directory:

[authentication_externalldap]
exclude = root
ldapurl = ldap://192.168.0.1:389
suffix = cn=Users,dc=adroot,dc=com
bindname = cn=Administrator, cn=Users, dc=adroot, dc=com
bindpasswd = s3cr3t
filter = objectClass=*
attr = cn

User provisioning

This feature allows to automatically create a user account if it does not already exist in the LDAP directory configured in the [ldap] section of the base plugin.

User provisioning is needed for example if an external LDAP is used to authenticate users. The users won't be able to log in to the MMC web interface even if their login and password are rights, because the local LDAP doesn't store thir accounts.

Section « provisioning »

This optional section tells the MMC agent provisioning manager how to provision a user account. Each Python plugin can register "provisioner" objects to the provisioning manager, that then can be used to provision users.

When a user logs in to the MMC web interface, the authenticator manager authenticates this user. If the authentication succeed, then the provisioning manager runs each provisioner.

The authenticator object that successfully authenticates the user must pass to the provisioning manager the user informations, so that the provisioners have data to create or update the user entry.

Available options for the "provisioning" section

Option name	Description	Optional	Default value
method	space-separated list of provisioners	yes

For example, this configuration tells to use the "externalldap" provisioner to create the user account:

[provisioning]
method = externalldap

provisioning_external

This section defines some configuration directives for the externalldap authenticator.

Available options for the "authentication_externalldap" section:

Option name	Description	Optional	Default value
exclude ldap_uid ldap_givenName ldap_sn profile_attr profile_acl<profilename>	space-separated list of login that won't be provisioned by this provisioner. name of the external LDAP field that is corresponding to the local uid field. The uid LDAP attribute is the user login. name of the external LDAP field that is corresponding to the local givenName field name of the external LDAP field that is corresponding to the local sn (SurName) field The ACLs fields of the user that logs in can be filled according to the value of an attribute from the external LDAP. This option should contain the field name. The ACLs field of the user that logs in with the profile <profilename>.	yes no no no yes yes
profile_group_mapping profile_group_prefix	If enabled, users with the same profile will be put in the same users group. If profile_group_mapping is enabled, the created groups name will be prefixed with the given string.	yes yes	False

To create a user account, the MMC agent needs the user's login, password, given name and surname. That's why the ldap_uid`È,ldap_givenNameandldap_sn`` options are mandatory.

Here is a simple example of an authenticators and provisioners chain that authenticates users using an Active Directory, and create accounts:

[authentication]
method = baseldap externalldap

[authentication_externalldap]
exclude = root
ldapurl = ldap://192.168.0.1:389
suffix = cn=Users,dc=adroot,dc=com
bindname = cn=Administrator, cn=Users, dc=adroot, dc=com
bindpasswd = s3cr3t
filter = objectClass=*
attr = cn

[provisioning]
method = externalldap

[provisioning_externalldap]
exclude = root
ldap_uid = cn
ldap_givenName = sn
ldap_sn = sn

Subscription informations

This section contains all the information needed when the version is not a community one. It allow for example to send mail to the administrator directly from the GUI when something went wrong.

Available options for the "subscription" section:

Option name	Description	Optional	Default value
product_name	A combination of "MDS" and "Pulse 2" to describe the product	yes	MDS
vendor_name	The vendor's name	yes	Mandriva
vendor_mail customer_name customer_mail comment	The vendor's email address The customer's name The customer's email address A comment on the customer	yes yes yes yes	sales@mandriva.com
users	The number of users included in the subscription. 0 is for infinite.	yes	0
computers	The number of computers included in the subscription. 0 is for infinite.	yes	0
support_mail	The support's email address	yes	customer@customercare.mandriva.com
support_phone support_comment	The support's phone number A comment about the support	yes yes	0810 LINBOX