1.\" Copyright (c) 2012 2.\" David E. O'Brien <obrien@FreeBSD.org>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgment: 14.\" This product includes software developed by David E. O'Brien and 15.\" contributors. 16.\" 4. Neither the name of the author nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANT ABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" $FreeBSD$ 33.\" 34.Dd March 9, 2016 35.Dt FILEMON 4 36.Os 37.Sh NAME 38.Nm filemon 39.Nd the filemon device 40.Sh SYNOPSIS 41.In dev/filemon/filemon.h 42.Sh DESCRIPTION 43The 44.Nm 45device allows a process to collect file operations data of its children. 46The device 47.Pa /dev/filemon 48responds to two 49.Xr ioctl 2 50calls. 51.Pp 52.Nm 53is not intended to be a security auditing tool. 54Many syscalls are not tracked and binaries of foreign ABI will not be fully 55audited. 56It is intended for auditing of processes for the purpose of determining its 57dependencies in an efficient and easily parsable format. 58An example of this is 59.Xr make 1 60which uses this module with 61.Sy .MAKE.MODE=meta 62to handle incremental builds more smartly. 63.Pp 64System calls are denoted using the following single letters: 65.Pp 66.Bl -tag -width indent -compact 67.It Ql C 68.Xr chdir 2 69.It Ql D 70.Xr unlink 2 71.It Ql E 72.Xr exec 2 73.It Ql F 74.Xr fork 2 , 75.Xr vfork 2 76.It Ql L 77.Xr link 2 , 78.Xr linkat 2 , 79.Xr symlink 2 , 80.Xr symlinkat 2 81.It Ql M 82.Xr rename 2 83.It Ql R 84.Xr open 2 85for read 86.It Ql S 87.Xr stat 2 88.It Ql W 89.Xr open 2 90for write 91.It Ql X 92.Xr _exit 2 93.El 94.Pp 95Note that 96.Ql R 97following 98.Ql W 99records can represent a single 100.Xr open 2 101for R/W, 102or two separate 103.Xr open 2 104calls, one for 105.Ql R 106and one for 107.Ql W . 108Note that only successful system calls are captured. 109.Sh IOCTLS 110User mode programs communicate with the 111.Nm 112driver through a number of ioctls which are described below. 113Each takes a single argument. 114.Bl -tag -width ".Dv FILEMON_SET_PID" 115.It Dv FILEMON_SET_FD 116Write the internal tracing buffer to the supplied open file descriptor. 117.It Dv FILEMON_SET_PID 118Child process ID to trace. 119.El 120.Sh RETURN VALUES 121.\" .Rv -std ioctl 122The 123.Fn ioctl 124function returns the value 0 if successful; 125otherwise the value \-1 is returned and the global variable 126.Va errno 127is set to indicate the error. 128.Sh ERRORS 129The 130.Fn ioctl 131system call 132with 133.Dv FILEMON_SET_FD 134will fail if: 135.Bl -tag -width Er 136.It Bq Er EEXIST 137The 138.Nm 139handle is already associated with a file descriptor. 140.El 141.Sh FILES 142.Bl -tag -width ".Pa /dev/filemon" 143.It Pa /dev/filemon 144.El 145.Sh EXAMPLES 146.Bd -literal 147#include <sys/types.h> 148#include <sys/stat.h> 149#include <sys/wait.h> 150#include <sys/ioctl.h> 151#include <dev/filemon/filemon.h> 152#include <fcntl.h> 153#include <err.h> 154#include <unistd.h> 155 156static void 157open_filemon(void) 158{ 159 pid_t child; 160 int fm_fd, fm_log; 161 162 if ((fm_fd = open("/dev/filemon", O_RDWR | O_CLOEXEC)) == -1) 163 err(1, "open(\e"/dev/filemon\e", O_RDWR)"); 164 if ((fm_log = open("filemon.out", 165 O_CREAT | O_WRONLY | O_TRUNC | O_CLOEXEC, DEFFILEMODE)) == -1) 166 err(1, "open(filemon.out)"); 167 168 if (ioctl(fm_fd, FILEMON_SET_FD, &fm_log) == -1) 169 err(1, "Cannot set filemon log file descriptor"); 170 171 if ((child = fork()) == 0) { 172 child = getpid(); 173 if (ioctl(fm_fd, FILEMON_SET_PID, &child) == -1) 174 err(1, "Cannot set filemon PID"); 175 /* Do something here. */ 176 } else { 177 wait(&child); 178 close(fm_fd); 179 } 180} 181.Ed 182.Pp 183Creates a file named 184.Pa filemon.out 185and configures the 186.Nm 187device to write the 188.Nm 189buffer contents to it. 190.Sh SEE ALSO 191.Xr dtrace 1 , 192.Xr ktrace 1 , 193.Xr script 1 , 194.Xr truss 1 , 195.Xr ioctl 2 196.Sh HISTORY 197A 198.Nm 199device appeared in 200.Fx 9.1 . 201.Sh BUGS 202Loading 203.Nm 204may reduce system performance for the noted syscalls. 205.Pp 206Only children of the set process are logged. 207Processes can escape being traced by double forking. 208This is not seen as a problem as the intended use is build monitoring, which 209does not make sense to have daemons for. 210.Pp 211Unloading the module may panic the system, thus requires using 212.Ic kldunload -f . 213