Fix a haddock/docstring issue

[ganeti-local] / hbal.1

diff --git a/hbal.1 b/hbal.1
index 767b4ef..3f0c915 100644 (file)
--- a/hbal.1
+++ b/hbal.1
@@ -7,11 +7,15 @@ hbal \- Cluster balancer for Ganeti
 .B "[-C]"
 .B "[-p]"
 .B "[-o]"
 .B "[-C]"
 .B "[-p]"
 .B "[-o]"

+.B "[-v... | -q]"

 .BI "[-l" limit "]"
 .BI "[-O" name... "]"
 .BI "[-l" limit "]"
 .BI "[-O" name... "]"

+.BI "[-e" score "]"

 .BI "[-m " cluster "]"
 .BI "[-n " nodes-file " ]"
 .BI "[-i " instances-file "]"
 .BI "[-m " cluster "]"
 .BI "[-n " nodes-file " ]"
 .BI "[-i " instances-file "]"

+.BI "[--max-cpu " cpu-ratio "]"
+.BI "[--min-disk " disk-ratio "]"

 
 .B hbal
 .B --version
 
 .B hbal
 .B --version

@@ -87,6 +91,10 @@ percentage of nodes failing N+1 check
 \(em
 percentage of instances living (either as primary or secondary) on
 offline nodes
 \(em
 percentage of instances living (either as primary or secondary) on
 offline nodes

+.TP
+\(em
+coefficent of variance of the ratio of virtual-to-physical cpus (for
+primary instaces of the node)

 .RE
 
 The free memory and free disk values help ensure that all nodes are
 .RE
 
 The free memory and free disk values help ensure that all nodes are

@@ -135,7 +143,7 @@ dynamically-computed metrics, such as:
 .RS 4
 .TP 3
 \(em
 .RS 4
 .TP 3
 \(em

-CPU usage of instances, combined with VCPU versus PCPU count
+CPU usage of instances

 .TP
 \(em
 Disk IO usage
 .TP
 \(em
 Disk IO usage

@@ -192,6 +200,12 @@ total disk
 .B f_dsk
 free disk
 .TP
 .B f_dsk
 free disk
 .TP

+.B pcpu
+the number of physical cpus on the node
+.TP
+.B vcpu
+the number of virtual cpus allocated to primary instances
+.TP

 .B pri
 number of primary instances
 .TP
 .B pri
 number of primary instances
 .TP

@@ -203,6 +217,9 @@ percent of free memory
 .TP
 .B p_fdsk
 percent of free disk
 .TP
 .B p_fdsk
 percent of free disk

+.TP
+.B r_cpu
+ratio of virtual to physical cpus

 .RE
 
 .TP
 .RE
 
 .TP

@@ -245,6 +262,28 @@ node is offline, since this move requires a failover.
 these nodes will not be included in the score calculation (except for
 the percentage of instances on offline nodes)
 .RE
 these nodes will not be included in the score calculation (except for
 the percentage of instances on offline nodes)
 .RE

+Note that hbal will also mark as offline any nodes which are reported
+by RAPI as such, or that have "?" in file-based input in any numeric
+fields.
+.RE
+
+.TP
+.BI "-e" score ", --min-score=" score
+This parameter denotes the minimum score we are happy with and alters
+the computation in two ways:
+.RS
+.RS 4
+.TP 3
+\(em
+if the cluster has the initial score lower than this value, then we
+don't enter the algorithm at all, and exit with success
+.TP
+\(em
+during the iterative process, if we reach a score lower than this
+value, we exit the algorithm
+.RE
+The default value of the parameter is currently \fI1e-9\fR (chosen
+empirically).

 .RE
 
 .TP
 .RE
 
 .TP

@@ -263,8 +302,10 @@ how to customize the default value via the environment).
 .BI "-m" cluster
 Collect data not from files but directly from the
 .I cluster
 .BI "-m" cluster
 Collect data not from files but directly from the
 .I cluster

-given as an argument via RAPI. This work for both Ganeti 1.2 and
-Ganeti 2.0.
+given as an argument via RAPI. If the argument doesn't contain a colon
+(:), then it is converted into a fully-built URL via prepending
+https:// and appending the default RAPI port, otherwise it's
+considered a fully-specified URL and is used as-is.

 
 .TP
 .BI "-l" N ", --max-length=" N
 
 .TP
 .BI "-l" N ", --max-length=" N

@@ -272,10 +313,31 @@ Restrict the solution to this length. This can be used for example to
 automate the execution of the balancing.
 
 .TP
 automate the execution of the balancing.
 
 .TP

+.BI "--max-cpu " cpu-ratio
+The maximum virtual-to-physical cpu ratio, as a floating point number
+between zero and one. For example, specifying \fIcpu-ratio\fR as
+\fB2.5\fR means that, for a 4-cpu machine, a maximum of 10 virtual
+cpus should be allowed to be in use for primary instances. A value of
+one doesn't make sense though, as that means no disk space can be used
+on it.
+
+.TP
+.BI "--min-disk " disk-ratio
+The minimum amount of free disk space remaining, as a floating point
+number. For example, specifying \fIdisk-ratio\fR as \fB0.25\fR means
+that at least one quarter of disk space should be left free on nodes.
+
+.TP

 .B -v, --verbose
 Increase the output verbosity. Each usage of this option will increase
 the verbosity (currently more than 2 doesn't make sense) from the
 .B -v, --verbose
 Increase the output verbosity. Each usage of this option will increase
 the verbosity (currently more than 2 doesn't make sense) from the

-default of zero.
+default of one.
+
+.TP
+.B -q, --quiet
+Decrease the output verbosity. Each usage of this option will decrease
+the verbosity (less than zero doesn't make sense) from the default of
+one.

 
 .TP
 .B -V, --version
 
 .TP
 .B -V, --version

@@ -300,9 +362,6 @@ with cryptic errors messages in this case.
 
 The algorithm is not perfect.
 
 
 The algorithm is not perfect.
 

-The algorithm doesn't deal with non-\fBdrbd\fR instances, and chokes
-on input data which has such instances.
-

 The output format is not easily scriptable, and the program should
 feed moves directly into Ganeti (either via RAPI or via a gnt-debug
 input file).
 The output format is not easily scriptable, and the program should
 feed moves directly into Ganeti (either via RAPI or via a gnt-debug
 input file).

@@ -488,3 +547,13 @@ list (but hopefully will end in the same state).
 .SH SEE ALSO
 .BR hn1 "(1), " hscan "(1), " ganeti "(7), " gnt-instance "(8), "
 .BR gnt-node "(8)"
 .SH SEE ALSO
 .BR hn1 "(1), " hscan "(1), " ganeti "(7), " gnt-instance "(8), "
 .BR gnt-node "(8)"

+
+.SH "COPYRIGHT"
+.PP
+Copyright (C) 2009 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.