NORDUGRID-MEMO-5

GACL mini-howto

Grid Acces Control List (GACL)

GACL an XML-based ACL language to controll access to files & directories on a storage element.

Hierarchy of gaclfiles

Each directory and file should have an associated gaclfile. When a new file <myfile> is uploaded or a new directory called <mydir> is made, the corresponding .gacl-myfile or .gacl-mydir files with the default rules is created by the server. Each new directory gets two associated .gacl files:

.gacl-<mydir> (in the parent directory)
<mydir>/.gacl (inside the directory itself)

The first controls what can be done with <mydir> and second - inside <mydir>. In a gacl-controlled storage, the ACLs of a file/directory are always determined in the following order:

the .gacl-<myfile> is considered
in case .gacl-<myfile> is missing the .gacl file of the directory containing the file is checked
after this, the ../.gacl
then, the ../../.gacl

The .gacl-<myfile> always has a priority over any .gacl files. Hence the current .gacl file is used during creation of new files/directories (.gacl controls what can be done within the directory) and if for some reason a file/directory has no .gacl-<myfile>/.gacl-<mydir> file.

The default rule is configurable at server. Normally such rule gives full permissions to the owner of the file/directory and locks everybody else out (see the default .gacl file below in the example sections).

Syntax of a gaclfile

More detailed information about GACL can be obtained at GridSite. Here we present simplified description.

<gacl>
  <entry>
    <WHO block>
    <WHAT block>
  </entry>
  <entry>
    <WHO section>
    <WHAT section>
  </entry>
</gacl>

WARNING!!! an invalid .gacl file may result in the FULL loss of control and access to your file/directory!!! If such disaster happens You have to contact server's administrator.

A gaclfile contains a set of one or more gaclentries. A gaclentry should be considered as a "WHO is allowed/denied to do WHAT" type of rule. When evaluated, a user is tested against the entries in turn, and resulted allowed/denied actions are combained in way described below.

WHO block

A gaclentry defines the WHO block by a set of one or more credentials or predefined keywords like "any-user". If more than one credentials are used to describe the WHO block, they must ALL apply to the tested identity (user) (AND operation of credentials within an entry). The WHO block of the entry is then associated with Allow and Deny rules for certain capabilities. Deny rules always overwrite Allows. If something is not allowed then it is by default denied.

The following credential constructions can be used to define the WHO block:

<any-user>      	#everybody
</any-user>

<auth-user>		#not really useful (every user is already authenticated at this point)
</auth-user>	

<person>		#a person identified by its DN
 <dn>/O=Grid/O=NorduGrid/OU=quark.lu.se/CN=Some User</dn>
</person>

<dn-list>		#a list of DNs stored in a file (default location is /etc/grid/security)
 <url>a_file_in_/etc/grid/security_with_a_list_of_DNs</url>
</dn-list>

<voms>
 <voms>DN of VOMS server</voms>
 <vo>VO name</vo> 
 <group>Group</group> 
 <role>Role</role> 
 <capability>Capability</capability>
</voms>

Everything is case sensitive, NO wildcards or regular expressions are supported in the DN names or VOMS group/role/capabilities. If element is omitted that means it matches any value. If element has multiple value any of them will match.

One WHO block can be made of multiple credentials which are combained using AND logic.

An example WHO block looks like:

<person>
 <dn>/O=Grid/O=NorduGrid/OU=quark.lu.se/CN=Some User</dn>
</person>
<voms-cred>
  <vo>Mighty VO</vo>
  <role>ordinary user</role> 	
</voms-cred>

WHAT block

The WHAT block is defined by ALLOW and DENY blocks. A gaclentry can have one ALLOW and one DENY block. In the ALLOW block, all the allowed actions have to be listed, and in the DENY block, all the banned ones. Allow and deny rules are evaluated separately and combined at the end of ACL processing in such a way that any DENY for a specific permission type overrides any ALLOW. In this way, the order of entries in the ACL is not significant.

Syntax of ALLOW block:

<allow>
action
action
...
</allow>

Syntax of DENY block:

<deny>
action
action
...
</deny>

The actions which can be allowed or denied, with their effect on directories and files, are listed below.

For a directory /<dir1>/<dir2>/<DIR>:

Action for directory	Permission	GACL file usually used
List contents	<list/>	/<dir1>/<dir2>/.gacl-<DIR>
Change into it	<list/>	/<dir1>/<dir2>/.gacl-<DIR>
Create new file	See file action
Delete file	See file action
Delete this directory	<write/>	/<dir1>/<dir2>/.gacl-<DIR>
Create new subdirectory	See below
Create this directory	<write/>	/<dir1>/<dir2>/.gacl
Obtain information about it	<read/>	/<dir1>/<dir2>/.gacl-<DIR>

For a file /<dir1>/<dir2>/<FILE>:

Action for file	Permission	GACL file usually used
Open for reading	<read/>	/<dir1>/<dir2>/.gacl-<FILE>
Open for (over)writing	<write/>	/<dir1>/<dir2>/.gacl-<FILE>
Create	<write/>	/<dir1>/<dir2>/.gacl
Delete	<write/>	/<dir1>/<dir2>/.gacl-<FILE>
Obtain information about it	<list/>	/<dir1>/<dir2>/.gacl-<FILE>

Access control action

Action for access control	Permission	GACL file used
Modify/Create/Delete	<admin/>	File itself

An example for a WHAT block:

<allow><read/><list/><write/></allow>	
<deny><admin/></deny>

Working with gaclfiles

Changing a file/directory's ACL means uploading a modified .gacl-<myfile> gaclfile into the directory where the file is situated.

Hint: you can use the gsincftp client to check the content of a GACL file:
ncftp / > more .gacl-<myfile>

There is an utility ngacl which can be used to check and modify GACL properties of files/directories.

Session example

> ngacl get gsiftp://hathi.hep.lu.se/public/mydir

this prints the contents of the directory-specific external gaclfile gsiftp://hathi.hep.lu.se/public/.gacl-mydir to the standard output

> ngacl get gsiftp://hathi.hep.lu.se/public/mydir/

this prints the contents of directory's internal gaclfile gsiftp://hathi.hep.lu.se/public/mydir/.gacl to the standard output. Note the trailing slash!

> ngacl get gsiftp://hathi.hep.lu.se/public/mydir/ > /tmp/mygacl

this saves the output to a file /tmp/mygacl, so that you can modify ACL

> ngacl set gsiftp://hathi.hep.lu.se/public/mydir/ < /tmp/mygacl

this uploads the /tmp/mygacl as the new internal gaclfile gsiftp://hathi.hep.lu.se/public/mydir/.gacl

Examples

Search order for GACL rules

Below is an example to show files used while determining gacl rules applied to an object. For an object /dir1/dir2/.../dirA/dirB/dirC/obj, these files are checked:

/dir1/dir2/.../dirA/dirB/dirC/.gacl-obj
/dir1/dir2/.../dirA/dirB/dirC/.gacl
/dir1/dir2/.../dirA/dirB/.gacl
/dir1/dir2/.../dirA/.gacl
...

First file found is used to determine allowed actions.

gaclfile examples

This is the default .gacl (of default installation) which gets created for every new file or a new directory:

<gacl>
  <entry>
    <person>
       <dn>/O=Grid/O=NorduGrid/OU=quark.lu.se/CN=User Name</dn>
    </person>
    <allow><read/><list/><write/><admin/></allow>
  </entry>
</gacl>

Here the <dn>...</dn> is taken from the user's proxy. The above ACL gives full control (read,list,write,admin) to the creator of the file BUT locks out everybody else.

This is a .gacl-readme file which gives the read permission to everyone and write permission only to a specific user for the readme file:

<gacl>
  <entry>
    <any-user>
    </any-user>
    <allow><read/></allow>
  </entry>
  <entry>
    <person>
       <dn>/O=Grid/O=NorduGrid/OU=quark.lu.se/CN=User Name</dn>
    </person>
    <allow><read/><list/><write/><admin/></allow>
  </entry>
</gacl>

Further information

GACL is now part of the Gridsite project