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

Last change on this file since 187 was 187, checked in by tim, 14 years ago

early versions of SConstruct build scripts

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