Version 1.10.6.
[libguestfs.git] / fish / guestfish.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 guestfish - the libguestfs Filesystem Interactive SHell
6
7 =head1 SYNOPSIS
8
9  guestfish [--options] [commands]
10
11  guestfish
12
13  guestfish [--ro|--rw] -a disk.img
14
15  guestfish [--ro|--rw] -a disk.img -m dev[:mountpoint]
16
17  guestfish -d libvirt-domain
18
19  guestfish [--ro|--rw] -a disk.img -i
20
21  guestfish -d libvirt-domain -i
22
23 =head1 WARNING
24
25 Using guestfish in read/write mode on live virtual machines can be
26 dangerous, potentially causing disk corruption.  Use the I<--ro>
27 (read-only) option to use guestfish safely if the disk image or
28 virtual machine might be live.
29
30 =head1 DESCRIPTION
31
32 Guestfish is a shell and command-line tool for examining and modifying
33 virtual machine filesystems.  It uses libguestfs and exposes all of
34 the functionality of the guestfs API, see L<guestfs(3)>.
35
36 Guestfish gives you structured access to the libguestfs API, from
37 shell scripts or the command line or interactively.  If you want to
38 rescue a broken virtual machine image, you should look at the
39 L<virt-rescue(1)> command.
40
41 =head1 EXAMPLES
42
43 =head2 As an interactive shell
44
45  $ guestfish
46  
47  Welcome to guestfish, the libguestfs filesystem interactive shell for
48  editing virtual machine filesystems.
49  
50  Type: 'help' for a list of commands
51        'man' to read the manual
52        'quit' to quit the shell
53  
54  ><fs> add-ro disk.img
55  ><fs> run
56  ><fs> list-filesystems
57  /dev/sda1: ext4
58  /dev/vg_guest/lv_root: ext4
59  /dev/vg_guest/lv_swap: swap
60  ><fs> mount /dev/vg_guest/lv_root /
61  ><fs> cat /etc/fstab
62  # /etc/fstab
63  # Created by anaconda
64  [...]
65  ><fs> exit
66
67 =head2 From shell scripts
68
69 Create a new C</etc/motd> file in a guest or disk image:
70
71  guestfish <<_EOF_
72  add disk.img
73  run
74  mount /dev/vg_guest/lv_root /
75  write /etc/motd "Welcome, new users"
76  _EOF_
77
78 List the LVM logical volumes in a disk image:
79
80  guestfish -a disk.img --ro <<_EOF_
81  run
82  lvs
83  _EOF_
84
85 List all the filesystems in a disk image:
86
87  guestfish -a disk.img --ro <<_EOF_
88  run
89  list-filesystems
90  _EOF_
91
92 =head2 On one command line
93
94 Update C</etc/resolv.conf> in a guest:
95
96  guestfish \
97    add disk.img : run : mount /dev/vg_guest/lv_root / : \
98    write /etc/resolv.conf "nameserver 1.2.3.4"
99
100 Edit C</boot/grub/grub.conf> interactively:
101
102  guestfish --rw --add disk.img \
103    --mount /dev/vg_guest/lv_root \
104    --mount /dev/sda1:/boot \
105    edit /boot/grub/grub.conf
106
107 =head2 Mount disks automatically
108
109 Use the I<-i> option to automatically mount the
110 disks from a virtual machine:
111
112  guestfish --ro -a disk.img -i cat /etc/group
113
114  guestfish --ro -d libvirt-domain -i cat /etc/group
115
116 Another way to edit C</boot/grub/grub.conf> interactively is:
117
118  guestfish --rw -a disk.img -i edit /boot/grub/grub.conf
119
120 =head2 As a script interpreter
121
122 Create a 100MB disk containing an ext2-formatted partition:
123
124  #!/usr/bin/guestfish -f
125  sparse test1.img 100M
126  run
127  part-disk /dev/sda mbr
128  mkfs ext2 /dev/sda1
129
130 =head2 Start with a prepared disk
131
132 An alternate way to create a 100MB disk called C<test1.img> containing
133 a single ext2-formatted partition:
134
135  guestfish -N fs
136
137 To list what is available do:
138
139  guestfish -N help | less
140
141 =head2 Remote control
142
143  eval "`guestfish --listen`"
144  guestfish --remote add-ro disk.img
145  guestfish --remote run
146  guestfish --remote lvs
147
148 =head1 OPTIONS
149
150 =over 4
151
152 =item B<--help>
153
154 Displays general help on options.
155
156 =item B<-h>
157
158 =item B<--cmd-help>
159
160 Lists all available guestfish commands.
161
162 =item B<-h cmd>
163
164 =item B<--cmd-help cmd>
165
166 Displays detailed help on a single command C<cmd>.
167
168 =item B<-a image>
169
170 =item B<--add image>
171
172 Add a block device or virtual machine image to the shell.
173
174 The format of the disk image is auto-detected.  To override this and
175 force a particular format use the I<--format=..> option.
176
177 Using this flag is mostly equivalent to using the C<add> command,
178 with C<readonly:true> if the I<--ro> flag was given, and
179 with C<format:...> if the I<--format=...> flag was given.
180
181 =item B<-c URI>
182
183 =item B<--connect URI>
184
185 When used in conjunction with the I<-d> option, this specifies
186 the libvirt URI to use.  The default is to use the default libvirt
187 connection.
188
189 =item B<--csh>
190
191 If using the I<--listen> option and a csh-like shell, use this option.
192 See section L</REMOTE CONTROL AND CSH> below.
193
194 =item B<-d libvirt-domain>
195
196 =item B<--domain libvirt-domain>
197
198 Add disks from the named libvirt domain.  If the I<--ro> option is
199 also used, then any libvirt domain can be used.  However in write
200 mode, only libvirt domains which are shut down can be named here.
201
202 Using this flag is mostly equivalent to using the C<add-domain> command,
203 with C<readonly:true> if the I<--ro> flag was given, and
204 with C<format:...> if the I<--format:...> flag was given.
205
206 =item B<-D>
207
208 =item B<--no-dest-paths>
209
210 Don't tab-complete paths on the guest filesystem.  It is useful to be
211 able to hit the tab key to complete paths on the guest filesystem, but
212 this causes extra "hidden" guestfs calls to be made, so this option is
213 here to allow this feature to be disabled.
214
215 =item B<--echo-keys>
216
217 When prompting for keys and passphrases, guestfish normally turns
218 echoing off so you cannot see what you are typing.  If you are not
219 worried about Tempest attacks and there is no one else in the room
220 you can specify this flag to see what you are typing.
221
222 =item B<-f file>
223
224 =item B<--file file>
225
226 Read commands from C<file>.  To write pure guestfish
227 scripts, use:
228
229  #!/usr/bin/guestfish -f
230
231 =item B<--format=raw|qcow2|..>
232
233 =item B<--format>
234
235 The default for the I<-a> option is to auto-detect the format of the
236 disk image.  Using this forces the disk format for I<-a> options which
237 follow on the command line.  Using I<--format> with no argument
238 switches back to auto-detection for subsequent I<-a> options.
239
240 For example:
241
242  guestfish --format=raw -a disk.img
243
244 forces raw format (no auto-detection) for C<disk.img>.
245
246  guestfish --format=raw -a disk.img --format -a another.img
247
248 forces raw format (no auto-detection) for C<disk.img> and reverts to
249 auto-detection for C<another.img>.
250
251 If you have untrusted raw-format guest disk images, you should use
252 this option to specify the disk format.  This avoids a possible
253 security problem with malicious guests (CVE-2010-3851).  See also
254 L</add-drive-opts>.
255
256 =item B<-i>
257
258 =item B<--inspector>
259
260 Using L<virt-inspector(1)> code, inspect the disks looking for
261 an operating system and mount filesystems as they would be
262 mounted on the real virtual machine.
263
264 Typical usage is either:
265
266  guestfish -d myguest -i
267
268 (for an inactive libvirt domain called I<myguest>), or:
269
270  guestfish --ro -d myguest -i
271
272 (for active domains, readonly), or specify the block device directly:
273
274  guestfish --rw -a /dev/Guests/MyGuest -i
275
276 Note that the command line syntax changed slightly over older
277 versions of guestfish.  You can still use the old syntax:
278
279  guestfish [--ro] -i disk.img
280
281  guestfish [--ro] -i libvirt-domain
282
283 Using this flag is mostly equivalent to using the C<inspect-os>
284 command and then using other commands to mount the filesystems that
285 were found.
286
287 =item B<--keys-from-stdin>
288
289 Read key or passphrase parameters from stdin.  The default is
290 to try to read passphrases from the user by opening C</dev/tty>.
291
292 =item B<--listen>
293
294 Fork into the background and listen for remote commands.  See section
295 L</REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
296
297 =item B<--live>
298
299 Connect to a live virtual machine.
300 (Experimental, see L<guestfs(3)/ATTACHING TO RUNNING DAEMONS>).
301
302 =item B<-m dev[:mountpoint[:options]]>
303
304 =item B<--mount dev[:mountpoint[:options]]>
305
306 Mount the named partition or logical volume on the given mountpoint.
307
308 If the mountpoint is omitted, it defaults to C</>.
309
310 You have to mount something on C</> before most commands will work.
311
312 If any I<-m> or I<--mount> options are given, the guest is
313 automatically launched.
314
315 If you don't know what filesystems a disk image contains, you can
316 either run guestfish without this option, then list the partitions,
317 filesystems and LVs available (see L</list-partitions>,
318 L</list-filesystems> and L</lvs> commands), or you can use the
319 L<virt-filesystems(1)> program.
320
321 The third (and rarely used) part of the mount parameter is the list of
322 mount options used to mount the underlying filesystem.  If this is not
323 given, then the mount options are either the empty string or C<ro>
324 (the latter if the I<--ro> flag is used).  By specifying the mount
325 options, you override this default choice.  Probably the only time you
326 would use this is to enable ACLs and/or extended attributes if the
327 filesystem can support them:
328
329  -m /dev/sda1:/:acl,user_xattr
330
331 Using this flag is equivalent to using the C<mount-options> command.
332
333 =item B<-n>
334
335 =item B<--no-sync>
336
337 Disable autosync.  This is enabled by default.  See the discussion
338 of autosync in the L<guestfs(3)> manpage.
339
340 =item B<-N type>
341
342 =item B<--new type>
343
344 =item B<-N help>
345
346 Prepare a fresh disk image formatted as "type".  This is an
347 alternative to the I<-a> option: whereas I<-a> adds an existing disk,
348 I<-N> creates a preformatted disk with a filesystem and adds it.
349 See L</PREPARED DISK IMAGES> below.
350
351 =item B<--progress-bars>
352
353 Enable progress bars, even when guestfish is used non-interactively.
354
355 Progress bars are enabled by default when guestfish is used as an
356 interactive shell.
357
358 =item B<--no-progress-bars>
359
360 Disable progress bars.
361
362 =item B<--remote[=pid]>
363
364 Send remote commands to C<$GUESTFISH_PID> or C<pid>.  See section
365 L</REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
366
367 =item B<-r>
368
369 =item B<--ro>
370
371 This changes the I<-a>, I<-d> and I<-m> options so that disks are
372 added and mounts are done read-only.
373
374 The option must always be used if the disk image or virtual machine
375 might be running, and is generally recommended in cases where you
376 don't need write access to the disk.
377
378 Note that prepared disk images created with I<-N> are not affected by
379 this option.  Also commands like C<add> are not affected - you have to
380 specify the C<readonly:true> option explicitly if you need it.
381
382 See also L</OPENING DISKS FOR READ AND WRITE> below.
383
384 =item B<--selinux>
385
386 Enable SELinux support for the guest.  See L<guestfs(3)/SELINUX>.
387
388 =item B<-v>
389
390 =item B<--verbose>
391
392 Enable very verbose messages.  This is particularly useful if you find
393 a bug.
394
395 =item B<-V>
396
397 =item B<--version>
398
399 Display the guestfish / libguestfs version number and exit.
400
401 =item B<-w>
402
403 =item B<--rw>
404
405 This changes the I<-a>, I<-d> and I<-m> options so that disks are
406 added and mounts are done read-write.
407
408 See L</OPENING DISKS FOR READ AND WRITE> below.
409
410 =item B<-x>
411
412 Echo each command before executing it.
413
414 =back
415
416 =head1 COMMANDS ON COMMAND LINE
417
418 Any additional (non-option) arguments are treated as commands to
419 execute.
420
421 Commands to execute should be separated by a colon (C<:>), where the
422 colon is a separate parameter.  Thus:
423
424  guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
425
426 If there are no additional arguments, then we enter a shell, either an
427 interactive shell with a prompt (if the input is a terminal) or a
428 non-interactive shell.
429
430 In either command line mode or non-interactive shell, the first
431 command that gives an error causes the whole shell to exit.  In
432 interactive mode (with a prompt) if a command fails, you can continue
433 to enter commands.
434
435 =head1 USING launch (OR run)
436
437 As with L<guestfs(3)>, you must first configure your guest by adding
438 disks, then launch it, then mount any disks you need, and finally
439 issue actions/commands.  So the general order of the day is:
440
441 =over 4
442
443 =item *
444
445 add or -a/--add
446
447 =item *
448
449 launch (aka run)
450
451 =item *
452
453 mount or -m/--mount
454
455 =item *
456
457 any other commands
458
459 =back
460
461 C<run> is a synonym for C<launch>.  You must C<launch> (or C<run>)
462 your guest before mounting or performing any other commands.
463
464 The only exception is that if any of the I<-i>, I<-m>, I<--mount>,
465 I<-N> or I<--new> options were given then C<run> is done
466 automatically, simply because guestfish can't perform the action you
467 asked for without doing this.
468
469 =head1 OPENING DISKS FOR READ AND WRITE
470
471 The guestfish, L<guestmount(1)> and L<virt-rescue(1)> options I<--ro>
472 and I<--rw> affect whether the other command line options I<-a>,
473 I<-c>, I<-d>, I<-i> and I<-m> open disk images read-only or for
474 writing.
475
476 In libguestfs E<le> 1.10, guestfish, guestmount and virt-rescue
477 defaulted to opening disk images supplied on the command line for
478 write.  To open a disk image read-only you have to do I<-a image --ro>.
479
480 This matters: If you accidentally open a live VM disk image writable
481 then you will cause irreversible disk corruption.
482
483 By libguestfs 1.12 we intend to change the default the other way.
484 Disk images will be opened read-only.  You will have to either specify
485 I<guestfish --rw>, I<guestmount --rw>, I<virt-rescue --rw>, or change
486 the configuration file C</etc/libguestfs-tools.conf> in order to get
487 write access for disk images specified by those other command line
488 options.
489
490 This version of guestfish, guestmount and virt-rescue has a I<--rw>
491 option which does nothing (it is already the default).  However it is
492 highly recommended that you use this option to indicate that you need
493 write access, and prepare your scripts for the day when this option
494 will be required for write access.
495
496 B<Note:> This does I<not> affect commands like L</add> and L</mount>,
497 or any other libguestfs program apart from guestfish and guestmount.
498
499 =head1 QUOTING
500
501 You can quote ordinary parameters using either single or double
502 quotes.  For example:
503
504  add "file with a space.img"
505
506  rm '/file name'
507
508  rm '/"'
509
510 A few commands require a list of strings to be passed.  For these, use
511 a whitespace-separated list, enclosed in quotes.  Strings containing whitespace
512 to be passed through must be enclosed in single quotes.  A literal single quote
513 must be escaped with a backslash.
514
515  vgcreate VG "/dev/sda1 /dev/sdb1"
516  command "/bin/echo 'foo      bar'"
517  command "/bin/echo \'foo\'"
518
519 =head1 OPTIONAL ARGUMENTS
520
521 Some commands take optional arguments.  These arguments appear in this
522 documentation as C<[argname:..]>.  You can use them as in these
523 examples:
524
525  add-drive-opts filename
526
527  add-drive-opts filename readonly:true
528
529  add-drive-opts filename format:qcow2 readonly:false
530
531 Each optional argument can appear at most once.  All optional
532 arguments must appear after the required ones.
533
534 =head1 NUMBERS
535
536 This section applies to all commands which can take integers
537 as parameters.
538
539 =head2 SIZE SUFFIX
540
541 When the command takes a parameter measured in bytes, you can use one
542 of the following suffixes to specify kilobytes, megabytes and larger
543 sizes:
544
545 =over 4
546
547 =item B<k> or B<K> or B<KiB>
548
549 The size in kilobytes (multiplied by 1024).
550
551 =item B<KB>
552
553 The size in SI 1000 byte units.
554
555 =item B<M> or B<MiB>
556
557 The size in megabytes (multiplied by 1048576).
558
559 =item B<MB>
560
561 The size in SI 1000000 byte units.
562
563 =item B<G> or B<GiB>
564
565 The size in gigabytes (multiplied by 2**30).
566
567 =item B<GB>
568
569 The size in SI 10**9 byte units.
570
571 =item B<T> or B<TiB>
572
573 The size in terabytes (multiplied by 2**40).
574
575 =item B<TB>
576
577 The size in SI 10**12 byte units.
578
579 =item B<P> or B<PiB>
580
581 The size in petabytes (multiplied by 2**50).
582
583 =item B<PB>
584
585 The size in SI 10**15 byte units.
586
587 =item B<E> or B<EiB>
588
589 The size in exabytes (multiplied by 2**60).
590
591 =item B<EB>
592
593 The size in SI 10**18 byte units.
594
595 =item B<Z> or B<ZiB>
596
597 The size in zettabytes (multiplied by 2**70).
598
599 =item B<ZB>
600
601 The size in SI 10**21 byte units.
602
603 =item B<Y> or B<YiB>
604
605 The size in yottabytes (multiplied by 2**80).
606
607 =item B<YB>
608
609 The size in SI 10**24 byte units.
610
611 =back
612
613 For example:
614
615  truncate-size /file 1G
616
617 would truncate the file to 1 gigabyte.
618
619 Be careful because a few commands take sizes in kilobytes or megabytes
620 (eg. the parameter to L</memsize> is specified in megabytes already).
621 Adding a suffix will probably not do what you expect.
622
623 =head2 OCTAL AND HEXADECIMAL NUMBERS
624
625 For specifying the radix (base) use the C convention: C<0> to prefix
626 an octal number or C<0x> to prefix a hexadecimal number.  For example:
627
628  1234      decimal number 1234
629  02322     octal number, equivalent to decimal 1234
630  0x4d2     hexadecimal number, equivalent to decimal 1234
631
632 When using the C<chmod> command, you almost always want to specify an
633 octal number for the mode, and you must prefix it with C<0> (unlike
634 the Unix L<chmod(1)> program):
635
636  chmod 0777 /public  # OK
637  chmod 777 /public   # WRONG! This is mode 777 decimal = 01411 octal.
638
639 Commands that return numbers usually print them in decimal, but
640 some commands print numbers in other radices (eg. C<umask> prints
641 the mode in octal, preceeded by C<0>).
642
643 =head1 WILDCARDS AND GLOBBING
644
645 Neither guestfish nor the underlying guestfs API performs
646 wildcard expansion (globbing) by default.  So for example the
647 following will not do what you expect:
648
649  rm-rf /home/*
650
651 Assuming you don't have a directory called literally C</home/*>
652 then the above command will return an error.
653
654 To perform wildcard expansion, use the C<glob> command.
655
656  glob rm-rf /home/*
657
658 runs C<rm-rf> on each path that matches (ie. potentially running
659 the command many times), equivalent to:
660
661  rm-rf /home/jim
662  rm-rf /home/joe
663  rm-rf /home/mary
664
665 C<glob> only works on simple guest paths and not on device names.
666
667 If you have several parameters, each containing a wildcard, then glob
668 will perform a Cartesian product.
669
670 =head1 COMMENTS
671
672 Any line which starts with a I<#> character is treated as a comment
673 and ignored.  The I<#> can optionally be preceeded by whitespace,
674 but B<not> by a command.  For example:
675
676  # this is a comment
677          # this is a comment
678  foo # NOT a comment
679
680 Blank lines are also ignored.
681
682 =head1 RUNNING COMMANDS LOCALLY
683
684 Any line which starts with a I<!> character is treated as a command
685 sent to the local shell (C</bin/sh> or whatever L<system(3)> uses).
686 For example:
687
688  !mkdir local
689  tgz-out /remote local/remote-data.tar.gz
690
691 will create a directory C<local> on the host, and then export
692 the contents of C</remote> on the mounted filesystem to
693 C<local/remote-data.tar.gz>.  (See C<tgz-out>).
694
695 To change the local directory, use the C<lcd> command.  C<!cd> will
696 have no effect, due to the way that subprocesses work in Unix.
697
698 =head2 LOCAL COMMANDS WITH INLINE EXECUTION
699
700 If a line starts with I<E<lt>!> then the shell command is executed (as
701 for I<!>), but subsequently any output (stdout) of the shell command
702 is parsed and executed as guestfish commands.
703
704 Thus you can use shell script to construct arbitrary guestfish
705 commands which are then parsed by guestfish.
706
707 For example it is tedious to create a sequence of files
708 (eg. C</foo.1> through C</foo.100>) using guestfish commands
709 alone.  However this is simple if we use a shell script to
710 create the guestfish commands for us:
711
712  <! for n in `seq 1 100`; do echo write /foo.$n $n; done
713
714 or with names like C</foo.001>:
715
716  <! for n in `seq 1 100`; do printf "write /foo.%03d %d\n" $n $n; done
717
718 When using guestfish interactively it can be helpful to just run the
719 shell script first (ie. remove the initial C<E<lt>> character so it is
720 just an ordinary I<!> local command), see what guestfish commands it
721 would run, and when you are happy with those prepend the C<E<lt>>
722 character to run the guestfish commands for real.
723
724 =head1 PIPES
725
726 Use C<command E<lt>spaceE<gt> | command> to pipe the output of the
727 first command (a guestfish command) to the second command (any host
728 command).  For example:
729
730  cat /etc/passwd | awk -F: '$3 == 0 { print }'
731
732 (where C<cat> is the guestfish cat command, but C<awk> is the host awk
733 program).  The above command would list all accounts in the guest
734 filesystem which have UID 0, ie. root accounts including backdoors.
735 Other examples:
736
737  hexdump /bin/ls | head
738  list-devices | tail -1
739  tgz-out / - | tar ztf -
740
741 The space before the pipe symbol is required, any space after the pipe
742 symbol is optional.  Everything after the pipe symbol is just passed
743 straight to the host shell, so it can contain redirections, globs and
744 anything else that makes sense on the host side.
745
746 To use a literal argument which begins with a pipe symbol, you have
747 to quote it, eg:
748
749  echo "|"
750
751 =head1 HOME DIRECTORIES
752
753 If a parameter starts with the character C<~> then the tilde may be
754 expanded as a home directory path (either C<~> for the current user's
755 home directory, or C<~user> for another user).
756
757 Note that home directory expansion happens for users known I<on the
758 host>, not in the guest filesystem.
759
760 To use a literal argument which begins with a tilde, you have to quote
761 it, eg:
762
763  echo "~"
764
765 =head1 ENCRYPTED DISKS
766
767 Libguestfs has some support for Linux guests encrypted according to
768 the Linux Unified Key Setup (LUKS) standard, which includes nearly all
769 whole disk encryption systems used by modern Linux guests.  Currently
770 only LVM-on-LUKS is supported.
771
772 Identify encrypted block devices and partitions using L</vfs-type>:
773
774  ><fs> vfs-type /dev/sda2
775  crypto_LUKS
776
777 Then open those devices using L</luks-open>.  This creates a
778 device-mapper device called C</dev/mapper/luksdev>.
779
780  ><fs> luks-open /dev/sda2 luksdev
781  Enter key or passphrase ("key"): <enter the passphrase>
782
783 Finally you have to tell LVM to scan for volume groups on
784 the newly created mapper device:
785
786  vgscan
787  vg-activate-all true
788
789 The logical volume(s) can now be mounted in the usual way.
790
791 Before closing a LUKS device you must unmount any logical volumes on
792 it and deactivate the volume groups by calling C<vg-activate false VG>
793 on each one.  Then you can close the mapper device:
794
795  vg-activate false /dev/VG
796  luks-close /dev/mapper/luksdev
797
798 =head1 WINDOWS PATHS
799
800 If a path is prefixed with C<win:> then you can use Windows-style
801 drive letters and paths (with some limitations).  The following
802 commands are equivalent:
803
804  file /WINDOWS/system32/config/system.LOG
805
806  file win:\windows\system32\config\system.log
807
808  file WIN:C:\Windows\SYSTEM32\CONFIG\SYSTEM.LOG
809
810 The parameter is rewritten "behind the scenes" by looking up the
811 position where the drive is mounted, prepending that to the path,
812 changing all backslash characters to forward slash, then resolving the
813 result using L</case-sensitive-path>.  For example if the E: drive
814 was mounted on C</e> then the parameter might be rewritten like this:
815
816  win:e:\foo\bar => /e/FOO/bar
817
818 This only works in argument positions that expect a path.
819
820 =head1 UPLOADING AND DOWNLOADING FILES
821
822 For commands such as C<upload>, C<download>, C<tar-in>, C<tar-out> and
823 others which upload from or download to a local file, you can use the
824 special filename C<-> to mean "from stdin" or "to stdout".  For example:
825
826  upload - /foo
827
828 reads stdin and creates from that a file C</foo> in the disk image,
829 and:
830
831  tar-out /etc - | tar tf -
832
833 writes the tarball to stdout and then pipes that into the external
834 "tar" command (see L</PIPES>).
835
836 When using C<-> to read from stdin, the input is read up to the end of
837 stdin.  You can also use a special "heredoc"-like syntax to read up to
838 some arbitrary end marker:
839
840  upload -<<END /foo
841  input line 1
842  input line 2
843  input line 3
844  END
845
846 Any string of characters can be used instead of C<END>.  The end
847 marker must appear on a line of its own, without any preceeding or
848 following characters (not even spaces).
849
850 Note that the C<-E<lt>E<lt>> syntax only applies to parameters used to
851 upload local files (so-called "FileIn" parameters in the generator).
852
853 =head1 EXIT ON ERROR BEHAVIOUR
854
855 By default, guestfish will ignore any errors when in interactive mode
856 (ie. taking commands from a human over a tty), and will exit on the
857 first error in non-interactive mode (scripts, commands given on the
858 command line).
859
860 If you prefix a command with a I<-> character, then that command will
861 not cause guestfish to exit, even if that (one) command returns an
862 error.
863
864 =head1 REMOTE CONTROL GUESTFISH OVER A SOCKET
865
866 Guestfish can be remote-controlled over a socket.  This is useful
867 particularly in shell scripts where you want to make several different
868 changes to a filesystem, but you don't want the overhead of starting
869 up a guestfish process each time.
870
871 Start a guestfish server process using:
872
873  eval "`guestfish --listen`"
874
875 and then send it commands by doing:
876
877  guestfish --remote cmd [...]
878
879 To cause the server to exit, send it the exit command:
880
881  guestfish --remote exit
882
883 Note that the server will normally exit if there is an error in a
884 command.  You can change this in the usual way.  See section
885 L</EXIT ON ERROR BEHAVIOUR>.
886
887 =head2 CONTROLLING MULTIPLE GUESTFISH PROCESSES
888
889 The C<eval> statement sets the environment variable C<$GUESTFISH_PID>,
890 which is how the I<--remote> option knows where to send the commands.
891 You can have several guestfish listener processes running using:
892
893  eval "`guestfish --listen`"
894  pid1=$GUESTFISH_PID
895  eval "`guestfish --listen`"
896  pid2=$GUESTFISH_PID
897  ...
898  guestfish --remote=$pid1 cmd
899  guestfish --remote=$pid2 cmd
900
901 =head2 REMOTE CONTROL AND CSH
902
903 When using csh-like shells (csh, tcsh etc) you have to add the
904 I<--csh> option:
905
906  eval "`guestfish --listen --csh`"
907
908 =head2 REMOTE CONTROL DETAILS
909
910 Remote control happens over a Unix domain socket called
911 C</tmp/.guestfish-$UID/socket-$PID>, where C<$UID> is the effective
912 user ID of the process, and C<$PID> is the process ID of the server.
913
914 Guestfish client and server versions must match exactly.
915
916 =head1 PREPARED DISK IMAGES
917
918 Use the I<-N type> or I<--new type> parameter to select one of a set
919 of preformatted disk images that guestfish can make for you to save
920 typing.  This is particularly useful for testing purposes.  This
921 option is used instead of the I<-a> option, and like I<-a> can appear
922 multiple times (and can be mixed with I<-a>).
923
924 The new disk is called C<test1.img> for the first I<-N>, C<test2.img>
925 for the second and so on.  Existing files in the current directory are
926 I<overwritten>.
927
928 The type briefly describes how the disk should be sized, partitioned,
929 how filesystem(s) should be created, and how content should be added.
930 Optionally the type can be followed by extra parameters, separated by
931 C<:> (colon) characters.  For example, I<-N fs> creates a default
932 100MB, sparsely-allocated disk, containing a single partition, with
933 the partition formatted as ext2.  I<-N fs:ext4:1G> is the same, but
934 for an ext4 filesystem on a 1GB disk instead.
935
936 To list the available types and any extra parameters they take, run:
937
938  guestfish -N help | less
939
940 Note that the prepared filesystem is not mounted.  You would usually
941 have to use the C<mount /dev/sda1 /> command or add the
942 I<-m /dev/sda1> option.
943
944 If any I<-N> or I<--new> options are given, the guest is automatically
945 launched.
946
947 =head2 EXAMPLES
948
949 Create a 100MB disk with an ext4-formatted partition:
950
951  guestfish -N fs:ext4
952
953 Create a 32MB disk with a VFAT-formatted partition, and mount it:
954
955  guestfish -N fs:vfat:32M -m /dev/sda1
956
957 Create a blank 200MB disk:
958
959  guestfish -N disk:200M
960
961 =head1 PROGRESS BARS
962
963 Some (not all) long-running commands send progress notification
964 messages as they are running.  Guestfish turns these messages into
965 progress bars.
966
967 When a command that supports progress bars takes longer than two
968 seconds to run, and if progress bars are enabled, then you will see
969 one appearing below the command:
970
971  ><fs> copy-size /large-file /another-file 2048M
972  / 10% [#####-----------------------------------------] 00:30
973
974 The spinner on the left hand side moves round once for every progress
975 notification received from the backend.  This is a (reasonably) golden
976 assurance that the command is "doing something" even if the progress
977 bar is not moving, because the command is able to send the progress
978 notifications.  When the bar reaches 100% and the command finishes,
979 the spinner disappears.
980
981 Progress bars are enabled by default when guestfish is used
982 interactively.  You can enable them even for non-interactive modes
983 using I<--progress-bars>, and you can disable them completely using
984 I<--no-progress-bars>.
985
986 =head1 GUESTFISH COMMANDS
987
988 The commands in this section are guestfish convenience commands, in
989 other words, they are not part of the L<guestfs(3)> API.
990
991 =head2 help
992
993  help
994  help cmd
995
996 Without any parameter, this provides general help.
997
998 With a C<cmd> parameter, this displays detailed help for that command.
999
1000 =head2 quit | exit
1001
1002 This exits guestfish.  You can also use C<^D> key.
1003
1004 @FISH_COMMANDS@
1005
1006 =head1 COMMANDS
1007
1008 @ACTIONS@
1009
1010 =head1 EXIT CODE
1011
1012 guestfish returns 0 if the commands completed without error, or
1013 1 if there was an error.
1014
1015 =head1 ENVIRONMENT VARIABLES
1016
1017 =over 4
1018
1019 =item EDITOR
1020
1021 The C<edit> command uses C<$EDITOR> as the editor.  If not
1022 set, it uses C<vi>.
1023
1024 =item GUESTFISH_PID
1025
1026 Used with the I<--remote> option to specify the remote guestfish
1027 process to control.  See section
1028 L</REMOTE CONTROL GUESTFISH OVER A SOCKET>.
1029
1030 =item HEXEDITOR
1031
1032 The L</hexedit> command uses C<$HEXEDITOR> as the external hex
1033 editor.  If not specified, the external L<hexedit(1)> program
1034 is used.
1035
1036 =item HOME
1037
1038 If compiled with GNU readline support, various files in the
1039 home directory can be used.  See L</FILES>.
1040
1041 =item LIBGUESTFS_APPEND
1042
1043 Pass additional options to the guest kernel.
1044
1045 =item LIBGUESTFS_DEBUG
1046
1047 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This has the
1048 same effect as using the B<-v> option.
1049
1050 =item LIBGUESTFS_MEMSIZE
1051
1052 Set the memory allocated to the qemu process, in megabytes.  For
1053 example:
1054
1055  LIBGUESTFS_MEMSIZE=700
1056
1057 =item LIBGUESTFS_PATH
1058
1059 Set the path that guestfish uses to search for kernel and initrd.img.
1060 See the discussion of paths in L<guestfs(3)>.
1061
1062 =item LIBGUESTFS_QEMU
1063
1064 Set the default qemu binary that libguestfs uses.  If not set, then
1065 the qemu which was found at compile time by the configure script is
1066 used.
1067
1068 =item LIBGUESTFS_TRACE
1069
1070 Set C<LIBGUESTFS_TRACE=1> to enable command traces.
1071
1072 =item PAGER
1073
1074 The C<more> command uses C<$PAGER> as the pager.  If not
1075 set, it uses C<more>.
1076
1077 =item TMPDIR
1078
1079 Location of temporary directory, defaults to C</tmp> except for the
1080 cached supermin appliance which defaults to C</var/tmp>.
1081
1082 If libguestfs was compiled to use the supermin appliance then the
1083 real appliance is cached in this directory, shared between all
1084 handles belonging to the same EUID.  You can use C<$TMPDIR> to
1085 configure another directory to use in case C</var/tmp> is not large
1086 enough.
1087
1088 =back
1089
1090 =head1 FILES
1091
1092 =over 4
1093
1094 =item $HOME/.libguestfs-tools.rc
1095
1096 =item /etc/libguestfs-tools.conf
1097
1098 This configuration file controls the default read-only or read-write
1099 mode (I<--ro> or I<--rw>).
1100
1101 See L</OPENING DISKS FOR READ AND WRITE>.
1102
1103 =item $HOME/.guestfish
1104
1105 If compiled with GNU readline support, then the command history
1106 is saved in this file.
1107
1108 =item $HOME/.inputrc
1109
1110 =item /etc/inputrc
1111
1112 If compiled with GNU readline support, then these files can be used to
1113 configure readline.  For further information, please see
1114 L<readline(3)/INITIALIZATION FILE>.
1115
1116 To write rules which only apply to guestfish, use:
1117
1118  $if guestfish
1119  ...
1120  $endif
1121
1122 Variables that you can set in inputrc that change the behaviour
1123 of guestfish in useful ways include:
1124
1125 =over 4
1126
1127 =item completion-ignore-case (default: on)
1128
1129 By default, guestfish will ignore case when tab-completing
1130 paths on the disk.  Use:
1131
1132  set completion-ignore-case off
1133
1134 to make guestfish case sensitive.
1135
1136 =back
1137
1138 =item test1.img
1139
1140 =item test2.img (etc)
1141
1142 When using the I<-N> or I<--new> option, the prepared disk or
1143 filesystem will be created in the file C<test1.img> in the current
1144 directory.  The second use of I<-N> will use C<test2.img> and so on.
1145 Any existing file with the same name will be overwritten.
1146
1147 =back
1148
1149 =head1 SEE ALSO
1150
1151 L<guestfs(3)>,
1152 L<http://libguestfs.org/>,
1153 L<virt-cat(1)>,
1154 L<virt-copy-in(1)>,
1155 L<virt-copy-out(1)>,
1156 L<virt-df(1)>,
1157 L<virt-edit(1)>,
1158 L<virt-filesystems(1)>,
1159 L<virt-inspector(1)>,
1160 L<virt-list-filesystems(1)>,
1161 L<virt-list-partitions(1)>,
1162 L<virt-ls(1)>,
1163 L<virt-make-fs(1)>,
1164 L<virt-rescue(1)>,
1165 L<virt-resize(1)>,
1166 L<virt-tar(1)>,
1167 L<virt-tar-in(1)>,
1168 L<virt-tar-out(1)>,
1169 L<virt-win-reg(1)>,
1170 L<hexedit(1)>.
1171
1172 =head1 AUTHORS
1173
1174 Richard W.M. Jones (C<rjones at redhat dot com>)
1175
1176 =head1 COPYRIGHT
1177
1178 Copyright (C) 2009-2011 Red Hat Inc.
1179 L<http://libguestfs.org/>
1180
1181 This program is free software; you can redistribute it and/or modify
1182 it under the terms of the GNU General Public License as published by
1183 the Free Software Foundation; either version 2 of the License, or
1184 (at your option) any later version.
1185
1186 This program is distributed in the hope that it will be useful,
1187 but WITHOUT ANY WARRANTY; without even the implied warranty of
1188 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
1189 GNU General Public License for more details.
1190
1191 You should have received a copy of the GNU General Public License
1192 along with this program; if not, write to the Free Software
1193 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.