diff --git a/.gitignore b/.gitignore index e44c5167c..2b1e4b2c2 100644 --- a/.gitignore +++ b/.gitignore @@ -39,6 +39,7 @@ guestfish.1 guestfs.3 html/guestfish.1.html html/guestfs.3.html +html/recipes.html initramfs initramfs.timestamp initramfs.*.img diff --git a/Makefile.am b/Makefile.am index 1b5ea897c..c0c2ebbef 100644 --- a/Makefile.am +++ b/Makefile.am @@ -44,7 +44,12 @@ EXTRA_DIST = \ 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 @@ -135,7 +140,38 @@ html/guestfish.1.html: guestfish.pod guestfish-actions.pod --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 'guestfish recipes' >> $@-t; \ + echo '' >> $@-t; \ + echo '' >> $@-t; \ + echo '' >> $@-t; \ + echo '' >> $@-t; \ + echo '

guestfish recipes

' >> $@-t; \ + echo '

You can also find these in the recipes/ subdirectory of the source.

' >> $@-t; \ + for f in recipes/*.sh; do \ + b=`basename $$f .sh`; \ + echo -n '' >> $@-t; \ + if [ -r recipes/$$b.html ]; then \ + cat recipes/$$b.html >> $@-t; \ + else \ + echo '

$$b

' >> $@-t; \ + fi; \ + echo '
' >> $@-t; \
+	  sed -e 's,&,\&,g' -e 's,<,\<,g' -e 's,>,\>,g' < $$f >> $@-t; \
+	  echo '
' >> $@-t; \ + if [ -r recipes/$$b.example ]; then \ + echo '

Example output

' >> $@-t; \ + echo '
' >> $@-t; \
+	    sed -e 's,&,\&,g' -e 's,<,\<,g' -e 's,>,\>,g' < recipes/$$b.example >> $@-t; \
+	    echo '
' >> $@-t; \ + fi; \ + done; \ + echo '' >> $@-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. diff --git a/libguestfs.spec.in b/libguestfs.spec.in index ec65ffac3..1830bc5ac 100644 --- a/libguestfs.spec.in +++ b/libguestfs.spec.in @@ -327,7 +327,7 @@ rm -rf $RPM_BUILD_ROOT %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* diff --git a/recipes/LICENSE b/recipes/LICENSE new file mode 100644 index 000000000..d15411e51 --- /dev/null +++ b/recipes/LICENSE @@ -0,0 +1,2 @@ +All the scripts in the recipes/ subdirectory may be freely +copied without any restrictions. diff --git a/recipes/README b/recipes/README new file mode 100644 index 000000000..6a1f72889 --- /dev/null +++ b/recipes/README @@ -0,0 +1,26 @@ +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

..

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 ... diff --git a/recipes/clone.example b/recipes/clone.example new file mode 100644 index 000000000..8e8a1c1a8 --- /dev/null +++ b/recipes/clone.example @@ -0,0 +1,20 @@ +$ 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 + +> cat /etc/resolv.conf +nameserver 192.168.1.1 +> cat /etc/HOSTNAME +newmachine diff --git a/recipes/clone.html b/recipes/clone.html new file mode 100644 index 000000000..a9998e181 --- /dev/null +++ b/recipes/clone.html @@ -0,0 +1,19 @@ +

Clone and edit a virtual machine

+ +

+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. +

+ +

+In this simple recipe, we overwrite the /etc/resolv.conf file +with a new nameserver entry, and change /etc/HOSTNAME. +

+ +

+There are lots of possible improvements to this script, such as +using qcow snapshots so that cloned VMs share storage with their +"parent" preimages. +

diff --git a/recipes/clone.sh b/recipes/clone.sh new file mode 100755 index 000000000..e3fc11cf1 --- /dev/null +++ b/recipes/clone.sh @@ -0,0 +1,15 @@ +#!/bin/sh - + +preimage="$1" +newimage="$2" +root="$3" +nameserver="$4" +hostname="$5" + +dd if="$preimage" of="$newimage" + +guestfish -a "$newimage" -m "$root" <Fix an unbootable VM by editing /boot/grub/grub.conf + +

+If you messed up your VM and made it unbootable, it's +often useful to be able to go in and edit /boot/grub/grub.conf. +This guestfish script shows how to do that. +

+ +

+Usage assumes that the VM has a separate /boot +partition containing grub, which is usually the case. So +for example: +

+ +
+editgrub.sh broken-guest.img /dev/sda1
+
diff --git a/recipes/editgrub.sh b/recipes/editgrub.sh new file mode 100755 index 000000000..4cb8ee9c7 --- /dev/null +++ b/recipes/editgrub.sh @@ -0,0 +1,3 @@ +#!/bin/sh - + +guestfish -a "$1" -m "$2" vi /grub/grub.conf diff --git a/recipes/show-devices.example b/recipes/show-devices.example new file mode 100644 index 000000000..ccab9ef47 --- /dev/null +++ b/recipes/show-devices.example @@ -0,0 +1,14 @@ +$ 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 diff --git a/recipes/show-devices.html b/recipes/show-devices.html new file mode 100644 index 000000000..f89a8ea89 --- /dev/null +++ b/recipes/show-devices.html @@ -0,0 +1,7 @@ +

Display the devices, partitions, LVs, VGs and PVs in a guest image

+ +

+This very simple script shows how you can display an overview +of what devices, partitions and LVM data are found in a +guest image. +

diff --git a/recipes/show-devices.sh b/recipes/show-devices.sh new file mode 100755 index 000000000..6fd2b75bc --- /dev/null +++ b/recipes/show-devices.sh @@ -0,0 +1,10 @@ +#!/bin/sh - + +guestfish -a "$1" <Make a virtual machine out of a tarball + +

+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. +

+ +

+The usage is: +

+ +
+tar2vm.sh input.tar.gz output.img 100M
+
+ +

+where (for example) 100M 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). +

diff --git a/recipes/tar2vm.sh b/recipes/tar2vm.sh new file mode 100755 index 000000000..d71a5ef2d --- /dev/null +++ b/recipes/tar2vm.sh @@ -0,0 +1,11 @@ +#!/bin/sh - + +guestfish <