1.\" Copyright (c) 1989, 1990, 1993
2.\" The Regents of the University of California. 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.\" 4. Neither the name of the University nor the names of its contributors
13.\" may be used to endorse or promote products derived from this software
14.\" without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" From: @(#)mtree.8 8.2 (Berkeley) 12/11/93
| 1.\" Copyright (c) 1989, 1990, 1993
2.\" The Regents of the University of California. 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.\" 4. Neither the name of the University nor the names of its contributors
13.\" may be used to endorse or promote products derived from this software
14.\" without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" From: @(#)mtree.8 8.2 (Berkeley) 12/11/93
|
29.\" $FreeBSD: head/usr.sbin/mtree/mtree.8 141846 2005-02-13 22:25:33Z ru $
| 29.\" $FreeBSD: head/usr.sbin/mtree/mtree.8 144295 2005-03-29 11:44:17Z tobez $
|
30.\"
31.Dd January 11, 2004
32.Dt MTREE 8
33.Os
34.Sh NAME
35.Nm mtree
36.Nd map a directory hierarchy
37.Sh SYNOPSIS
38.Nm
39.Op Fl LPUcdeinqruxw
40.Bk -words
41.Op Fl f Ar spec
42.Ek
43.Bk -words
44.Op Fl f Ar spec
45.Ek
46.Bk -words
47.Op Fl K Ar keywords
48.Ek
49.Bk -words
50.Op Fl k Ar keywords
51.Ek
52.Bk -words
53.Op Fl p Ar path
54.Ek
55.Bk -words
56.Op Fl s Ar seed
57.Ek
58.Bk -words
59.Op Fl X Ar exclude-list
60.Ek
61.Sh DESCRIPTION
62The
63.Nm
64utility compares the file hierarchy rooted in the current directory against a
65specification read from the standard input.
66Messages are written to the standard output for any files whose
67characteristics do not match the specifications, or which are
68missing from either the file hierarchy or the specification.
69.Pp
70The options are as follows:
71.Bl -tag -width flag
72.It Fl L
73Follow all symbolic links in the file hierarchy.
74.It Fl P
75Do not follow symbolic links in the file hierarchy, instead consider
76the symbolic link itself in any comparisons.
77This is the default.
78.It Fl U
79Modify the owner, group, permissions, and modification time of existing
80files to match the specification and create any missing directories or
81symbolic links.
82User, group and permissions must all be specified for missing directories
83to be created.
84Corrected mismatches are not considered errors.
85.It Fl c
86Print a specification for the file hierarchy to the standard output.
87.It Fl d
88Ignore everything except directory type files.
89.It Fl e
90Do not complain about files that are in the file hierarchy, but not in the
91specification.
92.It Fl i
93Indent the output 4 spaces each time a directory level is descended when
94create a specification with the
95.Fl c
96option.
97This does not affect either the /set statements or the comment before each
98directory.
99It does however affect the comment before the close of each directory.
100.It Fl n
101Do not emit pathname comments when creating a specification.
102Normally
103a comment is emitted before each directory and before the close of that
104directory when using the
105.Fl c
106option.
107.It Fl q
108Quiet mode.
109Do not complain when a
110.Dq missing
111directory cannot be created because it already exists.
112This occurs when the directory is a symbolic link.
113.It Fl r
114Remove any files in the file hierarchy that are not described in the
115specification.
116.It Fl u
117Same as
118.Fl U
119except a status of 2 is returned if the file hierarchy did not match
120the specification.
121.It Fl w
122Make some errorconditions non-fatal warnings.
123.It Fl x
124Do not descend below mount points in the file hierarchy.
125.It Fl f Ar file
126Read the specification from
127.Ar file ,
128instead of from the standard input.
129.Pp
130If this option is specified twice, the two specifications are compared
131to each other rather than to the file hierarchy.
132The specifications be sorted like output generated using
133.Fl c .
134The output format in this case is somewhat remniscent of
135.Xr comm 1 ,
136having "in first spec only", "in second spec only", and "different"
137columns, prefixed by zero, one and two TAB characters respectively.
138Each entry in the "different" column occupies two lines, one from each specfication.
139.It Fl K Ar keywords
140Add the specified (whitespace or comma separated)
141.Ar keywords
142to the current set of keywords.
143.It Fl k Ar keywords
144Use the ``type'' keyword plus the specified (whitespace or comma separated)
145.Ar keywords
146instead of the current set of keywords.
147.It Fl p Ar path
148Use the file hierarchy rooted in
149.Ar path ,
150instead of the current directory.
151.It Fl s Ar seed
152Display a single checksum to the standard error output that represents all
153of the files for which the keyword
154.Cm cksum
155was specified.
156The checksum is seeded with the specified value.
157.It Fl X Ar exclude-list
158The specified file contains
159.Xr fnmatch 3
160patterns matching files to be excluded from
161the specification, one to a line.
162If the pattern contains a
163.Ql \&/
164character, it will be matched against entire pathnames (relative to
165the starting directory); otherwise,
166it will be matched against basenames only.
167No comments are allowed in
168the
169.Ar exclude-list
170file.
171.El
172.Pp
173Specifications are mostly composed of ``keywords'', i.e., strings
174that specify values relating to files.
175No keywords have default values, and if a keyword has no value set, no
176checks based on it are performed.
177.Pp
178Currently supported keywords are as follows:
179.Bl -tag -width Cm
180.It Cm cksum
181The checksum of the file using the default algorithm specified by
182the
183.Xr cksum 1
184utility.
185.It Cm flags
186The file flags as a symbolic name.
187See
188.Xr chflags 1
189for information on these names.
190If no flags are to be set the string
191.Dq none
192may be used to override the current default.
193.It Cm ignore
194Ignore any file hierarchy below this file.
195.It Cm gid
196The file group as a numeric value.
197.It Cm gname
198The file group as a symbolic name.
199.It Cm md5digest
200The MD5 message digest of the file.
201.It Cm sha1digest
202The
203.Tn FIPS
204160-1
205.Pq Dq Tn SHA-1
206message digest of the file.
| 30.\"
31.Dd January 11, 2004
32.Dt MTREE 8
33.Os
34.Sh NAME
35.Nm mtree
36.Nd map a directory hierarchy
37.Sh SYNOPSIS
38.Nm
39.Op Fl LPUcdeinqruxw
40.Bk -words
41.Op Fl f Ar spec
42.Ek
43.Bk -words
44.Op Fl f Ar spec
45.Ek
46.Bk -words
47.Op Fl K Ar keywords
48.Ek
49.Bk -words
50.Op Fl k Ar keywords
51.Ek
52.Bk -words
53.Op Fl p Ar path
54.Ek
55.Bk -words
56.Op Fl s Ar seed
57.Ek
58.Bk -words
59.Op Fl X Ar exclude-list
60.Ek
61.Sh DESCRIPTION
62The
63.Nm
64utility compares the file hierarchy rooted in the current directory against a
65specification read from the standard input.
66Messages are written to the standard output for any files whose
67characteristics do not match the specifications, or which are
68missing from either the file hierarchy or the specification.
69.Pp
70The options are as follows:
71.Bl -tag -width flag
72.It Fl L
73Follow all symbolic links in the file hierarchy.
74.It Fl P
75Do not follow symbolic links in the file hierarchy, instead consider
76the symbolic link itself in any comparisons.
77This is the default.
78.It Fl U
79Modify the owner, group, permissions, and modification time of existing
80files to match the specification and create any missing directories or
81symbolic links.
82User, group and permissions must all be specified for missing directories
83to be created.
84Corrected mismatches are not considered errors.
85.It Fl c
86Print a specification for the file hierarchy to the standard output.
87.It Fl d
88Ignore everything except directory type files.
89.It Fl e
90Do not complain about files that are in the file hierarchy, but not in the
91specification.
92.It Fl i
93Indent the output 4 spaces each time a directory level is descended when
94create a specification with the
95.Fl c
96option.
97This does not affect either the /set statements or the comment before each
98directory.
99It does however affect the comment before the close of each directory.
100.It Fl n
101Do not emit pathname comments when creating a specification.
102Normally
103a comment is emitted before each directory and before the close of that
104directory when using the
105.Fl c
106option.
107.It Fl q
108Quiet mode.
109Do not complain when a
110.Dq missing
111directory cannot be created because it already exists.
112This occurs when the directory is a symbolic link.
113.It Fl r
114Remove any files in the file hierarchy that are not described in the
115specification.
116.It Fl u
117Same as
118.Fl U
119except a status of 2 is returned if the file hierarchy did not match
120the specification.
121.It Fl w
122Make some errorconditions non-fatal warnings.
123.It Fl x
124Do not descend below mount points in the file hierarchy.
125.It Fl f Ar file
126Read the specification from
127.Ar file ,
128instead of from the standard input.
129.Pp
130If this option is specified twice, the two specifications are compared
131to each other rather than to the file hierarchy.
132The specifications be sorted like output generated using
133.Fl c .
134The output format in this case is somewhat remniscent of
135.Xr comm 1 ,
136having "in first spec only", "in second spec only", and "different"
137columns, prefixed by zero, one and two TAB characters respectively.
138Each entry in the "different" column occupies two lines, one from each specfication.
139.It Fl K Ar keywords
140Add the specified (whitespace or comma separated)
141.Ar keywords
142to the current set of keywords.
143.It Fl k Ar keywords
144Use the ``type'' keyword plus the specified (whitespace or comma separated)
145.Ar keywords
146instead of the current set of keywords.
147.It Fl p Ar path
148Use the file hierarchy rooted in
149.Ar path ,
150instead of the current directory.
151.It Fl s Ar seed
152Display a single checksum to the standard error output that represents all
153of the files for which the keyword
154.Cm cksum
155was specified.
156The checksum is seeded with the specified value.
157.It Fl X Ar exclude-list
158The specified file contains
159.Xr fnmatch 3
160patterns matching files to be excluded from
161the specification, one to a line.
162If the pattern contains a
163.Ql \&/
164character, it will be matched against entire pathnames (relative to
165the starting directory); otherwise,
166it will be matched against basenames only.
167No comments are allowed in
168the
169.Ar exclude-list
170file.
171.El
172.Pp
173Specifications are mostly composed of ``keywords'', i.e., strings
174that specify values relating to files.
175No keywords have default values, and if a keyword has no value set, no
176checks based on it are performed.
177.Pp
178Currently supported keywords are as follows:
179.Bl -tag -width Cm
180.It Cm cksum
181The checksum of the file using the default algorithm specified by
182the
183.Xr cksum 1
184utility.
185.It Cm flags
186The file flags as a symbolic name.
187See
188.Xr chflags 1
189for information on these names.
190If no flags are to be set the string
191.Dq none
192may be used to override the current default.
193.It Cm ignore
194Ignore any file hierarchy below this file.
195.It Cm gid
196The file group as a numeric value.
197.It Cm gname
198The file group as a symbolic name.
199.It Cm md5digest
200The MD5 message digest of the file.
201.It Cm sha1digest
202The
203.Tn FIPS
204160-1
205.Pq Dq Tn SHA-1
206message digest of the file.
|
| 207.It Cm sha256digest
208The
209.Tn FIPS
210180-2
211.Pq Dq Tn SHA-256
212message digest of the file.
|
207.It Cm ripemd160digest
208The
209.Tn RIPEMD160
210message digest of the file.
211.It Cm mode
212The current file's permissions as a numeric (octal) or symbolic
213value.
214.It Cm nlink
215The number of hard links the file is expected to have.
216.It Cm nochange
217Make sure this file or directory exists but otherwise ignore all attributes.
218.It Cm uid
219The file owner as a numeric value.
220.It Cm uname
221The file owner as a symbolic name.
222.It Cm size
223The size, in bytes, of the file.
224.It Cm link
225The file the symbolic link is expected to reference.
226.It Cm time
227The last modification time of the file.
228.It Cm type
229The type of the file; may be set to any one of the following:
230.Pp
231.Bl -tag -width Cm -compact
232.It Cm block
233block special device
234.It Cm char
235character special device
236.It Cm dir
237directory
238.It Cm fifo
239fifo
240.It Cm file
241regular file
242.It Cm link
243symbolic link
244.It Cm socket
245socket
246.El
247.El
248.Pp
249The default set of keywords are
250.Cm flags ,
251.Cm gid ,
252.Cm mode ,
253.Cm nlink ,
254.Cm size ,
255.Cm link ,
256.Cm time ,
257and
258.Cm uid .
259.Pp
260There are four types of lines in a specification.
261.Pp
262The first type of line sets a global value for a keyword, and consists of
263the string ``/set'' followed by whitespace, followed by sets of keyword/value
264pairs, separated by whitespace.
265Keyword/value pairs consist of a keyword, followed by an equals sign
266(``=''), followed by a value, without whitespace characters.
267Once a keyword has been set, its value remains unchanged until either
268reset or unset.
269.Pp
270The second type of line unsets keywords and consists of the string
271``/unset'', followed by whitespace, followed by one or more keywords,
272separated by whitespace.
273.Pp
274The third type of line is a file specification and consists of a file
275name, followed by whitespace, followed by zero or more whitespace
276separated keyword/value pairs.
277The file name may be preceded by whitespace characters.
278The file name may contain any of the standard file name matching
279characters (``['', ``]'', ``?'' or ``*''), in which case files
280in the hierarchy will be associated with the first pattern that
281they match.
282.Pp
283Each of the keyword/value pairs consist of a keyword, followed by an
284equals sign (``=''), followed by the keyword's value, without
285whitespace characters.
286These values override, without changing, the global value of the
287corresponding keyword.
288.Pp
289All paths are relative.
290Specifying a directory will cause subsequent files to be searched
291for in that directory hierarchy.
292Which brings us to the last type of line in a specification: a line
293containing only the string
294.Dq Pa ..\&
295causes the current directory
296path to ascend one level.
297.Pp
298Empty lines and lines whose first non-whitespace character is a hash
299mark (``#'') are ignored.
300.Pp
301The
302.Nm
303utility exits with a status of 0 on success, 1 if any error occurred,
304and 2 if the file hierarchy did not match the specification.
305A status of 2 is converted to a status of 0 if the
306.Fl U
307option is used.
308.Sh FILES
309.Bl -tag -width /etc/mtree -compact
310.It Pa /etc/mtree
311system specification directory
312.El
313.Sh EXIT STATUS
314.Ex -std
315.Sh EXAMPLES
316To detect system binaries that have been ``trojan horsed'', it is recommended
317that
318.Nm
319.Fl K
| 213.It Cm ripemd160digest
214The
215.Tn RIPEMD160
216message digest of the file.
217.It Cm mode
218The current file's permissions as a numeric (octal) or symbolic
219value.
220.It Cm nlink
221The number of hard links the file is expected to have.
222.It Cm nochange
223Make sure this file or directory exists but otherwise ignore all attributes.
224.It Cm uid
225The file owner as a numeric value.
226.It Cm uname
227The file owner as a symbolic name.
228.It Cm size
229The size, in bytes, of the file.
230.It Cm link
231The file the symbolic link is expected to reference.
232.It Cm time
233The last modification time of the file.
234.It Cm type
235The type of the file; may be set to any one of the following:
236.Pp
237.Bl -tag -width Cm -compact
238.It Cm block
239block special device
240.It Cm char
241character special device
242.It Cm dir
243directory
244.It Cm fifo
245fifo
246.It Cm file
247regular file
248.It Cm link
249symbolic link
250.It Cm socket
251socket
252.El
253.El
254.Pp
255The default set of keywords are
256.Cm flags ,
257.Cm gid ,
258.Cm mode ,
259.Cm nlink ,
260.Cm size ,
261.Cm link ,
262.Cm time ,
263and
264.Cm uid .
265.Pp
266There are four types of lines in a specification.
267.Pp
268The first type of line sets a global value for a keyword, and consists of
269the string ``/set'' followed by whitespace, followed by sets of keyword/value
270pairs, separated by whitespace.
271Keyword/value pairs consist of a keyword, followed by an equals sign
272(``=''), followed by a value, without whitespace characters.
273Once a keyword has been set, its value remains unchanged until either
274reset or unset.
275.Pp
276The second type of line unsets keywords and consists of the string
277``/unset'', followed by whitespace, followed by one or more keywords,
278separated by whitespace.
279.Pp
280The third type of line is a file specification and consists of a file
281name, followed by whitespace, followed by zero or more whitespace
282separated keyword/value pairs.
283The file name may be preceded by whitespace characters.
284The file name may contain any of the standard file name matching
285characters (``['', ``]'', ``?'' or ``*''), in which case files
286in the hierarchy will be associated with the first pattern that
287they match.
288.Pp
289Each of the keyword/value pairs consist of a keyword, followed by an
290equals sign (``=''), followed by the keyword's value, without
291whitespace characters.
292These values override, without changing, the global value of the
293corresponding keyword.
294.Pp
295All paths are relative.
296Specifying a directory will cause subsequent files to be searched
297for in that directory hierarchy.
298Which brings us to the last type of line in a specification: a line
299containing only the string
300.Dq Pa ..\&
301causes the current directory
302path to ascend one level.
303.Pp
304Empty lines and lines whose first non-whitespace character is a hash
305mark (``#'') are ignored.
306.Pp
307The
308.Nm
309utility exits with a status of 0 on success, 1 if any error occurred,
310and 2 if the file hierarchy did not match the specification.
311A status of 2 is converted to a status of 0 if the
312.Fl U
313option is used.
314.Sh FILES
315.Bl -tag -width /etc/mtree -compact
316.It Pa /etc/mtree
317system specification directory
318.El
319.Sh EXIT STATUS
320.Ex -std
321.Sh EXAMPLES
322To detect system binaries that have been ``trojan horsed'', it is recommended
323that
324.Nm
325.Fl K
|
320.Cm sha1digest
| 326.Cm sha256digest
|
321be run on the file systems, and a copy of the results stored on a different
322machine, or, at least, in encrypted form.
323The output file itself should be digested using the
| 327be run on the file systems, and a copy of the results stored on a different
328machine, or, at least, in encrypted form.
329The output file itself should be digested using the
|
324.Xr md5 1
| 330.Xr sha256 1
|
325utility.
326Then, periodically,
327.Nm
328and
| 331utility.
332Then, periodically,
333.Nm
334and
|
329.Xr md5 1
| 335.Xr sha256 1
|
330should be run against the on-line specifications.
331While it is possible for the bad guys to change the on-line specifications
332to conform to their modified binaries, it is believed to be
333impractical for them to create a modified specification which has
| 336should be run against the on-line specifications.
337While it is possible for the bad guys to change the on-line specifications
338to conform to their modified binaries, it is believed to be
339impractical for them to create a modified specification which has
|
334the same MD5 digest as the original.
| 340the same SHA-256 digest as the original.
|
335.Pp
336The
337.Fl d
338and
339.Fl u
340options can be used in combination to create directory hierarchies
341for distributions and other such things; the files in
342.Pa /etc/mtree
343were used to create almost all directories in this
344.Fx
345distribution.
346.Sh SEE ALSO
347.Xr chflags 1 ,
348.Xr chgrp 1 ,
349.Xr chmod 1 ,
350.Xr cksum 1 ,
351.Xr md5 1 ,
352.Xr stat 2 ,
353.Xr fts 3 ,
354.Xr md5 3 ,
355.Xr chown 8
356.Sh HISTORY
357The
358.Nm
359utility appeared in
360.Bx 4.3 Reno .
361The
362.Tn MD5
363digest capability was added in
364.Fx 2.1 ,
365in response to the widespread use of programs which can spoof
366.Xr cksum 1 .
367The
368.Tn SHA-1
369and
370.Tn RIPEMD160
371digests were added in
372.Fx 4.0 ,
373as new attacks have demonstrated weaknesses in
374.Tn MD5 .
| 341.Pp
342The
343.Fl d
344and
345.Fl u
346options can be used in combination to create directory hierarchies
347for distributions and other such things; the files in
348.Pa /etc/mtree
349were used to create almost all directories in this
350.Fx
351distribution.
352.Sh SEE ALSO
353.Xr chflags 1 ,
354.Xr chgrp 1 ,
355.Xr chmod 1 ,
356.Xr cksum 1 ,
357.Xr md5 1 ,
358.Xr stat 2 ,
359.Xr fts 3 ,
360.Xr md5 3 ,
361.Xr chown 8
362.Sh HISTORY
363The
364.Nm
365utility appeared in
366.Bx 4.3 Reno .
367The
368.Tn MD5
369digest capability was added in
370.Fx 2.1 ,
371in response to the widespread use of programs which can spoof
372.Xr cksum 1 .
373The
374.Tn SHA-1
375and
376.Tn RIPEMD160
377digests were added in
378.Fx 4.0 ,
379as new attacks have demonstrated weaknesses in
380.Tn MD5 .
|
| 381The
382.Tn SHA-256
383digest was added in
384.Fx 6.0 .
|
375Support for file flags was added in
376.Fx 4.0 ,
377and mostly comes from
378.Nx .
| 385Support for file flags was added in
386.Fx 4.0 ,
387and mostly comes from
388.Nx .
|