diff options
Diffstat (limited to '00DCACHE')
-rw-r--r-- | 00DCACHE | 745 |
1 files changed, 745 insertions, 0 deletions
diff --git a/00DCACHE b/00DCACHE new file mode 100644 index 0000000..58747b2 --- /dev/null +++ b/00DCACHE @@ -0,0 +1,745 @@ + + Configuring The Device Cache File Path + + Contents + + A. Introduction and History + B. Device Cache File Format + 1. Integrity Checks + 2. The Setgid and Setuid-root States + C. Device Cache File Path Options + 1. Path Named by ``-D'' + 2. Path Named in Environment Variable + 3. Default System-wide Path + a. Build Procedure + 4. Default Personal Path + 5. Modified Default Personal Path + D. Displaying the Default Path + Appendix A, Unix Dialects Without a Device Cache + Appendix B, Lsof Dialects and Their Permissions + 1. Setuid-root Lsof Dialects + 2. Setgid Lsof Dialects That Surrender Setgid + Permission + + +A. Introduction and History +=========================== + +Lsof writes a file of information about the contents of the nodes +in /dev (or /devices) to reduce its startup overhead on later calls. +It does this for all Unix dialects, except those noted in Appendix A. + +This file, called the device cache file, enables lsof to avoid +calling the kernel stat(2) function on every node in /dev (or +/devices) from which it builds a table of correspondence between +major/minor device numbers and device names. + +A full scan of /dev (or /devices) on some systems may involve +calling the sometimes-slow stat(2) function 10,000 times or more. +Furthermore, each stat(2) call consumes space in the kernel's name +cache, forcing from it path name components that would be more +useful when lsof tries to associate them with open files. + +While it's hard to question the usefulness of the device cache, +it's also hard to decide where it should be written. When the +feature was first added, the device cache file was written to /tmp, +and its ownership was set to that of the real user ID (UID) under +which the creating lsof process was run. However, to enable any +process to update it when /dev (or /devices) changed, lsof set its +modes to 0666, thus allowing anyone to read or write it. + +The writing of a world-readable and world-writable device cache +file to any place has security weaknesses. A clever intruder who +carefully preserves the integrity of the file might be able to +remove devices that would prevent lsof from observing the intruder's +files. A clever intruder might also be able to put a symbolic link +in place and trick lsof into writing to the link's destination with +its effective permissions, thus bypassing the real user's (possibly +weaker) permissions. + +Later the location of the device cache file was changed. It was +converted to a personal file, located in the home directory of each +real UID that executed lsof, and owned by that UID. Thus it was +no longer possible for one user to affect lsof's access to the +device cache file, nor was it possible for a user to mount a symbolic +link attack on a restricted file, but the result was that each lsof +user had a private copy of the device cache file. + +The device cache file feature has undergone some further refinements +in path name formation to reach its present state. This documentation +describes the path name formation options open to the lsof builder +and user after those refinements, and how lsof attempts to insure +that none of the options presents a security risk. + + +B. Device Cache File Format +=========================== + +The device cache file is a flat file of ASCII text. It has an +initial statement of how many sections the file might contain -- +the possible sections are character devices, block devices, clone +devices, pseudo devices, and checksum. The character devices and +checksum sections are always present. + +Each section has a header that numbers the entries in the section. + +The last section is a checksum section that contains a 16 bit cyclic +redundancy (CRC) checksum of everything in the file but the checksum +section itself. + +Lsof always sets the permission modes of the device cache file to +0600, and the owner to the real UID of the process that executes +lsof; the group, the real group ID (GID) of the lsof process. + +Setting the permission modes to 0600 means that a system-wide device +cache file won't be usable unless the procedure that builds it +changes the modes after lsof has written it. A suitable procedure +for building a system-wide device cache that shows how to adjust +these inadequate permission modes is given in the Default System-wide +Path section. + + +B.1. Integrity Checks +===================== + +When lsof opens the device cache file it makes these integrity +checks: + + 1. Lsof must gain permission from access(2) to be able to + open the file for reading. If lsof is writing the file, + it usually cedes permission control to the applicable + directory and file modes and ownerships. (Some additional + checks apply and they're described in the sections on path + options.) + + By explicit design lsof never writes to the system-wide + device cache file, even when the real UID of its process + is root. The system-wide device cache file must be written + with a root-owned procedure via the ``-D[b|u<path>'' options + -- i.e., under the system administrator's control. (See + the Build Procedure sub-section of the Default System-wide + Path section.) + + 2. The device cache file's modes must be 0600 (0644 if lsof + is reading a system-wide device cache file) and its size + must be non-zero. + + 3. There must be a correctly formatted section count line + at the beginning of the file. + + 4. Each section must have a header line with a count that + properly numbers the lines in the section. The first words + of legal section titles are "device", "block", "clone", + "pseudo", and "CRC". + + 5. The lines of a section must have the proper format. + + 6. All lines are included in a 16 bit CRC, and it is recorded + in a non-checksummed section line at the end of the file. + + 7. The checksum computed when the file is read must match the + checksum recorded when the file was written. + + 8. The checksum section line must be followed by end-of- + information. + + 9. Lsof must be able to get matching results from stat(2) + on a randomly chosen entry of the device section. + + +B.2. The Setgid and Setuid-root States +====================================== + +There are two fundamental ways in which lsof is granted access to +restricted system resources. Both access methods are related to the +effective permissions given the lsof binary or executable. + +The first and preferable way to grant lsof access to system resources +through the permissions endowed on its executable is the giving of +set group ID (setgid) permission. The group is the one that has +permission to read the kernel memory and swap devices -- e.g., /dev/kmem, +/dev/mem, /dev/swap, etc. + +This method of granting access is called setgid mode because it +enables lsof to run with an effective group ID set to the one +granted by the permissions of its executable file and by the group +that owns the executable file. See the getegid(2) man page for a +further discussion of effective group ID. + +Usually lsof only needs setgid permission to open access to the +kernel memory files. After they're open, lsof drops its setgid +permission. + +The second and least preferable way to grant lsof access to system +resources through the permissions endowed on its executable is the +giving of set user ID to root (setuid-root) permission. This is +much too strong a permission, but necessary: to use the -X option +fully for the version of lsof for AIX 5 and above; to use the +version of lsof for HP-UX 11.11 and above; and to use the version +of lsof for Linux 2.1.72 and above. These lsof implementations +require setuid-root permission to be able to access restricted +resources -- e.g., the individual files of the /proc file system. +(But note that the setuid-root Linux lsof doesn't need and has no +device cache support.) + +Lsof never drops setuid-root permission, because it needs that +power throughout its execution. However, when the lsof process is +setuid-root, lsof disallows these device cache file path options: + + 1. It ignores the ``-D[b|r|u]<path>'' options. It accepts + only the ``-Di'' and ``-Dr'' options. + + 2. It refuses to recognize a path supplied via an environment + variable. + + 3. It refuses to accept an additional path component from an + environment variable to be inserted in the middle of a + personal device cache file path. + +Each restriction is imposed because setuid-root power might allow +a malicious user to form a device cache file path that would give +read access to a normally inaccessible place (That's bad enough.), +or write access to a critical system file (That's the worst case.) + +There is one further state that lsof can enter that is slightly +different from the setuid-root and setgid states. That state occurs +when lsof is being run from a root shell -- i.e., the lsof real +user ID is root. To avoid accidental complications, when lsof is +in this state, it ignores all environment variable options. + +In the rest of this document you will find more detailed discussion +of the special restrictions caused by the type of permission that +has been given the lsof executable. + + +C. Device Cache File Path Options +================================= + +Lsof offers five options for constructing the path to the device +cache file. Each has special conditions and safeguards that +surround its use. The options are: + + 1. A device cache file that is named in the <path> component + of the parameters of lsof's ``-D'' option. + + ========================================================= + * This is a default option of the lsof distribution. * + * * + * Paths specified with this option are read-only unless * + * the real UID of the lsof process is root (0), or the * + * lsof process is able to surrender setgid permission * + * (See Appendix B) and it is not setuid-root. * + ========================================================= + + 2. A device cache file whose name is specified by an environment + variable. + + ========================================================= + * This is a default option of the lsof distribution. * + * * + * This option is enabled when the lsof dialect is able * + * to surrender setgid permission (See Appendix B.), and * + * the lsof process is not setuid-root. * + * * + * The environment variable path is read-only if the * + * lsof process does not surrender setgid permission * + * (See Appendix B.) * + ========================================================= + + 3. A system-wide default device cache file, located at a path + determined by the builder of lsof. The lsof builder is also + responsible for building the device cache file, using a + different lsof path formation option at a suitable time -- + e.g., when the system is booted. + + ========================================================= + * This is option is disabled by default in the lsof * + * distribution. * + * * + * The path specified with this option is read-only. * + ========================================================= + + 4. A default personal device cache file, located in the UID's + home directory. + + ========================================================= + * This is a default option of the lsof distribution. * + ========================================================= + + 5. A personal device cache file whose name is modified by an + environment variable. + + ========================================================= + * This is a default option of the lsof distribution. * + * * + * The modified personal path is read-only if the lsof * + * process does not surrender setgid permission. * + * * + * This option is disabled when the lsof process is * + * setuid-root or its real UID is root (0). * + ========================================================= + +When there are multiple choices for the device cache file path, +lsof chooses from the above list in the order the list is given, +subject to restrictions based on the effective group and user IDs +that are in effect. + +Each possible path name is discussed in a later section that +describes the restrictions that apply to it and the method for +building lsof to use it. + +In one special case lsof will use two paths in order. When a +system-wide device cache file is enabled, and lsof finds that it +doesn't exist, lsof will attempt to use a personal device cache +file. + + +C.1. Path Named by ``-D'' +========================= + +The ``-D[b|r|u]<path>'' option can name a path for the device cache +file where it is unconditionally built (`b'); read, but never +rebuilt (`r'); and read and rebuilt, if necessary (`u'). + +If the lsof process is setuid-root, no path may be specified with +the ``-D'' option -- i.e., only the `i' function is accepted. The +`r' option may be used if it doesn't have a path argument. + +If the lsof process is not setuid-root, nor is the real UID of the +lsof process root, a path may accompany the `b', `r', and `u' +functions if the lsof process surrenders setgid permission. (See +Appendix B.) If the process doesn't surrender setgid permission, +then a path may accompany only `r'. + +Lsof's permission to access a device cache file at a path specified +with ``-D[b|r|u]<path>'' depends completely on the permission modes +and ownerships of the file and its directory components. + +When the real UID of the lsof process is root (0), paths may be +specified with ``-D[b|r|u]''. + +==================================================================== +* * +* The ``-D[b|r|u]<path>'' option is enabled by default in the lsof * +* distribution by the following definition in the dialect's * +* machine.h header file: * +* * +* #define HASDCACHE 1 * +* * +* To disable all device cache file options, including all ``-D'' * +* forms, change the above line in the dialect's machine.h file to: * +* * +* /* #define HASDCACHE 1 */ * +* * +* or remove it. * +* * +* The ``-D[b|r|u]<path>'' options are disabled when the lsof * +* process is setuid-root. If the lsof process isn't setuid-root, * +* nor is its real UID root (0), and if the lsof process surrenders * +* setgid permission, ``-D[b|r|u]'' may be accompanied by a path. * +* * +* A path may accompany ``-D[b|u]'' when the real UID of the lsof * +* process is root. * +* * +* ``-Dr'' without a path name argument is always acceptable. * +* * +==================================================================== + + +C.2. Path Named in Environment Variable +======================================= + +A device cache file path may be declared in an environment variable. +This option is defined in the dialect's machine.h header file with +the HASENVDC definition. The value of the HASENVDC definition is +the environment variable's name. + +Lsof will use the value of the environment variable named by HASENVDC +for the device cache file path unless either of the following +conditions apply: + + 1. The lsof process is in the setuid-root state. +or + 2. The effective and real UIDs of the lsof process are root + (0). + +Lsof uses the value of the HASENVDC environment variable as the +device cache file path after it senses there is no path declared by +a ``-D'' option. + +A path from an environment variable is read-only unless the lsof +process surrenders setgid permission. (See Appendix B.) + +==================================================================== +* * +* The path name environment variable option is enabled by default, * +* and the environment variable is named LSOFDEVCACHE in the lsof * +* distribution by the following definition in the dialect's * +* machine.h header file: * +* * +* #define HASENVDC "LSOFDEVCACHE" * +* * +* To disable the path name environment variable option, change * +* the above line in the dialect's machine.h header file to: * +* * +* /* #define HASENVDC "LSOFDEVCACHE" */ * +* * +* or remove it. To change the name of the environment variable, * +* change the quoted value of the HASENVDC definition -- e.g., this * +* form changes the environment variable name to "FOOBAR": * +* * +* #define HASENVDC "FOOBAR" * +* * +* You can disable the path name environment option by disabling * +* all device cache file processing when you remove or by disabling * +* the HASDCACHE definition in the dialect's machine.h header file. * +* * +* The path name environment option is disabled when the lsof * +* process is setuid-root or when the real UID of the lsof process * +* is root (0). * +* * +* The path named in an environment variable is read-only unless * +* the lsof process surrenders setgid permission. (See Appendix * +* B.) * +* * +==================================================================== + + +C.3. Default System-wide Path +============================= + +When a default system-wide device cache file path is defined (It's +not enabled by default in the lsof distribution.), lsof will use +it after it discovers no path has been specified by a ``-D'' option +and no path has been specified in the environment variable named +in the string #define HASENVDC of the dialect's machine.h header +file. + +Lsof must be able to open the system-wide device cache file -- +i.e., it must have read access to the file and search access to +the directories that lead it. As part of its integrity checks, +lsof requires that the system-wide device cache file's permission +modes be 0644. + +When lsof discovers that the named system-wide device cache file +doesn't exist, it will attempt to open a personal device cache file +should that path formation option be enabled. This is the *only* +case where lsof will attempt to use two device cache file paths. + +The system-wide device cache file is read-only; lsof will never +attempt to write to it. However, when the real UID of the lsof +process is root, that process may name the system-wide device +cache file with ``-D[b|u]<path>''. + +==================================================================== +* * +* The system-wide file path option is disabled by default in the * +* lsof distribution. This place-marking definition in a dialect's * +* machine.h header file may be altered to enable a system-wide * +* device cache file path: * +* * +* /* #define HASSYSDC "/your/choice/of/path" */ * +* * +* To enable the system-wide name option, declaring that its path * +* is ``/foo/bar/lsof.dc'', change the above line in the dialect's * +* machine.h header file to: * +* * +* #define HASSYSDC "/foo/bar/lsof.dc" * +* * +* or change the quoted string of the definition to the path of * +* your choice. * +* * +* You can disable the path name environment option by disabling * +* all device cache file processing when you remove or disable the * +* HASDCACHE definition in the dialect's machine.h header file. * +* * +* The system-wide device cache file is read-only. * +* * +==================================================================== + + +C.3.a. Build Procedure +====================== + +The system administrator must build the system-wide device cache +file at an appropriate time -- e.g., each time the system is booted, +and each time a node is added, deleted or modified in /dev (or +/devices). The procedure that builds the system-wide device cache +file must use lsof's ``-D[b|u]<path>'' options to build the file, +and must change the file's permission modes to 0644 after it has +been built. + +Here's a simple shell script procedure to build a system-wide device +cache file. It assumes: + + 1. The Unix dialect's kernel supports the interpreter script + execution option -- i.e., a script whose first line has + the form ``#!<path_to_interpreter>''. + + 2. The chmod, echo, rm, sh, and test programs are located + in ``/bin''. + + 3. The string value of the HASSYSDC definition in the dialect's + machine.h header file is the path ``/your/choice/of/path''. + + 4. The lsof executable is located in ``/usr/local/etc''. + + #!/bin/sh + # + # Simple script to build a system-wide device cache file + # for lsof. + + HASSYSDC=/your/choice/of/path + /bin/rm -f $HASSYSDC + /usr/local/etc/lsof -Du$HASSYSDC > /dev/null 2>&1 + if /bin/test $? -ne 0 + then + /bin/echo "WARNING: failed to create $HASSYSDC" + exit 1 + fi + /bin/chmod 0644 $HASSYSDC + exit 0 + +The invocation of lsof uses the ``-Du$HASSYSDC'' option to read +the device cache file and recreate it if necessary. The invocation +can be made more efficient if a known process PID -- e.g., ``-p1'' +-- can be specified. However, if that PID is not always active +when lsof is called, lsof might set its exit code non-zero, causing +the subsequent test to believe that the lsof call failed. When in +doubt, omit the PID specification and accept the extra lsof processing +time for reporting and discarding all open file information. + + +C.4. Default Personal Path +========================== + +The default personal path option is defined by default in the lsof +distribution. The path is formed of the home directory of the real +UID of the lsof process, followed optionally by the contents of +the HASPERSDCPATH environment variable, followed by ``.lsof_'', +followed by the first component (characters up to the first period) +of the name returned by gethostname(2). + +If gethostname(2) returns nothing, then nothing will follow the +``.lsof_'' string. If the first character of what gethostname(2) +returns is a `.', then all the gethostname(2) value will follow +the ``/lsof_'' string. (See the ``%l'' conversion for a way to +make lsof include the entire host name in the path.) + +==================================================================== +* * +* The personal path option is enabled by default in the lsof * +* distribution. The HASPERSDC #define in a dialect's machine.h * +* header is a format specification that tells lsof how to form the * +* personal device cache file path. The conversions in the format * +* specification begin with `%' , ala the printf(3) function of the * +* standard I/O library. These conversions are supported: * +* * +* ``%%'' causes a single `%' to appear in the path. * +* * +* ``%0'' is a separator that marks the beginning of a path * +* for a setuid-root lsof process or one whose real * +* UID is 0. When lsof reaches this conversion and * +* the process is setuid-root or has a real UID of * +* root, it erases any previously formed path and * +* restarts with the next HASPERSDC format character. * +* If lsof reaches this conversion and the process is * +* not setuid-root and its real UID is not root, path * +* formation is ended. * +* * +* ``%h'' causes the home directory of the real UID of the * +* lsof process to appear in the path. * +* * +* ``%l'' causes the full name returned by gethostname(2) to * +* appear in the path. * +* * +* ``%L'' causes the first component of the name returned by * +* gethostname(2) to appear in the path. The first * +* component is defined to be what appears to the * +* left of the first `.'. If nothing appears to the * +* left then everything will appear in the path. * +* * +* ``%p'' causes the value of (HASPERSDCPATH) from the * +* process environment to appear in the path. If the * +* (HASPERSDCPATH) value doesn't end in a '/', one * +* will be added. * +* * +* ``%u'' causes the login name associated with the real UID * +* of the lsof process to appear in the path. * +* * +* ``%U'' causes the real UID of the lsof process, converted * +* to a decimal string, to appear in the path. * +* * +* All other characters are copied from the format to the * +* path. CAUTION: THINK VERY CAREFULLY ABOUT THE EFFECT OF * +* USING CHARACTERS THAT FORM AN ABSOLUTE COMPONENT LIKE * +* ``/tmp'' IN THE FORMAT. Consider what power your dialect * +* might have (e.g., if it is setuid-root) when lsof must * +* create a device cache file at the path. Consider using a * +* ``%0'' conversion to declare an alternate path for lsof * +* processes that are setuid-root or whose real uid is root. * +* See the "How do I put the personal device cache file in * +* /tmp?" question and answer in 00FAQ for an explanation of * +* this example: * +* * +* #define HASPERSDC "/tmp/.lsof_%u_%l_pers%0%h/.lsof_%L" * +* * +* This is the format specification that appears in the machine.h * +* header files of the lsof distribution: * +* * +* #define HASPERSDC "%h/%p.lsof_%L" * +* * +* It causes the path to be formed from the home directory of the * +* real UID of the lsof process (``%h''), followed by `/', followed * +* by the contents of the environment variable named by * +* HASPERSDCPATH and a trailing `/', as needed (``%p''), followed * +* by the string ``.lsof_'', and terminated with the first * +* component of the host's name (``%L''). * +* * +* To change the personal path option, change the HASPERSDC string * +* and recompile lsof. To disable the personal path option, remove * +* or disable HASPERSDC. The personal path option is disabled when * +* HASDCACHE is not defined. * +* * +==================================================================== + + +C.5. Modified Default Personal Path +=================================== + +The modified default personal path form is a special case of the +default personal path. In this form the value of the environment +variable named by the HASPERSDCPATH #define is inserted in the +personal path when the ``%p'' conversion appears in the HASPERSDC +format specification. + +This allows, for example, the lsof user to move personal device +cache files to another branch of the home directory, perhaps to a +sub-directory where multiple device cache files may appear from +different machines that use the same NFS- mounted home directory. + +The HASPERSDCPATH definition of the dialect's machine.h header file +names the environment variable. By default in the lsof distribution +it is LSOFPERSDCPATH. + +The modified personal path component is ignored when lsof process +is setuid-root is root, lest it be maliciously or accidentally used in +some convoluted form to access paths the real UID cannot. The +modified personal path component is also ignored when the real UID +of the lsof process is root (0), so that lsof will not accidentally +use a personal environment value. + +If the lsof process surrenders setgid permission (See Appendix B.), +lsof can read from and write to the modified personal path. If, +however, the lsof process doesn't surrender setgid permission, the +modified personal path is read-only. + +If your dialect runs setuid-root or doesn't surrender its setgid +permission, and you want to use the LSOFPERSDCPATH environment +variable to address a collection of device cache files in a +subdirectory, you will have to gather the collection in the +subdirectory yourself with shell copy or move commands. + +==================================================================== +* * +* The modified personal path option is enabled by default in the * +* lsof distribution with these definitions in the dialect's * +* machine.h header file: * +* * +* #define HASPERSDCPATH "LSOFPERSDCPATH" * +* and * +* #define HASPERSDC "%h/%p.lsof_%L" * +* * +* The value of the definition is the name of the environment * +* variable that contains the modified personal path name * +* component that is inserted in the personal path when ``%p'' * +* appears in HASPERSDC. See the Default Personal Path section * +* for a complete description of the ``%p'' conversion. * +* * +* To disable the modified personal path name component, disable * +* the HASPERSDCPATH definition in the dialect's machine.h header * +* file -- e.g., change it to: * +* * +* /* #define HASPERSDCPATH "LSOFPERSDCPATH" */ * +* * +* or remove the definition altogether. If you do this, don't * +* forget to remove any ``%p'' conversion from HASPERSDC. * +* * +* The modified personal path option is disabled when HASDCACHE is * +* not defined. * +* * +* The modified personal path environment variable value is ignored * +* when the lsof process is setuid-root or when the real UID of * +* the lsof process is root (0). * +* * +* The modified personal path is read-only when the lsof process * +* doesn't surrender its setgid permission. * +* * +==================================================================== + + +D. Displaying the Default Path +============================== + +Whatever device cache file path formation options you decide to +use, remember that the lsof help output, displayed in response to +its ``-h'' or ``-?'' help options, will display the read-mode +default (the highest numbered) path that lsof has been enabled to +form from which it will read. + +Since some paths are read-only, the path displayed in help option +output may not be the one to which lsof will write, should that +become necessary. To see the read-only and write device cache file +paths, environment variable names, and the personal device cache +file format specification (HASPERSDC), use the -D? option. + + +Appendix A, Unix Dialects Without a Device Cache +================================================ + +Linux lsof implementations that obtain their information from files +in the /proc file system do not have device cache support. Generally +lsof for Linux versions 2.1.72 and greater are /proc based. + + +Appendix B, Lsof Dialects and Their Permissions +=============================================== + +These are the permissions recommended in the lsof distribution. + + +Appendix B.1 Setuid-root Lsof Dialects +====================================== + +These dialect versions of lsof need root permission. For general +use they may have to be installed setuid-root. + + Apple Darwin 9 and Mac OS X 10.[567] + HP-UX 11.11 and 11.23 + Linux (no device cache support needed) + + +Appendix B.2 Setgid Lsof Dialects That Surrender Setgid Permission +================================================================== + +Lsof versions for these dialects have WILLDROPGID defined in their +machine.h header files. + + AIX 5.[12] and 5.3-ML1 + FreeBSD 4.x, 4.1x, 5.x and [6789].x for x86-based systems + FreeBSD 5.x, [6789].x fnd 10.xor Alpha, AMD64 and Sparc64-a + based systems + HP-UX 11.00 + NetBSD 1.[456], 2.x and 3.x for Alpha, x86, and SPARC-based + systems + NEXTSTEP 3.[13] + OpenBSD 2.[89] and 3.[0-9] for x86-based systems + OPENSTEP 4.x + SCO OpenServer Release 5.0.4 for x86-based systems + SCO|Caldera UnixWare 7.1.4 for x86-based systems + Solaris 2.6, 8, 9 and 10 + Tru64 UNIX 5.1 + + +Vic Abell <abe@purdue.edu> +April 10, 2012 |