.\"	$NetBSD: filemon.4,v 1.19 2016/01/11 06:21:23 wiz Exp $
.\"
.\" Copyright (c) 2011, Juniper Networks, Inc.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd January 6, 2016
.Dt FILEMON 4
.Os
.Sh NAME
.Nm filemon
.Nd track interesting system calls
.Sh SYNOPSIS
.Cd "pseudo-device filemon"
.Sh DESCRIPTION
In normal situations,
.Nm
is not built-in to the kernel, and a call to open
.Pa /dev/filemon
will auto-load the
.Nm
module (see
.Xr module 7
for more details).
.Pp
(Although not recommended, the
.Nm
facility can be included in a kernel build by adding
.Bd -literal -offset indent
pseudo-device filemon
.Ed
.Pp
to the kernel configuration file.)
.Pp
.Nm
provides a means for tracking the successful system calls performed by
a process and its descendants.
It is used by
.Xr make 1
to track the activities of build scripts, for the purpose of automatically
learning dependencies.
.Pp
The data captured by
.Nm
for the script
.Bd -literal -offset indent
n=`wc -l /etc/motd`; echo "int motd_lines = $n;" > foo.h.new
cmp -s foo.h foo.h.new 2> /dev/null || mv foo.h.new foo.h
.Ed
.Pp
looks like:
.Bd -literal -offset indent
# filemon version 4
# Target pid 24291
V 4
E 29676 /bin/sh
R 29676 /etc/ld.so.conf
R 29676 /lib/libedit.so.2
R 29676 /lib/libterminfo.so.1
R 29676 /lib/libc.so.12
F 29676 4899
E 4899 /usr/bin/wc
R 4899 /etc/ld.so.conf
R 4899 /usr/lib/libc.so.12
R 4899 /etc/motd
X 4899 0
W 29676 foo.h.new
X 29676 0
# Bye bye
E 3250 /bin/sh
R 3250 /etc/ld.so.conf
R 3250 /lib/libedit.so.2
R 3250 /lib/libterminfo.so.1
R 3250 /lib/libc.so.12
W 26673 /dev/null
E 26673 /usr/bin/cmp
R 26673 /etc/ld.so.conf
R 26673 /usr/lib/libc.so.12
X 26673 2
E 576 /bin/mv
R 576 /etc/ld.so.conf
R 576 /lib/libc.so.12
M 576 'foo.h.new' 'foo.h'
X 576 0
X 3250 0
# Bye bye
.Ed
.Pp
Most records follow the format:
.Bd -literal -offset indent
type pid data
.Ed
.Pp
where
.Ar type
is one of the list below, and unless otherwise specified,
.Ar data
is a pathname.
.Bl -tag -width Ds -offset indent
.It Dv C
.Xr chdir 2 .
.It Dv D
.Xr unlink 2 .
.It Dv E
.Xr exec 3 .
.It Dv F
.Xr fork 2 ,
.Xr vfork 2 ;
.Ar data
is the process id of the child.
.It Dv L
.Xr link 2 ,
.Xr symlink 2 ;
.Ar data
is two pathnames.
.It Dv M
.Xr rename 2 ;
.Ar data
is two pathnames.
.It Dv R
.Xr open 2
for read or read-write.
.It Dv W
.Xr open 2
for writing or read-write.
.It Dv X
.Xr exit 3 ;
.Ar data
is the exit status.
.It Dv V
indicates the version of
.Nm .
.El
.Pp
A
.Nm
instance is created by opening
.Pa /dev/filemon .
Then use
.Fn ioctl filemon_fd FILEMON_SET_PID &pid
to identify the target process to monitor, and
.Fn ioctl filemon_fd FILEMON_SET_FD &output_fd
to direct the event log to an already-opened output file.
.Sh FILES
.Bd -literal
/dev/filemon
.Ed
.Sh EXAMPLES
The following example demonstrates the basic usage of
.Nm :
.Pp
.Bd -literal -offset indent
#include <filemon.h>

pid_t pid;
int filemon_fd, temp_fd;
int status;

filemon_fd = open("/dev/filemon", O_RDWR);
temp_fd = mkstemp("/tmp/filemon.XXXXXXX");
/* give filemon the temp file to use */
ioctl(filemon_fd, FILEMON_SET_FD, &temp_fd);
/* children do not need these once they exec */
fcntl(filemon_fd, F_SETFD, FD_CLOEXEC);
fcntl(temp_fd, F_SETFD, FD_CLOEXEC);

pid = fork();
switch(pid) {
 case -1:
     err(1, "cannot fork");
     break;
 case 0:
     pid = getpid();
     /* tell filemon to monitor this process */
     ioctl(filemon_fd, FILEMON_SET_PID, &pid);
     execvp(...);
     _exit(1);
     break;
 default:
     status = wait();
     close(filemon_fd);
     lseek(temp_fd, SEEK_SET, 0);
     /* read the captured syscalls from temp_fd */
     close(temp_fd);
     break;
}
.Ed
.Pp
The output of
.Nm
is intended to be simple to parse.
It is possible to achieve almost equivalent results with
.Xr dtrace 1
though on many systems this requires elevated privileges.
Also,
.Xr ktrace 1
can capture similar data, but records failed system calls as well as
successful, and is thus more complex to post-process.
.Sh HISTORY
.Nm
was contributed by Juniper Networks.
.Sh SECURITY CONSIDERATIONS
If the monitored process exits, and its pid gets reused,
.Nm
will continue to report events for the new process (and its
descendants) without any authorization checks.
.Pp
Monitoring of a process enables the target process to write to the
tracking process's file descriptor.
.Sh RESTRICTIONS
The
.Nm
facility can only be used to track processes running in the system's
native emulation.
Neither processes using any of the
.Dv COMPAT_xxx
compatibility layers nor
any descendants of such processes can be tracked.
.Pp
If two processes are monitored, and one is a descendant of the other, events
related to the descendant process and its further descendants are delivered
only to the descendant process's monitor.
If a process is being monitored by two instances of
.Nm ,
events will be delivered only to the first instance created (when
.Pa /dev/filemon
was opened), regardless of the order in which the monitoring processes
called
.Fn ioctl fd FILEMON_SET_PID pid .