1virt-win-reg(1)             Virtualization Support             virt-win-reg(1)
2
3
4

NAME

6       virt-win-reg - Export and merge Windows Registry entries from a Windows
7       guest
8

SYNOPSIS

10        virt-win-reg domname 'HKLM\Path\To\Subkey'
11
12        virt-win-reg domname 'HKLM\Path\To\Subkey' name
13
14        virt-win-reg domname 'HKLM\Path\To\Subkey' @
15
16        virt-win-reg --merge domname [input.reg ...]
17
18        virt-win-reg [--options] disk.img ... # instead of domname
19

WARNING

21       You must not use "virt-win-reg" with the --merge option on live virtual
22       machines.  If you do this, you will get irreversible disk corruption in
23       the VM.  "virt-win-reg" tries to stop you from doing this, but doesn't
24       catch all cases.
25
26       Modifying the Windows Registry is an inherently risky operation.  The
27       format is deliberately obscure and undocumented, and Registry changes
28       can leave the system unbootable.  Therefore when using the --merge
29       option, make sure you have a reliable backup first.
30

DESCRIPTION

32       This program can export and merge Windows Registry entries from a
33       Windows guest.
34
35       The first parameter is the libvirt guest name or the raw disk image of
36       a Windows guest.
37
38       If --merge is not specified, then the chosen registry key is
39       displayed/exported (recursively).  For example:
40
41        $ virt-win-reg Windows7 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft'
42
43       You can also display single values from within registry keys, for
44       example:
45
46        $ cvkey='HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion'
47        $ virt-win-reg Windows7 $cvkey ProductName
48        Windows 7 Enterprise
49
50       With --merge, you can merge a textual regedit file into the Windows
51       Registry:
52
53        $ virt-win-reg --merge Windows7 changes.reg
54
55   NOTE
56       This program is only meant for simple access to the registry.  If you
57       want to do complicated things with the registry, we suggest you
58       download the Registry hive files from the guest using libguestfs(3) or
59       guestfish(1) and access them locally, eg. using hivex(3), hivexsh(1) or
60       hivexregedit(1).
61

OPTIONS

63       --help
64           Display brief help.
65
66       --version
67           Display version number and exit.
68
69       --debug
70           Enable debugging messages.
71
72       -c URI
73       --connect URI
74           If using libvirt, connect to the given URI.  If omitted, then we
75           connect to the default libvirt hypervisor.
76
77           If you specify guest block devices directly, then libvirt is not
78           used at all.
79
80       --format raw
81           Specify the format of disk images given on the command line.  If
82           this is omitted then the format is autodetected from the content of
83           the disk image.
84
85           If disk images are requested from libvirt, then this program asks
86           libvirt for this information.  In this case, the value of the
87           format parameter is ignored.
88
89           If working with untrusted raw-format guest disk images, you should
90           ensure the format is always specified.
91
92       --merge
93           In merge mode, this merges a textual regedit file into the Windows
94           Registry of the virtual machine.  If this flag is not given then
95           virt-win-reg displays or exports Registry entries instead.
96
97           Note that --merge is unsafe to use on live virtual machines, and
98           will result in disk corruption.  However exporting (without this
99           flag) is always safe.
100
101       --encoding UTF-16LE|ASCII
102           When merging (only), you may need to specify the encoding for
103           strings to be used in the hive file.  This is explained in detail
104           in "ENCODING STRINGS" in Win::Hivex::Regedit(3).
105
106           The default is to use UTF-16LE, which should work with recent
107           versions of Windows.
108
109       --unsafe-printable-strings
110           When exporting (only), assume strings are UTF-16LE and print them
111           as strings instead of hex sequences.  Remove the final zero
112           codepoint from strings if present.
113
114           This is unsafe and does not preserve the fidelity of strings in the
115           original Registry for various reasons:
116
117           ·   Assumes the original encoding is UTF-16LE.  ASCII strings and
118               strings in other encodings will be corrupted by this
119               transformation.
120
121           ·   Assumes that everything which has type 1 or 2 is really a
122               string and that everything else is not a string, but the type
123               field in real Registries is not reliable.
124
125           ·   Loses information about whether a zero codepoint followed the
126               string in the Registry or not.
127
128           This all happens because the Registry itself contains no
129           information about how strings are encoded (see "ENCODING STRINGS"
130           in Win::Hivex::Regedit(3)).
131
132           You should only use this option for quick hacking and debugging of
133           the Registry contents, and never use it if the output is going to
134           be passed into another program or stored in another Registry.
135

SUPPORTED SYSTEMS

137       The program currently supports Windows NT-derived guests starting with
138       Windows XP through to at least Windows 8.
139
140       The following Registry keys are supported:
141
142       "HKEY_LOCAL_MACHINE\SAM"
143       "HKEY_LOCAL_MACHINE\SECURITY"
144       "HKEY_LOCAL_MACHINE\SOFTWARE"
145       "HKEY_LOCAL_MACHINE\SYSTEM"
146       "HKEY_USERS\.DEFAULT"
147       "HKEY_USERS\SID"
148           where SID is a Windows User SID (eg. "S-1-5-18").
149
150       "HKEY_USERS\username"
151           where username is a local user name (this is a libguestfs
152           extension).
153
154       You can use "HKLM" as a shorthand for "HKEY_LOCAL_MACHINE", and "HKU"
155       for "HKEY_USERS".
156
157       The literal keys "HKEY_USERS\$SID" and "HKEY_CURRENT_USER" are not
158       supported (there is no "current user").
159
160   WINDOWS 8
161       Windows 8 "fast startup" can prevent virt-win-reg from being able to
162       edit the Registry.  See "WINDOWS HIBERNATION AND WINDOWS 8 FAST
163       STARTUP" in guestfs(3).
164

ENCODING

166       "virt-win-reg" expects that regedit files have already been reencoded
167       in the local encoding.  Usually on Linux hosts, this means UTF-8 with
168       Unix-style line endings.  Since Windows regedit files are often in
169       UTF-16LE with Windows-style line endings, you may need to reencode the
170       whole file before or after processing.
171
172       To reencode a file from Windows format to Linux (before processing it
173       with the --merge option), you would do something like this:
174
175        iconv -f utf-16le -t utf-8 < win.reg | dos2unix > linux.reg
176
177       To go in the opposite direction, after exporting and before sending the
178       file to a Windows user, do something like this:
179
180        unix2dos linux.reg | iconv -f utf-8 -t utf-16le > win.reg
181
182       For more information about encoding, see Win::Hivex::Regedit(3).
183
184       If you are unsure about the current encoding, use the file(1) command.
185       Recent versions of Windows regedit.exe produce a UTF-16LE file with
186       Windows-style (CRLF) line endings, like this:
187
188        $ file software.reg
189        software.reg: Little-endian UTF-16 Unicode text, with very long lines,
190        with CRLF line terminators
191
192       This file would need conversion before you could --merge it.
193

CurrentControlSet etc.

195       Registry keys like "CurrentControlSet" don’t really exist in the
196       Windows Registry at the level of the hive file, and therefore you
197       cannot modify these.
198
199       "CurrentControlSet" is usually an alias for "ControlSet001".  In some
200       circumstances it might refer to another control set.  The way to find
201       out is to look at the "HKLM\SYSTEM\Select" key:
202
203        # virt-win-reg WindowsGuest 'HKLM\SYSTEM\Select'
204        [HKEY_LOCAL_MACHINE\SYSTEM\Select]
205        "Current"=dword:00000001
206        "Default"=dword:00000001
207        "Failed"=dword:00000000
208        "LastKnownGood"=dword:00000002
209
210       "Current" is the one which Windows will choose when it boots.
211
212       Similarly, other "Current..." keys in the path may need to be replaced.
213

DELETING REGISTRY KEYS AND VALUES

215       To delete a whole registry key, use the syntax:
216
217        [-HKEY_LOCAL_MACHINE\Foo]
218
219       To delete a single value within a key, use the syntax:
220
221        [HKEY_LOCAL_MACHINE\Foo]
222        "Value"=-
223

WINDOWS TIPS

225       Note that some of these tips modify the guest disk image.  The guest
226       must be shut off, else you will get disk corruption.
227
228   RUNNING A BATCH SCRIPT WHEN A USER LOGS IN
229       Prepare a DOS batch script, VBScript or executable.  Upload this using
230       guestfish(1).  For this example the script is called "test.bat" and it
231       is uploaded into "C:\":
232
233        guestfish -i -d WindowsGuest upload test.bat /test.bat
234
235       Prepare a regedit file containing the registry change:
236
237        cat > test.reg <<'EOF'
238        [HKLM\Software\Microsoft\Windows\CurrentVersion\RunOnce]
239        "Test"="c:\\test.bat"
240        EOF
241
242       In this example we use the key "RunOnce" which means that the script
243       will run precisely once when the first user logs in.  If you want it to
244       run every time a user logs in, replace "RunOnce" with "Run".
245
246       Now update the registry:
247
248        virt-win-reg --merge WindowsGuest test.reg
249
250   INSTALLING A SERVICE
251       This section assumes you are familiar with Windows services, and you
252       either have a program which handles the Windows Service Control
253       Protocol directly or you want to run any program using a service
254       wrapper like SrvAny or the free RHSrvAny.
255
256       First upload the program and optionally the service wrapper.  In this
257       case the test program is called "test.exe" and we are using the
258       RHSrvAny wrapper:
259
260        guestfish -i -d WindowsGuest <<EOF
261          upload rhsrvany.exe /rhsrvany.exe
262          upload test.exe /test.exe
263        EOF
264
265       Prepare a regedit file containing the registry changes.  In this
266       example, the first registry change is needed for the service itself or
267       the service wrapper (if used).  The second registry change is only
268       needed because I am using the RHSrvAny service wrapper.
269
270        cat > service.reg <<'EOF'
271        [HKLM\SYSTEM\ControlSet001\services\RHSrvAny]
272        "Type"=dword:00000010
273        "Start"=dword:00000002
274        "ErrorControl"=dword:00000001
275        "ImagePath"="c:\\rhsrvany.exe"
276        "DisplayName"="RHSrvAny"
277        "ObjectName"="NetworkService"
278
279        [HKLM\SYSTEM\ControlSet001\services\RHSrvAny\Parameters]
280        "CommandLine"="c:\\test.exe"
281        "PWD"="c:\\Temp"
282        EOF
283
284       Notes:
285
286       ·   For use of "ControlSet001" see the section above in this manual
287           page.  You may need to adjust this according to the control set
288           that is in use by the guest.
289
290       ·   "ObjectName" controls the privileges that the service will have.
291           An alternative is "ObjectName"="LocalSystem" which would be the
292           most privileged account.
293
294       ·   For the meaning of the magic numbers, see this Microsoft KB
295           article: http://support.microsoft.com/kb/103000.
296
297       Update the registry:
298
299        virt-win-reg --merge WindowsGuest service.reg
300

SHELL QUOTING

302       Be careful when passing parameters containing "\" (backslash) in the
303       shell.  Usually you will have to use 'single quotes' or double
304       backslashes (but not both) to protect them from the shell.
305
306       Paths and value names are case-insensitive.
307

SEE ALSO

309       hivex(3), hivexsh(1), hivexregedit(1), guestfs(3), guestfish(1),
310       virt-cat(1), virt-tail(1), Sys::Guestfs(3), Win::Hivex(3),
311       Win::Hivex::Regedit(3), Sys::Virt(3), http://libguestfs.org/.
312

AUTHOR

314       Richard W.M. Jones http://people.redhat.com/~rjones/
315
317       Copyright (C) 2010 Red Hat Inc.
318

LICENSE

320       This program is free software; you can redistribute it and/or modify it
321       under the terms of the GNU General Public License as published by the
322       Free Software Foundation; either version 2 of the License, or (at your
323       option) any later version.
324
325       This program is distributed in the hope that it will be useful, but
326       WITHOUT ANY WARRANTY; without even the implied warranty of
327       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
328       General Public License for more details.
329
330       You should have received a copy of the GNU General Public License along
331       with this program; if not, write to the Free Software Foundation, Inc.,
332       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
333

BUGS

335       To get a list of bugs against libguestfs, use this link:
336       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
337
338       To report a new bug against libguestfs, use this link:
339       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
340
341       When reporting a bug, please supply:
342
343       ·   The version of libguestfs.
344
345       ·   Where you got libguestfs (eg. which Linux distro, compiled from
346           source, etc)
347
348       ·   Describe the bug accurately and give a way to reproduce it.
349
350       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
351           into the bug report.
352
353
354
355libguestfs-1.44.0                 2021-01-05                   virt-win-reg(1)
Impressum