X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/4162995d96e95daa23dd53992deb5b25933fa84d..d45574de156bec9c17d2910c380c9a30fb25027c:/man/hail.rst

diff --git a/man/hail.rst b/man/hail.rst
index 23b12e5..72733a2 100644
--- a/man/hail.rst
+++ b/man/hail.rst
@@ -9,31 +9,29 @@ hail - Ganeti IAllocator plugin
 SYNOPSIS
 --------
 
-**hail** [ **-t** *file* | **--simulate** *spec* ] [options...] *input-file*
+**hail** [ **-t** *file* | **\--simulate** *spec* ] [options...] *input-file*
 
-**hail** --version
+**hail** \--version
 
 DESCRIPTION
 -----------
 
-hail is a Ganeti IAllocator plugin that allows automatic instance
-placement and automatic instance secondary node replacement using the
-same algorithm as **hbal**(1).
+hail is a Ganeti IAllocator plugin that implements the instance
+placement and movement using the same algorithm as **hbal**\(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.
 
+If the input file name is ``-`` (a single minus sign), then the request
+data will be read from *stdin*.
+
 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.
@@ -42,37 +40,51 @@ 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 (*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.
+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 node changes (*change-node* mode), we currently support DRBD
+instances only, and all three modes (primary changes, secondary changes
+and all node changes).
+
+For group moves (*change-group* mode), again only DRBD is supported, and
+we compute the correct sequence that will result in a group change; job
+failure mid-way will result in a split instance. The choice of node(s)
+on the target group is based on the group score, and the choice of group
+is based on the same algorithm as allocations (group with lowest score
+after placement).
 
-In all cases, the cluster scoring is identical to the hbal algorithm.
+The deprecated *multi-evacuate* modes is no longer supported.
+
+In all cases, the cluster (or group) scoring is identical to the hbal
+algorithm.
 
 OPTIONS
 -------
 
 The options that can be passed to the program are as follows:
 
--p, --print-nodes
-  Prints the before and after node status, in a format designed to
-  allow the user to understand the node's most important
-  parameters. See the man page **hbal**(1) for more details about this
-  field.
+-p, \--print-nodes
+  Prints the before and after node status, in a format designed to allow
+  the user to understand the node's most important parameters. See the
+  man page **htools**\(1) for more details about this option.
 
--t *datafile*, --text-data=*datafile*
-  The name of the file holding cluster information, to override the
-  data in the JSON request itself. This is mostly used for debugging.
+-t *datafile*, \--text-data=*datafile*
+  The name of the file holding cluster information, to override the data
+  in the JSON request itself. This is mostly used for debugging. The
+  format of the file is described in the man page **htools**\(1).
 
---simulate *description*
-  Similar to the **-t** option, this allows overriding the cluster
-  data with a simulated cluster. For details about the description,
-  see the man page **hspace**(1).
+\--simulate *description*
+  Backend specification: similar to the **-t** option, this allows
+  overriding the cluster data with a simulated cluster. For details
+  about the description, see the man page **htools**\(1).
 
--S *filename*, --save-cluster=*filename*
+-S *filename*, \--save-cluster=*filename*
   If given, the state of the cluster before and the iallocator run is
   saved to a file named *filename.pre-ialloc*, respectively
   *filename.post-ialloc*. This allows re-feeding the cluster state to
-  any of the htools utilities.
+  any of the htools utilities via the ``-t`` option.
 
 -v
   This option increases verbosity and can be used for debugging in order
@@ -106,6 +118,14 @@ 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).
 
+BUGS
+----
+
+Networks (as configured by **gnt-network**\(8)) are not taken into
+account in Ganeti 2.7. The only way to guarantee that they work
+correctly is having your networks connected to all nodegroups. This will
+be fixed in a future version.
+
 .. vim: set textwidth=72 :
 .. Local Variables:
 .. mode: rst