Added guestfish recipes.

2026-03-21 22:53:37 +00:00 · 2009-04-25 11:34:18 +01:00
parent ae17137f64
commit b86d7b9756
16 changed files with 215 additions and 3 deletions
--- 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
--- 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 '<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,&,\&amp;,g' -e 's,<,\&lt;,g' -e 's,>,\&gt;,g' < $$f >> $@-t; \
+	  echo '</pre>' >> $@-t; \
+	  if [ -r recipes/$$b.example ]; then \
+	    echo '<h3>Example output</h3>' >> $@-t; \
+	    echo '<pre>' >> $@-t; \
+	    sed -e 's,&,\&amp;,g' -e 's,<,\&lt;,g' -e 's,>,\&gt;,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.
--- 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*

--- a/recipes/LICENSE
+++ b/recipes/LICENSE
@@ -0,0 +1,2 @@
+All the scripts in the recipes/ subdirectory may be freely
+copied without any restrictions.
--- a/recipes/README
+++ 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 <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 ...
--- a/recipes/clone.example
+++ 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
+
+><fs> cat /etc/resolv.conf 
+nameserver 192.168.1.1
+><fs> cat /etc/HOSTNAME
+newmachine
--- a/recipes/clone.html
+++ b/recipes/clone.html
@@ -0,0 +1,19 @@
+<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>
--- a/recipes/clone.sh
+++ 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" <<EOF
+write-file /etc/resolv.conf "nameserver $nameserver" 0
+write-file /etc/HOSTNAME "$hostname" 0
+sync
+EOF
--- a/recipes/editgrub.html
+++ b/recipes/editgrub.html
@@ -0,0 +1,17 @@
+<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>
--- a/recipes/editgrub.sh
+++ b/recipes/editgrub.sh
@@ -0,0 +1,3 @@
+#!/bin/sh -
+
+guestfish -a "$1" -m "$2" vi /grub/grub.conf
--- a/recipes/show-devices.example
+++ 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
--- a/recipes/show-devices.html
+++ b/recipes/show-devices.html
@@ -0,0 +1,7 @@
+<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>
--- a/recipes/show-devices.sh
+++ b/recipes/show-devices.sh
@@ -0,0 +1,10 @@
+#!/bin/sh -
+
+guestfish -a "$1" <<EOF
+run
+list-devices
+list-partitions
+pvs
+vgs
+lvs
+EOF
--- a/recipes/tar2vm.example
+++ b/recipes/tar2vm.example
@@ -0,0 +1,8 @@
+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
--- a/recipes/tar2vm.html
+++ b/recipes/tar2vm.html
@@ -0,0 +1,23 @@
+<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>
--- a/recipes/tar2vm.sh
+++ b/recipes/tar2vm.sh
@@ -0,0 +1,11 @@
+#!/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