generator: Don't use real uuidgen for UUIDs.
[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 -a disk.img
14
15  guestfish -a disk.img -m dev[:mountpoint]
16
17  guestfish -i libvirt-domain
18
19  guestfish -i disk.img [disk.img ...]
20
21 =head1 WARNING
22
23 Using guestfish in read/write mode on live virtual machines can be
24 dangerous, potentially causing disk corruption.  Use the I<--ro>
25 (read-only) option to use guestfish safely if the disk image or
26 virtual machine might be live.
27
28 =head1 EXAMPLES
29
30 =head2 As an interactive shell
31
32  $ guestfish
33  
34  Welcome to guestfish, the libguestfs filesystem interactive shell for
35  editing virtual machine filesystems.
36  
37  Type: 'help' for a list of commands
38        'man' to read the manual
39        'quit' to quit the shell
40  
41  ><fs> man
42
43 =head2 From shell scripts
44
45 Create a new C</etc/motd> file in a guest:
46
47  guestfish <<_EOF_
48  add disk.img
49  run
50  mount /dev/vg_guest/lv_root /
51  write /etc/motd "Welcome, new users"
52  _EOF_
53
54 List the LVM logical volumes in a guest:
55
56  guestfish -a disk.img --ro <<_EOF_
57  run
58  lvs
59  _EOF_
60
61 =head2 On one command line
62
63 Update C</etc/resolv.conf> in a guest:
64
65  guestfish \
66    add disk.img : run : mount /dev/vg_guest/lv_root / : \
67    write /etc/resolv.conf "nameserver 1.2.3.4"
68
69 Edit C</boot/grub/grub.conf> interactively:
70
71  guestfish --add disk.img \
72    --mount /dev/vg_guest/lv_root \
73    --mount /dev/sda1:/boot \
74    edit /boot/grub/grub.conf
75
76 =head2 Using virt-inspector
77
78 Use the I<-i> option to get virt-inspector to mount
79 the filesystems automatically as they would be mounted
80 in the virtual machine:
81
82  guestfish --ro -i disk.img cat /etc/group
83
84 =head2 As a script interpreter
85
86 Create a 100MB disk containing an ext2-formatted partition:
87
88  #!/usr/bin/guestfish -f
89  sparse test1.img 100M
90  run
91  part-disk /dev/sda mbr
92  mkfs ext2 /dev/sda1
93
94 =head2 Start with a prepared disk
95
96 An alternate way to create a 100MB disk called C<test1.img> containing
97 a single ext2-formatted partition:
98
99  guestfish -N fs
100
101 To list what is available do:
102
103  guestfish -N list | less
104
105 =head2 Remote control
106
107  eval `guestfish --listen --ro`
108  guestfish --remote add disk.img
109  guestfish --remote run
110  guestfish --remote lvs
111
112 =head1 DESCRIPTION
113
114 Guestfish is a shell and command-line tool for examining and modifying
115 virtual machine filesystems.  It uses libguestfs and exposes all of
116 the functionality of the guestfs API, see L<guestfs(3)>.
117
118 Guestfish gives you structured access to the libguestfs API, from
119 shell scripts or the command line or interactively.  If you want to
120 rescue a broken virtual machine image, you should look at the
121 L<virt-rescue(1)> command.
122
123 =head1 OPTIONS
124
125 =over 4
126
127 =item B<--help>
128
129 Displays general help on options.
130
131 =item B<-h> | B<--cmd-help>
132
133 Lists all available guestfish commands.
134
135 =item B<-h cmd> | B<--cmd-help cmd>
136
137 Displays detailed help on a single command C<cmd>.
138
139 =item B<-a image> | B<--add image>
140
141 Add a block device or virtual machine image to the shell.
142
143 =item B<-D> | B<--no-dest-paths>
144
145 Don't tab-complete paths on the guest filesystem.  It is useful to be
146 able to hit the tab key to complete paths on the guest filesystem, but
147 this causes extra "hidden" guestfs calls to be made, so this option is
148 here to allow this feature to be disabled.
149
150 =item B<-f file> | B<--file file>
151
152 Read commands from C<file>.  To write pure guestfish
153 scripts, use:
154
155  #!/usr/bin/guestfish -f
156
157 =item B<-i> | B<--inspector>
158
159 Run virt-inspector on the named libvirt domain or list of disk
160 images.  If virt-inspector is available and if it can identify
161 the domain or disk images, then partitions will be mounted
162 correctly at start-up.
163
164 Typical usage is either:
165
166  guestfish -i myguest
167
168 (for an inactive libvirt domain called I<myguest>), or:
169
170  guestfish --ro -i myguest
171
172 (for active domains, readonly), or specify the block device directly:
173
174  guestfish -i /dev/Guests/MyGuest
175
176 You cannot use I<-a>, I<-m>, I<-N>, I<--listen>, I<--remote> or
177 I<--selinux> in conjunction with this option, and options other than
178 I<--ro> might not behave correctly.
179
180 See also: L<virt-inspector(1)>.
181
182 =item B<--listen>
183
184 Fork into the background and listen for remote commands.  See section
185 L</REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
186
187 =item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]>
188
189 Mount the named partition or logical volume on the given mountpoint.
190
191 If the mountpoint is omitted, it defaults to C</>.
192
193 You have to mount something on C</> before most commands will work.
194
195 If any I<-m> or I<--mount> options are given, the guest is
196 automatically launched.
197
198 If you don't know what filesystems a disk image contains, you
199 can either run guestfish without this option, then list the partitions
200 and LVs available (see L</list-partitions> and L</lvs> commands),
201 or you can use the L<virt-list-filesystems(1)> program.
202
203 =item B<-n> | B<--no-sync>
204
205 Disable autosync.  This is enabled by default.  See the discussion
206 of autosync in the L<guestfs(3)> manpage.
207
208 =item B<-N type> | B<--new type> | B<-N list>
209
210 Prepare a fresh disk image formatted as "type".  This is an
211 alternative to the I<-a> option: whereas I<-a> adds an existing disk,
212 I<-N> creates a preformatted disk with a filesystem and adds it.
213 See L</PREPARED DISK IMAGES> below.
214
215 =item B<--remote[=pid]>
216
217 Send remote commands to C<$GUESTFISH_PID> or C<pid>.  See section
218 L</REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
219
220 =item B<-r> | B<--ro>
221
222 This changes the I<-a> and I<-m> options so that disks are added and
223 mounts are done read-only (see L<guestfs(3)/guestfs_mount_ro>).
224
225 The option must always be used if the disk image or virtual machine
226 might be running, and is generally recommended in cases where you
227 don't need write access to the disk.
228
229 Note that prepared disk images created with I<-N> are not affected by
230 the I<--ro> option.
231
232 =item B<--selinux>
233
234 Enable SELinux support for the guest.  See L<guestfs(3)/SELINUX>.
235
236 =item B<-v> | B<--verbose>
237
238 Enable very verbose messages.  This is particularly useful if you find
239 a bug.
240
241 =item B<-V> | B<--version>
242
243 Display the guestfish / libguestfs version number and exit.
244
245 =item B<-x>
246
247 Echo each command before executing it.
248
249 =back
250
251 =head1 COMMANDS ON COMMAND LINE
252
253 Any additional (non-option) arguments are treated as commands to
254 execute.
255
256 Commands to execute should be separated by a colon (C<:>), where the
257 colon is a separate parameter.  Thus:
258
259  guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
260
261 If there are no additional arguments, then we enter a shell, either an
262 interactive shell with a prompt (if the input is a terminal) or a
263 non-interactive shell.
264
265 In either command line mode or non-interactive shell, the first
266 command that gives an error causes the whole shell to exit.  In
267 interactive mode (with a prompt) if a command fails, you can continue
268 to enter commands.
269
270 =head1 USING launch (OR run)
271
272 As with L<guestfs(3)>, you must first configure your guest by adding
273 disks, then launch it, then mount any disks you need, and finally
274 issue actions/commands.  So the general order of the day is:
275
276 =over 4
277
278 =item *
279
280 add or -a/--add
281
282 =item *
283
284 launch (aka run)
285
286 =item *
287
288 mount or -m/--mount
289
290 =item *
291
292 any other commands
293
294 =back
295
296 C<run> is a synonym for C<launch>.  You must C<launch> (or C<run>)
297 your guest before mounting or performing any other commands.
298
299 The only exception is that if the I<-m> or I<--mount> option was
300 given, the guest is automatically run for you (simply because
301 guestfish can't mount the disks you asked for without doing this).
302
303 =head1 QUOTING
304
305 You can quote ordinary parameters using either single or double
306 quotes.  For example:
307
308  add "file with a space.img"
309
310  rm '/file name'
311
312  rm '/"'
313
314 A few commands require a list of strings to be passed.  For these, use
315 a whitespace-separated list, enclosed in quotes.  Strings containing whitespace
316 to be passed through must be enclosed in single quotes.  A literal single quote
317 must be escaped with a backslash.
318
319  vgcreate VG "/dev/sda1 /dev/sdb1"
320  command "/bin/echo 'foo      bar'"
321  command "/bin/echo \'foo\'"
322
323 =head1 NUMBERS
324
325 This section applies to all commands which can take integers
326 as parameters.
327
328 =head2 SIZE SUFFIX
329
330 When the command takes a parameter measured in bytes, you can use one
331 of the following suffixes to specify kilobytes, megabytes and larger
332 sizes:
333
334 =over 4
335
336 =item B<k> or B<K> or B<KiB>
337
338 The size in kilobytes (multiplied by 1024).
339
340 =item B<KB>
341
342 The size in SI 1000 byte units.
343
344 =item B<M> or B<MiB>
345
346 The size in megabytes (multiplied by 1048576).
347
348 =item B<MB>
349
350 The size in SI 1000000 byte units.
351
352 =item B<G> or B<GiB>
353
354 The size in gigabytes (multiplied by 2**30).
355
356 =item B<GB>
357
358 The size in SI 10**9 byte units.
359
360 =item B<T> or B<TiB>
361
362 The size in terabytes (multiplied by 2**40).
363
364 =item B<TB>
365
366 The size in SI 10**12 byte units.
367
368 =item B<P> or B<PiB>
369
370 The size in petabytes (multiplied by 2**50).
371
372 =item B<PB>
373
374 The size in SI 10**15 byte units.
375
376 =item B<E> or B<EiB>
377
378 The size in exabytes (multiplied by 2**60).
379
380 =item B<EB>
381
382 The size in SI 10**18 byte units.
383
384 =item B<Z> or B<ZiB>
385
386 The size in zettabytes (multiplied by 2**70).
387
388 =item B<ZB>
389
390 The size in SI 10**21 byte units.
391
392 =item B<Y> or B<YiB>
393
394 The size in yottabytes (multiplied by 2**80).
395
396 =item B<YB>
397
398 The size in SI 10**24 byte units.
399
400 =back
401
402 For example:
403
404  truncate-size /file 1G
405
406 would truncate the file to 1 gigabyte.
407
408 Be careful because a few commands take sizes in kilobytes or megabytes
409 (eg. the parameter to L</memsize> is specified in megabytes already).
410 Adding a suffix will probably not do what you expect.
411
412 =head2 OCTAL AND HEXADECIMAL NUMBERS
413
414 For specifying the radix (base) use the C convention: C<0> to prefix
415 an octal number or C<0x> to prefix a hexadecimal number.  For example:
416
417  1234      decimal number 1234
418  02322     octal number, equivalent to decimal 1234
419  0x4d2     hexadecimal number, equivalent to decimal 1234
420
421 When using the C<chmod> command, you almost always want to specify an
422 octal number for the mode, and you must prefix it with C<0> (unlike
423 the Unix L<chmod(1)> program):
424
425  chmod 0777 /public  # OK
426  chmod 777 /public   # WRONG! This is mode 777 decimal = 01411 octal.
427
428 Commands that return numbers usually print them in decimal, but
429 some commands print numbers in other radices (eg. C<umask> prints
430 the mode in octal, preceeded by C<0>).
431
432 =head1 WILDCARDS AND GLOBBING
433
434 Neither guestfish nor the underlying guestfs API performs
435 wildcard expansion (globbing) by default.  So for example the
436 following will not do what you expect:
437
438  rm-rf /home/*
439
440 Assuming you don't have a directory literally called C</home/*>
441 then the above command will return an error.
442
443 To perform wildcard expansion, use the C<glob> command.
444
445  glob rm-rf /home/*
446
447 runs C<rm-rf> on each path that matches (ie. potentially running
448 the command many times), equivalent to:
449
450  rm-rf /home/jim
451  rm-rf /home/joe
452  rm-rf /home/mary
453
454 C<glob> only works on simple guest paths and not on device names.
455
456 If you have several parameters, each containing a wildcard, then glob
457 will perform a cartesian product.
458
459 =head1 COMMENTS
460
461 Any line which starts with a I<#> character is treated as a comment
462 and ignored.  The I<#> can optionally be preceeded by whitespace,
463 but B<not> by a command.  For example:
464
465  # this is a comment
466          # this is a comment
467  foo # NOT a comment
468
469 Blank lines are also ignored.
470
471 =head1 RUNNING COMMANDS LOCALLY
472
473 Any line which starts with a I<!> character is treated as a command
474 sent to the local shell (C</bin/sh> or whatever L<system(3)> uses).
475 For example:
476
477  !mkdir local
478  tgz-out /remote local/remote-data.tar.gz
479
480 will create a directory C<local> on the host, and then export
481 the contents of C</remote> on the mounted filesystem to
482 C<local/remote-data.tar.gz>.  (See C<tgz-out>).
483
484 To change the local directory, use the C<lcd> command.  C<!cd> will
485 have no effect, due to the way that subprocesses work in Unix.
486
487 =head1 PIPES
488
489 Use C<command E<lt>spaceE<gt> | command> to pipe the output of the
490 first command (a guestfish command) to the second command (any host
491 command).  For example:
492
493  cat /etc/passwd | awk -F: '$3 == 0 { print }'
494
495 (where C<cat> is the guestfish cat command, but C<awk> is the host awk
496 program).  The above command would list all accounts in the guest
497 filesystem which have UID 0, ie. root accounts including backdoors.
498 Other examples:
499
500  hexdump /bin/ls | head
501  list-devices | tail -1
502  tgz-out / - | tar ztf -
503
504 The space before the pipe symbol is required, any space after the pipe
505 symbol is optional.  Everything after the pipe symbol is just passed
506 straight to the host shell, so it can contain redirections, globs and
507 anything else that makes sense on the host side.
508
509 To use a literal argument which begins with a pipe symbol, you have
510 to quote it, eg:
511
512  echo "|"
513
514 =head1 HOME DIRECTORIES
515
516 If a parameter starts with the character C<~> then the tilde may be
517 expanded as a home directory path (either C<~> for the current user's
518 home directory, or C<~user> for another user).
519
520 Note that home directory expansion happens for users known I<on the
521 host>, not in the guest filesystem.
522
523 To use a literal argument which begins with a tilde, you have to quote
524 it, eg:
525
526  echo "~"
527
528 =head1 WINDOWS PATHS
529
530 If a path is prefixed with C<win:> then you can use Windows-style
531 paths (with some limitations).  The following commands are equivalent:
532
533  file /WINDOWS/system32/config/system.LOG
534
535  file win:/windows/system32/config/system.log
536
537  file win:\windows\system32\config\system.log
538
539  file WIN:C:\Windows\SYSTEM32\conFIG\SYSTEM.LOG
540
541 This syntax implicitly calls C<case-sensitive-path> (q.v.) so it also
542 handles case insensitivity like Windows would.  This only works in
543 argument positions that expect a path.
544
545 =head1 UPLOADING AND DOWNLOADING FILES
546
547 For commands such as C<upload>, C<download>, C<tar-in>, C<tar-out> and
548 others which upload from or download to a local file, you can use the
549 special filename C<-> to mean "from stdin" or "to stdout".  For example:
550
551  upload - /foo
552
553 reads stdin and creates from that a file C</foo> in the disk image,
554 and:
555
556  tar-out /etc - | tar tf -
557
558 writes the tarball to stdout and then pipes that into the external
559 "tar" command (see L</PIPES>).
560
561 When using C<-> to read from stdin, the input is read up to the end of
562 stdin.  You can also use a special "heredoc"-like syntax to read up to
563 some arbitrary end marker:
564
565  upload -<<END /foo
566  input line 1
567  input line 2
568  input line 3
569  END
570
571 Any string of characters can be used instead of C<END>.  The end
572 marker must appear on a line of its own, without any preceeding or
573 following characters (not even spaces).
574
575 Note that the C<-E<lt>E<lt>> syntax only applies to parameters used to
576 upload local files (so-called "FileIn" parameters in the generator).
577
578 =head1 EXIT ON ERROR BEHAVIOUR
579
580 By default, guestfish will ignore any errors when in interactive mode
581 (ie. taking commands from a human over a tty), and will exit on the
582 first error in non-interactive mode (scripts, commands given on the
583 command line).
584
585 If you prefix a command with a I<-> character, then that command will
586 not cause guestfish to exit, even if that (one) command returns an
587 error.
588
589 =head1 REMOTE CONTROL GUESTFISH OVER A SOCKET
590
591 Guestfish can be remote-controlled over a socket.  This is useful
592 particularly in shell scripts where you want to make several different
593 changes to a filesystem, but you don't want the overhead of starting
594 up a guestfish process each time.
595
596 Start a guestfish server process using:
597
598  eval `guestfish --listen`
599
600 and then send it commands by doing:
601
602  guestfish --remote cmd [...]
603
604 To cause the server to exit, send it the exit command:
605
606  guestfish --remote exit
607
608 Note that the server will normally exit if there is an error in a
609 command.  You can change this in the usual way.  See section
610 L</EXIT ON ERROR BEHAVIOUR>.
611
612 =head2 CONTROLLING MULTIPLE GUESTFISH PROCESSES
613
614 The C<eval> statement sets the environment variable C<$GUESTFISH_PID>,
615 which is how the I<--remote> option knows where to send the commands.
616 You can have several guestfish listener processes running using:
617
618  eval `guestfish --listen`
619  pid1=$GUESTFISH_PID
620  eval `guestfish --listen`
621  pid2=$GUESTFISH_PID
622  ...
623  guestfish --remote=$pid1 cmd
624  guestfish --remote=$pid2 cmd
625
626 =head2 REMOTE CONTROL DETAILS
627
628 Remote control happens over a Unix domain socket called
629 C</tmp/.guestfish-$UID/socket-$PID>, where C<$UID> is the effective
630 user ID of the process, and C<$PID> is the process ID of the server.
631
632 Guestfish client and server versions must match exactly.
633
634 =head1 PREPARED DISK IMAGES
635
636 Use the I<-N type> or I<--new type> parameter to select one of a set
637 of preformatted disk images that guestfish can make for you to save
638 typing.  This is particularly useful for testing purposes.  This
639 option is used instead of the I<-a> option, and like I<-a> can appear
640 multiple times (and can be mixed with I<-a>).
641
642 The new disk is called C<test1.img> for the first I<-N>, C<test2.img>
643 for the second and so on.  Existing files in the current directory are
644 I<overwritten>.
645
646 The type briefly describes how the disk should be sized, partitioned,
647 how filesystem(s) should be created, and how content should be added.
648 Optionally the type can be followed by extra parameters, separated by
649 C<:> (colon) characters.  For example, I<-N fs> creates a default
650 100MB, sparsely-allocated disk, containing a single partition, with
651 the partition formatted as ext2.  I<-N fs:ext4:1G> is the same, but
652 for an ext4 filesystem on a 1GB disk instead.
653
654 To list the available types and any extra parameters they take, run:
655
656  guestfish -N list | less
657
658 Note that the prepared filesystem is not mounted.  You would usually
659 have to use the C<mount /dev/sda1 /> command or add the
660 I<-m /dev/sda1> option.
661
662 If any I<-N> or I<--new> options are given, the guest is automatically
663 launched.
664
665 =head2 EXAMPLES
666
667 Create a 100MB disk with an ext4-formatted partition:
668
669  guestfish -N fs:ext4
670
671 Create a 32MB disk with a VFAT-formatted partition, and mount it:
672
673  guestfish -N fs:vfat:32M -m /dev/sda1
674
675 Create a blank 200MB disk:
676
677  guestfish -N disk:200M
678
679 =head1 GUESTFISH COMMANDS
680
681 The commands in this section are guestfish convenience commands, in
682 other words, they are not part of the L<guestfs(3)> API.
683
684 =head2 alloc | allocate
685
686  alloc filename size
687
688 This creates an empty (zeroed) file of the given size, and then adds
689 so it can be further examined.
690
691 For more advanced image creation, see L<qemu-img(1)> utility.
692
693 Size can be specified using standard suffixes, eg. C<1M>.
694
695 =head2 echo
696
697  echo [params ...]
698
699 This echos the parameters to the terminal.
700
701 =head2 edit | vi | emacs
702
703  edit filename
704
705 This is used to edit a file.  It downloads the file, edits it
706 locally using your editor, then uploads the result.
707
708 The editor is C<$EDITOR>.  However if you use the alternate
709 commands C<vi> or C<emacs> you will get those corresponding
710 editors.
711
712 =head2 glob
713
714  glob command args...
715
716 Expand wildcards in any paths in the args list, and run C<command>
717 repeatedly on each matching path.
718
719 See section WILDCARDS AND GLOBBING.
720
721 =head2 help
722
723  help
724  help cmd
725
726 Without any parameter, this lists all commands.  With a C<cmd>
727 parameter, this displays detailed help for a command.
728
729 =head2 lcd
730
731  lcd directory
732
733 Change the local directory, ie. the current directory of guestfish
734 itself.
735
736 Note that C<!cd> won't do what you might expect.
737
738 =head2 man | manual
739
740  man
741
742 Opens the manual page for guestfish.
743
744 =head2 more | less
745
746  more filename
747
748  less filename
749
750 This is used to view a file.
751
752 The default viewer is C<$PAGER>.  However if you use the alternate
753 command C<less> you will get the C<less> command specifically.
754
755 =head2 quit | exit
756
757 This exits guestfish.  You can also use C<^D> key.
758
759 =head2 reopen
760
761  reopen
762
763 Close and reopen the libguestfs handle.  It is not necessary to use
764 this normally, because the handle is closed properly when guestfish
765 exits.  However this is occasionally useful for testing.
766
767 =head2 sparse
768
769  sparse filename size
770
771 This creates an empty sparse file of the given size, and then adds
772 so it can be further examined.
773
774 In all respects it works the same as the C<alloc> command, except that
775 the image file is allocated sparsely, which means that disk blocks are
776 not assigned to the file until they are needed.  Sparse disk files
777 only use space when written to, but they are slower and there is a
778 danger you could run out of real disk space during a write operation.
779
780 For more advanced image creation, see L<qemu-img(1)> utility.
781
782 Size can be specified using standard suffixes, eg. C<1M>.
783
784 =head2 supported
785
786  supported
787
788 This command returns a list of the optional groups
789 known to the daemon, and indicates which ones are
790 supported by this build of the libguestfs appliance.
791
792 See also L<guestfs(3)/AVAILABILITY>.
793
794 =head2 time
795
796  time command args...
797
798 Run the command as usual, but print the elapsed time afterwards.  This
799 can be useful for benchmarking operations.
800
801 =head1 COMMANDS
802
803 @ACTIONS@
804
805 =head1 EXIT CODE
806
807 guestfish returns 0 if the commands completed without error, or
808 1 if there was an error.
809
810 =head1 ENVIRONMENT VARIABLES
811
812 =over 4
813
814 =item EDITOR
815
816 The C<edit> command uses C<$EDITOR> as the editor.  If not
817 set, it uses C<vi>.
818
819 =item GUESTFISH_PID
820
821 Used with the I<--remote> option to specify the remote guestfish
822 process to control.  See section
823 L</REMOTE CONTROL GUESTFISH OVER A SOCKET>.
824
825 =item HOME
826
827 If compiled with GNU readline support, various files in the
828 home directory can be used.  See L</FILES>.
829
830 =item LIBGUESTFS_APPEND
831
832 Pass additional options to the guest kernel.
833
834 =item LIBGUESTFS_DEBUG
835
836 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This has the
837 same effect as using the B<-v> option.
838
839 =item LIBGUESTFS_MEMSIZE
840
841 Set the memory allocated to the qemu process, in megabytes.  For
842 example:
843
844  LIBGUESTFS_MEMSIZE=700
845
846 =item LIBGUESTFS_PATH
847
848 Set the path that guestfish uses to search for kernel and initrd.img.
849 See the discussion of paths in L<guestfs(3)>.
850
851 =item LIBGUESTFS_QEMU
852
853 Set the default qemu binary that libguestfs uses.  If not set, then
854 the qemu which was found at compile time by the configure script is
855 used.
856
857 =item LIBGUESTFS_TRACE
858
859 Set C<LIBGUESTFS_TRACE=1> to enable command traces.
860
861 =item PAGER
862
863 The C<more> command uses C<$PAGER> as the pager.  If not
864 set, it uses C<more>.
865
866 =item TMPDIR
867
868 Location of temporary directory, defaults to C</tmp>.
869
870 If libguestfs was compiled to use the supermin appliance then each
871 handle will require rather a large amount of space in this directory
872 for short periods of time (~ 80 MB).  You can use C<$TMPDIR> to
873 configure another directory to use in case C</tmp> is not large
874 enough.
875
876 =back
877
878 =head1 FILES
879
880 =over 4
881
882 =item $HOME/.guestfish
883
884 If compiled with GNU readline support, then the command history
885 is saved in this file.
886
887 =item $HOME/.inputrc
888
889 =item /etc/inputrc
890
891 If compiled with GNU readline support, then these files can be used to
892 configure readline.  For further information, please see
893 L<readline(3)/INITIALIZATION FILE>.
894
895 To write rules which only apply to guestfish, use:
896
897  $if guestfish
898  ...
899  $endif
900
901 Variables that you can set in inputrc that change the behaviour
902 of guestfish in useful ways include:
903
904 =over 4
905
906 =item completion-ignore-case (default: on)
907
908 By default, guestfish will ignore case when tab-completing
909 paths on the disk.  Use:
910
911  set completion-ignore-case off
912
913 to make guestfish case sensitive.
914
915 =back
916
917 =item test1.img
918
919 =item test2.img (etc)
920
921 When using the C<-N> or C<--new> option, the prepared disk or
922 filesystem will be created in the file C<test1.img> in the current
923 directory.  The second use of C<-N> will use C<test2.img> and so on.
924 Any existing file with the same name will be overwritten.
925
926 =back
927
928 =head1 SEE ALSO
929
930 L<guestfs(3)>,
931 L<http://libguestfs.org/>,
932 L<virt-cat(1)>,
933 L<virt-df(1)>,
934 L<virt-edit(1)>,
935 L<virt-list-filesystems(1)>,
936 L<virt-list-partitions(1)>,
937 L<virt-ls(1)>,
938 L<virt-make-fs(1)>,
939 L<virt-rescue(1)>,
940 L<virt-resize(1)>,
941 L<virt-tar(1)>,
942 L<virt-win-reg(1)>.
943
944 =head1 AUTHORS
945
946 Richard W.M. Jones (C<rjones at redhat dot com>)
947
948 =head1 COPYRIGHT
949
950 Copyright (C) 2009-2010 Red Hat Inc.
951 L<http://libguestfs.org/>
952
953 This program is free software; you can redistribute it and/or modify
954 it under the terms of the GNU General Public License as published by
955 the Free Software Foundation; either version 2 of the License, or
956 (at your option) any later version.
957
958 This program is distributed in the hope that it will be useful,
959 but WITHOUT ANY WARRANTY; without even the implied warranty of
960 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
961 GNU General Public License for more details.
962
963 You should have received a copy of the GNU General Public License
964 along with this program; if not, write to the Free Software
965 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.