SGI
Open Source
FAM FAQ

About and Capabilities:

Obtaining and Requirements:

Building and Installing:

Running and Using:

Miscellaneous:


About and Capabilities

What is FAM?

FAM, the File Alteration Monitor, provides an API that applications can use to be notified when specific files or directories are changed.

FAM comes in two parts: fam, the daemon that listens for requests and delivers notification, and libfam, a library that client applications can use to communicate with fam.

FAM was originally written for IRIX in 1989 by Bruce Karsh, and was rewritten in 1995 by Bob Miller. This open-source release of FAM builds and runs on both Linux and IRIX, and is almost identical to the version of FAM that ships with IRIX 6.5.x.

What can I do with FAM?

You can make tools more usable by enabling them to respond to changes in the system, rather than requiring the user to manually request that the tool update itself.

For example, consider a graphical file manager: When the user creates or removes a file thru the file manager, their changes are visible immediately, as they should be. However, if they create or remove a file thru some other means (such as typing "touch foo" or "rm foo" in a shell), some file managers will continue to display out-of-date information until the user manually directs the file manager to reread the contents of the directory. That's not the way it should be! The user should be able to trust that their file manager really shows them their files as they are, not their files as they were at some unknown point in the past.

Other tools can use FAM too. For example, rather than polling your mailbox every few seconds, your biff program could use FAM. When displaying the contents of a directory on the local machine, your web browser could FAM the directory, and always display the current contents of the directory. A system administration tool that manages login accounts might FAM /etc/passwd and /etc/shadow so that it could reflect changes to accounts made by some other administrator editing the files by hand or thru another tool. A software installation tool might FAM its history database so that it could update itself when new software was installed. A filesystem tool might FAM /etc/mtab to display the filesystems currently mounted. A daemon such as inetd might FAM its configuration file so that the user would not have to remember to kill -HUP after changing its configuration. And so on!

Why would I use FAM instead of polling?

It's easy to have an application that periodically polls the files it's interested in to determine whether they've changed since the last poll. There are three reasons to use FAM instead:

Latency: The problem with polling is that the longer your process waits between polls, the longer the delay between a file operation and your process finding out about it. You can reduce latency by decreasing the polling interval, but that means your process spends more time and more system resources doing nothing useful. With FAM, your process can express interest in files or directories, and then do useful work (or sleep) until FAM says the files have changed.

Duplication of effort: If you have many processes polling the same file, they're all going to have to periodically wake up, check the file, and go back to sleep. If they all used FAM, no one would have to poll. If fam is running on a system without IMon (see below), then fam will have to poll, but in this case, you've still got only one process waking up to poll; the others only wake up when there's something for them to do.

Network traffic: When a process asks fam to watch a file that is NFS mounted from a remote host, the local fam will ask fam on the remote host to monitor the files. This means that notification of changes on remote machines can be achieved using network traffic only when the files have changed. (If fam isn't running on the remote host, then the local fam has to poll the files over NFS; however, that's no worse than what an application would have to do if it weren't using FAM, and it still means that only one process is polling, regardless of how many are interested in the files.)

What operating systems does FAM support?

We develop primarily on Red Hat Linux and IRIX, so you should have no problems running it on one of those operating systems. FAM also runs on most GNU/Linux and BSD distributions, and should be fairly easy to port to other Unix-like operating systems as FAM uses GNU autotools.

The next major release of FAM (FAM 2.7.0) will feature a feature-based configure script rather than an operating-system based script. It is hoped that this will make it even easier to build FAM on other platforms.

If you manage to build FAM on another operating system, please let us know.

What events does FAM report?

FAM can report when a file is created, deleted, modified, or executed. See Events.h in the source code for more details.

What filesystems can FAM monitor?

FAM depends on a file monitor for local filesystems. IMon should work on any filesystem, as should polling mode in case you have no kernel monitor.

FAM also has special support for remote filesystems. If you monitor an NFS-mounted filesystem, FAM will try to get updates from a FAM running on the remote system, reducing network load.

Does FAM work without a kernel monitor?

Yes. If FAM is running on a system that doesn't have a supported kernel monitor, it polls. This isn't as efficient as using a kernel monitor, but it does mean that applications using the FAM API will continue to work, even on systems without a kernel monitor. Even when FAM has to resort to polling, it still means that there's only one process polling the filesystem, regardless of how many applications are using FAM. Without FAM, those processes would all poll.

Does FAM have any limitations?

One level: FAM was designed to monitor only one level deep. That is, if you monitor a directory, FAM will report full details of any files changing in that directory, the directory name if a file one level one level deeper changed, and nothing if the event occurs deeper than that. This makes FAM well-suited for graphical file managers (which typically only show the contents of one directory at a time) or other programs that monitor files they know the names of, but it will mean a little bit of work if you want FAM to report all changes on a file system.

Simultaneous requests: Each client process can have up to 1024 active requests. This is a limitation of the select() system call.

Does FAM have any bugs?

Rapid requests: If a client monitors a directory containing several thousand files or several hundred directories and fam is built with the DNotify patch, fam will start to use lots of CPU time and stop reporting changes. This issue has been resolved in a recent GNU C library release.

Others: As with all software, FAM probably still has bugs. If you think you've discovered one, please first check the list of known bugs. If it does not appear there, please file a new bug in SGI OSS Bugzilla. If you would like the bug resolved quickly, it is helpful to provide a reproducible test case and/or a patch that fixes the problem.


Obtaining and Requirements

Where can I obtain FAM?

FAM is now distributed as part of many Unix-like operating systems, including IRIX and several GNU/Linux and BSD distributions. If FAM is not already installed on your machine, have a look on your installation media to see if it's available.

If you'd like to have the latest official version, or your operating system does not supply it, you can download FAM and related files from the FAM download area.

What else will I need?

Portmapper: FAM uses RPC, so your system will need a portmapper.

What else might be useful?

Kernel Monitor: FAM is far more efficient if your system has a supported kernel-based file monitor such as IMon or DNotify. FAM has built-in support for IMon, and will soon officially support DNotify. Until then, you'll need to add IMon support to the Linux kernel with one of the IMon patches, or add DNotify support to FAM with the DNotify patch.

Superserver: An internet superserver such as inetd or xinetd will let your system easily start the FAM daemon on demand.

Which kernel monitor should I use?

On IRIX, use IMon.

On Linux, use DNotify if it is supported by your kernel (it's standard on Linux 2.4 and higher). Otherwise, use IMon.

On other platforms, see if a similar kernel monitor is available, and add support for it in FAM. For example, FreeBSD's kqueue feature could be used in FAM.


Building and Installing

How do I use this version of FAM on IRIX?

Please see the FAM OSS on IRIX page.

What did you do to my configuration files?

Both make install and the RPM packages generated by make rpm attempt to use a Perl script called editconf.perl to edit your inetd.conf, rpc, and ld.so.conf files if the lines they need aren't already there. (In the case of the RPM package, editconf.perl hangs around so that it can remove FAM from those files if you ever uninstall the RPM.)

The next major release of FAM (FAM 2.7.0) will remove this.

How do I make FAM work with inetd or xinetd?

FAM can be configured to spawn from either of these superservers. make install should help add the necessary line to your inetd configuration file, and it should be fairly simple to configure FAM to work with xinetd. Sample entries for each should be included in a future FAM release.

Why do I get an error about an uninitialized const member?

This error occurs when building FAM with GCC 3.x. This does not appear to be a bug in FAM, but is a very common problem. Remove the const modifier from the declaration of iotype in Scheduler.h or get the latest version of FAM.


Running and Using

Is fam secure?

Older versions of FAM had a known security weakness that allowed clients to learn the names of files and directories on the system. This version of fam does not have that problem. Connections from local clients are treated as untrusted unless the client is able to communicate over a Unix domain socket readable only by the client's claimed UID. Connections from remote clients are treated as untrusted unless they originate from a privileged port, and requests are only services if they fall on filesystems that have been exported to the requesting host. (Export verification is not currently implemented on Linux.)

How do I run fam in debug mode? Start fam with the -d command line option. This can be done by running fam -d from the command line (debug output will be sent to stderr), or by adding -d to your superserver's fam entry (debug output will usually be sent to syslog). The logging level may also be configurable in the configuration file in a future version.

Note that only one fam process can run at a time, so if your system already has an instance of fam, the second instance will not work. This means you'll have to disable fam in inetd (or at least kill all running fam processes) before running fam on the command line.

Note that running fam in debug mode will cause the fam process to stay in the foreground.

How do I enable or disable fam's networking features?

The main networking feature of fam is that it will try to connect to a remote fam if you monitor files on an NFS-mounted mount point, meaning that the local fam can wait for the remote fam to tell it when a file has changed, rather than polling files at a fixed interval over a network.

If you are concerned about excessive network traffic, you can disable polling of remote NFS servers with the -l command line option or the disable_pollster configuration file option.

If you are concerned about remote users being able to gain access to your system thru a bug in fam, you can disable listening for remote requests with the -L command line option or the local_only configuration file option. Note that this option is not obeyed if you use a superserver such as inetd. You can make fam local only via xinetd by adding this line to your fam service file: bind = 127.0.0.1. A similar option may exist in inetd.

Conversely, some systems (such as Red Hat Linux) currently ship with local only enabled by default using the above xinetd method. To enable fam's networking features in this case, remove this option from your xinetd configuration file.

How do I stop fam from dying?

There are two things fam does that might make it seem like it is dying:

Idle Timeout: fam's default behavior is to close after 5 seconds of inactivity, which is useful when it is being started from inetd. If you want to fam some other way and have it stay open indefinately, add -T 0 to your command line.

Daemonization: fam's default behavior is to background (or "daemonize") itself if your system supports this, which may give the impression that the fam process has terminated. To run fam in the foreground, add -f to your command line.

Why can't I monitor large directories?

On some systems, there are limits to the number of files or directories that can be monitored simultaneously. See the limitations section above for more information.

Why do I get logwatch messages with Service sgi_fam: no_address?

These messages are created when fam is running thru xinetd and xinetd is unable to determine the IP address of the client. This seems to occur on systems where fam is configured to only listen on the loopback device (127.0.0.1) and is not thought to be a security issue.


Miscellaneous

Who uses FAM?

FAM is used extensively under IRIX on the IRIX Interactive Desktop.

FAM is being used in Enlightenment, GNOME/Nautilus, and KDE.

Some other uses of FAM are mentioned on the links page.

What's the difference between FAM, fam, and famd?

FAM: the entire FAM system, including fam and libfam

fam: the old name for the FAM daemon

famd: the new name for the FAM daemon

Where can I get more information?

You can read the FAM documentation.

You can find FAM tutorials, sample code, bindings, and other FAM-related links on the links page.

You can post your questions to the FAM mailing list.