Add PCICAP_{ID,NEXTPTR} to avoid using magic number
[dragonfly.git] / usr.sbin / mtree / mtree.8
CommitLineData
984263bc
MD
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.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University 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 REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS 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.\" From: @(#)mtree.8 8.2 (Berkeley) 12/11/93
33.\" $FreeBSD: src/usr.sbin/mtree/mtree.8,v 1.16.2.11 2003/03/11 22:31:29 trhodes Exp $
3ac6dd5c 34.\" $DragonFly: src/usr.sbin/mtree/mtree.8,v 1.6 2007/10/20 13:43:00 swildner Exp $
984263bc
MD
35.\"
36.Dd February 26, 1999
37.Dt MTREE 8
38.Os
39.Sh NAME
40.Nm mtree
41.Nd map a directory hierarchy
42.Sh SYNOPSIS
43.Nm
44.Op Fl LPUcdeinqrux
45.Bk -words
46.Op Fl f Ar spec
47.Ek
48.Bk -words
49.Op Fl K Ar keywords
50.Ek
51.Bk -words
52.Op Fl k Ar keywords
53.Ek
54.Bk -words
55.Op Fl p Ar path
56.Ek
57.Bk -words
58.Op Fl s Ar seed
59.Ek
60.Bk -words
61.Op Fl X Ar exclude-list
62.Ek
63.Sh DESCRIPTION
64The
65.Nm
66utility compares the file hierarchy rooted in the current directory against a
67specification read from the standard input.
68Messages are written to the standard output for any files whose
69characteristics do not match the specifications, or which are
70missing from either the file hierarchy or the specification.
71.Pp
72The options are as follows:
73.Bl -tag -width flag
74.It Fl L
75Follow all symbolic links in the file hierarchy.
76.It Fl P
77Don't follow symbolic links in the file hierarchy, instead consider
78the symbolic link itself in any comparisons. This is the default.
79.It Fl U
80Modify the owner, group and permissions of existing files to match
81the specification and create any missing directories or symbolic 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
90Don't 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. Normally
102a comment is emitted before each directory and before the close of that
103directory when using the
104.Fl c
105option.
106.It Fl q
107Quiet mode. Do not complain when a
108.Dq missing
109directory cannot be created because it already exists.
110This occurs when the directory is a symbolic link.
111.It Fl r
112Remove any files in the file hierarchy that are not described in the
113specification.
114.It Fl u
115Same as
116.Fl U
117except a status of 2 is returned if the file hierarchy did not match
118the specification.
119.It Fl x
120Don't descend below mount points in the file hierarchy.
121.It Fl f Ar file
122Read the specification from
123.Ar file ,
124instead of from the standard input.
125.It Fl K Ar keywords
126Add the specified (whitespace or comma separated)
127.Ar keywords
128to the current set of keywords.
129.It Fl k Ar keywords
130Use the ``type'' keyword plus the specified (whitespace or comma separated)
131.Ar keywords
132instead of the current set of keywords.
133.It Fl p Ar path
134Use the file hierarchy rooted in
135.Ar path ,
136instead of the current directory.
137.It Fl s Ar seed
138Display a single checksum to the standard error output that represents all
139of the files for which the keyword
140.Cm cksum
141was specified.
142The checksum is seeded with the specified value.
143.It Fl X Ar exclude-list
144The specified file contains
145.Xr fnmatch 3
146patterns matching files to be excluded from
147the specification, one to a line.
148If the pattern contains a
149.Ql \&/
150character, it will be matched against entire pathnames (relative to
151the starting directory); otherwise,
152it will be matched against basenames only. No comments are allowed in
153the
154.Ar exclude-list
155file.
156.El
157.Pp
50a7b6f7 158Specifications are mostly composed of ``keywords'', i.e. strings
984263bc
MD
159that specify values relating to files.
160No keywords have default values, and if a keyword has no value set, no
161checks based on it are performed.
162.Pp
163Currently supported keywords are as follows:
164.Bl -tag -width Cm
165.It Cm cksum
166The checksum of the file using the default algorithm specified by
167the
168.Xr cksum 1
169utility.
170.It Cm flags
171The file flags as a symbolic name. See
172.Xr chflags 1
173for information on these names. If no flags are to be set the string
174.Dq none
175may be used to override the current default.
176.It Cm ignore
177Ignore any file hierarchy below this file.
178.It Cm gid
179The file group as a numeric value.
180.It Cm gname
181The file group as a symbolic name.
182.It Cm md5digest
183The MD5 message digest of the file.
184.It Cm sha1digest
185The
186.Tn FIPS
187160-1
188.Pq Dq Tn SHA-1
189message digest of the file.
190.It Cm ripemd160digest
191The
192.Tn RIPEMD160
193message digest of the file.
194.It Cm mode
195The current file's permissions as a numeric (octal) or symbolic
196value.
197.It Cm nlink
198The number of hard links the file is expected to have.
199.It Cm nochange
200Make sure this file or directory exists but otherwise ignore all attributes.
201.It Cm uid
202The file owner as a numeric value.
203.It Cm uname
204The file owner as a symbolic name.
205.It Cm size
206The size, in bytes, of the file.
207.It Cm link
208The file the symbolic link is expected to reference.
209.It Cm time
210The last modification time of the file.
211.It Cm type
212The type of the file; may be set to any one of the following:
213.Pp
214.Bl -tag -width Cm -compact
215.It Cm block
216block special device
217.It Cm char
218character special device
219.It Cm dir
220directory
221.It Cm fifo
222fifo
223.It Cm file
224regular file
225.It Cm link
226symbolic link
227.It Cm socket
228socket
229.El
230.El
231.Pp
232The default set of keywords are
233.Cm flags ,
234.Cm gid ,
235.Cm mode ,
236.Cm nlink ,
237.Cm size ,
238.Cm link ,
239.Cm time ,
240and
241.Cm uid .
242.Pp
243There are four types of lines in a specification.
244.Pp
245The first type of line sets a global value for a keyword, and consists of
246the string ``/set'' followed by whitespace, followed by sets of keyword/value
247pairs, separated by whitespace.
248Keyword/value pairs consist of a keyword, followed by an equals sign
249(``=''), followed by a value, without whitespace characters.
250Once a keyword has been set, its value remains unchanged until either
251reset or unset.
252.Pp
253The second type of line unsets keywords and consists of the string
254``/unset'', followed by whitespace, followed by one or more keywords,
255separated by whitespace.
256.Pp
257The third type of line is a file specification and consists of a file
258name, followed by whitespace, followed by zero or more whitespace
259separated keyword/value pairs.
260The file name may be preceded by whitespace characters.
261The file name may contain any of the standard file name matching
262characters (``['', ``]'', ``?'' or ``*''), in which case files
263in the hierarchy will be associated with the first pattern that
264they match.
265.Pp
266Each of the keyword/value pairs consist of a keyword, followed by an
267equals sign (``=''), followed by the keyword's value, without
268whitespace characters.
269These values override, without changing, the global value of the
270corresponding keyword.
271.Pp
272All paths are relative.
273Specifying a directory will cause subsequent files to be searched
274for in that directory hierarchy.
275Which brings us to the last type of line in a specification: a line
276containing only the string
277.Dq Pa ..\&
278causes the current directory
279path to ascend one level.
280.Pp
281Empty lines and lines whose first non-whitespace character is a hash
282mark (``#'') are ignored.
283.Pp
284The
285.Nm
286utility exits with a status of 0 on success, 1 if any error occurred,
287and 2 if the file hierarchy did not match the specification.
288A status of 2 is converted to a status of 0 if the
289.Fl U
290option is used.
49781055
SW
291.Sh FILES
292.Bl -tag -width /etc/mtree -compact
293.It Pa /etc/mtree
294system specification directory
295.El
984263bc
MD
296.Sh EXAMPLES
297To detect system binaries that have been ``trojan horsed'', it is recommended
298that
299.Nm
300.Fl K
301.Cm sha1digest
302be run on the file systems, and a copy of the results stored on a different
303machine, or, at least, in encrypted form.
304The output file itself should be digested using the
305.Xr md5 1
306utility.
307Then, periodically,
308.Nm
309and
310.Xr md5 1
311should be run against the on-line specifications.
312While it is possible for the bad guys to change the on-line specifications
313to conform to their modified binaries, it is believed to be
314impractical for them to create a modified specification which has
315the same MD5 digest as the original.
316.Pp
317The
318.Fl d
319and
320.Fl u
321options can be used in combination to create directory hierarchies
322for distributions and other such things; the files in
323.Pa /etc/mtree
324were used to create almost all directories in this
9bb2a92d 325.Dx
984263bc 326distribution.
50a7b6f7
SW
327.Pp
328To create an
329.Pa /etc/mtree
330style BSD.*.dist file, use
331.Nm
332.Fl c
333.Fl d
334.Fl i
335.Fl n
336.Fl k
3ac6dd5c 337.Cm uname,gname,mode,nochange .
984263bc
MD
338.Sh DIAGNOSTICS
339.Ex -std
340.Sh SEE ALSO
341.Xr chflags 1 ,
342.Xr chgrp 1 ,
343.Xr chmod 1 ,
344.Xr cksum 1 ,
345.Xr md5 1 ,
346.Xr stat 2 ,
347.Xr fts 3 ,
348.Xr md5 3 ,
349.Xr chown 8
350.Sh HISTORY
351The
352.Nm
353utility appeared in
354.Bx 4.3 Reno .
355The
356.Tn MD5
357digest capability was added in
358.Fx 2.1 ,
359in response to the widespread use of programs which can spoof
360.Xr cksum 1 .
361The
362.Tn SHA-1
363and
364.Tn RIPEMD160
365digests were added in
366.Fx 4.0 ,
367as new attacks have demonstrated weaknesses in
368.Tn MD5 .
369Support for file flags was added in
370.Fx 4.0 ,
371and mostly comes from
372.Nx .