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