guestfs.3
html/guestfish.1.html
html/guestfs.3.html
+html/recipes.html
initramfs
initramfs.timestamp
initramfs.*.img
HACKING TODO \
tests.c \
libguestfs.pc libguestfs.pc.in \
- gitlog-to-changelog
+ gitlog-to-changelog \
+ recipes/LICENSE \
+ recipes/README \
+ recipes/*.html \
+ recipes/*.sh \
+ recipes/*.example
# Build the root filesystem.
# Currently this is arch-dependent, so it seems like putting it in
--htmldir html \
--outfile $@
-website: html/guestfs.3.html html/guestfish.1.html
+# Recipes web page.
+html/recipes.html: $(wildcard recipes/*.sh) $(wildcard recipes/*.html) $(wildcard recipes/*.example) Makefile
+ rm -f $@ $@-t
+ echo '<html><head><title>guestfish recipes</title>' >> $@-t; \
+ echo '<link rel="stylesheet" href="http://et.redhat.com/~rjones/css/standard.css" type="text/css" title="Standard"/>' >> $@-t; \
+ echo '<link rel="stylesheet" href="http://et.redhat.com/~rjones/css/numbering.css" type="text/css" title="Standard"/>' >> $@-t; \
+ echo '<link rel="alternate stylesheet" href="http://et.redhat.com/~rjones/css/easytoread.css" type="text/css" title="High contrast, big fonts"/>' >> $@-t; \
+ echo '</head><body>' >> $@-t; \
+ echo '<h1>guestfish recipes</h1>' >> $@-t; \
+ echo '<p>You can also find these in the <code>recipes/</code> subdirectory of the source.</p>' >> $@-t; \
+ for f in recipes/*.sh; do \
+ b=`basename $$f .sh`; \
+ echo -n '<a name="'$$b'"></a>' >> $@-t; \
+ if [ -r recipes/$$b.html ]; then \
+ cat recipes/$$b.html >> $@-t; \
+ else \
+ echo '<h2>$$b</h2>' >> $@-t; \
+ fi; \
+ echo '<pre>' >> $@-t; \
+ sed -e 's,&,\&,g' -e 's,<,\<,g' -e 's,>,\>,g' < $$f >> $@-t; \
+ echo '</pre>' >> $@-t; \
+ if [ -r recipes/$$b.example ]; then \
+ echo '<h3>Example output</h3>' >> $@-t; \
+ echo '<pre>' >> $@-t; \
+ sed -e 's,&,\&,g' -e 's,<,\<,g' -e 's,>,\>,g' < recipes/$$b.example >> $@-t; \
+ echo '</pre>' >> $@-t; \
+ fi; \
+ done; \
+ echo '</body></html>' >> $@-t; \
+ mv $@-t $@
+
+website: html/guestfs.3.html html/guestfish.1.html html/recipes.html
cp $^ html/pod.css $(HOME)/d/redhat/et-website/libguestfs/
# Generate the ChangeLog automatically from the gitlog.
%files -n guestfish
%defattr(-,root,root,-)
-%doc html/guestfish.1.html html/pod.css
+%doc html/guestfish.1.html html/pod.css recipes/
%{_bindir}/guestfish
%{_mandir}/man1/guestfish.1*
--- /dev/null
+All the scripts in the recipes/ subdirectory may be freely
+copied without any restrictions.
--- /dev/null
+This directory contains guestfish-based shell which give some useful
+recipes to follow.
+
+These also get copied to the website here:
+http://et.redhat.com/~rjones/libguestfs/recipes.html
+
+The format for each recipe is:
+
+ foo.sh Shell script, using guestfish.
+ foo.html HTML snippet describing the recipe (should start
+ with <h2>..</h2> giving the title of the recipe)
+ foo.example Plain text snippet showing example output.
+
+Everything in the recipes/ directory may be used and distributed
+without restrictions.
+
+To run a script before libguestfs has been installed, you can do
+something like this:
+
+ LIBGUESTFS_PATH=.. PATH=../fish:$PATH ./show-devices.sh disk.img
+
+You can apply these recipes in your own programs by translating the
+guestfish commands into API calls in the language of your choice. The
+translation is a simple 1-1 mapping.
+
+Got a useful tip or recipe? Please contribute ...
--- /dev/null
+$ clone.sh /tmp/test.img /tmp/new.img /dev/sda1 192.168.1.1 newmachine
+204800+0 records in
+204800+0 records out
+104857600 bytes (105 MB) copied, 2.02821 s, 51.7 MB/s
+write-file /etc/resolv.conf "nameserver 192.168.1.1" 0
+write-file /etc/HOSTNAME "newmachine" 0
+sync
+
+$ guestfish -a /tmp/new.img -m /dev/sda1
+
+Welcome to guestfish, the libguestfs filesystem interactive shell for
+editing virtual machine filesystems.
+
+Type: 'help' for help with commands
+ 'quit' to quit the shell
+
+><fs> cat /etc/resolv.conf
+nameserver 192.168.1.1
+><fs> cat /etc/HOSTNAME
+newmachine
--- /dev/null
+<h2>Clone and edit a virtual machine</h2>
+
+<p>
+This script shows how you might have a library of premade
+virtual machines ready for cloning, but as a final step you
+use libguestfs or guestfish to customize some configuration
+files inside the VM before it's ready to go.
+</p>
+
+<p>
+In this simple recipe, we overwrite the <code>/etc/resolv.conf</code> file
+with a new nameserver entry, and change <code>/etc/HOSTNAME</code>.
+</p>
+
+<p>
+There are lots of possible improvements to this script, such as
+using qcow snapshots so that cloned VMs share storage with their
+"parent" preimages.
+</p>
--- /dev/null
+#!/bin/sh -
+
+preimage="$1"
+newimage="$2"
+root="$3"
+nameserver="$4"
+hostname="$5"
+
+dd if="$preimage" of="$newimage"
+
+guestfish -a "$newimage" -m "$root" <<EOF
+write-file /etc/resolv.conf "nameserver $nameserver" 0
+write-file /etc/HOSTNAME "$hostname" 0
+sync
+EOF
--- /dev/null
+<h2>Fix an unbootable VM by editing /boot/grub/grub.conf</h2>
+
+<p>
+If you messed up your VM and made it unbootable, it's
+often useful to be able to go in and edit <code>/boot/grub/grub.conf</code>.
+This guestfish script shows how to do that.
+</p>
+
+<p>
+Usage assumes that the VM has a separate <code>/boot</code>
+partition containing grub, which is usually the case. So
+for example:
+</p>
+
+<pre>
+editgrub.sh broken-guest.img /dev/sda1
+</pre>
--- /dev/null
+#!/bin/sh -
+
+guestfish -a "$1" -m "$2" vi /grub/grub.conf
--- /dev/null
+$ show-devices.sh /dev/mapper/Guests-RHEL53PV32
+run
+list-devices
+/dev/sda
+list-partitions
+/dev/sda1
+/dev/sda2
+pvs
+/dev/sda2
+vgs
+VolGroup00
+lvs
+/dev/VolGroup00/LogVol00
+/dev/VolGroup00/LogVol01
--- /dev/null
+<h2>Display the devices, partitions, LVs, VGs and PVs in a guest image</h2>
+
+<p>
+This very simple script shows how you can display an overview
+of what devices, partitions and LVM data are found in a
+guest image.
+</p>
--- /dev/null
+#!/bin/sh -
+
+guestfish -a "$1" <<EOF
+run
+list-devices
+list-partitions
+pvs
+vgs
+lvs
+EOF
--- /dev/null
+tar2vm.sh ../libguestfs-1.0.10.tar.gz /tmp/test.img 10M
+alloc /tmp/test.img 10M
+run
+sfdisk /dev/sda 0 0 0 ,
+mkfs ext3 /dev/sda1
+mount /dev/sda1 /
+tgz-in ../libguestfs-1.0.10.tar.gz /
+umount-all
--- /dev/null
+<h2>Make a virtual machine out of a tarball</h2>
+
+<p>
+This script shows how you might generate a whole virtual
+machine, or a disk image for a virtual machine, starting
+with a tarball that contains the content for the machine.
+</p>
+
+<p>
+The usage is:
+</p>
+
+<pre>
+tar2vm.sh input.tar.gz output.img 100M
+</pre>
+
+<p>
+where (for example) <code>100M</code> is the size of the output
+disk image. You have to specify a size that is large enough to contain all
+the contents of the tarball, but not too large that there is too much
+wasted space (unless you want to give the VM extra working space of
+course).
+</p>
--- /dev/null
+#!/bin/sh -
+
+guestfish <<EOF
+alloc $2 $3
+run
+sfdisk /dev/sda 0 0 0 ,
+mkfs ext3 /dev/sda1
+mount /dev/sda1 /
+tgz-in $1 /
+umount-all
+EOF
git.annexia.org / libguestfs.git / commitdiff