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 files

In this section we explain the format of the the storage-authzdb, kpwd and vorolemap files. They are used by the authzdb plug-in, vorolemap plug-in,and kpwd plug-in.

[return to top]


In gPlazma, except for the kpwd plug-in, authorization is a two-step process. First, a username is obtained from a mapping of the user’s DN or his DN and role, then a mapping of username to UID and GID with optional additional session parameters like the root path is performed. For the second mapping usually the file called storage-authzdb is used.

[return to top]

Preparing storage-authzdb

The default location of the storage-authzdb is /etc/grid-security. Before the mapping entries there has to be a line specifying the version of the used file format.


version 2.1

dCache supports versions 2.1 and to some extend 2.2.

Except for empty lines and comments (lines start with #) the configuration lines have the following format:

 authorize <username> (read-only|read-write) <UID> <GID>[,<GID>]* <homedir> <rootdir> 

For legacy reasons there may be a third path entry which is ignored by dCache. The username here has to be the name the user has been mapped to in the first step (e.g., by his DN).


authorize john read-write 1001 100 / /data/experiments /

In this example user <john> will be mapped to UID 1001 and GID 100 with read access on the directory /data/experiments. You may choose to set the user’s root directory to /.


authorize adm read-write 1000 100 / / /

In this case the user <adm> will be granted read/write access in any path, given that the file system permissions in Chimera also allow the transfer.

The first path is nearly always left as /, but it may be used as a home directory in interactive session, as a subdirectory of the root path. Upon login, the second path is used as the user’s root, and a cd is performed to the first path. The first path is always defined as being relative to the second path.

Multiple GIDs can be assigned by using comma-separated values for the GID file, as in


authorize john read-write 1001 100,101,200 / / /

The lines of the storage-authzdb file are similar to the login lines of the dcache.kpwd file. If you already have a dcache.kwpd file, you can easily create storage-authzdb by taking the lines from your dcache.kpwd file that start with the word login, for example,


login john read-write 1001 100 / /data/experiments /

and replace the word login with authorize. The following line does this for you.

[root] # sed "s/^ *login/authorize/" dcache.kpwd|grep "^authorize" > storage-authzdb 

[return to top]

The gplazmalite-vorole-mapping plug-in

The second is the storage-authzdb used in other plug-ins. See the above documentation on storage-authdb for how to create the file.

[return to top]

Preparing grid-vorolemap

The file is similar in format to the grid-mapfile, however there is an additional field following the DN (Certificate Subject), containing the FQAN (Fully Qualified Attribute Name).

"/C=DE/O=GermanGrid/OU=DESY/CN=John Doe" "/some-vo" doegroup
"/C=DE/DC=GermanGrid/O=DESY/CN=John Doe" "/some-vo/Role=NULL" doegroup
"/C=DE/DC=GermanGrid/O=DESY/CN=John Doe" "/some-vo/Role=NULL/Capability=NULL" doegroup 

Therefore each line has three fields: the user’s DN, the user’s FQAN, and the username that the DN and FQAN combination are to be mapped to.

The FQAN is sometimes semantically referred to as the role. The same user can be mapped to different usernames depending on what their FQAN is. The FQAN is determined by how the user creates their proxy, for example, using voms-proxy-init . The FQAN contains the user’s Group, Role (optional), and Capability (optional). The latter two may be set to the string NULL, in which case they will be ignored by the plug-in. Therefore the three lines in the example above are equivalent.


If a user is authorized in multiple roles, for example

"/DC=org/DC=doegrids/OU=People/CN=John Doe" "/some-vo/sub-grp" vo_sub_grp_user
"/DC=org/DC=doegrids/OU=People/CN=John Doe" "/some-vo/sub-grp/Role=user" vouser
"/DC=org/DC=doegrids/OU=People/CN=John Doe" "/some-vo/sub-grp/Role=admin" voadmin
"/DC=org/DC=doegrids/OU=People/CN=John Doe" "/some-vo/sub-grp/Role=prod" voprod

he will get the username corresponding to the FQAN found in the proxy that the user creates for use by the client software. If the user actually creates several roles in his proxy, authorization (and subsequent check of path and file system permissions) will be attempted for each role in the order that they are found in the proxy.

In a GridFTP URL, the user may also explicitly request a username.


in which case other roles will be disregarded.

[return to top]

Authorizing a VO

Instead of individual DNs, it is allowed to use * or "*" as the first field, such as


"*" "/desy/Role=production/" desyprod 

In that case, any DN with the corresponding role will match. It should be noted that a match is first attempted with the explicit DN. Therefore if both DN and "*" matches can be made, the DN match will take precedence. This is true for the revocation matches as well (see below).

Thus a user with subject /C=DE/O=GermanGrid/OU=DESY/CN=John Doe and role /desy/Role=production will be mapped to username desyprod via the above storage-authzdb line with "*" for the DN, except if there is also a line such as

"/C=DE/O=GermanGrid/OU=DESY/CN=John Doe" "/desy/Role=production" desyprod2

in which case the username will be desyprod2.

[return to top]

Revocation Entries

To create a revocation entry, add a line with a dash (-) as the username, such as

"/C=DE/O=GermanGrid/OU=DESY/CN=John Doe" "/desy/production" -

or modify the username of the entry if it already exists. The behaviour is undefined if there are two entries which differ only by username.

Since DN is matched first, if a user would be authorized by his VO membership through a "*" entry, but is matched according to his DN to a revocation entry, authorization would be denied. Likewise if a whole VO were denied in a revocation entry, but some user in that VO could be mapped to a username through his DN, then authorization would be granted.

[return to top]

More Examples


Suppose that there are users in production roles that are expected to write into the storage system data which will be read by other users. In that case, to protect the data the non-production users would be given read-only access. Here in /etc/grid-security/grid-vorolemap the production role maps to username cmsprod, and the role which reads the data maps to cmsuser.

"*" "/cms/uscms/Role=cmsprod" cmsprod "*" "/cms/uscms/Role=cmsuser" cmsuser

The read-write privilege is controlled by the third field in the lines of /etc/grid-security/storage-authzdb

authorize cmsprod  read-write  9811 5063 / /data /
authorize cmsuser  read-only  10001 6800 / /data /


Another use case is when users are to have their own directories within the storage system. This can be arranged within the gPlazma configuration files by mapping each user’s DN to a unique username and then mapping each username to a unique root path. As an example, lines from /etc/grid-security/grid-vorolemap would therefore be written

"/DC=org/DC=doegrids/OU=People/CN=Selby Booth" "/cms" cms821
"/DC=org/DC=doegrids/OU=People/CN=Kenja Kassi" "/cms" cms822
"/DC=org/DC=doegrids/OU=People/CN=Ameil Fauss" "/cms" cms823

and the corresponding lines from /etc/grid-security/storage-authzdb would be

authorize cms821 read-write 10821 7000 / /data/cms821 /
authorize cms822 read-write 10822 7000 / /data/cms822 /
authorize cms823 read-write 10823 7000 / /data/cms823 /

[return to top]

The kpwd plug-in

The section in the gPlazma policy file for the kpwd plug-in specifies the location of the dcache.kpwd file, for example


# dcache.kpwd

To maintain only one such file, make sure that this is the same location as defined in /usr/share/dcache/defaults/

Use /usr/share/dcache/examples/gplazma/dcache.kpwd to create this file.

To be able to alter entries in the dcache.kpwd file conveniantly the dcache script offers support for doing this.


[user] $dcache kpwd dcuseradd testuser -u 12345 -g 1000 -h / -r / -f / -w read-write -p password

adds this to the kpwd file:

passwd testuser ae39aec3 read-write 12345 1000 / /

There are many more commands for altering the kpwd-file, see the dcache-script help for further commands available.

[return to top]

The gridmap plug-in

Two file locations are defined in the policy file for this plug-in:

# grid-mapfile

[return to top]

Preparing the grid-mapfile

The grid-mapfile is the same as that used in other applications. It can be created in various ways, either by connecting directly to VOMS or GUMS servers, or by hand.

Each line contains two fields: a DN (Certificate Subject) in quotes, and the username it is to be mapped to.


"/C=DE/O=GermanGrid/OU=DESY/CN=John Doe" johndoe

When using the gridmap plug-in, the storage-authzdb file must also be configured. See the section called “storage-authzdb for details.