Welcome to guestfish, the libguestfs filesystem interactive shell for
editing virtual machine filesystems.
- Type: 'help' for help with commands
+ Type: 'help' for a list of commands
+ 'man' to read the manual
'quit' to quit the shell
- ><fs> help
+ ><fs> man
=head2 From shell scripts
=head2 As a script interpreter
-Create a 50MB disk containing an ext2-formatted partition:
+Create a 100MB disk containing an ext2-formatted partition:
#!/usr/bin/guestfish -f
- alloc /tmp/output.img 50M
+ sparse test1.img 100M
run
part-disk /dev/sda mbr
mkfs ext2 /dev/sda1
+=head2 Start with a prepared disk
+
+An alternate way to create a 100MB disk called C<test1.img> containing
+a single ext2-formatted partition:
+
+ guestfish -N fs
+
+To list what is available do:
+
+ guestfish -N list | less
+
=head2 Remote control
eval `guestfish --listen --ro`
guestfish -i /dev/Guests/MyGuest
-You cannot use I<-a>, I<-m>, I<--listen>, I<--remote> or I<--selinux>
-in conjunction with this option, and options other than I<--ro> might
-not behave correctly.
+You cannot use I<-a>, I<-m>, I<-N>, I<--listen>, I<--remote> or
+I<--selinux> in conjunction with this option, and options other than
+I<--ro> might not behave correctly.
See also: L<virt-inspector(1)>.
Disable autosync. This is enabled by default. See the discussion
of autosync in the L<guestfs(3)> manpage.
+=item B<-N type> | B<--new type> | B<-N list>
+
+Prepare a fresh disk image formatted as "type". This is an
+alternative to the I<-a> option: whereas I<-a> adds an existing disk,
+I<-N> creates a preformatted disk with a filesystem and adds it.
+See L</PREPARED DISK IMAGES> below.
+
=item B<--remote[=pid]>
Send remote commands to C<$GUESTFISH_PID> or C<pid>. See section
might be running, and is generally recommended in cases where you
don't need write access to the disk.
+Note that prepared disk images created with I<-N> are not affected by
+the I<--ro> option.
+
=item B<--selinux>
Enable SELinux support for the guest. See L<guestfs(3)/SELINUX>.
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<upload>, C<download>, C<tar-in>, C<tar-out> 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</foo> 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</PIPES>).
+
+When using C<-> to read from stdin, the input is read up to the end of
+stdin. You can also use a special "heredoc"-like syntax to read up to
+some arbitrary end marker:
+
+ upload -<<END /foo
+ input line 1
+ input line 2
+ input line 3
+ END
+
+Any string of characters can be used instead of C<END>. The end
+marker must appear on a line of its own, without any preceeding or
+following characters (not even spaces).
+
+Note that the C<-E<lt>E<lt>> syntax only applies to parameters used to
+upload local files (so-called "FileIn" parameters in the generator).
+
=head1 EXIT ON ERROR BEHAVIOUR
By default, guestfish will ignore any errors when in interactive mode
Guestfish client and server versions must match exactly.
-=head1 UPLOADING AND DOWNLOADING FILES
+=head1 PREPARED DISK IMAGES
-For commands such as C<upload>, C<download>, C<tar-in>, C<tar-out> 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:
+Use the I<-N type> or I<--new type> parameter to select one of a set
+of preformatted disk images that guestfish can make for you to save
+typing. This is particularly useful for testing purposes. This
+option is used instead of the I<-a> option, and like I<-a> can appear
+multiple times (and can be mixed with I<-a>).
- upload - /foo
+The new disk is called C<test1.img> for the first I<-N>, C<test2.img>
+for the second and so on. Existing files in the current directory are
+I<overwritten>.
-reads stdin and creates from that a file C</foo> in the disk image,
-and:
+The type briefly describes how the disk should be sized, partitioned,
+how filesystem(s) should be created, and how content should be added.
+Optionally the type can be followed by extra parameters, separated by
+C<:> (colon) characters. For example, I<-N fs> creates a default
+100MB, sparsely-allocated disk, containing a single partition, with
+the partition formatted as ext2. I<-N fs:ext4:1G> is the same, but
+for an ext4 filesystem on a 1GB disk instead.
- tar-out /etc - | tar tf -
+To list the available types and any extra parameters they take, run:
-writes the tarball to stdout and then pipes that into the external
-"tar" command (see L</PIPES>).
+ guestfish -N list | less
-When using C<-> to read from stdin, the input is read up to the end of
-stdin. You can also use a special "heredoc"-like syntax to read up to
-some arbitrary end marker:
+Note that the prepared filesystem is not mounted. You would usually
+have to use the C<mount /dev/sda1 /> command or add the
+I<-m /dev/sda1> option.
- upload -<<END /foo
- input line 1
- input line 2
- input line 3
- END
+If any I<-N> or I<--new> options are given, the guest is automatically
+launched.
-Any string of characters can be used instead of C<END>. The end
-marker must appear on a line of its own, without any preceeding or
-following characters (not even spaces).
+=head2 EXAMPLES
-Note that the C<-E<lt>E<lt>> syntax only applies to parameters used to
-upload local files (so-called "FileIn" parameters in the generator).
+Create a 100MB disk with an ext4-formatted partition:
+
+ guestfish -N fs:ext4
+
+Create a 32MB disk with a VFAT-formatted partition, and mount it:
+
+ guestfish -N fs:vfat:32M -m /dev/sda1
+
+Create a blank 200MB disk:
+
+ guestfish -N disk:200M
=head1 GUESTFISH COMMANDS
Note that C<!cd> won't do what you might expect.
+=head2 man | manual
+
+ man
+
+Opens the manual page for guestfish.
+
=head2 more | less
more filename
=head1 EXIT CODE
-guestfish returns I<0> if the commands completed without error, or
-I<1> if there was an error.
+guestfish returns 0 if the commands completed without error, or
+1 if there was an error.
=head1 SEE ALSO
=head1 COPYRIGHT
-Copyright (C) 2009 Red Hat Inc.
+Copyright (C) 2009-2010 Red Hat Inc.
L<http://libguestfs.org/>
This program is free software; you can redistribute it and/or modify