Resource Manager

Table of Contents

1. Introduction
2. Features
3. Architecture overview
4. Components
4.1. PAM Module
4.2. Configuration File
4.3. Command Line Client Program
4.4. Resource Manager Daemon
5. Location of source code
6. Author

1. Introduction

Important

The name 'Resource Manager' is historical and misleading. resmgr itself actually does not manage any resources anymore, it's current purpose is to track user logins. Any other jobs are carried out by external helper programs.

Normally access to device files of audio devices, CD writers, USB cameras etc. is restricted to root by default. That means normal user's can't access them which is not what users expect from a desktop installation.

There are several aproaches to grant normal users access nevertheless:

  • make the devices accessible to everyone. This is probably the simplest approach. The downside is these devices will always be accessible, even if another user is sitting at the console.

  • make the devices accessible to a group. This is just a variation of the above. Adding and removing users dynamically to and from groups upon login is useless as once a user is member of a group he can create a setgid binary to regain group membership anytime.

  • make applications that open devices setuid root. This is a very common approach for example for CD-burning but it's unsuitable for e.g. sound devices. The biggest problem are the security problems it causes very frequently. This approach should be considered deprecated.

  • use a pam module and/or the xdm script framework (TakeConsole/GiveConsole) to change the ownership of various devices to the user logging in, and change it back to root when the user logs out. This solves the problem, but doesn't deal with hotplug devices that can appear and vanish any time. Additionally only one user can be given ownership to the devices at a time. That means additional sessions for different users as supported by modern display managers are of limited use.

  • use a daemon that opens the devices on demand on behalf of the user and have it pass the file descriptor to the user's application via an AF_LOCAL socket. This is what resmgr did in the past. This method works without actually having to touch the device nodes on disk, can cope with hotplugged devices and supports multiple concurrent users. The disadvantage is that one has to patch the software to call resmgr functions instead of opening the devices directly. That's not always possible, e.g. most commercial games are binary only and do need to access sound devices.

  • combine the previous two methods but use file system ACLs instead of chown or fd passing via socket. Using ACLs it's possible to grant access to multiple users individually without changing the owner of the device. For this purpose the filesystem that holds /dev must support ACLs of course.

resmgr and it's compagnon hal-resmgr implement the latter method. resmgrd tracks user logins and executes programs when users log in and out. One of those programs is hal-resmgr which fetches device information from hal and installs ACLs in the file system according to the login information from resmgr.

2. Features

  • Optional fine grained access control. Devices are grouped in to classes like 'sound' or 'cdrom'. Instead of granting users access to the 'desktop' class which includes most other classes it's also possible to only grant access to selected classes based on properties like login tty, pam service or host name.

  • Multiple user support. resmgr can manage sessions for multiple concurrent users. For example it's possible to log in with a different user on a second X server via kdm/gdm and still get access to sound devices.

  • PAM integration. For tracking logins a pam module is provided. There is no need to patch any scripts or applications, just edit your pam config in order to enable resmgr support.

  • Slim. resmgr itself is pure C without extra dependencies. hal-resmgr which is linked against dbus and hal libs is built separately and talks to the resmgr daemon via socket.

3. Architecture overview

Figure 1. resmgr Overview

resmgr Overview

(1)

When started, the resmgr daemon reads the list of available device classes and access control rules from it's configuration files.

(2)

When a user logs in and the login program (e.g. gdm, kdm) opens a PAM session the pam_resmgr PAM module tells the resmgr daemon the user name, tty, pam service, whether it's a remote login etc. Access control rules from the config file determine which classes a user gets. The daemon then executes programs associated with the login classes.

(3)

HAL knows the devices installed in the system. The HAL fdi file determines the login classes a device should be assigned to. It may for example match for certain USB vendor and device IDs and class a device as scanner.

(4)

hal-resmgr is a program which gets executed when a user logs in. It looks up device information in hal and asks resmgr which users should get access to which classes. It then grants access to devices according to that information by installing file system ACLs.

(5)

In the future PolicyKit might be used to look up class information. resmgr would feed login information into PolicyKit then.

4. Components

4.1. PAM Module

Description

pam_resgmr is a PAM session module that can be used to register a user session with the resource manager at login, and remove it when the user logs out. It can also be configured to grant the user access to additional login classes.

Synopsis

pam_resmgr.so [ OPTIONS ]

Options

grant=class

This option instructs pam_resmgr to tell the resource manager to grant the user access to login class class in addition to any classes defined by the default access control lists given in /etc/resmgr.conf

fake_ttyname

use a generated fake tty name when registering with resmgr. This is useful for ssh with privilege separation as it always sets the pam tty to the same string for all users.

fake_ttyname_if_needed

as above but only use the fake name if the pam tty doesn't start with a slash or colon. This is useful if ssh and other services share the same pam config file.

Examples

Add the following line to /etc/pam.d/sshd: 

session optional pam_resmgr.so fake_ttyname

For XDM you might want to use 

session optional pam_resmgr.so grant=desktop

or just 

session optional pam_resmgr.so

4.2. Configuration File

Description

The file /etc/resmgr.conf defines the login classes for the resource manager resmgrd. The minimal configuration is to define a single resource class and manage everything else dynamically. You may also define access control lists in this configuration file though.

Additionally all files with suffix .conf in the directory /etc/resmgr.conf.d/ are read in alphabetical order. This mechanism is intended for packages that want to define additional ressource classes or access control rules. The recommended name for files placed in that directory is NUMBER-PACKAGENAME.conf where NUMBER is a number between zero and 99.

Everything starting from a hash mark unto the end of the line is a com- ment, and is ignored.

The configuration file can contain the following commands:

class NAME

Defines a login class named NAME

Class names must be unique. Class names may only consist of upper or lower ASCII characters, underscores, dashes, colons and periods.

class NAME includes CHILDREN...

Defines that granting access to class NAME also grants access to CHILDREN classes. 

class desktop
class floppy
class cdrom
class desktop includes floppy
class desktop includes cdrom

ongrant CLASS run COMMAND...

Defines that when a user is granted access to class CLASS the command COMMAND is run. The environment variables RES_USER and RES_CLASS are set to the name of the involved user resp. class. 

ongrant desktop run /bin/ls

onrevoke CLASS run COMMAND...

Works the same as ongrant but gets executed when access to a class is revoked

allow class acl...

Grants all users matched by the ACL statement access to login class class. Any subsequent access control statements for this class will be ignored.

deny class acl...

Denies all users matched by the ACL statement access to login class class. Any subsequent access control statements for this class will be ignored.

ACL Format

ACLs attached to a login class is made up of one or more match clauses of the format name=value, where name can be one of user, group, tty, rhost or service. value can be a literal value or a glob expression, such as meissner (a user name), /dev/tty[0-9]*, or :* (for matching all logins on a local X display).

These match clauses can be combined using the standard boolean opera- tors &&, ||, and !. Note that !name=value is equivalent to name!=value.

Sub-expressions can be grouped by putting them in brackets.

Usually, an ACL will contain just a single user or group name, but you can specify several, forming an AND clause. When a name is preceded by an exclamation mark, the match result is negated.

For example, the following statements for the login class desktop will deny access to users uucp and news, but grant access to everyone in group wheel, and everyone else as long as they're logged in at the console or a local X11 session: 

deny  desktop user=uucp || user=news
allow desktop group=wheel
allow desktop tty=/dev/tty[0-9]* || tty=:0

4.3. Command Line Client Program

Description

The resmgr command is a command line client for the resource manager daemon resmgrd(8). It passes the specified command to the daemon, and prints the response.

Synopsis

resmgr [-s socket] [-u user] [-t] [command...]

Options

resmgr understands the following command line options:

-t

By default, resmgr will not include the server's numeric response codes in its output. By using the -t option, you can force resmgr to display the server's response as-is.

-u user

This option can be used by the root user when he wishes to con- tact the resource manager as user. This option is mostly for debugging and testing purposes.

-s socket

specifies the name of the socket on which the resource manager is listening. This option is mostly for debugging and testing purposes.

Commands

Currently, the resource manager protocol supports the following commands, all of which can be performed from the command line using resmgr:

help

Display the list of available commands.

login user tty [rhost=hostname] [service=servicename]

Indicates to the resource manager that user logged in on terminal tty. This will cause the resource manager to create a session record for the, and grant the user access to all resource classes that ACLs he matches.

This command is restricted to the administrator. Usually, the login command is executed by the pam_resmgr module when the user logs in, but you can also use it from the X11 GiveConsole script, for instance.

The syntax of the tty parameter is mostly irrelevant, except that it must be unique. When calling login with a tty name for which a session already exists, the previous session is deleted first. This is intended to increase robustness, when for some reason the logout command was not issued.

Example: 

# resmgr login joesix :0
success

logout tty

This will cause the resource manager to delete any session record for the indicated tty, and decrement the reference count on the user record associated with that session. If this was the last session for the user, all access rights for the user are revoked.

This command is restricted to the administrator. Usually, the logout command is executed by the pam_resmgr module when the user logs in, but you can also use it from the X11 TakeConsole script, for instance.

logout

This command lists all currently active sessions. It is restricted to the administrator.

grant user class

This command grants the indicated user access to the resource class class.

This command is restricted to the administrator. Usually, the grant command is executed by the pam_resmgr module when the user logs in, but you can also use it from the X11 GiveConsole script, for instance.

Example: 

# resmgr grant joesix modem
success

revoke user [class]

This command revokes a user's access rights to the given class. If no class argument is given, access to all classes is revoked.

this command is restricted to the administrator. It is not very useful, but was added for symmetry with grant.

dump [type]

dumps resmgrd's internal state. The output can be piped into resmgr again to restore the state. For example after restart of the daemon.

Without aguments dump dumps the entire internal state. By passing any of classes, sessions, grants, devices, dynamic-devices or static-devices as type argument the output can be stricted to the specified kind of data.

this command is restricted to the administrator.

4.4. Resource Manager Daemon

Description

resmgrd is a daemon that tracks when users log in and out. When a user logs in, a session is opened in resmgr. When the user logs out the session is closed.

the resmgr configuration defines login classes. Users can be granted access to such login classes either manually or by defining rules.

Synopsis

resmgrd [-s socket] [-f configfile] [-k] [-d]

Options

resmgrd understands the following command line options:

-k

Kill a running resmgr daemon.

-d

Don't fork to become a daemon, enable debug output.

-f configfile

use a different configuration file than /etc/resmgr.conf. This option is mostly for debugging and testing purposes.

-s socket

specifies the name of the socket on which the resource manager daemon should listen. This option is mostly for debugging and testing purposes.

5.  Location of source code

The resmgr source repository ist hosted at Novell Forge

6.  Author

resmgr was written by Olaf Kirch and is currently maintained by Ludwig Nussel and Marcus Meissner