Authorization System

Ganglia contains a simple authorization system to selectively allow or deny users access to certain parts of the gweb application. We rely on the web server to provide authentication, so any Apache authentication system (htpasswd, LDAP, etc) is supported.

Configuration

The authorization system has three modes of operation.

1. $conf['auth_system'] = 'readonly'; : Anyone is allowed to view any resource. No-one can edit anything. This is the default setting.

2. $conf['auth_system'] = 'disabled'; : Anyone is allowed to view or edit any resource.

3. $conf['auth_system'] = 'enabled'; : Anyone may view public clusters without login. Authenticated users may gain elevated privileges.

If you wish to enable or disable authorization, please add your change to your conf.php file.

When a user successfully authenticates, a hash is generated from the username + a secret key, and is stored in a cookie and made available to the rest of gweb. If the secret key value becomes known, it is possible for an attacker to assume the identity of any user.

You may change this secret value at any time. Users who have already logged in will need to log in again.

Enabling Authentication

Enabling authentication requires two steps:

1. Configure your web server to require authentication when accessing gweb/login.php, and to provide the $_SERVER['REMOTE_USER'] variable to gweb/login.php. (This variable is not needed on any other gweb page.)

2. Configure your web server to provide $_SERVER['ganglia_secret']. This is a secret value used for hashing authenticated user names.

If login.php does not require authentication, the user will see an error message and no authorization will be allowed.

[[authentication_failed.jpg|alt=A Failed Authentication]]

Apache

SetEnv ganglia_secret yourSuperSecretValueGoesHere

<Files "login.php">
  AuthType Basic
  AuthName "Ganglia Access"
  AuthUserFile /var/lib/ganglia/htpasswd
  Require valid-user
</Files>

More information about configuring authentication in Apache can be found at http://httpd.apache.org/docs/2.2/howto/auth.html. Note that Apache need only provide authentication. Authorization is provided by gweb configuration.

Nginx

WARNING: This configuration is untested. If you are able to test this, please report results to ganglia-developers at lists.sourceforge.net.

location ~ \.php$ { {
  fastcgi_param ganglia_secret yourSuperSecretValueGoesHere;
}

location /login.php  {
  auth_basic            "Ganglia Access";
  auth_basic_user_file  /var/lib/ganglia/htpasswd;
  fastcgi_param  REMOTE_USER    $remote_user;
}

http://wiki.nginx.org/HttpAuthBasicModule

Lighttpd

WARNING: This configuration is untested. If you are able to test this, please report results to ganglia-developers at lists.sourceforge.net.

setenv.add-environment = (
  "ganglia_secret" => "yourSuperSecretValueGoesHere"
)


server.modules               += ( "mod_auth" )
auth.backend                 = "plain"
auth.backend.plain.userfile  = "/etc/lighttpd/lighttpd.user"
auth.require                 = (
  "/login.php" => (
    "method"    => "basic",
    "realm"     => "Ganglia Access",
    "require"   => "valid-user",
  )
)

Access Controls

The default access control setup has the following properties: * Guests may view all public clusters. * Admins may view all public & private clusters, and edit configuration (views) for them. * Guests may not view private clusters.

Additional rules may be configured as required. This configuration should go in conf.php. GangliaAcl is based on Zend_Acl. More documentation is available at http://framework.zend.com/manual/en/zend.acl.html.

Note that there is no built-in distinction between a 'user' and a 'group' in Zend_Acl. Both are implemented as roles. The system supports the configuration of heirarchical sets of ACL rules. We implement user/group semantics by making all user roles children of the GangliaAcl::GUEST role, and all clusters children of GangliaAcl::ALL.

Constants

Name	Meaning
GangliaAcl::ALL_CLUSTERS	Every cluster should descend from this role. Guests have 'view' access on GangliaAcl::ALL_CLUSTERS.
GangliaAcl::GUEST	Every user should descend from this role. (Users may also have other roles, but this one grants global view privileges to public clusters.)
GangliaAcl::ADMIN	Admins may access all private clusters and edit configuration for any cluster.
GangliaAcl::VIEW	This permission is granted to guests on all clusters, and then selectively denied for private clusters.
GangliaAcl::EDIT	This permission is used to determine if a user may update views and perform any other configuration tasks.

Actions

Currently we only support two actions, 'view' and 'edit'. These are applied on a per-cluster basis. So one user may have 'view' access to all clusters, but 'edit' access to only one.

Examples

These should go in your conf.php file. The usernames you use will be the ones provided by whatever authentication system you are using in Apache. If you want to explicitly allow/deny access to certain clusters, you need to spell that out here.

Accessing the ACL

All later examples assume you have this code to start with:

$acl = GangliaAcl::getInstance();

Making a user an admin

$acl->addRole( 'username', GangliaAcl::ADMIN );

Defining a private cluster

$acl->addPrivateCluster( 'clustername' );

Granting certain users access to a private cluster

$acl->addPrivateCluster( 'clustername' );
$acl->addRole( 'username', GangliaAcl::GUEST );
$acl->allow( 'username', 'clustername', GangliaAcl::VIEW );

Granting users access to edit some clusters

$acl->addRole( 'username', GangliaAcl::GUEST );
$acl->add( new Zend_Acl_Resource( 'clustername' ), GangliaAcl::ALL_CLUSTERS );
$acl->allow( 'username', 'clustername', GangliaAcl::EDIT );