release notes | Book: 3.2, 4.0, 4.1, 4.2, 5.0, 5.1, 5.2, 6.0 (unreleased) | Wiki | Q&A black_bg
Web: Multi-page, Single page | PDF: A4-size, Letter-size | eBook: epub black_bg

Configuration

gPlazma2 is configured by the PAM-style configuration file /etc/dcache/gplazma.conf. Each line of the file is either a comment (i.e., starts with #, is empty, or defines a plugin. Plugin defining lines start with the plugin stack type (one of auth, map, account, session identity), followed by a PAM-style modifier (one of optional, sufficient, required, requisite), the plugin name and an optional list of key-value pairs of parameters. During the login process they will be executed in the order auth, map, account and session. The identity plugins are not used during login, but later on to map from UID+GID back to user names (e.g., for NFS). Within these groups they are used in the order they are specified.

auth|map|account|session|identity optional|required|requisite|sufficient <plug-in> ["<key>=<value>" ...]

A complete configuration file will look something like this:

Example:

# Some comment
auth    optional  x509
auth    optional  voms
map     requisite vorolemap
map     requisite authzdb authzdb=/etc/grid-security/authzdb
session requisite authzdb

Login Phases

auth

auth-plug-ins are used to read the users public and private credentials and ask some authority, if those are valid for accessing the system.

map

map-plug-ins map the user information obtained in the auth step to UID and GIDs. This may also be done in several steps (e.g., the vorolemap plug-in maps the users DN+FQAN to a username which is then mapped to UID/GIDs by the authzdb plug-in.

account

account-plug-ins verify the validity of a possibly mapped identity of the user and may reject the login depending on information gathered within the map step.

session

session plug-ins usually enrich the session with additional attributes like the user’s home directory.

identity

identity plug-ins are responsible for mapping UID and GID to user names and vice versa during the work with dCache.

The meaning of the modifiers follow the PAM specification:

Modifiers

optional

The success or failure of this plug-in is only important if it is the only plug-in in the stack associated with this type.

sufficient

Success of such a plug-in is enough to satisfy the authentication requirements of the stack of plug-ins (if a prior required plug-in has failed the success of this one is ignored). A failure of this plug-in is not deemed as fatal for the login attempt. If the plug-in succeeds gPlazma2 immediately proceeds with the next plug-in type or returns control to the door if this was the last stack.

required

Failure of such a plug-in will ultimately lead to gPlazma2 returning failure but only after the remaining plug-ins for this type have been invoked.

requisite

Like required, however, in the case that such a plug-in returns a failure, control is directly returned to the door.

[return to top]

Plug-ins

gPlazma2 functionality is configured by combining different types of plug-ins to work together in a way that matches your requirements. For this purpose there are five different types of plug-ins. These types correspond to the keywords auth, map, account, session and identity as described in the previous section. The plug-ins can be configured via properties that may be set in dcache.conf, the layout-file or in gplazma.conf.

[return to top]

auth Plug-ins

The kpwd plug-in authorizes users by username and password, by pairs of DN and FQAN and by Kerberos principals.

Properties

gplazma.kpwd.file

Path to dcache.kpwd

Default: /etc/dcache/dcache.kpwd

The voms plug-in is an auth plug-in. It can be used to verify X.509 credentials. It takes the certificates and checks their validity by testing them against the trusted CAs. The verified certificates are then stored and passed on to the other plug-ins in the stack.

Properties

gplazma.vomsdir.ca

Path to ca certificates

Default: /etc/grid-security/certificates

gplazma.vomsdir.dir

Path to vomsdir

Default: /etc/grid-security/vomsdir

[return to top]

X.509 plug-in

The X.509 plug-in is a auth plug-in that extracts X.509 certificate chains from the credentials of a user to be used by other plug-ins.

[return to top]

map Plug-ins

As a map plug-in it maps usernames to UID and GID. And as a session plug-in it adds root and home path information to the session based on the user’s username.

Properties

gplazma.kpwd.file

Path to dcache.kpwd

Default: /etc/dcache/dcache.kpwd

[return to top]

authzdb

The authzdb plug-in takes a username and maps it to UID+GID using the storage-authzdb file.

Properties

gplazma.authzdb.file

Path to storage-authzdb

Default: /etc/grid-security/storage-authzdb

[return to top]

GridMap

The gridmap plug-in maps GLOBUS identities and Kerberos identities to usernames.

Properties

gplazma.gridmap.file

Path to grid-mapfile

Default: /etc/grid-security/grid-mapfile

[return to top]

vorolemap

The voms plug-in maps pairs of DN and FQAN to usernames via a vorolemap file.

Properties

gplazma.vorolemap.file

Path to grid-vorolemap

/etc/grid-security/grid-vorolemap

The krb5 plug-in maps a kerberos principal to a username by removing the domain part from the principal.

Example:


                user@KRB-DOMAIN.EXAMPLE.ORG to user
              

[return to top]

nsswitch

The nsswitch plug-in uses the system’s nsswitch configuration to provide mapping.

Typically nsswitch plug-in will be combined with vorolemap plug-in, gridmap plug-in or krb5 plug-in:

Example:

# Map grid users to local accounts
auth    optional  x509 #1
auth    optional  voms #2
map     requisite vorolemap #3
map     requisite nsswitch #4
session requisite nsswitch #5

In this example following is happening: extract user’s DN (1), extract and verify VOMS attributes (2), map DN+Role to a local account (3), extract uid and gids for a local account (4) and, finally, extract users home directory (5).

The nis plug-in uses an existing NIS service to map username+password to a username.

Properties

gplazma.nis.server

NIS server host

Default: nisserv.domain.com

gplazma.nis.domain

NIS domain

Default: domain.com

The result of nis plug-in can be used by other plug-ins:

Example:

# Map grid or kerberos users to local accounts
auth    optional  x509 #1
auth    optional  voms #2
map     requisite vorolemap #3
map     optional  krb5 #4
map     optional  nis #5
session requisite nis #6

In this example two access methods are considered: grid based and kerberos based. If user comes with grid certificate and VOMS role: extract user’s DN (1), extract and verify VOMS attributes (2), map DN+Role to a local account (3). If user comes with Kerberos ticket: extract local account (4). After this point in both cases we talk to NIS to get uid and gids for a local account (5) and, finally, adding users home directory (6).

[return to top]

account Plug-ins

The argus plug-in bans users by their DN. It talks to your site’s ARGUS system (see https://twiki.cern.ch/twiki/bin/view/EGEE/AuthorizationFramework ) to check for banned users.

Properties

gplazma.argus.hostcert

Path to host certificate

Default: /etc/grid-security/hostcert.pem

gplazma.argus.hostkey

Path to host key

Default: /etc/grid-security/hostkey.pem

gplazma.argus.hostkey.password

Password for host key

Default:

gplazma.argus.ca

Path to CA certificates

Default: /etc/grid-security/certificates

gplazma.argus.endpoint

URL of PEP service

Default: https://localhost:8154/authz

[return to top]

banfile

The banfile plug-in bans users by their principal class and the associated name. It is configured via a simple plain text file.

Example:

# Ban users by principal
alias dn=org.globus.gsi.jaas.GlobusPrincipal
alias kerberos=javax.security.auth.kerberos.KerberosPrincipal
alias fqan=org.dcache.auth.FQANPrincipal
alias name=org.dcache.auth.LoginNamePrincipal

ban name:ernie
ban kerberos:BERT@EXAMPLE.COM
ban com.example.SomePrincipal:Samson

In this example the first line is a comment. Lines 2 to 5 define aliases for principal class names that can then be used in the following banning section. The four aliases defined in this example are actually hard coded into gPlazma, therefore you can use these short names without explicitly defining them in your configuration file. Line 7 to 9 contain ban definitions. Line 9 directly uses the class name of a principal class instead of using an alias.

Please note that the plug-in only supports principals whose assiciated name is a single line of plain text. In programming terms this means the constructor of the principal class has to take exactly one single string parameter.

For the plugin to work, the configuration file has to exist even if it is empty.

Properties

gplazma.banfile.path

Path to configuration file

Default: /etc/dcache/ban.conf

To activate the banfile plug-in it has to be added to gplazma.conf:

Example:

# Map grid or kerberos users to local accounts
auth    optional  x509
auth    optional  voms
map     requisite vorolemap
map     optional  krb5
map     optional  nis
session requisite nis
account requisite banfile

[return to top]

session Plug-ins

The kpwd plug-in adds root and home path information to the session, based on the username.

Properties

gplazma.kpwd.file

Path to dcache.kpwd

Default: /etc/dcache/dcache.kpwd

[return to top]

authzdb

The authzdb plug-in adds root and home path information to the session, based and username using the storage-authzdb file.

Properties

gplazma.authzdb.file

Path to storage-authzdb

Default: /etc/grid-security/storage-authzdb

[return to top]

nsswitch

The nsswitch plug-in adds root and home path information to the session, based on the username using your system’s nsswitch service.

Typically nsswitch plug-in will be combined with vorolemap plug-in, gridmap plug-in or krb5 plug-in:

Example:

# Map grid users to local accounts
auth    optional  x509 #1
auth    optional  voms #2
map     requisite vorolemap #3
map     requisite nsswitch #4
session requisite nsswitch #5

In this example following is happening: extract user’s DN (1), extract and verify VOMS attributes (2), map DN+Role to a local account (3), extract uid and gids for a local account (4) and, finally, extract users home directory (5).

The nis plug-in adds root and home path information to the session, based on the username using your site’s NIS service.

Properties

gplazma.nis.server

NIS server host

Default: nisserv.domain.com

gplazma.nis.domain

NIS domain

Default: domain.com

The result of nis plug-in can be used by other plug-ins:

Example:

# Map grid or kerberos users to local accounts
auth    optional  x509 #1
auth    optional  voms #2
map     requisite vorolemap #3
map     optional  krb5 #4
map     optional  nis #5
session requisite nis #6

In this example two access methods are considered: grid based and kerberos based. If user comes with grid certificate and VOMS role: extract user’s DN (1), extract and verify VOMS attributes (2), map DN+Role to a local account (3). If user comes with Kerberos ticket: extract local account (4). After this point in both cases we talk to NIS to get uid and gids for a local account (5) and, finally, adding users home directory (6).

The ldap plug-in is a map, session and identity plugin. As a map plugin it maps user names to UID and GID. As a session plugin it adds root and home path information to the session. As an identity plugin it supports reverse mapping of UID and GID to user and group names repectively.

Properties

gplazma.ldap.url

LDAP server url. Use ldap:// prefix to connect to plain LDAP and ldaps:// for secured LDAP.

Example: ldaps://example.org:389

gplazma.ldap.organization

Top level (base DN) of the LDAP directory tree

Example: o="Example, Inc.", c=DE

gplazma.ldap.tree.people

LDAP subtree containing user information. The path to the user records will be formed using the base DN and the value of this property as a organizational unit (ou) subdirectory.

Default: People

Example: Setting gplazma.ldap.organization=o="Example, Inc.", c=DE and gplazma.ldap.tree.people=People will have the plugin looking in the LDAP directory ou=People, o="Example, Inc.", c=DE for user information.

gplazma.ldap.tree.groups

LDAP subtree containing group information. The path to the group records will be formed using the base DN and the value of this property as a organizational unit (ou) subdirectory.

Default: Groups

Example: Setting gplazma.ldap.organization=o="Example, Inc.", c=DE and gplazma.ldap.tree.groups=Groups will have the plugin looking in the LDAP directory ou=Groups, o="Example, Inc.", c=DE for group information.

gplazma.ldap.userfilter

LDAP filter expression to find user entries. The filter has to contain the %s exactly once. That occurence will be substituted with the user name before the filter is applied.

Default: (uid=%s)

gplazma.ldap.home-dir

the user’s home directory. LDAP attribute identifiers surrounded by % will be expanded to their corresponding value. You may also use a literal value or mix literal values and attributes.

Default: %homeDirectory%

gplazma.ldap.root-dir

the user’s root directory. LDAP attribute identifiers surrounded by % will be expanded to their corresponding value. You may also use a literal value or mix literal values and attributes.

Default: /

As a session plugin the ldap plug-in assigns two directories to the user’s session: the root directory and the home directory. The root directory is the root of the directory hierarchy visible to the user, while the home directory is the directory the user starts his session in. In default mode, the root directory is set to / and the home directory is set to %homeDirectory%, thus the user starts his session in the home directory, as it is stored on the LDAP server, and is able to go up in the directory hierarchy to /. For a different use-case, for example if dCache is used as a cloud storage, it may be desireable for the users to see only their own storage space. For this use case home-dir can be set to / and root-dir be set to %homeDirectory%. In both path properties any %val% expression will be expanded to the the value of the attribute with the name val as it is stored in the user record on the LDAP server.

[return to top]

identity Plug-ins

[return to top]

nsswitch

The nsswitch plug-in provides forward and reverse mapping for NFSv4.1 using your system’s nsswitch service.

The nis plug-in forward and reverse mapping for NFSv4.1 using your site’s NIS service.

Properties

gplazma.nis.server

NIS server host

Default: nisserv.domain.com

gplazma.nis.domain

NIS domain

Default: domain.com