path: root/sh/hivexsh.pod

=encoding utf8

=head1 NAME

hivexsh - Windows Registry hive shell

=head1 SYNOPSIS

 hivexsh [-options] [hivefile]

=head1 DESCRIPTION

This program provides a simple shell for navigating Windows Registry
'hive' files.  It uses the hivex library for access to these binary
files.

Firstly you will need to provide a hive file from a Windows operating
system.  The hive files are usually located in
C<C:\Windows\System32\Config> and have names like C<software>,
C<system> etc (without any file extension).  For more information
about hive files, read L<hivex(3)>.  For information about downloading
files from virtual machines, read L<virt-cat(1)> and L<guestfish(1)>.

You can provide the name of the hive file to examine on the command
line.  For example:

 hivexsh software

Or you can start C<hivexsh> without any arguments, and immediately use
the C<load> command to load a hive:

 $ hivexsh
 
 Welcome to hivexsh, the hivex interactive shell for examining
 Windows Registry binary hive files.
 
 Type: 'help' for help with commands
       'quit' to quit the shell
 
 > load software
 software\>

Navigate through the hive's keys using the C<cd> command, as if it
contained a filesystem, and use C<ls> to list the subkeys of the
current key.  Other commands are listed below.

=head1 OPTIONS

=over 4

=item B<-d>

Enable lots of debug messages.  If you find a Registry file that this
program cannot parse, please enable this option and post the complete
output I<and> the Registry hive file in your bug report.

=item B<-f> filename

Read commands from C<filename> instead of stdin.  To write a hivexsh
script, use:

 #!/usr/bin/hivexsh -f

=item B<-w>

If this option is given, then writes are allowed to the hive
(see L</commit> command below, and the discussion of
modifying hives in L<hivex(3)/WRITING TO HIVE FILES>).

B<Important Note:> Even if you specify this option, nothing is written
to a hive unless you call the L</commit> command.  If you exit the
shell without committing, all changes will be discarded.

If this option is not given, then write commands are disabled.

=back

=head1 COMMANDS

=over 4

=item B<add> name

Add a subkey named C<name> below the current node.  The name may
contain spaces and punctuation characters, and does not need to be
quoted.

The new key will have no subkeys and no values (see C<setval>).

There must be no existing subkey called C<name>, or this command will
fail.  To replace an existing subkey, delete it first like this:

 cd name
 del

=item B<cd> path

Change to the subkey C<path>.  Use Windows-style backslashes to
separate path elements, and start with a backslash in order to start
from the root of the hive.  For example:

 cd \Classes\*

moves from the root node, to the C<Classes> node, to the C<*> node.
If you were already at the root node, you could do this instead:

 cd Classes\*

or even:

 cd Classes
 cd *

Path elements (node names) are matched case insensitively, and
characters like space, C<*>, and C<?> have I<no> special significance.

C<cd ..> may be used to go to the parent directory.

C<cd> without any arguments prints the current path.

Be careful with C<cd \> since the readline library has an undocumented
behaviour where it will think the final backslash is a continuation
(it reads the next line of input and appends it).  Put a single space
after the backslash.

=item B<close> | B<unload>

Close the currently loaded hive.

If you modified the hive, all uncommitted writes are lost when you
call this command (or if the shell exits).  You have to call C<commit>
to write changes.

=item B<commit> [newfile]

Commit changes to the hive.  If the optional C<newfile> parameter is
supplied, then the hive is written to that file, else the original
file is overwritten.

Note that you have to specify the C<-w> flag, otherwise no writes are
allowed.

=item B<del>

Delete the current node and everything beneath it.  The current
directory is moved up one level (as if you did C<cd ..>) after
this command.

You cannot delete the root node.

=item B<exit> | B<quit>

Exit the shell.

=item B<load> hivefile

Load the binary hive named C<hivefile>.  The currently loaded hive, if
any, is closed.  The current directory is changed back to the root
node.

=item B<ls>

List the subkeys of the current hive Registry key.  Note this command
does not take any arguments.

=item B<lsval> [key]

List the (key, value) pairs of the current hive Registry key.  If no
argument is given then all pairs are displayed.  If C<key> is given,
then the value of the named key is displayed.  If C<@> is given, then
the value of the default key is displayed.

=item B<setval> nrvals

This command replaces all (key, value) pairs at the current node with
the values in subsequent input.  C<nrvals> is the number of values
(ie. (key, value) pairs), and any existing values at this node are
deleted.  So C<setval 0> just deletes any values at the current node.

The command reads 2 * nrvals lines of input, with each pair of
lines of input corresponding to a key and a value to add.

For example, the following setval command replaces whatever is at the
current node with two (key, value) pairs.  The default key is set to
the UTF16-LE-encoded string "abcd".  The other value is named
"ANumber" and is a little-endian DWORD 0x12345678.

 setval 2
 @
 string:abcd
 ANumber
 dword:12345678

The first line of each pair is the key (the special key C<@> means
the default key, but you can also use a blank line).

The second line of each pair is the value, which has a special format
C<type:value> with possible types summarized in the table below:

 none                 No data is stored, and the type is set to 0.
 
 string:abc           "abc" is stored as a UTF16-LE-encoded
                      string (type 1).  Note that only 7 bit
                      ASCII strings are supported as input.
 
 expandstring:...     Same as string but with type 2.
 
 dword:0x01234567     A DWORD (type 4) with the hex value
                      0x01234567.  You can also use decimal
                      or octal numbers here.
 
 qword:0x0123456789abcdef
                      A QWORD (type 11) with the hex value
                      0x0123456789abcdef.  You can also use
                      decimal or octal numbers here.
 
 hex:<type>:<hexbytes>
 hex:1:41,00,42,00,43,00,44,00,00,00
                      This is the generic way to enter any
                      value.  <type> is the integer value type.
                      <hexbytes> is a list of pairs of hex
                      digits which are treated as bytes.
                      (Any non-hex-digits here are ignored,
                      so you can separate bytes with commas
                      or spaces if you want).

=back

=head1 EXAMPLE

 $ guestfish --ro -i Windows7
 ><fs> download win:c:\windows\system32\config\software software
 ><fs> quit
 
 $ hivexsh software
 
 Welcome to hivexsh, the hivex interactive shell for examining
 Windows Registry binary hive files.
 
 Type: 'help' for help with commands
       'quit' to quit the shell
 
 software\> ls
 ATI Technologies
 Classes
 Clients
 Intel
 Microsoft
 ODBC
 Policies
 RegisteredApplications
 Sonic
 Wow6432Node
 software\> quit

=head1 SEE ALSO

L<hivex(3)>,
L<hivexget(1)>,
L<hivexml(1)>,
L<virt-win-reg(1)>,
L<guestfs(3)>,
L<http://libguestfs.org/>,
L<virt-cat(1)>,
L<virt-edit(1)>.

=head1 AUTHORS

Richard W.M. Jones (C<rjones at redhat dot com>)

=head1 COPYRIGHT

Copyright (C) 2009-2010 Red Hat Inc.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

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 for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.