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