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

Last change on this file since 130 was 125, checked in by tim, 16 years ago

added early version of class name parsing. additional work still needed.

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