1virt-win-reg(1) Virtualization Support virt-win-reg(1)
2
6 virt-win-reg - Export and merge Windows Registry entries from a Windows
7 guest
8
10 virt-win-reg domname 'HKLM\Path\To\Subkey'
11 virt-win-reg domname 'HKLM\Path\To\Subkey' name
13 virt-win-reg domname 'HKLM\Path\To\Subkey' @
15 virt-win-reg --merge domname [input.reg ...]
17 virt-win-reg [--options] disk.img ... # instead of domname
19
21 You must not use "virt-win-reg" with the "--merge" option on live
22 virtual machines. If you do this, you will get irreversible disk
23 corruption in the VM. "virt-win-reg" tries to stop you from doing
24 this, but doesn't catch all cases.
25 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
32 This program can export and merge Windows Registry entries from a
33 Windows guest.
34 The first parameter is the libvirt guest name or the raw disk image of
36 a Windows guest.
37 If "--merge" is not specified, then the chosen registry key is
39 displayed/exported (recursively). For example:
40 $ virt-win-reg Windows7 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft'
42 You can also display single values from within registry keys, for
44 example:
45 $ cvkey='HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion'
47 $ virt-win-reg Windows7 $cvkey ProductName
48 Windows 7 Enterprise
49 With "--merge", you can merge a textual regedit file into the Windows
51 Registry:
52 $ virt-win-reg --merge Windows7 changes.reg
54 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
63 --help
64 Display brief help.
65 --version
67 Display version number and exit.
68 --debug
70 Enable debugging messages.
71 --connect URI | -c URI
73 If using libvirt, connect to the given URI. If omitted, then we
74 connect to the default libvirt hypervisor.
75 If you specify guest block devices directly, then libvirt is not
77 used at all.
78 --format raw
80 Specify the format of disk images given on the command line. If
81 this is omitted then the format is autodetected from the content of
82 the disk image.
83 If disk images are requested from libvirt, then this program asks
85 libvirt for this information. In this case, the value of the
86 format parameter is ignored.
87 If working with untrusted raw-format guest disk images, you should
89 ensure the format is always specified.
90 --merge
92 In merge mode, this merges a textual regedit file into the Windows
93 Registry of the virtual machine. If this flag is not given then
94 virt-win-reg displays or exports Registry entries instead.
95 Note that "--merge" is unsafe to use on live virtual machines, and
97 will result in disk corruption. However exporting (without this
98 flag) is always safe.
99 --encoding UTF-16LE|ASCII
101 When merging (only), you may need to specify the encoding for
102 strings to be used in the hive file. This is explained in detail
103 in "ENCODING STRINGS" in Win::Hivex::Regedit(3).
104 The default is to use UTF-16LE, which should work with recent
106 versions of Windows.
107
109 The program currently supports Windows NT-derived guests starting with
110 Windows XP through to at least Windows 7.
111 Registry support is done for "HKEY_LOCAL_MACHINE\SAM",
113 "HKEY_LOCAL_MACHINE\SECURITY", "HKEY_LOCAL_MACHINE\SOFTWARE",
114 "HKEY_LOCAL_MACHINE\SYSTEM" and "HKEY_USERS\.DEFAULT".
115 You can use "HKLM" as a shorthand for "HKEY_LOCAL_MACHINE", and "HKU"
117 for "HKEY_USERS".
118 "HKEY_USERS\$SID" and "HKEY_CURRENT_USER" are not supported at this
120 time.
121
123 "virt-win-reg" expects that regedit files have already been reencoded
124 in the local encoding. Usually on Linux hosts, this means UTF-8 with
125 Unix-style line endings. Since Windows regedit files are often in
126 UTF-16LE with Windows-style line endings, you may need to reencode the
127 whole file before or after processing.
128 To reencode a file from Windows format to Linux (before processing it
130 with the "--merge" option), you would do something like this:
131 iconv -f utf-16le -t utf-8 < win.reg | dos2unix > linux.reg
133 To go in the opposite direction, after exporting and before sending the
135 file to a Windows user, do something like this:
136 unix2dos linux.reg | iconv -f utf-8 -t utf-16le > win.reg
138 For more information about encoding, see Win::Hivex::Regedit(3).
140 If you are unsure about the current encoding, use the file(1) command.
142 Recent versions of Windows regedit.exe produce a UTF-16LE file with
143 Windows-style (CRLF) line endings, like this:
144 $ file software.reg
146 software.reg: Little-endian UTF-16 Unicode text, with very long lines,
147 with CRLF line terminators
148 This file would need conversion before you could "--merge" it.
150
152 Registry keys like "CurrentControlSet" don't really exist in the
153 Windows Registry at the level of the hive file, and therefore you
154 cannot modify these.
155 "CurrentControlSet" is usually an alias for "ControlSet001". In some
157 circumstances it might refer to another control set. The way to find
158 out is to look at the "HKLM\SYSTEM\Select" key:
159 # virt-win-reg WindowsGuest 'HKLM\SYSTEM\Select'
161 [HKEY_LOCAL_MACHINE\SYSTEM\Select]
162 "Current"=dword:00000001
163 "Default"=dword:00000001
164 "Failed"=dword:00000000
165 "LastKnownGood"=dword:00000002
166 "Current" is the one which Windows will choose when it boots.
168 Similarly, other "Current..." keys in the path may need to be replaced.
170
172 Note that some of these tips modify the guest disk image. The guest
173 must be shut off, else you will get disk corruption.
174 RUNNING A BATCH SCRIPT WHEN A USER LOGS IN
176 Prepare a DOS batch script, VBScript or executable. Upload this using
177 guestfish(1). For this example the script is called "test.bat" and it
178 is uploaded into "C:\":
179 guestfish -i -d WindowsGuest upload test.bat /test.bat
181 Prepare a regedit file containing the registry change:
183 cat > test.reg <<'EOF'
185 [HKLM\Software\Microsoft\Windows\CurrentVersion\RunOnce]
186 "Test"="c:\\test.bat"
187 EOF
188 In this example we use the key "RunOnce" which means that the script
190 will run precisely once when the first user logs in. If you want it to
191 run every time a user logs in, replace "RunOnce" with "Run".
192 Now update the registry:
194 virt-win-reg --merge WindowsGuest test.reg
196 INSTALLING A SERVICE
198 This section assumes you are familiar with Windows services, and you
199 either have a program which handles the Windows Service Control
200 Protocol directly or you want to run any program using a service
201 wrapper like SrvAny or the free RHSrvAny.
202 First upload the program and optionally the service wrapper. In this
204 case the test program is called "test.exe" and we are using the
205 RHSrvAny wrapper:
206 guestfish -i -d WindowsGuest <<EOF
208 upload rhsrvany.exe /rhsrvany.exe
209 upload test.exe /test.exe
210 EOF
211 Prepare a regedit file containing the registry changes. In this
213 example, the first registry change is needed for the service itself or
214 the service wrapper (if used). The second registry change is only
215 needed because I am using the RHSrvAny service wrapper.
216 cat > service.reg <<'EOF'
218 [HKLM\SYSTEM\ControlSet001\services\RHSrvAny]
219 "Type"=dword:00000010
220 "Start"=dword:00000002
221 "ErrorControl"=dword:00000001
222 "ImagePath"="c:\\rhsrvany.exe"
223 "DisplayName"="RHSrvAny"
224 "ObjectName"="NetworkService"
225 [HKLM\SYSTEM\ControlSet001\services\RHSrvAny\Parameters]
227 "CommandLine"="c:\\test.exe"
228 "PWD"="c:\\Temp"
229 EOF
230 Notes:
232 · For use of "ControlSet001" see the section above in this manual
234 page. You may need to adjust this according to the control set
235 that is in use by the guest.
236 · "ObjectName" controls the privileges that the service will have.
238 An alternative is "ObjectName"="LocalSystem" which would be the
239 most privileged account.
240 · For the meaning of the magic numbers, see this Microsoft KB
242 article: <http://support.microsoft.com/kb/103000>.
243 Update the registry:
245 virt-win-reg --merge WindowsGuest service.reg
247
249 Be careful when passing parameters containing "\" (backslash) in the
250 shell. Usually you will have to use 'single quotes' or double
251 backslashes (but not both) to protect them from the shell.
252 Paths and value names are case-insensitive.
254 Libvirt guest names can contain arbitrary characters, some of which
256 have meaning to the shell such as "#" and space. You may need to quote
257 or escape these characters on the command line. See the shell manual
258 page sh(1) for details.
259
261 hivex(3), hivexsh(1), hivexregedit(1), guestfs(3), guestfish(1),
262 virt-cat(1), Sys::Guestfs(3), Sys::Guestfs::Lib(3), Win::Hivex(3),
263 Win::Hivex::Regedit(3), Sys::Virt(3), <http://libguestfs.org/>.
264
266 When reporting bugs, please enable debugging and capture the complete
267 output:
268 export LIBGUESTFS_DEBUG=1
270 virt-win-reg --debug [... rest ...] > /tmp/virt-win-reg.log 2>&1
271 Attach /tmp/virt-win-reg.log to a new bug report at
273 <https://bugzilla.redhat.com/>
274
276 Richard W.M. Jones <http://people.redhat.com/~rjones/>
277
279 Copyright (C) 2010 Red Hat Inc.
280 This program is free software; you can redistribute it and/or modify it
282 under the terms of the GNU General Public License as published by the
283 Free Software Foundation; either version 2 of the License, or (at your
284 option) any later version.
285 This program is distributed in the hope that it will be useful, but
287 WITHOUT ANY WARRANTY; without even the implied warranty of
288 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
289 General Public License for more details.
290 You should have received a copy of the GNU General Public License along
292 with this program; if not, write to the Free Software Foundation, Inc.,
293 675 Mass Ave, Cambridge, MA 02139, USA.
294libguestfs-1.8.15 2011-11-10 virt-win-reg(1)