Note about using FUSE / mountlo code.
[libguestfs.git] / guestfish-actions.pod
1 =head2 add-cdrom | cdrom
2
3  add-cdrom filename
4
5 This function adds a virtual CD-ROM disk image to the guest.
6
7 This is equivalent to the qemu parameter C<-cdrom filename>.
8
9 =head2 add-drive | add
10
11  add-drive filename
12
13 This function adds a virtual machine disk image C<filename> to the
14 guest.  The first time you call this function, the disk appears as IDE
15 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
16 so on.
17
18 You don't necessarily need to be root when using libguestfs.  However
19 you obviously do need sufficient permissions to access the filename
20 for whatever operations you want to perform (ie. read access if you
21 just want to read the image or write access if you want to modify the
22 image).
23
24 This is equivalent to the qemu parameter C<-drive file=filename>.
25
26 =head2 aug-close
27
28  aug-close
29
30 Close the current Augeas handle and free up any resources
31 used by it.  After calling this, you have to call
32 C<aug-init> again before you can use any other
33 Augeas functions.
34
35 =head2 aug-defnode
36
37  aug-defnode name expr val
38
39 Defines a variable C<name> whose value is the result of
40 evaluating C<expr>.
41
42 If C<expr> evaluates to an empty nodeset, a node is created,
43 equivalent to calling C<aug-set> C<expr>, C<value>.
44 C<name> will be the nodeset containing that single node.
45
46 On success this returns a pair containing the
47 number of nodes in the nodeset, and a boolean flag
48 if a node was created.
49
50 =head2 aug-defvar
51
52  aug-defvar name expr
53
54 Defines an Augeas variable C<name> whose value is the result
55 of evaluating C<expr>.  If C<expr> is NULL, then C<name> is
56 undefined.
57
58 On success this returns the number of nodes in C<expr>, or
59 C<0> if C<expr> evaluates to something which is not a nodeset.
60
61 =head2 aug-get
62
63  aug-get path
64
65 Look up the value associated with C<path>.  If C<path>
66 matches exactly one node, the C<value> is returned.
67
68 =head2 aug-init
69
70  aug-init root flags
71
72 Create a new Augeas handle for editing configuration files.
73 If there was any previous Augeas handle associated with this
74 guestfs session, then it is closed.
75
76 You must call this before using any other C<aug-*>
77 commands.
78
79 C<root> is the filesystem root.  C<root> must not be NULL,
80 use C</> instead.
81
82 The flags are the same as the flags defined in
83 E<lt>augeas.hE<gt>, the logical I<or> of the following
84 integers:
85
86 =over 4
87
88 =item C<AUG_SAVE_BACKUP> = 1
89
90 Keep the original file with a C<.augsave> extension.
91
92 =item C<AUG_SAVE_NEWFILE> = 2
93
94 Save changes into a file with extension C<.augnew>, and
95 do not overwrite original.  Overrides C<AUG_SAVE_BACKUP>.
96
97 =item C<AUG_TYPE_CHECK> = 4
98
99 Typecheck lenses (can be expensive).
100
101 =item C<AUG_NO_STDINC> = 8
102
103 Do not use standard load path for modules.
104
105 =item C<AUG_SAVE_NOOP> = 16
106
107 Make save a no-op, just record what would have been changed.
108
109 =item C<AUG_NO_LOAD> = 32
110
111 Do not load the tree in C<aug-init>.
112
113 =back
114
115 To close the handle, you can call C<aug-close>.
116
117 To find out more about Augeas, see L<http://augeas.net/>.
118
119 =head2 aug-insert
120
121  aug-insert path label true|false
122
123 Create a new sibling C<label> for C<path>, inserting it into
124 the tree before or after C<path> (depending on the boolean
125 flag C<before>).
126
127 C<path> must match exactly one existing node in the tree, and
128 C<label> must be a label, ie. not contain C</>, C<*> or end
129 with a bracketed index C<[N]>.
130
131 =head2 aug-load
132
133  aug-load
134
135 Load files into the tree.
136
137 See C<aug_load> in the Augeas documentation for the full gory
138 details.
139
140 =head2 aug-ls
141
142  aug-ls path
143
144 This is just a shortcut for listing C<aug-match>
145 C<path/*> and sorting the resulting nodes into alphabetical order.
146
147 =head2 aug-match
148
149  aug-match path
150
151 Returns a list of paths which match the path expression C<path>.
152 The returned paths are sufficiently qualified so that they match
153 exactly one node in the current tree.
154
155 =head2 aug-mv
156
157  aug-mv src dest
158
159 Move the node C<src> to C<dest>.  C<src> must match exactly
160 one node.  C<dest> is overwritten if it exists.
161
162 =head2 aug-rm
163
164  aug-rm path
165
166 Remove C<path> and all of its children.
167
168 On success this returns the number of entries which were removed.
169
170 =head2 aug-save
171
172  aug-save
173
174 This writes all pending changes to disk.
175
176 The flags which were passed to C<aug-init> affect exactly
177 how files are saved.
178
179 =head2 aug-set
180
181  aug-set path val
182
183 Set the value associated with C<path> to C<value>.
184
185 =head2 blockdev-flushbufs
186
187  blockdev-flushbufs device
188
189 This tells the kernel to flush internal buffers associated
190 with C<device>.
191
192 This uses the L<blockdev(8)> command.
193
194 =head2 blockdev-getbsz
195
196  blockdev-getbsz device
197
198 This returns the block size of a device.
199
200 (Note this is different from both I<size in blocks> and
201 I<filesystem block size>).
202
203 This uses the L<blockdev(8)> command.
204
205 =head2 blockdev-getro
206
207  blockdev-getro device
208
209 Returns a boolean indicating if the block device is read-only
210 (true if read-only, false if not).
211
212 This uses the L<blockdev(8)> command.
213
214 =head2 blockdev-getsize64
215
216  blockdev-getsize64 device
217
218 This returns the size of the device in bytes.
219
220 See also C<blockdev-getsz>.
221
222 This uses the L<blockdev(8)> command.
223
224 =head2 blockdev-getss
225
226  blockdev-getss device
227
228 This returns the size of sectors on a block device.
229 Usually 512, but can be larger for modern devices.
230
231 (Note, this is not the size in sectors, use C<blockdev-getsz>
232 for that).
233
234 This uses the L<blockdev(8)> command.
235
236 =head2 blockdev-getsz
237
238  blockdev-getsz device
239
240 This returns the size of the device in units of 512-byte sectors
241 (even if the sectorsize isn't 512 bytes ... weird).
242
243 See also C<blockdev-getss> for the real sector size of
244 the device, and C<blockdev-getsize64> for the more
245 useful I<size in bytes>.
246
247 This uses the L<blockdev(8)> command.
248
249 =head2 blockdev-rereadpt
250
251  blockdev-rereadpt device
252
253 Reread the partition table on C<device>.
254
255 This uses the L<blockdev(8)> command.
256
257 =head2 blockdev-setbsz
258
259  blockdev-setbsz device blocksize
260
261 This sets the block size of a device.
262
263 (Note this is different from both I<size in blocks> and
264 I<filesystem block size>).
265
266 This uses the L<blockdev(8)> command.
267
268 =head2 blockdev-setro
269
270  blockdev-setro device
271
272 Sets the block device named C<device> to read-only.
273
274 This uses the L<blockdev(8)> command.
275
276 =head2 blockdev-setrw
277
278  blockdev-setrw device
279
280 Sets the block device named C<device> to read-write.
281
282 This uses the L<blockdev(8)> command.
283
284 =head2 cat
285
286  cat path
287
288 Return the contents of the file named C<path>.
289
290 Note that this function cannot correctly handle binary files
291 (specifically, files containing C<\0> character which is treated
292 as end of string).  For those you need to use the C<download>
293 function which has a more complex interface.
294
295 Because of the message protocol, there is a transfer limit 
296 of somewhere between 2MB and 4MB.  To transfer large files you should use
297 FTP.
298
299 =head2 checksum
300
301  checksum csumtype path
302
303 This call computes the MD5, SHAx or CRC checksum of the
304 file named C<path>.
305
306 The type of checksum to compute is given by the C<csumtype>
307 parameter which must have one of the following values:
308
309 =over 4
310
311 =item C<crc>
312
313 Compute the cyclic redundancy check (CRC) specified by POSIX
314 for the C<cksum> command.
315
316 =item C<md5>
317
318 Compute the MD5 hash (using the C<md5sum> program).
319
320 =item C<sha1>
321
322 Compute the SHA1 hash (using the C<sha1sum> program).
323
324 =item C<sha224>
325
326 Compute the SHA224 hash (using the C<sha224sum> program).
327
328 =item C<sha256>
329
330 Compute the SHA256 hash (using the C<sha256sum> program).
331
332 =item C<sha384>
333
334 Compute the SHA384 hash (using the C<sha384sum> program).
335
336 =item C<sha512>
337
338 Compute the SHA512 hash (using the C<sha512sum> program).
339
340 =back
341
342 The checksum is returned as a printable string.
343
344 =head2 chmod
345
346  chmod mode path
347
348 Change the mode (permissions) of C<path> to C<mode>.  Only
349 numeric modes are supported.
350
351 =head2 chown
352
353  chown owner group path
354
355 Change the file owner to C<owner> and group to C<group>.
356
357 Only numeric uid and gid are supported.  If you want to use
358 names, you will need to locate and parse the password file
359 yourself (Augeas support makes this relatively easy).
360
361 =head2 command
362
363  command 'arguments ...'
364
365 This call runs a command from the guest filesystem.  The
366 filesystem must be mounted, and must contain a compatible
367 operating system (ie. something Linux, with the same
368 or compatible processor architecture).
369
370 The single parameter is an argv-style list of arguments.
371 The first element is the name of the program to run.
372 Subsequent elements are parameters.  The list must be
373 non-empty (ie. must contain a program name).
374
375 The C<$PATH> environment variable will contain at least
376 C</usr/bin> and C</bin>.  If you require a program from
377 another location, you should provide the full path in the
378 first parameter.
379
380 Shared libraries and data files required by the program
381 must be available on filesystems which are mounted in the
382 correct places.  It is the caller's responsibility to ensure
383 all filesystems that are needed are mounted at the right
384 locations.
385
386 =head2 command-lines
387
388  command-lines 'arguments ...'
389
390 This is the same as C<command>, but splits the
391 result into a list of lines.
392
393 =head2 config
394
395  config qemuparam qemuvalue
396
397 This can be used to add arbitrary qemu command line parameters
398 of the form C<-param value>.  Actually it's not quite arbitrary - we
399 prevent you from setting some parameters which would interfere with
400 parameters that we use.
401
402 The first character of C<param> string must be a C<-> (dash).
403
404 C<value> can be NULL.
405
406 =head2 cp
407
408  cp src dest
409
410 This copies a file from C<src> to C<dest> where C<dest> is
411 either a destination filename or destination directory.
412
413 =head2 cp-a
414
415  cp-a src dest
416
417 This copies a file or directory from C<src> to C<dest>
418 recursively using the C<cp -a> command.
419
420 =head2 debug
421
422  debug subcmd 'extraargs ...'
423
424 The C<debug> command exposes some internals of
425 C<guestfsd> (the guestfs daemon) that runs inside the
426 qemu subprocess.
427
428 There is no comprehensive help for this command.  You have
429 to look at the file C<daemon/debug.c> in the libguestfs source
430 to find out what you can do.
431
432 =head2 dmesg
433
434  dmesg
435
436 This returns the kernel messages (C<dmesg> output) from
437 the guest kernel.  This is sometimes useful for extended
438 debugging of problems.
439
440 Another way to get the same information is to enable
441 verbose messages with C<set-verbose> or by setting
442 the environment variable C<LIBGUESTFS_DEBUG=1> before
443 running the program.
444
445 =head2 download
446
447  download remotefilename (filename|-)
448
449 Download file C<remotefilename> and save it as C<filename>
450 on the local machine.
451
452 C<filename> can also be a named pipe.
453
454 See also C<upload>, C<cat>.
455
456 Use C<-> instead of a filename to read/write from stdin/stdout.
457
458 =head2 drop-caches
459
460  drop-caches whattodrop
461
462 This instructs the guest kernel to drop its page cache,
463 and/or dentries and inode caches.  The parameter C<whattodrop>
464 tells the kernel what precisely to drop, see
465 L<http://linux-mm.org/Drop_Caches>
466
467 Setting C<whattodrop> to 3 should drop everything.
468
469 This automatically calls L<sync(2)> before the operation,
470 so that the maximum guest memory is freed.
471
472 =head2 equal
473
474  equal file1 file2
475
476 This compares the two files C<file1> and C<file2> and returns
477 true if their content is exactly equal, or false otherwise.
478
479 The external L<cmp(1)> program is used for the comparison.
480
481 =head2 exists
482
483  exists path
484
485 This returns C<true> if and only if there is a file, directory
486 (or anything) with the given C<path> name.
487
488 See also C<is-file>, C<is-dir>, C<stat>.
489
490 =head2 file
491
492  file path
493
494 This call uses the standard L<file(1)> command to determine
495 the type or contents of the file.  This also works on devices,
496 for example to find out whether a partition contains a filesystem.
497
498 The exact command which runs is C<file -bsL path>.  Note in
499 particular that the filename is not prepended to the output
500 (the C<-b> option).
501
502 =head2 fsck
503
504  fsck fstype device
505
506 This runs the filesystem checker (fsck) on C<device> which
507 should have filesystem type C<fstype>.
508
509 The returned integer is the status.  See L<fsck(8)> for the
510 list of status codes from C<fsck>.
511
512 Notes:
513
514 =over 4
515
516 =item *
517
518 Multiple status codes can be summed together.
519
520 =item *
521
522 A non-zero return code can mean "success", for example if
523 errors have been corrected on the filesystem.
524
525 =item *
526
527 Checking or repairing NTFS volumes is not supported
528 (by linux-ntfs).
529
530 =back
531
532 This command is entirely equivalent to running C<fsck -a -t fstype device>.
533
534 =head2 get-autosync
535
536  get-autosync
537
538 Get the autosync flag.
539
540 =head2 get-e2label
541
542  get-e2label device
543
544 This returns the ext2/3/4 filesystem label of the filesystem on
545 C<device>.
546
547 =head2 get-e2uuid
548
549  get-e2uuid device
550
551 This returns the ext2/3/4 filesystem UUID of the filesystem on
552 C<device>.
553
554 =head2 get-path
555
556  get-path
557
558 Return the current search path.
559
560 This is always non-NULL.  If it wasn't set already, then this will
561 return the default path.
562
563 =head2 get-qemu
564
565  get-qemu
566
567 Return the current qemu binary.
568
569 This is always non-NULL.  If it wasn't set already, then this will
570 return the default qemu binary name.
571
572 =head2 get-state
573
574  get-state
575
576 This returns the current state as an opaque integer.  This is
577 only useful for printing debug and internal error messages.
578
579 For more information on states, see L<guestfs(3)>.
580
581 =head2 get-verbose
582
583  get-verbose
584
585 This returns the verbose messages flag.
586
587 =head2 grub-install
588
589  grub-install root device
590
591 This command installs GRUB (the Grand Unified Bootloader) on
592 C<device>, with the root directory being C<root>.
593
594 =head2 hexdump
595
596  hexdump path
597
598 This runs C<hexdump -C> on the given C<path>.  The result is
599 the human-readable, canonical hex dump of the file.
600
601 Because of the message protocol, there is a transfer limit 
602 of somewhere between 2MB and 4MB.  To transfer large files you should use
603 FTP.
604
605 =head2 is-busy
606
607  is-busy
608
609 This returns true iff this handle is busy processing a command
610 (in the C<BUSY> state).
611
612 For more information on states, see L<guestfs(3)>.
613
614 =head2 is-config
615
616  is-config
617
618 This returns true iff this handle is being configured
619 (in the C<CONFIG> state).
620
621 For more information on states, see L<guestfs(3)>.
622
623 =head2 is-dir
624
625  is-dir path
626
627 This returns C<true> if and only if there is a directory
628 with the given C<path> name.  Note that it returns false for
629 other objects like files.
630
631 See also C<stat>.
632
633 =head2 is-file
634
635  is-file path
636
637 This returns C<true> if and only if there is a file
638 with the given C<path> name.  Note that it returns false for
639 other objects like directories.
640
641 See also C<stat>.
642
643 =head2 is-launching
644
645  is-launching
646
647 This returns true iff this handle is launching the subprocess
648 (in the C<LAUNCHING> state).
649
650 For more information on states, see L<guestfs(3)>.
651
652 =head2 is-ready
653
654  is-ready
655
656 This returns true iff this handle is ready to accept commands
657 (in the C<READY> state).
658
659 For more information on states, see L<guestfs(3)>.
660
661 =head2 kill-subprocess
662
663  kill-subprocess
664
665 This kills the qemu subprocess.  You should never need to call this.
666
667 =head2 launch | run
668
669  launch
670
671 Internally libguestfs is implemented by running a virtual machine
672 using L<qemu(1)>.
673
674 You should call this after configuring the handle
675 (eg. adding drives) but before performing any actions.
676
677 =head2 list-devices
678
679  list-devices
680
681 List all the block devices.
682
683 The full block device names are returned, eg. C</dev/sda>
684
685 =head2 list-partitions
686
687  list-partitions
688
689 List all the partitions detected on all block devices.
690
691 The full partition device names are returned, eg. C</dev/sda1>
692
693 This does not return logical volumes.  For that you will need to
694 call C<lvs>.
695
696 =head2 ll
697
698  ll directory
699
700 List the files in C<directory> (relative to the root directory,
701 there is no cwd) in the format of 'ls -la'.
702
703 This command is mostly useful for interactive sessions.  It
704 is I<not> intended that you try to parse the output string.
705
706 =head2 ls
707
708  ls directory
709
710 List the files in C<directory> (relative to the root directory,
711 there is no cwd).  The '.' and '..' entries are not returned, but
712 hidden files are shown.
713
714 This command is mostly useful for interactive sessions.  Programs
715 should probably use C<readdir> instead.
716
717 =head2 lstat
718
719  lstat path
720
721 Returns file information for the given C<path>.
722
723 This is the same as C<stat> except that if C<path>
724 is a symbolic link, then the link is stat-ed, not the file it
725 refers to.
726
727 This is the same as the C<lstat(2)> system call.
728
729 =head2 lvcreate
730
731  lvcreate logvol volgroup mbytes
732
733 This creates an LVM volume group called C<logvol>
734 on the volume group C<volgroup>, with C<size> megabytes.
735
736 =head2 lvm-remove-all
737
738  lvm-remove-all
739
740 This command removes all LVM logical volumes, volume groups
741 and physical volumes.
742
743 B<This command is dangerous.  Without careful use you
744 can easily destroy all your data>.
745
746 =head2 lvremove
747
748  lvremove device
749
750 Remove an LVM logical volume C<device>, where C<device> is
751 the path to the LV, such as C</dev/VG/LV>.
752
753 You can also remove all LVs in a volume group by specifying
754 the VG name, C</dev/VG>.
755
756 =head2 lvs
757
758  lvs
759
760 List all the logical volumes detected.  This is the equivalent
761 of the L<lvs(8)> command.
762
763 This returns a list of the logical volume device names
764 (eg. C</dev/VolGroup00/LogVol00>).
765
766 See also C<lvs-full>.
767
768 =head2 lvs-full
769
770  lvs-full
771
772 List all the logical volumes detected.  This is the equivalent
773 of the L<lvs(8)> command.  The "full" version includes all fields.
774
775 =head2 mkdir
776
777  mkdir path
778
779 Create a directory named C<path>.
780
781 =head2 mkdir-p
782
783  mkdir-p path
784
785 Create a directory named C<path>, creating any parent directories
786 as necessary.  This is like the C<mkdir -p> shell command.
787
788 =head2 mkfs
789
790  mkfs fstype device
791
792 This creates a filesystem on C<device> (usually a partition
793 or LVM logical volume).  The filesystem type is C<fstype>, for
794 example C<ext3>.
795
796 =head2 mount
797
798  mount device mountpoint
799
800 Mount a guest disk at a position in the filesystem.  Block devices
801 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
802 the guest.  If those block devices contain partitions, they will have
803 the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
804 names can be used.
805
806 The rules are the same as for L<mount(2)>:  A filesystem must
807 first be mounted on C</> before others can be mounted.  Other
808 filesystems can only be mounted on directories which already
809 exist.
810
811 The mounted filesystem is writable, if we have sufficient permissions
812 on the underlying device.
813
814 The filesystem options C<sync> and C<noatime> are set with this
815 call, in order to improve reliability.
816
817 =head2 mount-options
818
819  mount-options options device mountpoint
820
821 This is the same as the C<mount> command, but it
822 allows you to set the mount options as for the
823 L<mount(8)> I<-o> flag.
824
825 =head2 mount-ro
826
827  mount-ro device mountpoint
828
829 This is the same as the C<mount> command, but it
830 mounts the filesystem with the read-only (I<-o ro>) flag.
831
832 =head2 mount-vfs
833
834  mount-vfs options vfstype device mountpoint
835
836 This is the same as the C<mount> command, but it
837 allows you to set both the mount options and the vfstype
838 as for the L<mount(8)> I<-o> and I<-t> flags.
839
840 =head2 mounts
841
842  mounts
843
844 This returns the list of currently mounted filesystems.  It returns
845 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
846
847 Some internal mounts are not shown.
848
849 =head2 mv
850
851  mv src dest
852
853 This moves a file from C<src> to C<dest> where C<dest> is
854 either a destination filename or destination directory.
855
856 =head2 ping-daemon
857
858  ping-daemon
859
860 This is a test probe into the guestfs daemon running inside
861 the qemu subprocess.  Calling this function checks that the
862 daemon responds to the ping message, without affecting the daemon
863 or attached block device(s) in any other way.
864
865 =head2 pvcreate
866
867  pvcreate device
868
869 This creates an LVM physical volume on the named C<device>,
870 where C<device> should usually be a partition name such
871 as C</dev/sda1>.
872
873 =head2 pvremove
874
875  pvremove device
876
877 This wipes a physical volume C<device> so that LVM will no longer
878 recognise it.
879
880 The implementation uses the C<pvremove> command which refuses to
881 wipe physical volumes that contain any volume groups, so you have
882 to remove those first.
883
884 =head2 pvs
885
886  pvs
887
888 List all the physical volumes detected.  This is the equivalent
889 of the L<pvs(8)> command.
890
891 This returns a list of just the device names that contain
892 PVs (eg. C</dev/sda2>).
893
894 See also C<pvs-full>.
895
896 =head2 pvs-full
897
898  pvs-full
899
900 List all the physical volumes detected.  This is the equivalent
901 of the L<pvs(8)> command.  The "full" version includes all fields.
902
903 =head2 read-lines
904
905  read-lines path
906
907 Return the contents of the file named C<path>.
908
909 The file contents are returned as a list of lines.  Trailing
910 C<LF> and C<CRLF> character sequences are I<not> returned.
911
912 Note that this function cannot correctly handle binary files
913 (specifically, files containing C<\0> character which is treated
914 as end of line).  For those you need to use the C<read-file>
915 function which has a more complex interface.
916
917 =head2 rm
918
919  rm path
920
921 Remove the single file C<path>.
922
923 =head2 rm-rf
924
925  rm-rf path
926
927 Remove the file or directory C<path>, recursively removing the
928 contents if its a directory.  This is like the C<rm -rf> shell
929 command.
930
931 =head2 rmdir
932
933  rmdir path
934
935 Remove the single directory C<path>.
936
937 =head2 set-autosync | autosync
938
939  set-autosync true|false
940
941 If C<autosync> is true, this enables autosync.  Libguestfs will make a
942 best effort attempt to run C<umount-all> followed by
943 C<sync> when the handle is closed
944 (also if the program exits without closing handles).
945
946 This is disabled by default (except in guestfish where it is
947 enabled by default).
948
949 =head2 set-e2label
950
951  set-e2label device label
952
953 This sets the ext2/3/4 filesystem label of the filesystem on
954 C<device> to C<label>.  Filesystem labels are limited to
955 16 characters.
956
957 You can use either C<tune2fs-l> or C<get-e2label>
958 to return the existing label on a filesystem.
959
960 =head2 set-e2uuid
961
962  set-e2uuid device uuid
963
964 This sets the ext2/3/4 filesystem UUID of the filesystem on
965 C<device> to C<uuid>.  The format of the UUID and alternatives
966 such as C<clear>, C<random> and C<time> are described in the
967 L<tune2fs(8)> manpage.
968
969 You can use either C<tune2fs-l> or C<get-e2uuid>
970 to return the existing UUID of a filesystem.
971
972 =head2 set-path | path
973
974  set-path path
975
976 Set the path that libguestfs searches for kernel and initrd.img.
977
978 The default is C<$libdir/guestfs> unless overridden by setting
979 C<LIBGUESTFS_PATH> environment variable.
980
981 The string C<path> is stashed in the libguestfs handle, so the caller
982 must make sure it remains valid for the lifetime of the handle.
983
984 Setting C<path> to C<NULL> restores the default path.
985
986 =head2 set-qemu | qemu
987
988  set-qemu qemu
989
990 Set the qemu binary that we will use.
991
992 The default is chosen when the library was compiled by the
993 configure script.
994
995 You can also override this by setting the C<LIBGUESTFS_QEMU>
996 environment variable.
997
998 The string C<qemu> is stashed in the libguestfs handle, so the caller
999 must make sure it remains valid for the lifetime of the handle.
1000
1001 Setting C<qemu> to C<NULL> restores the default qemu binary.
1002
1003 =head2 set-verbose | verbose
1004
1005  set-verbose true|false
1006
1007 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
1008
1009 Verbose messages are disabled unless the environment variable
1010 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
1011
1012 =head2 sfdisk
1013
1014  sfdisk device cyls heads sectors 'lines ...'
1015
1016 This is a direct interface to the L<sfdisk(8)> program for creating
1017 partitions on block devices.
1018
1019 C<device> should be a block device, for example C</dev/sda>.
1020
1021 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1022 and sectors on the device, which are passed directly to sfdisk as
1023 the I<-C>, I<-H> and I<-S> parameters.  If you pass C<0> for any
1024 of these, then the corresponding parameter is omitted.  Usually for
1025 'large' disks, you can just pass C<0> for these, but for small
1026 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1027 out the right geometry and you will need to tell it.
1028
1029 C<lines> is a list of lines that we feed to C<sfdisk>.  For more
1030 information refer to the L<sfdisk(8)> manpage.
1031
1032 To create a single partition occupying the whole disk, you would
1033 pass C<lines> as a single element list, when the single element being
1034 the string C<,> (comma).
1035
1036 B<This command is dangerous.  Without careful use you
1037 can easily destroy all your data>.
1038
1039 =head2 stat
1040
1041  stat path
1042
1043 Returns file information for the given C<path>.
1044
1045 This is the same as the C<stat(2)> system call.
1046
1047 =head2 statvfs
1048
1049  statvfs path
1050
1051 Returns file system statistics for any mounted file system.
1052 C<path> should be a file or directory in the mounted file system
1053 (typically it is the mount point itself, but it doesn't need to be).
1054
1055 This is the same as the C<statvfs(2)> system call.
1056
1057 =head2 strings
1058
1059  strings path
1060
1061 This runs the L<strings(1)> command on a file and returns
1062 the list of printable strings found.
1063
1064 Because of the message protocol, there is a transfer limit 
1065 of somewhere between 2MB and 4MB.  To transfer large files you should use
1066 FTP.
1067
1068 =head2 strings-e
1069
1070  strings-e encoding path
1071
1072 This is like the C<strings> command, but allows you to
1073 specify the encoding.
1074
1075 See the L<strings(1)> manpage for the full list of encodings.
1076
1077 Commonly useful encodings are C<l> (lower case L) which will
1078 show strings inside Windows/x86 files.
1079
1080 The returned strings are transcoded to UTF-8.
1081
1082 Because of the message protocol, there is a transfer limit 
1083 of somewhere between 2MB and 4MB.  To transfer large files you should use
1084 FTP.
1085
1086 =head2 sync
1087
1088  sync
1089
1090 This syncs the disk, so that any writes are flushed through to the
1091 underlying disk image.
1092
1093 You should always call this if you have modified a disk image, before
1094 closing the handle.
1095
1096 =head2 tar-in
1097
1098  tar-in (tarfile|-) directory
1099
1100 This command uploads and unpacks local file C<tarfile> (an
1101 I<uncompressed> tar file) into C<directory>.
1102
1103 To upload a compressed tarball, use C<tgz-in>.
1104
1105 Use C<-> instead of a filename to read/write from stdin/stdout.
1106
1107 =head2 tar-out
1108
1109  tar-out directory (tarfile|-)
1110
1111 This command packs the contents of C<directory> and downloads
1112 it to local file C<tarfile>.
1113
1114 To download a compressed tarball, use C<tgz-out>.
1115
1116 Use C<-> instead of a filename to read/write from stdin/stdout.
1117
1118 =head2 tgz-in
1119
1120  tgz-in (tarball|-) directory
1121
1122 This command uploads and unpacks local file C<tarball> (a
1123 I<gzip compressed> tar file) into C<directory>.
1124
1125 To upload an uncompressed tarball, use C<tar-in>.
1126
1127 Use C<-> instead of a filename to read/write from stdin/stdout.
1128
1129 =head2 tgz-out
1130
1131  tgz-out directory (tarball|-)
1132
1133 This command packs the contents of C<directory> and downloads
1134 it to local file C<tarball>.
1135
1136 To download an uncompressed tarball, use C<tar-out>.
1137
1138 Use C<-> instead of a filename to read/write from stdin/stdout.
1139
1140 =head2 touch
1141
1142  touch path
1143
1144 Touch acts like the L<touch(1)> command.  It can be used to
1145 update the timestamps on a file, or, if the file does not exist,
1146 to create a new zero-length file.
1147
1148 =head2 tune2fs-l
1149
1150  tune2fs-l device
1151
1152 This returns the contents of the ext2, ext3 or ext4 filesystem
1153 superblock on C<device>.
1154
1155 It is the same as running C<tune2fs -l device>.  See L<tune2fs(8)>
1156 manpage for more details.  The list of fields returned isn't
1157 clearly defined, and depends on both the version of C<tune2fs>
1158 that libguestfs was built against, and the filesystem itself.
1159
1160 =head2 umount | unmount
1161
1162  umount pathordevice
1163
1164 This unmounts the given filesystem.  The filesystem may be
1165 specified either by its mountpoint (path) or the device which
1166 contains the filesystem.
1167
1168 =head2 umount-all | unmount-all
1169
1170  umount-all
1171
1172 This unmounts all mounted filesystems.
1173
1174 Some internal mounts are not unmounted by this call.
1175
1176 =head2 upload
1177
1178  upload (filename|-) remotefilename
1179
1180 Upload local file C<filename> to C<remotefilename> on the
1181 filesystem.
1182
1183 C<filename> can also be a named pipe.
1184
1185 See also C<download>.
1186
1187 Use C<-> instead of a filename to read/write from stdin/stdout.
1188
1189 =head2 vgcreate
1190
1191  vgcreate volgroup 'physvols ...'
1192
1193 This creates an LVM volume group called C<volgroup>
1194 from the non-empty list of physical volumes C<physvols>.
1195
1196 =head2 vgremove
1197
1198  vgremove vgname
1199
1200 Remove an LVM volume group C<vgname>, (for example C<VG>).
1201
1202 This also forcibly removes all logical volumes in the volume
1203 group (if any).
1204
1205 =head2 vgs
1206
1207  vgs
1208
1209 List all the volumes groups detected.  This is the equivalent
1210 of the L<vgs(8)> command.
1211
1212 This returns a list of just the volume group names that were
1213 detected (eg. C<VolGroup00>).
1214
1215 See also C<vgs-full>.
1216
1217 =head2 vgs-full
1218
1219  vgs-full
1220
1221 List all the volumes groups detected.  This is the equivalent
1222 of the L<vgs(8)> command.  The "full" version includes all fields.
1223
1224 =head2 write-file
1225
1226  write-file path content size
1227
1228 This call creates a file called C<path>.  The contents of the
1229 file is the string C<content> (which can contain any 8 bit data),
1230 with length C<size>.
1231
1232 As a special case, if C<size> is C<0>
1233 then the length is calculated using C<strlen> (so in this case
1234 the content cannot contain embedded ASCII NULs).
1235
1236 I<NB.> Owing to a bug, writing content containing ASCII NUL
1237 characters does I<not> work, even if the length is specified.
1238 We hope to resolve this bug in a future version.  In the meantime
1239 use C<upload>.
1240
1241 Because of the message protocol, there is a transfer limit 
1242 of somewhere between 2MB and 4MB.  To transfer large files you should use
1243 FTP.
1244
1245 =head2 zero
1246
1247  zero device
1248
1249 This command writes zeroes over the first few blocks of C<device>.
1250
1251 How many blocks are zeroed isn't specified (but it's I<not> enough
1252 to securely wipe the device).  It should be sufficient to remove
1253 any partition tables, filesystem superblocks and so on.
1254