[sheepdog] [PATCH v2] man: autogenerate sheepdog manuals
MORITA Kazutaka
morita.kazutaka at gmail.com
Fri May 31 11:32:47 CEST 2013
From: MORITA Kazutaka <morita.kazutaka at lab.ntt.co.jp>
Signed-off-by: MORITA Kazutaka <morita.kazutaka at lab.ntt.co.jp>
---
v2:
- rename QEMU/KVM to QEMU
- add sheepfs(8) to the see also section in sheep.8 and collie.8
- autogenerate sheepfs.8
- make man after executables because we use them to generate manuals
Makefile.am | 4 +-
man/Makefile.am | 33 ++++++++++
man/{collie.8 => collie.8.in} | 138 ++-------------------------------------
man/{sheep.8 => sheep.8.in} | 54 ++-------------
man/{sheepfs.8 => sheepfs.8.in} | 29 ++------
5 files changed, 51 insertions(+), 207 deletions(-)
rename man/{collie.8 => collie.8.in} (15%)
rename man/{sheep.8 => sheep.8.in} (43%)
rename man/{sheepfs.8 => sheepfs.8.in} (73%)
diff --git a/Makefile.am b/Makefile.am
index c0f31ac..16eb532 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -17,12 +17,14 @@ sheepdogsysconfdir = ${SHEEPDOGCONFDIR}
sheepdogsysconf_DATA =
-SUBDIRS = lib collie sheep include script man shepherd
+SUBDIRS = lib collie sheep include script shepherd
if BUILD_SHEEPFS
SUBDIRS += sheepfs
endif
+SUBDIRS += man
+
install-exec-local:
$(INSTALL) -d $(DESTDIR)/${localstatedir}/lib/sheepdog
diff --git a/man/Makefile.am b/man/Makefile.am
index 0343610..8c1f46a 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -5,3 +5,36 @@ dist_man_MANS = sheep.8 collie.8
if BUILD_SHEEPFS
dist_man_MANS += sheepfs.8
endif
+
+sheep.8.options = $(shell ../sheep/sheep -h | \
+ perl -ne 'print ".TP\n.BI $$1 \"\\fR, \\fP\" $$2\n$$3\n" if /^ ([^,]+), (\S+)\s+(.+)/' | \
+ sed 's/\\/\\\\\\/g' | \
+ sed 's/"/\\"/g' | \
+ perl -pe 's/\n/\\n/g')
+
+collie.8.options = $(shell ../collie/collie -h | \
+ perl -ne 'if (/^ (.+?) \s+(.+)/) {system "../collie/collie $$1 -h"; print "Description:\n $$2\n"}'| \
+ sed 's/Usage: collie \(.*\)/.TP\n.BI "\1"/g' | \
+ sed 's/\(^[a-zA-Z]*:\)/\n\1/g' | \
+ sed 's/\\/\\\\\\/g' | \
+ sed 's/"/\\"/g' | \
+ perl -pe 's/\n/\\n/g')
+
+sheepfs.8.options = $(shell ../sheepfs/sheepfs -h | \
+ perl -ne 'print ".TP\n.BI $$1 \"\\fR, \\fP\" $$2\n$$3\n" if /^ ([^,]+), (\S+)\s+(.+)/' | \
+ sed 's/\\/\\\\\\/g' | \
+ sed 's/"/\\"/g' | \
+ perl -pe 's/\n/\\n/g')
+
+%: %.in Makefile
+ rm -f $@-t $@
+ @sed \
+ -e "s#@DATE@#`date '+%Y-%m-%d'`#g" \
+ -e "s#@OPTIONS@#${$@.options}#g" \
+ $< > $@-t
+ mv $@-t $@
+
+all-local: $(dist_man_MANS)
+
+clean-local:
+ rm -rf $(dist_man_MANS)
diff --git a/man/collie.8 b/man/collie.8.in
similarity index 15%
rename from man/collie.8
rename to man/collie.8.in
index 3ca2372..7fdee4a 100644
--- a/man/collie.8
+++ b/man/collie.8.in
@@ -1,152 +1,23 @@
-.TH SHEEPDOG 8 2012-08-05
+.TH SHEEPDOG 8 @DATE@
.SH NAME
collie \- Command line utility for the sheep daemon
.SH SYNOPSIS
.B "collie <command> <subcommand> [options]"
.SH DESCRIPTION
.B collie
-- Sheepdog is a distributed storage system for KVM/QEMU. It provides
+- Sheepdog is a distributed storage system for QEMU. It provides
highly available block level storage volumes to virtual machines.
Sheepdog supports advanced volume management features such as snapshot,
cloning, and thin provisioning. The architecture of Sheepdog is fully
symmetric; there is no central node such as a meta-data server.
The server daemon is called sheep(8). A command line utility is available
-via collie(8). KVM/QEMU virtual machines use the sheep daemon via a block
+via collie(8). QEMU virtual machines use the sheep daemon via a block
driver available in qemu(1).
For more information, run 'collie <command> <subcommand> --help'.
-.SH OPTIONS
-.TP
-.BI \-a "\fR, \fP" \--address
-This option specifies the daemon address (default: localhost).
-.TP
-.BI \-p "\fR, \fP" \--port
-This option specifies the daemon port.
-.TP
-.BI \-i "\fR, \fP" \--index
-This option specifies the index of data objects.
-.TP
-.BI \-s "\fR, \fP" \--snapshot
-This option specifies a snapshot id or tag name.
-.TP
-.BI \-P "\fR, \fP" \--prealloc
-This option preallocates all the data objects.
-.TP
-.BI \-r "\fR, \fP" \--raw
-This option set raw output mode: omit headers, separate fields with single spaces and print all sizes in decimal bytes.
-.TP
-.BI \-d "\fR, \fP" \--delete
-This option deletes a key.
-.TP
-.BI \-x "\fR, \fP" \--exclusive
-This option enables exclusive write mode.
-.TP
-.BI \-b "\fR, \fP" \--store
-This option specifies the backend store.
-.TP
-.BI \-c "\fR, \fP" \--copies
-This option specifies the level of data redundancy (i.e. number of copies to maintain of each object).
-.TP
-.BI \-m "\fR, \fP" \--mode\ [safe|quorum|unsafe]
-This option controls the behavior when there are too few nodes for the configured redundancy. Mode 'safe' will halt cluster IO when (nr_nodes < nr_copies). Mode 'quorum' will halt cluster IO when (nr_nodes < nr_copies/2 + 1). Mode 'unsafe' will never halt the cluster and therefore data loss may result.
-.TP
-.BI \-f "\fR, \fP" \--force
-Do not prompt for confirmation.
-.TP
-.BI \-R "\fR, \fP" \--restore
-This option restores the cluster.
-.TP
-.BI \-h "\fR, \fP" \--help
-Display help and exit.
.SH COMMAND & SUBCOMMAND
-.TP
-.BI "vdi create [-P|--prealloc] [-a|--address address] [-p|--port port] [-h|--help] <vdiname> <size>"
-This command creates an image.
-.TP
-.BI "vdi snapshot [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
-This command creates a snapshot.
-.TP
-.BI "vdi check [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
-This command checks and repairs an image's consistency.
-.TP
-.BI "vdi clone [-s snapshot] [-P] [-a address] [-p port] [-h] <src vdi> <dst vdi>"
-This command clones an image.
-.TP
-.BI "vdi delete [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
-This command deletes an image.
-.TP
-.BI "vdi rollback [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
-This command rollbacks the current vdi to the requested snapshot.
-.TP
-.BI "vdi list [-a address] [-p port] [-r] [-h] [vdiname]"
-This command lists images.
-.TP
-.BI "vdi track [-i index] [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
-This command shows the object epoch trace in the image.
-.TP
-.BI "vdi tree [-a address] [-p port] [-h]"
-This command shows images in tree view format.
-.TP
-.BI "vdi graph [-a address] [-p port] [-h]"
-This command shows images in Graphviz dot format.
-.TP
-.BI "vdi object [-i index] [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
-This command shows object information in the image.
-.TP
-.BI "vdi setattr [-d] [-x] [-a address] [-p port] [-h] <vdiname> <key> [value]"
-This command sets a VDI attribute.
-.TP
-.BI "vdi getattr [-a address] [-p port] [-h] <vdiname> <key>"
-This command gets a VDI attribute.
-.TP
-.BI "vdi resize [-a address] [-p port] [-h] <vdiname> <new size>"
-This command resizes an image.
-.TP
-.BI "vdi read [-s snapshot] [-a address] [-p port] [-h] <vdiname> [<offset> [<len>]]"
-This command reads data from an image.
-.TP
-.BI "vdi write [-a address] [-p port] [-h] <vdiname> [<offset> [<len>]]"
-This command writes data to an image.
-.TP
-.BI "vdi backup [-s snapshot] [-F from] [-a address] [-p port] [-h] <vdiname>"
-This command creates an incremental backup between two snapshots.
-.TP
-.BI "vdi restore [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
-This command restores snapshot images from a backup.
-.TP
-.BI "node kill [-a address] [-p port] [-r] [-h] <node id>"
-This command kills the specified node.
-.TP
-.BI "node list [-a address] [-p port] [-r] [-h]"
-This command lists nodes.
-.TP
-.BI "node info [-a address] [-p port] [-r] [-h]"
-This command shows information about each node.
-.TP
-.BI "node recovery [-a address] [-p port] [-r] [-h]"
-This command shows nodes currently in recovery.
-.TP
-.BI "cluster info [-a address] [-p port] [-r] [-h]"
-This command shows cluster information.
-.TP
-.BI "cluster format [-b store] [-c copies] [-m mode] [-a address] [-p port] [-h]"
-This command creates a Sheepdog store.
-.TP
-.BI "cluster shutdown [-a address] [-p port] [-h]"
-This command stops Sheepdog.
-.TP
-.BI "cluster recover info [-a address] [-f] [-p port] [-h]"
-Show the status of recovery to user.
-.TP
-.BI "cluster recover force [-a address] [-f] [-p port] [-h]"
-Force recover cluster immediately.
-.TP
-.BI "cluster recover enable [-a address] [-f] [-p port] [-h]"
-Enable automatic recovery and run once recover if necessary.
-.TP
-.BI "cluster recover disable [-a address] [-f] [-p port] [-h]"
-Disable automatic recovery.
+ at OPTIONS@
.SH DEPENDENCIES
\fBSheepdog\fP requires QEMU 0.13.z or later and Corosync 1.y.z or 2.y.z.
@@ -157,6 +28,7 @@ none
.SH SEE ALSO
.BR sheep(8),
.BR qemu(1),
+.BR sheepfs(8),
.BR corosync_overview(8)
.SH AUTHORS
diff --git a/man/sheep.8 b/man/sheep.8.in
similarity index 43%
rename from man/sheep.8
rename to man/sheep.8.in
index f996431..93295a8 100644
--- a/man/sheep.8
+++ b/man/sheep.8.in
@@ -1,64 +1,21 @@
-.TH SHEEPDOG 8 2012-08-05
+.TH SHEEPDOG 8 @DATE@
.SH NAME
-sheep \- Distributed Block Storage System for KVM
+sheep \- Distributed Block Storage System for QEMU
.SH SYNOPSIS
.B "sheep [options] [PATH]"
.SH DESCRIPTION
.B sheep
-- Sheepdog is a distributed storage system for KVM/QEMU. It provides
+- Sheepdog is a distributed storage system for QEMU. It provides
highly available block level storage volumes to virtual machines.
Sheepdog supports advanced volume management features such as snapshot,
cloning, and thin provisioning. The architecture of Sheepdog is fully
symmetric; there is no central node such as a meta-data server.
The server daemon is called sheep(8). A command line utility is available
-via collie(8). KVM/QEMU virtual machines use the sheep daemon via a block
+via collie(8). QEMU virtual machines use the sheep daemon via a block
driver available in qemu(1).
.SH OPTIONS
-.TP
-.BI \-P "\fR, \fP" \--pidfile " pidfile"
-This option creates a pid file.
-.TP
-.BI \-p "\fR, \fP" \--port " port"
-This option specifies the IP port over which \fBsheep\fP looks for other
-sheepdog cluster nodes.
-.TP
-.BI \-f "\fR, \fP" \--foreground
-This option forces the sheepdog daemon to run in the foreground.
-.TP
-.BI \-d "\fR, \fP" \--debug
-This option displays debug messages.
-.TP
-.BI \-D "\fR, \fP" \--directio
-This option enables direct IO when accessing the object cache.
-.TP
-.BI \-z "\fR, \fP" \--zone
-This option specifies the availability zone id.
-.TP
-.BI \-c "\fR, \fP" \--cluster
-This option specifies the cluster driver.
-.TP
-.BI \-g "\fR, \fP" \--gateway
-Makes the sheep instance run in gateway mode.
-.TP
-.BI \-l "\fR, \fP" \--loglevel
-Specify the level of logging detail.
-.TP
-.BI \-o "\fR, \fP" \--stdout
-Log to stdout instead of shared logger.
-.TP
-.BI \-s "\fR, \fP" \--disk-space
-Specify the free disk space in megabytes.
-.TP
-.BI \-w "\fR, \fP" \--enable-cache " size[,mode]"
-Enable object cache and specify the max cache size in megabytes and mode.
-Mode can be writethrough (default) or writeback. (EXPERIMENTAL)
-.TP
-.BI \-y "\fR, \fP" \--myaddr
-Specify the address advertised to other sheep.
-.TP
-.BI \-h "\fR, \fP" \--help
-Display help and exit.
+ at OPTIONS@
.SH PATH
Proper LSB systems will store sheepdog files in /var/lib/sheepdog. The init
@@ -77,6 +34,7 @@ mount \-o remount,user_xattr /var/lib/sheepdog
.SH SEE ALSO
.BR collie(8),
.BR qemu(1),
+.BR sheepfs(8),
.BR corosync_overview(8)
.SH AUTHORS
diff --git a/man/sheepfs.8 b/man/sheepfs.8.in
similarity index 73%
rename from man/sheepfs.8
rename to man/sheepfs.8.in
index 5e285e0..58d8624 100644
--- a/man/sheepfs.8
+++ b/man/sheepfs.8.in
@@ -1,18 +1,18 @@
-.TH SHEEPDOG 8 2012-06-27
+.TH SHEEPDOG 8 @DATE@
.SH NAME
sheepfs \- A pseudo file system exports both Sheepdog's internal state as well as Sheepdog's storage
.SH SYNOPSIS
.B "sheepfs [OPTION]... MOUNTPOINT"
.SH DESCRIPTION
.B sheepfs
-- Sheepdog is a distributed storage system for KVM/QEMU. It provides
+- Sheepdog is a distributed storage system for QEMU. It provides
highly available block level storage volumes to virtual machines.
Sheepdog supports advanced volume management features such as snapshot,
cloning, and thin provisioning. The architecture of Sheepdog is fully
symmetric; there is no central node such as a meta-data server.
The server daemon is called sheep(8). A command line utility is available
-via collie(8). A pseudo file system is available via sheepfs(8). KVM/QEMU
+via collie(8). A pseudo file system is available via sheepfs(8). QEMU
virtual machines use the sheep daemon via a block driver available in qemu(1).
Sheepfs is a FUSE-based pseudo file system in userland to access both
@@ -37,28 +37,7 @@ can be used as
This file abstraction integrates well into kernel's pagecache.
.SH OPTIONS
-.TP
-.BI \-a "\fR, \fP" \--address
-This option specify the daemon address (default: localhost).
-.TP
-.BI \-p "\fR, \fP" \--port
-This option specify the daemon port (default: 7000).
-.TP
-.TP
-.BI \-d "\fR, \fP" \--debug
-This option enable debug output (implies -f).
-.TP
-.BI \-f "\fR, \fP" \--foreground
-This option let sheepfs run in the foreground.
-.TP
-.BI \-k "\fR, \fP" \--pagecache
-This option use local kernel's page cache to access volume.
-.TP
-.BI \-n "\fR, \fP" \--noobjectcache
-This option disable object cache of the attached volumes.
-.TP
-.BI \-h "\fR, \fP" \--help
-Display help and exit.
+ at OPTIONS@
.SH DEPENDENCIES
\fBSheepdog\fP requires QEMU 0.13.z or later and Corosync 1.y.z.
--
1.7.9.5
More information about the sheepdog
mailing list