source: trunk/doc/reglookup.1.docbook @ 120

Last change on this file since 120 was 119, checked in by tim, 16 years ago

adding reglookup-recover man page

  • Property svn:keywords set to Id
File size: 11.1 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<refentry id='reglookup.1'>
3  <!--  $Id: reglookup.1.docbook 119 2008-08-09 05:55:45Z tim $ -->
4  <refmeta>
5    <refentrytitle>reglookup</refentrytitle>
6    <manvolnum>1</manvolnum>
7    <refmiscinfo class="sectdesc">File Conversion Utilities</refmiscinfo>
8  </refmeta>
9  <refnamediv id='name'>
10    <refname>reglookup</refname>
11    <refpurpose>Windows NT+ registry reader/lookup tool</refpurpose>
12  </refnamediv>
13
14  <refsect1 id='synopsis'>
15    <title>SYNOPSIS</title>
16    <para>
17      <command>
18        reglookup [options] <replaceable>registry-file</replaceable>
19      </command>
20    </para>
21  </refsect1>
22
23  <refsect1 id='description'>
24    <title>DESCRIPTION</title>
25    <para>
26        reglookup is designed to read windows registry elements and
27        print them out to stdout in a CSV-like format.  It has filtering
28        options to narrow the focus of the output.  This tool is
29        designed to work with on Windows NT/2K/XP/2K3/Vista registries,
30        though your mileage may vary.
31    </para>
32  </refsect1>
33
34  <refsect1 id='options'>
35    <title>OPTIONS</title>
36    <para>
37      <command>reglookup</command> accepts the following parameters:
38    </para>
39
40    <variablelist remap='IP'>
41      <varlistentry>
42        <term>
43          <option>-p <replaceable>prefix-filter</replaceable></option>
44        </term>
45        <listitem>
46          <para>
47            Specify a path prefix filter.  Only keys/values under
48            this registry path will be output.
49          </para>
50        </listitem>
51      </varlistentry>
52    </variablelist>
53
54    <variablelist remap='IP'>
55      <varlistentry>
56        <term>
57          <option>-t <replaceable>type-filter</replaceable></option>
58        </term>
59        <listitem>
60          <para>
61            Specify a type filter.  Only elements which match this
62            registry data type will be printed.  Acceptable values
63            are:
64            <command>
65              NONE, SZ, EXPAND_SZ, BINARY, DWORD, DWORD_BE,
66              LINK, MULTI_SZ, RSRC_LIST, RSRC_DESC, RSRC_REQ_LIST, QWORD
67            </command>
68            and
69            <command>
70              KEY
71            </command>
72          </para>
73        </listitem>
74      </varlistentry>
75    </variablelist>
76
77    <variablelist remap='IP'>
78      <varlistentry>
79        <term>
80          <option>-h</option>
81        </term>
82        <listitem>
83          <para>
84            Enables the printing of a column header row. (default)
85          </para>
86        </listitem>
87      </varlistentry>
88    </variablelist>
89
90    <variablelist remap='IP'>
91      <varlistentry>
92        <term>
93          <option>-H</option>
94        </term>
95        <listitem>
96          <para>
97            Disables the printing of a column header row.
98          </para>
99        </listitem>
100      </varlistentry>
101    </variablelist>
102
103    <variablelist remap='IP'>
104      <varlistentry>
105        <term>
106          <option>-s</option>
107        </term>
108        <listitem>
109          <para>
110            Adds four additional columns to output containing
111            information from key security descriptors.  The columns
112            are: owner, group, sacl, dacl.
113            (This feature's output has not been extensively tested.)
114          </para>
115        </listitem>
116      </varlistentry>
117    </variablelist>
118
119    <variablelist remap='IP'>
120      <varlistentry>
121        <term>
122          <option>-S</option>
123        </term>
124        <listitem>
125          <para>
126            Disables the printing of security descriptor
127            information. (default)
128          </para>
129        </listitem>
130      </varlistentry>
131    </variablelist>
132
133    <variablelist remap='IP'>
134      <varlistentry>
135        <term>
136          <option>-v</option>
137        </term>
138        <listitem>
139          <para>
140            Verbose output. (Currently does little to nothing.)
141          </para>
142        </listitem>
143      </varlistentry>
144    </variablelist>
145
146    <variablelist remap='IP'>
147      <varlistentry>
148        <term>
149          <option><replaceable>registry-file</replaceable></option>
150        </term>
151        <listitem>
152          <para>
153            Required argument.  Specifies the location of the
154            registry file to read.  The system registry files should be
155            found under:
156            <command>%SystemRoot%/system32/config</command>.
157          </para>
158        </listitem>
159      </varlistentry>
160    </variablelist>
161  </refsect1>
162
163  <refsect1 id='output'>
164    <title>OUTPUT</title>
165    <para>
166      <!-- XXX: this should be a bit more formal -->
167      <command>reglookup</command> generates comma-separated values (CSV)
168      and writes them to stdout.  The format is designed to simplify parsing
169      algorithms of other tools by quoting CSV special characters using a
170      common hexadecimal format.  Specifically, special characters or non-ascii
171      bytes are converted to "\xQQ" where QQ is the hexadecimal value for
172      the byte.
173    </para>
174    <para>
175      The number of columns or fields in each line is fixed for a given run
176      of the program, but may vary based on the command line options provided.
177      See the header line for information on which fields are available and
178      what they contain.
179    </para>
180    <para>
181      Some fields in some lines may contain sub-fields which require additional
182      delimiters.  If these sub-delimiters occur in these sub-fields, they are
183      also encoded in the same way as commas or other special characters are. 
184      Currently, the second, third, and fourth level delimiters are "|", ":",
185      and " ", respectively.  These are particularly important to take note of
186      when security attributes are printed.  Please note that these delimiters
187      may occur in fields that are not sub-delimited, and should not be
188      interpreted as special.
189    </para>
190    <para>
191      Security attributes of registry keys have a complex structure which is
192      outlined here.  Each key will generally have an associated ACL (Access
193      Control List), which is made up of ACEs (Access Control Entries).  Each
194      ACE is delimited by the secondary delimiter mentioned above, "|".  The
195      fields within an ACE are delimited by the third-level delimiter, ":",
196      and consist of a SID, the ACE type (ALLOW, DENY, etc), a list of access
197      rights, and a list of flags.  The last two fields are delimited by the
198      fourth-level delimiter " ".  These final lists are simply human-readable
199      interpretations of bits.  The access rights abbreviations are listed
200      below along with their Microsoft-assigned names:
201      <screen>
202      QRY_VAL           KEY_QUERY_VALUE
203      SET_VAL           KEY_SET_VALUE
204      CREATE_KEY        KEY_CREATE_SUB_KEY
205      ENUM_KEYS         KEY_ENUMERATE_SUB_KEYS
206      NOTIFY            KEY_NOTIFY
207      CREATE_LNK        KEY_CREATE_LINK
208      WOW64_64          KEY_WOW64_64KEY
209      WOW64_32          KEY_WOW64_32KEY
210      DELETE            DELETE
211      R_CONT            READ_CONTROL
212      W_DAC             WRITE_DAC
213      W_OWNER           WRITE_OWNER
214      SYNC              SYNCHRONIZE
215      SYS_SEC           ACCESS_SYSTEM_SECURITY
216      MAX_ALLWD         MAXIMUM_ALLOWED
217      GEN_A             GENERIC_ALL
218      GEN_X             GENERIC_EXECUTE
219      GEN_W             GENERIC_WRITE
220      GEN_R             GENERIC_READ
221      </screen>
222
223      And the meaning of each flag is:
224      <screen>
225      OI        Object Inherit
226      CI        Container Inherit
227      NP        Non-Propagate
228      IO        Inherit Only
229      IA        Inherited ACE
230      </screen>
231
232      Please see the following references for more information:
233      <screen>
234        http://msdn2.microsoft.com/en-gb/library/ms724878.aspx
235        http://msdn2.microsoft.com/en-gb/library/aa374892.aspx
236        http://msdn2.microsoft.com/en-us/library/aa772242.aspx
237        http://support.microsoft.com/kb/220167
238      </screen>
239    </para>
240    <para>
241      Note that some of the bits listed above have either not been allocated by
242      Microsoft, or simply aren't documented.  If any bits are set in the above
243      two fields that aren't recognized, a hexidecimal representation of all of
244      these mystery bits will be included in the output.  For instance, if the
245      lowest bit and third lowest bit were not recognized while being set,
246      the number "0x5" would be included as an element in the list.
247    </para>
248    <para>
249      While the ACL/ACE output format is mostly stable at this point, minor
250      changes may be introduced in future versions.
251    </para>
252  </refsect1>
253
254  <refsect1 id='examples'>
255    <title>EXAMPLES</title>
256    <para>
257      To read and print the contents of an entire system registry
258      file:
259    </para>
260    <para>
261      <screen>
262        reglookup /mnt/win/c/WINNT/system32/config/system
263      </screen>
264    </para>
265    <para>
266      To limit the output to just those entries under the Services
267      key:
268    </para>
269    <para>
270      <screen>
271        reglookup -p /ControlSet002/Services /mnt/win/c/WINNT/system32/config/system
272      </screen>
273    </para>
274    <para>
275      To limit the output to all registry values of type BINARY:
276    </para>
277    <para>
278      <screen>
279        reglookup -t BINARY /mnt/win/c/WINNT/system32/config/system
280      </screen>
281    </para>
282    <para>
283      And to limit the output to BINARY values under the Services key:
284    </para>
285    <para>
286      <screen>
287        reglookup -t BINARY -p /ControlSet002/Services /mnt/win/c/WINNT/system32/config/system
288      </screen>
289    </para>
290  </refsect1>
291
292  <refsect1 id='bugs'>
293    <title>BUGS</title>
294    <para>
295      This program has been smoke-tested against most current Windows target
296      platforms, but a comprehensive test suite has not yet been developed.
297      (Please report results to the development mailing list if you encounter
298       any bugs.  Sample registry files and/or patches are greatly appreciated.)
299    </para>
300    <para>
301      Verbose output is not working.
302    </para>
303    <para>
304      The SID conversions haven't been carefully checked for accuracy.
305    </para>
306    <para>
307      The MTIME conversions appear correctly produce the stored UTC timestamp.
308      However, due to the periodicity of registry writes, and the complexity
309      of the conversion, a small amount of error (on the order of seconds) may
310      be possible.  The documentation available online from Microsoft on
311      this field is very poor.
312    </para>
313    <para>
314      Backslashes are currently considered special characters, to make
315      parsing easier for automated tools.  However, this causes paths
316      to be difficult to read by mere mortals.
317    </para>
318    <para>
319      For more information on registry format details, see:
320        http://sentinelchicken.com/research/registry_format/
321    </para>
322  </refsect1>
323
324  <refsect1 id='credits'>
325    <title>CREDITS</title>
326    <para>
327      This program was initially based on editreg.c by
328      Richard Sharpe.  It has since been rewritten to use a modified
329      version the regfio library written by Gerald Carter.  Heavy
330      modifications to the library and the original command line
331      interface have been done by Timothy D. Morgan.
332    </para>
333    <para>
334      Please see source code for a full list of copyrights.
335    </para>
336  </refsect1>
337
338  <refsect1 id='license'>
339    <title>LICENSE</title>
340    <para>
341      Please see the file "LICENSE" included with this software
342      distribution.
343    </para>
344    <para>     
345      This program is distributed in the hope that it will be useful,
346      but WITHOUT ANY WARRANTY; without even the implied warranty of
347      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
348      GNU General Public License version 3 for more details.
349    </para>
350  </refsect1>
351
352  <refsect1 id='seealso'>
353    <title>SEE ALSO</title>
354    <para>
355      reglookup-timeline(1) reglookup-recover(1)
356    </para>
357  </refsect1>
358</refentry>
Note: See TracBrowser for help on using the repository browser.