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

<?xml version="1.0" encoding="UTF-8"?>
<refentry id='reglookup.1'>
  <!--  $Id: reglookup.1.docbook 64 2006-07-23 16:02:53Z tim $ -->
  <refmeta>
    <refentrytitle>reglookup</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="sectdesc">File Conversion Utilities</refmiscinfo>
  </refmeta>
  <refnamediv id='name'>
    <refname>reglookup</refname>
    <refpurpose>windows NT+ registry reader/lookup tool</refpurpose>
  </refnamediv>

  <refsect1 id='synopsis'>
    <title>SYNOPSIS</title>
    <para>
      <command>
        reglookup [options] <replaceable>registry-file</replaceable>
      </command> 
    </para>
  </refsect1>

  <refsect1 id='description'>
    <title>DESCRIPTION</title>
    <para>
        reglookup is designed to read windows registry elements and
        print them out to stdout in a CSV-like format.  It has filtering
        options to narrow the focus of the output.  This tool is
        designed to work with on windows NT/2K/XP/2K3 registries, though
        your mileage may vary.
    </para>
  </refsect1>

  <refsect1 id='options'>
    <title>OPTIONS</title>
    <para>
      <command>reglookup</command> accepts the following parameters:
    </para>

    <variablelist remap='IP'>
      <varlistentry>
        <term>
          <option>-p <replaceable>prefix-filter</replaceable></option>
        </term>
        <listitem>
          <para>
            Specify a path prefix filter.  Only keys/values under
            this registry path will be output.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <variablelist remap='IP'>
      <varlistentry>
        <term>
          <option>-t <replaceable>type-filter</replaceable></option>
        </term>
        <listitem>
          <para>
            Specify a type filter.  Only elements which match this
            registry data type will be printed.  Acceptable values
            are: 
            <command>
              NONE, SZ, EXPAND_SZ, BINARY, DWORD, DWORD_BE,
              LINK, MULTI_SZ, RSRC_LIST, RSRC_DESC, RSRC_REQ_LIST,
            </command>
            and
            <command>
              KEY
            </command>
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <variablelist remap='IP'>
      <varlistentry>
        <term>
          <option>-h</option>
        </term>
        <listitem>
          <para>
            Enables the printing of a column header row. (default)
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <variablelist remap='IP'>
      <varlistentry>
        <term>
          <option>-H</option>
        </term>
        <listitem>
          <para>
            Disables the printing of a column header row.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <variablelist remap='IP'>
      <varlistentry>
        <term>
          <option>-s</option>
        </term>
        <listitem>
          <para>
            Adds four additional columns to output containing 
            information from key security descriptors.  The columns 
            are: owner, group, sacl, dacl.
            (This feature's output probably contains bugs right now.)
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <variablelist remap='IP'>
      <varlistentry>
        <term>
          <option>-S</option>
        </term>
        <listitem>
          <para>
            Disables the printing of security descriptor
            information. (default)
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <variablelist remap='IP'>
      <varlistentry>
        <term>
          <option>-v</option>
        </term>
        <listitem>
          <para>
            Verbose output. (Currently does little to nothing.)
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <variablelist remap='IP'>
      <varlistentry>
        <term>
          <option><replaceable>registry-file</replaceable></option>
        </term>
        <listitem>
          <para>
            Required argument.  Specifies the location of the
            registry file to read.  Typically, these files will be
            found on a NTFS partition under
            <command>%SystemRoot%/system32/config</command>.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id='output'>
    <title>OUTPUT</title>
    <para>
      <!-- XXX: this should be a bit more formal -->
      <command>reglookup</command> generates a comma-separated values (CSV) 
      compatible format to stdout.  The format is designed to simplify parsing 
      algorithms of other tools by quoting CSV special characters using a 
      common hexadecimal format.  Specifically, special characters or non-ascii 
      bytes are converted to "\xQQ" where QQ is the hexadecimal value for 
      the byte.
    </para>
  </refsect1>

  <refsect1 id='examples'>
    <title>EXAMPLES</title>
    <para>
      To read and print the contents of an entire system registry
      file: 
    </para>
    <para>
      <screen>
        reglookup /mnt/win/c/WINNT/system32/config/system
      </screen>
    </para>
    <para>
      To limit the output to just those entries under the Services
      key: 
    </para>
    <para>
      <screen>
        reglookup -p /ControlSet002/Services /mnt/win/c/WINNT/system32/config/system
      </screen>
    </para>
    <para>
      To limit the output to all registry values of type BINARY:
    </para>
    <para>
      <screen>
        reglookup -t BINARY /mnt/win/c/WINNT/system32/config/system
      </screen>
    </para>
    <para>
      And to limit the output to BINARY values under the Services key:
    </para>
    <para>
      <screen>
        reglookup -t BINARY -p /ControlSet002/Services /mnt/win/c/WINNT/system32/config/system
      </screen>
    </para>
  </refsect1>

  <refsect1 id='bugs'>
    <title>BUGS</title>
    <para>
      This program has only been tested on a few different systems.
      (Please report results to the development list if you test it 
      on Windows NT 4.0, 2003, or Vista registries.  Also, if you 
      test on any 64-bit architecture, please contact us.)
    </para>
    <para>
      Verbose output is not working.
    </para>
    <para>
      The SID conversions haven't been carefully checked for accuracy.
    </para>
    <para>
      The MTIME conversions appear correctly produce the stored UTC timestamp.
      However, due to the periodicity of registry writes, and the complexity
      of the conversion, a small amount of error (on the order of seconds) may
      be possible.  The documentation available online from Microsoft on 
      this field is very poor.
    </para>
    <para>
      Backslashes are currently considered special characters, to make 
      parsing easier for automated tools.  However, this causes paths 
      to be difficult to read.
    </para>
    <para>
      You'll notice that registry paths aren't all the same as the
      equivalents you see in the windows registry editor.  Don't ask me why 
      that is.  I just work here.
    </para>
    <para>
      This software should be considered unstable at this time.
    </para>
  </refsect1>

  <refsect1 id='credits'>
    <title>CREDITS</title>
    <para>
      This program was initially based on editreg.c by 
      Richard Sharpe.  It has since been rewritten to use a modified
      version the regfio library written by Gerald Carter.  Heavy
      modifications to the library and the original command line
      interface have been done by Timothy D. Morgan.
    </para>
    <para>
      Please see source code for a full list of copyrights.
    </para>
  </refsect1>

  <refsect1 id='license'>
    <title>LICENSE</title>
    <para>
      Please see the file "LICENSE" included with this software
      distribution.
    </para>
    <para>      
      This program is distributed in the hope that it will be useful,
      but WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      GNU General Public License version 2 for more details.
    </para>
  </refsect1>

  <refsect1 id='seealso'>
    <title>SEE ALSO</title>
    <para>
      reglookup-timeline(1)
    </para>
  </refsect1>
</refentry>