Add man page and .gitignore entry for hail

.gitignore

@@ -14,6 +14,7 @@ NEWS.html
 hn1
 hbal
 hscan
+hail
 *.prof*
 *.stat
 

hail.1

+.TH HAIL 1 2009-03-23 htools "Ganeti H-tools"
+.SH NAME
+hail \- Ganeti IAllocator plugin
+
+.SH SYNOPSIS
+.B hail
+.I "input-file"
+
+.B hail
+.B --version
+
+.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).
+
+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
+
+The program uses a simplified version of the hbal algorithm.
+
+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-node allocations (non-mirrored instances), again we select
+the node which, when chosen as the primary node, gives the best score.
+
+For dual-node allocations (mirrored instances), we chose the best
+pair; this is the only choice where the algoritm is non-trivial
+with regard to cluster size.
+
+For all choices, the cluster scoring is identical to the hbal
+algorithm.
+
+.SH 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 hn1 "(1), " hscan "(1), " ganeti "(7), " gnt-instance "(8), "
+.BR gnt-node "(8)"