X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=fish%2Fguestfish.pod;h=8fc720e106a9be1a38b7e8ce432a99d30d1f3d40;hb=5222be29f81fb98f0448d6e289c2c486fbc56883;hp=13a9fa7dd2d917233c4a37c0f0612e5e6e39bc7f;hpb=8980c01b46eafcf4b5dc127e4696c2cbe1bff09f;p=libguestfs.git diff --git a/fish/guestfish.pod b/fish/guestfish.pod index 13a9fa7..8fc720e 100644 --- a/fish/guestfish.pod +++ b/fish/guestfish.pod @@ -18,6 +18,13 @@ guestfish - the libguestfs Filesystem Interactive SHell guestfish -i disk.img [disk.img ...] +=head1 WARNING + +Using guestfish in read/write mode on live virtual machines can be +dangerous, potentially causing disk corruption. Use the I<--ro> +(read-only) option to use guestfish safely if the disk image or +virtual machine might be live. + =head1 EXAMPLES =head2 As an interactive shell @@ -98,14 +105,9 @@ the functionality of the guestfs API, see L. Guestfish gives you structured access to the libguestfs API, from shell scripts or the command line or interactively. If you want to -rescue a broken virtual machine image, you might want to look at the +rescue a broken virtual machine image, you should look at the L command. -Using guestfish in read/write mode on live virtual machines can be -dangerous, potentially causing disk corruption. Use the I<--ro> -(read-only) option to use guestfish safely if the disk image or -virtual machine might be live. - =head1 OPTIONS =over 4 @@ -168,7 +170,7 @@ See also: L. =item B<--listen> Fork into the background and listen for remote commands. See section -I below. +L below. =item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]> @@ -178,7 +180,7 @@ If the mountpoint is omitted, it defaults to C. You have to mount something on C before most commands will work. -If any C<-m> or C<--mount> options are given, the guest is +If any I<-m> or I<--mount> options are given, the guest is automatically launched. If you don't know what filesystems a disk image contains, you @@ -194,11 +196,11 @@ of autosync in the L manpage. =item B<--remote[=pid]> Send remote commands to C<$GUESTFISH_PID> or C. See section -I below. +L below. =item B<-r> | B<--ro> -This changes the C<-a> and C<-m> options so that disks are added and +This changes the I<-a> and I<-m> options so that disks are added and mounts are done read-only (see L). The option must always be used if the disk image or virtual machine @@ -272,7 +274,7 @@ any other commands C is a synonym for C. You must C (or C) your guest before mounting or performing any other commands. -The only exception is that if the C<-m> or C<--mount> option was +The only exception is that if the I<-m> or I<--mount> option was given, the guest is automatically run for you (simply because guestfish can't mount the disks you asked for without doing this). @@ -296,6 +298,25 @@ must be escaped with a backslash. command "/bin/echo 'foo bar'" command "/bin/echo \'foo\'" +=head1 NUMBERS + +Commands which take integers as parameters use the C convention which +is to use C<0> to prefix an octal number or C<0x> to prefix a +hexadecimal number. For example: + + 1234 decimal number 1234 + 02322 octal number, equivalent to decimal 1234 + 0x4d2 hexadecimal number, equivalent to decimal 1234 + +When using the C command, you almost always want to specify an +octal number for the mode, and you must prefix it with C<0> (unlike +the Unix L program): + + chmod 0777 /public # OK + chmod 777 /public # WRONG! This is mode 777 decimal = 01411 octal. + +Commands that return numbers currently always print them in decimal. + =head1 WILDCARDS AND GLOBBING Neither guestfish nor the underlying guestfs API performs @@ -348,6 +369,9 @@ will create a directory C on the host, and then export the contents of C on the mounted filesystem to C. (See C). +To change the local directory, use the C command. C will +have no effect, due to the way that subprocesses work in Unix. + =head1 PIPES Use CspaceE | command> to pipe the output of the @@ -363,6 +387,7 @@ Other examples: hexdump /bin/ls | head list-devices | tail -1 + tgz-out / - | tar ztf - The space before the pipe symbol is required, any space after the pipe symbol is optional. Everything after the pipe symbol is just passed @@ -405,6 +430,25 @@ This syntax implicitly calls C (q.v.) so it also handles case insensitivity like Windows would. This only works in argument positions that expect a path. +=head1 UPLOADING AND DOWNLOADING FILES + +For commands such as C, C, C, C and +others which upload from or download to a local file, you can use the +special filename C<-> to mean "from stdin" or "to stdout". For example: + + upload - /foo + +reads stdin and creates from that a file C in the disk image, +and: + + tar-out /etc - | tar tf - + +writes the tarball to stdout and then pipes that into the external +"tar" command (see L). + +When using C<-> to read from stdin, the input is read up to the end of +stdin. + =head1 EXIT ON ERROR BEHAVIOUR By default, guestfish will ignore any errors when in interactive mode @@ -436,13 +480,13 @@ To cause the server to exit, send it the exit command: guestfish --remote exit Note that the server will normally exit if there is an error in a -command. You can change this in the usual way. See section I. +command. You can change this in the usual way. See section +L. =head2 CONTROLLING MULTIPLE GUESTFISH PROCESSES The C statement sets the environment variable C<$GUESTFISH_PID>, -which is how the C<--remote> option knows where to send the commands. +which is how the I<--remote> option knows where to send the commands. You can have several guestfish listener processes running using: eval `guestfish --listen` @@ -526,9 +570,6 @@ The editor is C<$EDITOR>. However if you use the alternate commands C or C you will get those corresponding editors. -NOTE: This will not work reliably for large files -(> 2 MB) or binary files containing \0 bytes. - =head2 glob glob command args... @@ -566,9 +607,6 @@ This is used to view a file. The default viewer is C<$PAGER>. However if you use the alternate command C you will get the C command specifically. -NOTE: This will not work reliably for large files -(> 2 MB) or binary files containing \0 bytes. - =head2 quit | exit This exits guestfish. You can also use C<^D> key. @@ -641,6 +679,11 @@ can be useful for benchmarking operations. @ACTIONS@ +=head1 EXIT CODE + +guestfish returns 0 if the commands completed without error, or +1 if there was an error. + =head1 ENVIRONMENT VARIABLES =over 4 @@ -653,13 +696,13 @@ set, it uses C. =item GUESTFISH_PID Used with the I<--remote> option to specify the remote guestfish -process to control. See section I. +process to control. See section +L. =item HOME -If compiled with GNU readline support, then the command history -is saved in C<$HOME/.guestfish> +If compiled with GNU readline support, various files in the +home directory can be used. See L. =item LIBGUESTFS_APPEND @@ -709,21 +752,62 @@ enough. =back -=head1 EXIT CODE +=head1 FILES + +=over 4 + +=item $HOME/.guestfish + +If compiled with GNU readline support, then the command history +is saved in this file. + +=item $HOME/.inputrc + +=item /etc/inputrc + +If compiled with GNU readline support, then these files can be used to +configure readline. For further information, please see +L. -guestfish returns I<0> if the commands completed without error, or -I<1> if there was an error. +To write rules which only apply to guestfish, use: + + $if guestfish + ... + $endif + +Variables that you can set in inputrc that change the behaviour +of guestfish in useful ways include: + +=over 4 + +=item completion-ignore-case (default: on) + +By default, guestfish will ignore case when tab-completing +paths on the disk. Use: + + set completion-ignore-case off + +to make guestfish case sensitive. + +=back + +=back =head1 SEE ALSO L, L, L, +L, L, L, +L, L, +L, L, -L. +L, +L, +L. =head1 AUTHORS @@ -731,7 +815,7 @@ Richard W.M. Jones (C) =head1 COPYRIGHT -Copyright (C) 2009 Red Hat Inc. +Copyright (C) 2009-2010 Red Hat Inc. L This program is free software; you can redistribute it and/or modify