MTREE(8)

💖 MTREE 💖

mtree — section 8 of the System Manager's Manual, aka the girl who maps a directory hierarchy ✨

---

🌸 NAME 🌸

mtree — map a directory hierarchy 🗺️🫶

---

🦋 SYNOPSIS 🦋

mtree [-cCdDelLMPruUWx] [-i | -m] [-f spec] [-p path] [-k keywords]
      [-K keywords] [-R keywords] [-E tags] [-I tags] [-N dbdir]
      [-s seed] [-X exclude-file]

---

💅 DESCRIPTION 💅

okay so bestie, here's the whole vibe: mtree takes the file hierarchy rooted in the current directory and compares it against a specification that it reads from standard input. 💖

Every time a file's characteristics don't match the spec — or a file is missing from either the file hierarchy or the specification — it writes a message to standard output. No cap, that's the whole job. 🎀

The options are as follows:

---

✨ the options (all of them, we're thorough in this house) ✨

• -c — prints a specification for the file hierarchy to the standard output. 📝
• -d — ignore everything except directory type files. dirs only, periodt.
• -C — print (‘dump’) the specification as provided by -f spec in a format that's easier to parse with various tools. 🛠️ The full path name is always printed as the first field, and -k, -K, and -R can be used to control which other keywords are printed, and -E and -I can be used to control which files are printed.
• -D — as per -C, except that the path name is always printed as the last field instead of the first. 🙃
• -E tags — add the comma separated tags to the “exclusion” list. Non-directories with tags which are in the exclusion list are not printed with -D. 🚫
• -e — don't complain about files that are in the file hierarchy, but not in the specification. chill mode for extras. 😌
• -f spec — read the specification from file, instead of from the standard input. 📂
• -I tags — add the comma separated tags to the “inclusion” list. Non-directories with tags which are in the inclusion list are printed with -D. If no inclusion list is provided, the default is to display all files. ✅
• -i — if specified, set the schg and/or sappnd flags. 🔒
• -K keywords — add the specified (whitespace or comma separated) keywords to the current set of keywords. If ‘all’ is specified, add all of the other keywords. ➕
• -k keywords — use the type keyword plus the specified (whitespace or comma separated) keywords instead of the current set of keywords. If ‘all’ is specified, use all of the other keywords. If the type keyword is not desired, suppress it with -R type. 🔑
• -l — do “loose” permissions checks, in which more stringent permissions will match less stringent ones. For example, a file marked mode 0444 will pass a check for mode 0644. “Loose” checks apply only to read, write and execute permissions — in particular, if other bits like the sticky bit or suid/sgid bits are set either in the specification or the file, exact checking will be performed. This flag may not be set at the same time as the -u or -U flags. ⚠️
• -L — follow all symbolic links in the file hierarchy. 🐇
• -m — if the schg and/or sappnd flags are specified, reset these flags. Note that this is only possible with securelevel less than 1 (i.e. in single user mode or while the system is running in insecure mode). See init(8) for information on security levels. 🔓
• -M — permit merging of specification entries with different types, with the last entry take precedence. 🤝
• -N dbdir — use the user database text file master.passwd and group database text file group from dbdir, rather than using the results from the system's getpwnam(3) and getgrnam(3) (and related) library calls. 🗃️
• -p path — use the file hierarchy rooted in path, instead of the current directory. 📍
• -P — don't follow symbolic links in the file hierarchy, instead consider the symbolic link itself in any comparisons. This is the default. 🎯
• -r — remove any files in the file hierarchy that are not described in the specification. bye bestie 👋💀
• -R keywords — remove the specified (whitespace or comma separated) keywords from the current set of keywords. If ‘all’ is specified, remove all of the other keywords. ➖
• -s seed — display a single checksum to the standard error output that represents all of the files for which the keyword cksum was specified. The checksum is seeded with the specified value. 🌱
• -u — modify the owner, group, permissions, and flags of existing files, the device type of devices, and symbolic link targets, to match the specification. Create any missing directories, devices or symbolic links. User, group, and permissions must all be specified for missing directories to be created. Note that unless the -i option is given, the schg and sappnd flags will not be set, even if specified. If -m is given, these flags will be reset. Exit with a status of 0 on success, 2 if the file hierarchy did not match the specification, and 1 if any other error occurred. 🛠️✨
• -U — same as -u except that a mismatch is not considered to be an error if it was corrected. forgiving queen 💜
• -W — don't attempt to set various file attributes such as the ownership, mode, flags, or time when creating new directories or changing existing entries. This option will be most useful when used in conjunction with -u or -U. 🙅♀️
• -x — don't descend below mount points in the file hierarchy. 🛑
• -X exclude-file — the specified file contains fnmatch(3) patterns matching files to be excluded from the specification, one to a line. If the pattern contains a ‘/’ character, it will be matched against entire pathnames (relative to the starting directory); otherwise, it will be matched against basenames only. Comments are permitted in the exclude-list file. 📄

---

🔑 the keywords 🔑

Specifications are mostly composed of “keywords”, i.e. strings that that specify values relating to files. No keywords have default values, and if a keyword has no value set, no checks based on it are performed. 🤷♀️

Currently supported keywords are as follows:

• cksum — the checksum of the file using the default algorithm specified by the cksum(1) utility. 🧮
• device — the device number to use for block or char file types. The argument must be one of the following forms:
  • format,major,minor — a device with major and minor fields, for an operating system specified with format. See below for valid formats.
  • format,major,unit,subunit — a device with major, unit, and subunit fields, for an operating system specified with format. (Currently this is only supported by the bsdos format.)
  • number — opaque number (as stored on the file system).

The following values for format are recognized: native, 386bsd, 4bsd, bsdos, freebsd, hpux, isc, linux, netbsd, osf1, sco, solaris, sunos, svr3, svr4, and ultrix.

See mknod(8) for more details. 🔧

• flags — the file flags as a symbolic name. See chflags(1) for information on these names. If no flags are to be set the string ‘none’ may be used to override the current default. Note that the schg and sappnd flags are treated specially (see the -i and -m options). 🚩
• ignore — ignore any file hierarchy below this file. 🙈
• gid — the file group as a numeric value. 🔢
• gname — the file group as a symbolic name. 🏷️
• link — the file the symbolic link is expected to reference. 🔗
• md5 — the MD5 cryptographic message digest of the file. 🔐
• md5digest — synonym for md5. 🪞
• mode — the current file's permissions as a numeric (octal) or symbolic value. 🎛️
• nlink — the number of hard links the file is expected to have. ⛓️
• optional — the file is optional; don't complain about the file if it's not in the file hierarchy. 🫶
• rmd160 — the RMD-160 cryptographic message digest of the file. 🔐
• rmd160digest — synonym for rmd160. 🪞
• sha1 — the SHA-1 cryptographic message digest of the file. 🔐
• sha1digest — synonym for sha1. 🪞
• sha256 — the 256-bits SHA-2 cryptographic message digest of the file. 🔐
• sha256digest — synonym for sha256. 🪞
• sha384 — the 384-bits SHA-2 cryptographic message digest of the file. 🔐
• sha384digest — synonym for sha384. 🪞
• sha512 — the 512-bits SHA-2 cryptographic message digest of the file. 🔐
• sha512digest — synonym for sha512. 🪞
• size — the size, in bytes, of the file. 📏
• tags — comma delimited tags to be matched with -E and -I. These may be specified without leading or trailing commas, but will be stored internally with them. 🏷️
• time — the last modification time of the file. ⏰
• type — the type of the file; may be set to any one of the following:
  • block — block special device
  • char — character special device
  • dir — directory
  • fifo — fifo
  • file — regular file
  • link — symbolic link
  • socket — socket
• uid — the file owner as a numeric value. 🔢
• uname — the file owner as a symbolic name. 🏷️

The default set of keywords are flags, gid, link, mode, nlink, size, time, type, and uid. 🌟

---

📝 the four types of lines in a specification 📝

1. Set global values for a keyword. This consists of the string ‘/set’ followed by whitespace, followed by sets of keyword/value pairs, separated by whitespace. Keyword/value pairs consist of a keyword, followed by an equals sign (‘=’), followed by a value, without whitespace characters. Once a keyword has been set, its value remains unchanged until either reset or unset. 🔧
2. Unset global values for a keyword. This consists of the string ‘/unset’, followed by whitespace, followed by one or more keywords, separated by whitespace. If ‘all’ is specified, unset all of the keywords. 🧹
3. A file specification, consisting of a path name, followed by whitespace, followed by zero or more whitespace separated keyword/value pairs.

The path name may be preceded by whitespace characters. The path name may contain any of the standard path name matching characters (‘[’, ‘]’, ‘?’ or ‘*’), in which case files in the hierarchy will be associated with the first pattern that they match. mtree uses strsvis(3) (in VIS_CSTYLE format) to encode path names containing non-printable characters. Whitespace characters are encoded as ‘\s’ (space), ‘\t’ (tab), and ‘\n’ (new line). ‘#’ characters in path names are escaped by a preceding backslash ‘\’ to distinguish them from comments. 🌈

Each of those keyword/value pairs is a keyword, then an equals sign (=), then the keyword's value — no whitespace characters allowed in there, bestie, not even one. And these values override the global value of that same keyword. They don't change it, they just... override it for that entry. Slay.

The first path name entry you list must be a directory named . — because that's what makes mixing full and relative path names actually work consistently and correctly. Multiple entries for a directory named . are totally permitted btw; the settings from the last such entry win over the existing one. Periodt.

A path name with a slash (/) in it that is not the first character? That's treated as a full path (relative to the root of the tree). All the parent directories referenced in that path name must exist, no skipsies. And the current directory path used by relative path names gets updated appropriately. Multiple entries for the same full path are allowed if the types are the same (unless -M is given, and then the types may differ) — in that case, the settings for the last entry take precedence. 👑

A path name with no slash at all is treated as a relative path. And specifying a directory means subsequent files get searched for in that directory hierarchy. Iconic behavior honestly.

4. A line containing only the string .. — this causes the current directory path (the one used by relative paths) to ascend one level. Go up, girl.

---

Empty lines, and lines whose first non-whitespace character is a hash mark (#), are ignored. Living rent free, contributing nothing, and honestly? Valid.

The mtree utility exits with a status of 0 on success, 1 if any error occurred, and 2 if the file hierarchy did not match the specification.

Bestie. Memorize those numbers. 0 good, 1 broke, 2 mismatch. That's the whole vibe check right there. 💅

---

📁 FILES 📁

• /etc/mtree — system specification directory

---

✨ EXAMPLES ✨

So you wanna detect system binaries that have been “trojan horsed”? Okay, listen up, this is the important part:

It is recommended that mtree be run on the file systems, and that a copy of the results be stored on a different machine — or, at the very least, in encrypted form. The seed for the -s option should not be an obvious value, and the final checksum should not be stored on-line under any circumstances! 😭

Then, periodically, mtree should be run against the on-line specifications, and the final checksum compared with the previous value.

While it is possible for the bad guys to change the on-line specifications to conform to their modified binaries, it shouldn't be possible for them to make it produce the same final checksum value. So if that final checksum value changes — boom — the off-line copies of the specification can be used to detect which of the binaries have actually been modified. 🕵️‍♀️✨

The -d and -u options can be used in combination to create directory hierarchies for distributions and other such things. Two options, one slay.

---

👀 SEE ALSO 👀

chflags(1), chgrp(1), chmod(1), cksum(1), stat(2), fnmatch(3), fts(3), strsvis(3), chown(8), mknod(8)

The whole friend group. Go say hi. 🫶

---

🌈 HISTORY 🌈

• The mtree utility appeared in 4.3BSD-Reno.
• The optional keyword appeared in NetBSD 1.2.
• The -U flag appeared in NetBSD 1.3.
• The flags and md5 keywords, and -i and -m flags, appeared in NetBSD 1.4.
• The device, rmd160, sha1, tags, and all keywords, the -D, -E, -I, -l, -L, -N, -P, -R, -W, and -X flags, and support for full paths appeared in NetBSD 1.6.
• The sha256, sha384, and sha512 keywords appeared in NetBSD 3.0.

Look at that glow-up timeline. From 4.3BSD-Reno all the way to NetBSD 3.0 — a true main character arc. 💖

---

And that's the whole page, bestie!! 🎀 This one comes to us from Debian, dated September 12, 2006 — yeah, she's been iconic for a minute. Go forth and checksum responsibly. No cap. ✨🦋💜