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

