Table of Contents
This is a resource manager that will provide unprivileged users access to device files. This is a common problem for people writing hardware drivers etc that should be used by "ordinary" users, such as usb cameras, scanners, CD writers, audio devices, etc etc.
There are several aproaches to this issue
make the devices accessible to everyone. This is probably the simplest approach. The down side is these devices will always be accessible, even if another user is sitting at the console. Another problem with this approach is that it doesn't deal with hotplug devices (usb, pcmcia).
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 setuid 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 first problem above, but doesn't deal with hotplug devices either. 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.
Another solution to this is to create a daemon that will open the devices on behalf of the user, and pass the file descriptor to the user's application via an AF_LOCAL socket. This is what resmgr does.
resmgr solves all problems listed above. It does create a new problem, however. You need to patch your software to call resmgr functions rather than to open devices directly. That disadvantage can be mitigated if the file system supports ACLs though.
When started, the resmgr daemon reads it's access control and static device information from its configuration files and creates the server socket.
When a user logs in, a pam module (pam_resmgr) will tell resmgr to create a session for that user. Resmgr then grants access to certain groups of devices (called resource classes) according to the rules defined in the config files. Optionally, the pam module can tell resmgr to directly grant the user access to a specific ressource class. The user will then be allowed to access all devices within that class.
When hotplug devices are attached, the hotplug subsystem can tell the resource manager to dynamically add devices to a specific resource class. Likewise, when a device is detached the hotplug subsystem can call the resource manager and ask it to remove the device from the ressource class.
To access a device from within an application the application
has to call rsm_open_device instead of
open.
rsm_open_device then connects to the
resmgr socket asking
resmgrd to pass a file descriptor for the
device.
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 resources classes.
grant=class
This option instructs
pam_resmgr
to tell the resource manager to grant the user access
to resource 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.
The file /etc/resmgr.conf defines the
resource 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 devices and 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
where NUMBER-PACKAGENAME.conf
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:
NAME
Defines a resource class named
NAME
Class names must be unique. Class names may only consist of upper or lower ASCII characters, underscores, dashes, colons and periods.
NAMEincludes
CHILDREN...
Defines that granting access to class
NAME also grants access to
CHILDREN classes.
deviceclassflagsadd the specified device to the resource class class. Optionally, one or more flags can be specified.
The read-only flag marks the device read-only. Attempts to open the device for writing will be refused.
The scsi flag allows clients to ask for the corresponding raw SCSI device instead of the device itself. This is useful for applications such as CD writers or scanners that need to find and open the raw SCSI device corresponding to e.g. /dev/cdrom.
The nofacl flag prevents resmgr from installing file system ACLs for the device. Note that ACLs are only installed for devices of the file family.
deviceclassflags
Explicitely deny access to
device. Exclude statements
are useful for example before a statement that adds
usb:any
classacl...Grants all users matched by the ACL statement access to resource class class. Any subsequent access control statements for this class will be ignored.
classacl...Denies all users matched by the ACL statement access to resource class class. Any subsequent access control statements for this class will be ignored.
ACLs attached to a resource 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 resource 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
resmgr supports special handling of some type of devices. For this purpose device families were introduced. When adding a device to resmgr the family name has to be prepended to the device path, separated by a colon.
The family can be omitted for device name that start with a
slash. Resmgr will treat them as file unless they are opened
as another family and file flags allow that. For example you
may use resmgr add /dev/sr0 scsi to add a
device and later open either file:/dev/sr0
or scsi:/dev/sr0
regular files, character and block devices. Normally
device nodes in /dev
resmgr accepts the following syntax:
file:PATH
usb devices are normally not accessed via device files
but via the /proc/bus/usb
filesystem.
resmgr accepts any of the following syntax:
usb:/proc/bus/usb/BUSNR/DEVNR usb:key1=value1,key2=value2,... usb:BUSNR,DEVNR usb:BUSNR,DEVNR:/proc/bus/usb/BUSNR/DEVNR
key can be any of
bus,
dev,
class,
subclass,
vendor or
product
for SCSI devices applications often want to open the
SCSI-generic device instead of the disk device, e.g.
sg1
instead of sr0. Since the numbering
of both kind of devices is not related the scsi family
was introduced to automatically determine with devices
belong to together. So if you want to allow CD burning
on your recorder with the device
/dev/sr0 you would tell resmgr to
open scsi:/dev/sr0
resmgr accepts any of the following syntax:
scsi:/dev/NAME scsi:BUS.TARGET.LUN scsi:TARGET.LUN scsi:BUS.TARGET.LUN:/dev/NAME scsi:TARGET.LUN:/dev/NAME
PARIDE devices work similar to SCSI ones.
resmgr accepts any of the following syntax:
paride:/dev/NAME paride:MINOR paride:MINOR:/dev/NAME
the socket family deals with AF_LOCAL
sockets.
resmgr accepts any of the following syntax:
socket:PATH;dgram socket:PATH;stream
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.
resmgr understands the following command line options:
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.
userThis 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.
socketspecifies the name of the socket on which the resource manager is listening. This option is mostly for debugging and testing purposes.
Currently, the resource manager protocol supports the following commands, all of which can be performed from the command line using resmgr:
Display the list of available commands.
familyDisplay the list of devices available to the user.
The optional family argument can be used to specify a resource family. If specified, the listing will include only names from that specific family. In addition, device names will be mapped to that particular name space.
For instance, if the resource class includes the device /dev/cdrom, listing the scsi family would return a corresponding SCSI device specifier such as scsi:0,0,1. (Of course, this assumes that /dev/cdrom uses the SCSI CD driver, and that the user has permission to open the corresponding raw SCSI device).
flagsdeviceOpen the specified device and receive the file descriptor through the socket connection. Optionally, one or more flags can be passed.
The flag -ro tells the server to open the device read-only. Oth- erwise, the device is opened read-write.
If the device is flagged read-only, but the client tries to open it read-write, access is denied.
The device parameter is usually just the path name of the device that should be opened. However, you can prefix the name with a resource family to request a different interpretation of the device name, such as scsi:/dev/cdrom. This will open the raw SCSI device associated with /dev/cdrom. The device must have the scsi flag set, otherwise the request will be refused. This is useful for scanners and CD writers.
For the convenience of applications that want to open a device based on its SCSI ID, the scsi resource family supports an alternative device notation, which is scsi:[bus,]target,lun.
deviceCreates a lock file for the device, and put the PID of the client process into the file. The owner of the PID file is set to the uid of the client process, allowing the application to update the contents of the lock file if it puts itself into the background, for example.
If a conflicting lock exists, access is denied. If a stale lock file is found, the server returns error code 202 (stale lock file). This indicates that the client should perform an unlock call for this device, which will remove the stale lock.
deviceRemoves a lock file for the device. If a lock file exists which is neither owned by the uid of the calling application, and which is not a stale lockfile, access is denied. Otherwise the lock file is removed.
userttyrhost=hostname]
[service=servicename]
Indicates to the resource manager that user logged in on termi- nal tty. This will cause the resource manager to create a ses- sion 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.
ttyThis 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.
This command lists all currently active sessions. It is restricted to the administrator.
userclassThis 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.
userclassThis 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.
deviceclassflagsadd the specified device to the resource class class. Optionally, one or more flags can be specified.
The read-only flag marks the device read-only. Attempts to open the device for writing will be refused.
The scsi flag allows clients to ask for the corresponding raw SCSI device instead of the device itself. This is useful for applications such as CD writers or scanners that need to find and open the raw SCSI device corresponding to e.g. /dev/cdrom.
The nofacl flag prevents resmgr from installing file system ACLs for the device. Note that ACLs are only installed for devices of the file family.
This command is restricted to the administrator. It can be used by a hotplugging daemon to make a device available to local users when attached.
deviceclassThis command removes the specified device from resource class class. If no class argument is given, the device is removed from all classes.
This command is restricted to the administrator. It can be used by a hotplugging daemon to disable access to a device when it becomes unavailable.
resmgrd is a resource manager that allows applications to access and lock device files. It supports hot-plugging, i.e. devices can be added to a resource class as they become available, and can be removed when unplugged.
Devices are grouped in so-called resource classes. Each device in a resource class has an associated flag that defines whether applications are permitted to open it for reading and writing, or for reading only. The devices in a resource class can be defined in the static configura- tion file, but they can also be added and removed dynamically by a hot- plugging daemon.
For most purposes, having a single resource class will be enough, but you can have several if you want.
Access control to device files happens at the resource class level as well. Users can be granted the right to access devices from a certain resource class. Again, access control can be defined statically in the configuration file, or dynamically.
Applications communicate with resmgrd through an AF_LOCAL socket. When the client wants to access a device file, it asks the resource manager to do so. If permitted by the access control lists, the resource man- ager will open the device file and pass the open file descriptor back to the client via the AF_LOCAL socket.
Additionally, applications can use the resource manager to lock and unlock a device file. This happens via traditional UUCP-style lock files in /var/lock. The main purpose of this is to allow applications using serial devices to continue using UUCP-style locks.
All other operations, such as adding devices to a resource class, or granting a user access to a class, are restricted to the administrator.
Since patching every application for resmgr support is not possible, especially not for binary only applications, resmgr also supports file system ACLs in addition to the fd-over-socket feature. When a user logs in and is granted access to a certain class, resmgr walks all devices in that class and installs an ACL entry on it in the filesystem. When the user logs out, the ACL is removed again. If multiple users log in, multiple ACLs entries are installed.
As a fallback if the underlying filesystem of a device does not support ACLs, resmgr changes the owner of the file to the first user that is granted access to it. This is bascially what pam_logindevperm and pam_console do.
resmgrd understands the following command line options:
Kill a running resmgr daemon.
Don't fork to become a daemon, enable debug output.
configfile
use a different configuration file than
/etc/resmgr.conf. This option is
mostly for debugging and testing purposes.
socketspecifies the name of the socket on which the resource manager daemon should listen. This option is mostly for debugging and testing purposes.
The resmgr source repository ist hosted at Novell Forge