readme

linux-2.6.15.6

This could be solved with a secure user-space daemon which runs as
root and does the actual creation of pty-pairs. Such a daemon would
require modification to *every* programme that wants to use this new
mechanism. It also slows down creation of pty-pairs.

An alternative is to create a new open_pty() syscall which does much
the same thing as the user-space daemon. Once again, this requires
modifications to pty-handling programmes.

The devfs solution allows a device driver to "tag" certain device
files so that when an unopened device is opened, the ownerships are
changed to the current euid and egid of the opening process, and the
protections are changed to the default registered by the driver. When
the device is closed ownership is set back to root and protections are
set back to read-write for everybody. No programme need be changed.
The devpts filesystem provides this auto-ownership feature for Unix98
ptys. It doesn't support old-style pty devices, nor does it have all
the other features of devfs.

Intelligent device management

Devfs implements a simple yet powerful protocol for communication with
a device management daemon (devfsd) which runs in user space. It is
possible to send a message (either synchronously or asynchronously) to
devfsd on any event, such as registration/unregistration of device
entries, opening and closing devices, looking up inodes, scanning
directories and more. This has many possibilities. Some of these are
already implemented. See:


http://www.atnf.csiro.au/~rgooch/linux/

Device entry registration events can be used by devfsd to change
permissions of newly-created device nodes. This is one mechanism to
control device permissions.

Device entry registration/unregistration events can be used to run
programmes or scripts. This can be used to provide automatic mounting
of filesystems when a new block device media is inserted into the
drive.

Asynchronous device open and close events can be used to implement
clever permissions management. For example, the default permissions on
/dev/dsp do not allow everybody to read from the device. This is
sensible, as you don't want some remote user recording what you say at
your console. However, the console user is also prevented from
recording. This behaviour is not desirable. With asynchronous device
open and close events, you can have devfsd run a programme or script
when console devices are opened to change the ownerships for *other*
device nodes (such as /dev/dsp). On closure, you can run a different
script to restore permissions. An advantage of this scheme over
modifying the C library tty handling is that this works even if your
programme crashes (how many times have you seen the utmp database with
lingering entries for non-existent logins?).

Synchronous device open events can be used to perform intelligent
device access protections. Before the device driver open() method is
called, the daemon must first validate the open attempt, by running an
external programme or script. This is far more flexible than access
control lists, as access can be determined on the basis of other
system conditions instead of just the UID and GID.

Inode lookup events can be used to authenticate module autoload
requests. Instead of using kmod directly, the event is sent to
devfsd which can implement an arbitrary authentication before loading
the module itself.

Inode lookup events can also be used to construct arbitrary
namespaces, without having to resort to populating devfs with symlinks
to devices that don't exist.

Speculative Device Scanning

Consider an application (like cdparanoia) that wants to find all
CD-ROM devices on the system (SCSI, IDE and other types), whether or
not their respective modules are loaded. The application must
speculatively open certain device nodes (such as /dev/sr0 for the SCSI
CD-ROMs) in order to make sure the module is loaded. This requires
that all Linux distributions follow the standard device naming scheme
(last time I looked RedHat did things differently). Devfs solves the
naming problem.

The same application also wants to see which devices are actually
available on the system. With the existing system it needs to read the
/dev directory and speculatively open each /dev/sr* device to
determine if the device exists or not. With a large /dev this is an
inefficient operation, especially if there are many /dev/sr* nodes. A
solution like scsidev could reduce the number of /dev/sr* entries (but
of course that also requires all that inefficient directory scanning).

With devfs, the application can open the /dev/sr directory
(which triggers the module autoloading if required), and proceed to
read /dev/sr. Since only the available devices will have
entries, there are no inefficencies in directory scanning or device
openings.

-----------------------------------------------------------------------------

Who else does it?

FreeBSD has a devfs implementation. Solaris and AIX each have a
pseudo-devfs (something akin to scsidev but for all devices, with some
unspecified kernel support). BeOS, Plan9 and QNX also have it. SGI's
IRIX 6.4 and above also have a device filesystem.

While we shouldn't just automatically do something because others do
it, we should not ignore the work of others either. FreeBSD has a lot
of competent people working on it, so their opinion should not be
blithely ignored.

-----------------------------------------------------------------------------


How it works

Registering device entries

For every entry (device node) in a devfs-based /dev a driver must call
devfs_register(). This adds the name of the device entry, the
file_operations structure pointer and a few other things to an
internal table. Device entries may be added and removed at any
time. When a device entry is registered, it automagically appears in
any mounted devfs'.

Inode lookup

When a lookup operation on an entry is performed and if there is no
driver information for that entry devfs will attempt to call
devfsd. If still no driver information can be found then a negative
dentry is yielded and the next stage operation will be called by the
VFS (such as create() or mknod() inode methods). If driver information
can be found, an inode is created (if one does not exist already) and
all is well.

Manually creating device nodes

The mknod() method allows you to create an ordinary named pipe in the
devfs, or you can create a character or block special inode if one
does not already exist. You may wish to create a character or block
special inode so that you can set permissions and ownership. Later, if
a device driver registers an entry with the same name, the
permissions, ownership and times are retained. This is how you can set
the protections on a device even before the driver is loaded. Once you
create an inode it appears in the directory listing.

Unregistering device entries

A device driver calls devfs_unregister() to unregister an entry.

Chroot() gaols

2.2.x kernels

The semantics of inode creation are different when devfs is mounted
with the "explicit" option. Now, when a device entry is registered, it
will not appear until you use mknod() to create the device. It doesn't
matter if you mknod() before or after the device is registered with
devfs_register(). The purpose of this behaviour is to support
chroot(2) gaols, where you want to mount a minimal devfs inside the
gaol. Only the devices you specifically want to be available (through
your mknod() setup) will be accessible.

2.4.x kernels

As of kernel 2.3.99, the VFS has had the ability to rebind parts of
the global filesystem namespace into another part of the namespace.
This now works even at the leaf-node level, which means that
individual files and device nodes may be bound into other parts of the
namespace. This is like making links, but better, because it works
across filesystems (unlike hard links) and works through chroot()
gaols (unlike symbolic links).

Because of these improvements to the VFS, the multi-mount capability
in devfs is no longer needed. The administrator may create a minimal
device tree inside a chroot(2) gaol by using VFS bindings. As this
provides most of the features of the devfs multi-mount capability, I
removed the multi-mount support code (after issuing an RFC). This
yielded code size reductions and simplifications.

If you want to construct a minimal chroot() gaol, the following
command should suffice:

mount --bind /dev/null /gaol/dev/null


Repeat for other device nodes you want to expose. Simple!

-----------------------------------------------------------------------------


Operational issues


Instructions for the impatient

Nobody likes reading documentation. People just want to get in there
and play. So this section tells you quickly the steps you need to take
to run with devfs mounted over /dev. Skip these steps and you will end
up with a nearly unbootable system. Subsequent sections describe the
issues in more detail, and discuss non-essential configuration
options.

Devfsd
OK, if you're reading this, I assume you want to play with
devfs. First you should ensure that /usr/src/linux contains a
recent kernel source tree. Then you need to compile devfsd, the device
management daemon, available at

http://www.atnf.csiro.au/~rgooch/linux/.
Because the kernel has a naming scheme
which is quite different from the old naming scheme, you need to
install devfsd so that software and configuration files that use the
old naming scheme will not break.

Compile and install devfsd. You will be provided with a default
configuration file /etc/devfsd.conf which will provide
compatibility symlinks for the old naming scheme. Don't change this
config file unless you know what you're doing. Even if you think you
do know what you're doing, don't change it until you've followed all
the steps below and booted a devfs-enabled system and verified that it
works.

Now edit your main system boot script so that devfsd is started at the
very beginning (before any filesystem
checks). /etc/rc.d/rc.sysinit is often the main boot script
on systems with SysV-style boot scripts. On systems with BSD-style
boot scripts it is often /etc/rc. Also check
/sbin/rc.

NOTE that the line you put into the boot
script should be exactly:

/sbin/devfsd /dev

DO NOT use some special daemon-launching
programme, otherwise the boot script may not wait for devfsd to finish
initialising.

System Libraries
There may still be some problems because of broken software making
assumptions about device names. In particular, some software does not
handle devices which are symbolic links. If you are running a libc 5
based system, install libc 5.4.44 (if you have libc 5.4.46, go back to
libc 5.4.44, which is actually correct). If you are running a glibc
based system, make sure you have glibc 2.1.3 or later.

/etc/securetty
PAM (Pluggable Authentication Modules) is supposed to be a flexible
mechanism for providing better user authentication and access to
services. Unfortunately, it's also fragile, complex and undocumented
(check out RedHat 6.1, and probably other distributions as well). PAM
has problems with symbolic links. Append the following lines to your
/etc/securetty file:

vc/1
vc/2
vc/3
vc/4
vc/5
vc/6
vc/7
vc/8

This will not weaken security. If you have a version of util-linux
earlier than 2.10.h, please upgrade to 2.10.h or later. If you
absolutely cannot upgrade, then also append the following lines to
your /etc/securetty file:

1
2
3
4
5
6
7
8

This may potentially weaken security by allowing root logins over the
network (a password is still required, though). However, since there
are problems with dealing with symlinks, I'm suspicious of the level
of security offered in any case.

XFree86
While not essential, it's probably a good idea to upgrade to XFree86
4.0, as patches went in to make it more devfs-friendly. If you don't,
you'll probably need to apply the following patch to
/etc/security/console.perms so that ordinary users can run
startx. Note that not all distributions have this file (e.g. Debian),
so if it's not present, don't worry about it.

--- /etc/security/console.perms.orig    Sat Apr 17 16:26:47 1999 
+++ /etc/security/console.perms Fri Feb 25 23:53:55 2000 
@@ -14,7 +14,7 @@ 
 # man 5 console.perms 

 # file classes -- these are regular expressions 
-<console>=tty[0-9][0-9]* :[0-9]\.[0-9] :[0-9] 
+<console>=tty[0-9][0-9]* vc/[0-9][0-9]* :[0-9]\.[0-9] :[0-9] 

 # device classes -- these are shell-style globs 
 <floppy>=/dev/fd[0-1]* 

If the patch does not apply, then change the line:

<console>=tty[0-9][0-9]* :[0-9]\.[0-9] :[0-9]

with:

<console>=tty[0-9][0-9]* vc/[0-9][0-9]* :[0-9]\.[0-9] :[0-9]


Disable devpts
I've had a report of devpts mounted on /dev/pts not working
correctly. Since devfs will also manage /dev/pts, there is no
need to mount devpts as well. You should either edit your
/etc/fstab so devpts is not mounted, or disable devpts from
your kernel configuration.

Unsupported drivers
Not all drivers have devfs support. If you depend on one of these
drivers, you will need to create a script or tarfile that you can use
at boot time to create device nodes as appropriate. There is a
section which describes this. Another
section lists the drivers which have
devfs support.

/dev/mouse

Many disributions configure /dev/mouse to be the mouse device
for XFree86 and GPM. I actually think this is a bad idea, because it
adds another level of indirection. When looking at a config file, if
you see /dev/mouse you're left wondering which mouse
is being referred to. Hence I recommend putting the actual mouse
device (for example /dev/psaux) into your
/etc/X11/XF86Config file (and similarly for the GPM
configuration file).

Alternatively, use the same technique used for unsupported drivers
described above.

The Kernel
Finally, you need to make sure devfs is compiled into your kernel. Set
CONFIG_EXPERIMENTAL=y, CONFIG_DEVFS_FS=y and CONFIG_DEVFS_MOUNT=y by
using favourite configuration tool (i.e. make config or
make xconfig) and then make clean and then recompile your kernel and 
modules. At boot, devfs will be mounted onto /dev.

If you encounter problems booting (for example if you forgot a
configuration step), you can pass devfs=nomount at the kernel
boot command line. This will prevent the kernel from mounting devfs at
boot time onto /dev.

In general, a kernel built with CONFIG_DEVFS_FS=y but without mounting
devfs onto /dev is completely safe, and requires no
configuration changes. One exception to take note of is when
LABEL= directives are used in /etc/fstab. In this
case you will be unable to boot properly. This is because the
mount(8) programme uses /proc/partitions as part of
the volume label search process, and the device names it finds are not
available, because setting CONFIG_DEVFS_FS=y changes the names in
/proc/partitions, irrespective of whether devfs is mounted.

Now you've finished all the steps required. You're now ready to boot
your shiny new kernel. Enjoy.

Changing the configuration

OK, you've now booted a devfs-enabled system, and everything works.