Commit 49148d15 authored by Iustin Pop's avatar Iustin Pop

Move from hand-written man pages to RST/pandoc

This simplifies the maintenance of the man pages, and unifies the rst-to-*
converter to pandoc.
parent 92921ea4
......@@ -2,6 +2,10 @@
/.hpc
/coverage
/man/*.1
/doc/*.html
*.o
*.patch
*.diff
......
HPROGS = hbal hscan hail hspace
MANS = $(HPROGS:%=man/%.1)
HALLPROGS = $(HPROGS) test
HSRCS := $(wildcard Ganeti/HTools/*.hs) $(wildcard Ganeti/*.hs)
HDDIR = apidoc
......@@ -13,7 +14,8 @@ HPCEXCL = --exclude Main --exclude Ganeti.HTools.QC
# Haskell rules
all: $(HPROGS)
all: $(HPROGS) $(MANS)
$(HALLPROGS): %: %.hs Ganeti/HTools/Version.hs $(HSRCS) Makefile
$(GHC) --make $(HFLAGS) $(HEXTRA) $@
......@@ -23,7 +25,10 @@ test live-test: HEXTRA=-fhpc -Wwarn -fno-warn-missing-signatures \
-fno-warn-missing-methods -fno-warn-unused-imports
$(DOCS) : %.html : %
rst2html -v --strict $< $@
pandoc -f rst -t html -o $@ $<
%.1: %.rst
pandoc -s -f rst -t man -o $@ $<
doc: $(DOCS) Ganeti/HTools/Version.hs
rm -rf $(HDDIR)/*
......@@ -72,7 +77,7 @@ dist: regen-version Ganeti/HTools/Version.hs doc
rm -f $$ANAME $$ANAME.gz ; \
git archive --format=tar --prefix=$$PFX/ HEAD > $$ANAME ; \
tar -r -f $$ANAME --owner root --group root \
--transform="s,^,$$PFX/," version apidoc $(DOCS) ; \
--transform="s,^,$$PFX/," version apidoc $(DOCS) $(MANS); \
gzip -v9 $$ANAME ; \
TMPDIR=$$(mktemp -d) ; \
tar xzf $$ANAME.gz -C $$TMPDIR; \
......
......@@ -18,8 +18,8 @@ rebalance the cluster.
**Quick start** (see the installation section for more details):
- (have the ghc compiler and the prerequisite libraries installed)
- make
- ./hbal -m $cluster -C -p
- ``make``
- ``./hbal -m $cluster -C -p``
- look at the original and final cluster layout, and if acceptable,
execute the given commands
......@@ -35,7 +35,7 @@ cluster as equal as possible in their resource usage. It tries to
repeatedly move each instance one step, so that the cluster score
becomes better. We stop when no further move can improve the score.
For algorithm details and usage, see the man page hbal(1).
For algorithm details and usage, see the man page ``hbal(1)``.
IAllocator plugin
~~~~~~~~~~~~~~~~~
......@@ -46,7 +46,7 @@ needs to be installed in Ganeti's iallocator search path—usually
``/usr/lib/ganeti/iallocators`` or
``/usr/local/lib/ganeti/iallocators``, and after that it can be used via
ganeti's ``--iallocator`` option (in various gnt-node/gnt-instance
commands). See the man page hail(1) for more details.
commands). See the man page ``hail(1)`` for more details.
Cluster capacity estimator
~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -88,12 +88,13 @@ If installing from source, you need a working ghc compiler (6.8 at
least) and some extra Haskell libraries which usually need to be
installed manually:
- json (http://hackage.haskell.org/package/json)
- curl (http://hackage.haskell.org/package/curl)
- network (http://hackage.haskell.org/package/network)
- `json <http://hackage.haskell.org/package/json>`_
- `curl <http://hackage.haskell.org/package/curl>`_
- `network <http://hackage.haskell.org/package/network>`_
Once these are installed, just typing *make* in the top-level directory
should be enough.
should be enough. If you edit the documentation sources, you will need
the ``pandoc`` program to rebuilt it.
Only the ``hail`` program needs to be installed in a specific place, the
other tools are not location-dependent.
......
This diff is collapsed.
This diff is collapsed.
.TH HAIL 1 2009-03-23 htools "Ganeti H-tools"
.SH NAME
hail \- Ganeti IAllocator plugin
HAIL(1) htools | Ganeti H-tools
===============================
.SH SYNOPSIS
.B hail
.I "input-file"
NAME
----
.B hail
.B --version
hail - Ganeti IAllocator plugin
SYNOPSIS
--------
**hail** *input-file*
**hail** --version
DESCRIPTION
-----------
.SH DESCRIPTION
hail is a Ganeti IAllocator plugin that allows automatic instance
placement and automatic instance secondary node replacement using the
same algorithm as \fBhbal\fR(1).
same algorithm as **hbal**(1).
The program takes input via a JSON\(hyfile containing current cluster
state and the request details, and output (on stdout) a JSON\(hyformatted
The program takes input via a JSON-file containing current cluster
state and the request details, and output (on stdout) a JSON-formatted
response. In case of critical failures, the error message is printed
on stderr and the exit code is changed to show failure.
.SS ALGORITHM
ALGORITHM
~~~~~~~~~
The program uses a simplified version of the hbal algorithm.
......@@ -27,50 +34,54 @@ For relocations, we try to change the secondary node of the instance
to all the valid other nodes; the node which results in the best
cluster score is chosen.
For single\(hynode allocations (non\(hymirrored instances), again we
For single-node allocations (non-mirrored instances), again we
select the node which, when chosen as the primary node, gives the best
score.
For dual\(hynode allocations (mirrored instances), we chose the best
pair; this is the only choice where the algorithm is non\(hytrivial
For dual-node allocations (mirrored instances), we chose the best
pair; this is the only choice where the algorithm is non-trivial
with regard to cluster size.
For node evacuations (\fImulti-evacuate\fR mode), we iterate over all
For node evacuations (*multi-evacuate* mode), we iterate over all
instances which live as secondaries on those nodes and try to relocate
them using the single-instance relocation algorithm.
In all cases, the cluster scoring is identical to the hbal algorithm.
.SH CONFIGURATION
CONFIGURATION
-------------
For the tag-exclusion configuration (see the manpage of hbal for more
details), the list of which instance tags to consider as exclusion
tags will be read from the cluster tags, configured as follows:
- get all cluster tags starting with \fBhtools:iextags:\fR
- get all cluster tags starting with **htools:iextags:**
- use their suffix as the prefix for exclusion tags
For example, given a cluster tag like \fBhtools:iextags:service\fR,
all instance tags of the form \fBservice:X\fR will be considered as
For example, given a cluster tag like **htools:iextags:service**,
all instance tags of the form **service:X** will be considered as
exclusion tags, meaning that (e.g.) two instances which both have a
tag \fBservice:foo\fR will not be placed on the same primary node.
tag **service:foo** will not be placed on the same primary node.
.SH EXIT STATUS
EXIT STATUS
-----------
The exist status of the command will be zero, unless for some reason
the algorithm fatally failed (e.g. wrong node or instance data).
.SH SEE ALSO
.BR hbal "(1), " hspace "(1), " hscan "(1), " ganeti "(7), "
.BR gnt-instance "(8), " gnt-node "(8)"
SEE ALSO
--------
**hbal**(1), **hspace**(1), **hscan**(1), **ganeti**(7),
**gnt-instance**(8), **gnt-node**(8)
.SH "COPYRIGHT"
.PP
Copyright (C) 2009 Google Inc. Permission is granted to copy,
COPYRIGHT
---------
Copyright (C) 2009, 2010 Google Inc. Permission is granted to copy,
distribute and/or modify under the terms of the GNU General Public
License as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
.PP
On Debian systems, the complete text of the GNU General Public License
can be found in /usr/share/common-licenses/GPL.
This diff is collapsed.
.TH HSCAN 1 2009-03-23 htools "Ganeti H-tools"
.SH NAME
hscan \- Scan clusters via RAPI and save node/instance data
HSCAN(1) htools | Ganeti H-tools
================================
.SH SYNOPSIS
.B hscan
.B "[-p]"
.B "[--no-headers]"
.BI "[-d " path "]"
.I cluster...
NAME
----
.B hscan
.B --version
hscan - Scan clusters via RAPI and save node/instance data
SYNOPSIS
--------
**hscan** [-p] [--no-headers] [-d *path* ] *cluster...*
**hscan** --version
DESCRIPTION
-----------
.SH DESCRIPTION
hscan is a tool for scanning clusters via RAPI and saving their data
in the input format used by
.BR hbal "(1) and " hspace "(1)."
It will also show a one\(hyline score for each cluster scanned or, if
desired, the cluster state as show by the \fB-p\fR option to the other
tools.
in the input format used by **hbal**(1) and **hspace**(1). It will
also show a one-line score for each cluster scanned or, if desired,
the cluster state as show by the **-p** option to the other tools.
For each cluster, one file named \fIcluster\fB.data\ will be generated
For each cluster, one file named *cluster***.data** will be generated
holding the node and instance data. This file can then be used in
\fBhbal\fR(1) or \fBhspace\fR(1) via the \fB-t\fR option. In case the
**hbal**(1) or **hspace**(1) via the *-t* option. In case the
cluster name contains slashes (as it can happen when the cluster is a
fully-specified URL), these will be replaced with underscores.
The one\(hyline output for each cluster will show the following:
.RS
.TP
.B Name
The name of the cluster (or the IP address that was given, etc.)
.TP
.B Nodes
The number of nodes in the cluster
.TP
.B Inst
The number of instances in the cluster
.TP
.B BNode
The number of nodes failing N+1
.TP
.B BInst
The number of instances living on N+1\(hyfailed nodes
.TP
.B t_mem
Total memory in the cluster
.TP
.B f_mem
Free memory in the cluster
.TP
.B t_disk
Total disk in the cluster
.TP
.B f_disk
Free disk space in the cluster
.TP
.B Score
The score of the cluster, as would be reported by \fBhbal\fR(1) if
run on the generated data files.
.RE
The one-line output for each cluster will show the following:
Name
The name of the cluster (or the IP address that was given, etc.)
Nodes
The number of nodes in the cluster
Inst
The number of instances in the cluster
BNode
The number of nodes failing N+1
BInst
The number of instances living on N+1-failed nodes
t_mem
Total memory in the cluster
f_mem
Free memory in the cluster
t_disk
Total disk in the cluster
f_disk
Free disk space in the cluster
Score
The score of the cluster, as would be reported by **hbal**(1) if run
on the generated data files.
In case of errors while collecting data, all fields after the name of
the cluster are replaced with the error display.
.B Note:
this output format is not yet final so it should not be used for
scripting yet.
**Note:** this output format is not yet final so it should not be used
for scripting yet.
OPTIONS
-------
.SH OPTIONS
The options that can be passed to the program are as follows:
.TP
.B -p, --print-nodes
Prints the node status for each cluster after the cluster's one\(hyline
status display, in a format designed to allow the user to understand
the node's most important parameters. For details, see the man page
for \fBhbal\fR(1).
-p, --print-nodes
Prints the node status for each cluster after the cluster's one-line
status display, in a format designed to allow the user to understand
the node's most important parameters. For details, see the man page
for **hbal**(1).
.TP
.BI "-d " path
Save the node and instance data for each cluster under \fIpath\fR,
instead of the current directory.
-d *path*
Save the node and instance data for each cluster under *path*,
instead of the current directory.
.TP
.B -V, --version
Just show the program version and exit.
-V, --version
Just show the program version and exit.
.SH EXIT STATUS
EXIT STATUS
-----------
The exist status of the command will be zero, unless for some reason
loading the input data failed fatally (e.g. wrong node or instance
data).
.SH BUGS
BUGS
----
The program does not check its input data for consistency, and aborts
with cryptic errors messages in this case.
.SH EXAMPLE
.in +4n
.nf
.RB "$ " "hscan cluster1"
Name Nodes Inst BNode BInst t_mem f_mem t_disk f_disk Score
cluster1 2 2 0 0 1008 652 255 253 0.24404762
.RB "$ " "ls -l cluster1.data"
\-rw\-r\-\-r\-\- 1 root root 364 2009\-03\-23 07:26 cluster1.data
.fi
.in
.SH SEE ALSO
.BR hbal "(1), " hspace "(1), " hail "(1), "
.BR ganeti "(7), " gnt-instance "(8), " gnt-node "(8)"
.SH "COPYRIGHT"
.PP
Copyright (C) 2009 Google Inc. Permission is granted to copy,
EXAMPLE
-------
::
$ hscan cluster1
Name Nodes Inst BNode BInst t_mem f_mem t_disk f_disk Score
cluster1 2 2 0 0 1008 652 255 253 0.24404762
$ ls -l cluster1.data
-rw-r--r-- 1 root root 364 2009-03-23 07:26 cluster1.data
SEE ALSO
--------
**hbal**(1), **hspace**(1), **hail**(1), **ganeti**(7),
**gnt-instance**(8), **gnt-node**(8)
COPYRIGHT
---------
Copyright (C) 2009, 2010 Google Inc. Permission is granted to copy,
distribute and/or modify under the terms of the GNU General Public
License as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
.PP
On Debian systems, the complete text of the GNU General Public License
can be found in /usr/share/common-licenses/GPL.
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment