diff --git a/hail.1 b/hail.1 index 48c6d02045e8eb4b4082cc77f4829afa8f7599f7..99fd4902103661106713b07d9c5a9c26f9455ad1 100644 --- a/hail.1 +++ b/hail.1 @@ -14,8 +14,8 @@ 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 +The program takes input via a JSON\(hyfile containing current cluster +state and the request details, and output (on stdout) a JSON\(hyformatted response. In case of critical failures, the error message is printed on stderr and the exit code is changed to show failure. @@ -27,11 +27,12 @@ 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 single\(hynode allocations (non\(hymirrored 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 +For dual\(hynode allocations (mirrored instances), we chose the best +pair; this is the only choice where the algoritm is non\(hytrivial with regard to cluster size. For all choices, the cluster scoring is identical to the hbal diff --git a/hbal.1 b/hbal.1 index 52622fcc02d5a258acf71138d0ed89eebd2d89f7..2807030d91b5531c09ff759d6c344d3c1d77e914 100644 --- a/hbal.1 +++ b/hbal.1 @@ -45,11 +45,11 @@ cluster (nodes with their total and free disk, memory, etc.) and instance placement and computes a series of steps designed to bring the cluster into a better state. -The algorithm to do so is designed to be stable (i.e. it will give you -the same results when restarting it from the middle of the solution) -and reasonably fast. It is not, however, designed to be a perfect -algorithm - it is possible to make it go into a corner from which it -can find no improvement, because it only look one "step" ahead. +The algorithm used is designed to be stable (i.e. it will give you the +same results when restarting it from the middle of the solution) and +reasonably fast. It is not, however, designed to be a perfect +algorithm \(em it is possible to make it go into a corner from which +it can find no improvement, because it looks only one "step" ahead. By default, the program will show the solution incrementally as it is computed, in a somewhat cryptic format; for getting the actual Ganeti @@ -179,7 +179,7 @@ primary node, in effect simulating the startup of such instances. .SS OTHER POSSIBLE METRICS It would be desirable to add more metrics to the algorithm, especially -dynamically-computed metrics, such as: +dynamically\(hycomputed metrics, such as: .RS 4 .TP 3 \(em @@ -203,7 +203,7 @@ Note that the moves list will be split into independent steps, called "jobsets", but only for visual inspection, not for actually parallelisation. It is not possible to parallelise these directly when executed via "gnt-instance" commands, since a compound command -(e.g. failover and replace-disks) must be executed serially. Parallel +(e.g. failover and replace\-disks) must be executed serially. Parallel execution is only possible when using the Luxi backend and the \fI-L\fR option. @@ -218,13 +218,13 @@ Prints the before and after node status, in a format designed to allow the user to understand the node's most important parameters. It is possible to customise the listed information by passing a -comma-separated list of field names to this option (the field list is +comma\(hyseparated list of field names to this option (the field list is currently undocumented). By default, the node list will contain these informations: .RS .TP .B F -a character denoting the status of the node, with '-' meaning an +a character denoting the status of the node, with '\-' meaning an offline node, '*' meaning N+1 failure and blank meaning a good node .TP .B Name @@ -298,7 +298,7 @@ node status, but it can help in understanding instance moves. .TP .B -o, --oneline -Only shows a one-line output from the program, designed for the case +Only shows a one\(hyline output from the program, designed for the case when one wants to look at multiple clusters at once and check their status. @@ -337,7 +337,7 @@ 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 +by RAPI as such, or that have "?" in file\(hybased input in any numeric fields. .RE @@ -362,8 +362,8 @@ empirically). .TP .BI "--no-disk-moves" -This parameter prevents hbal from using disk move (i.e. "gnt-instance -replace-disks") operations. This will result in a much quicker +This parameter prevents hbal from using disk move (i.e. "gnt\-instance +replace\-disks") operations. This will result in a much quicker balancing, but of course the improvements are limited. It is up to the user to decide when to use one or another. @@ -404,9 +404,9 @@ how to customize the default value via the environment). Collect data not from files but directly from the .I cluster 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 +(:), then it is converted into a fully\(hybuilt URL via prepending https:// and appending the default RAPI port, otherwise it's -considered a fully-specified URL and is used as-is. +considered a fully\(hyspecified URL and is used as\(hyis. .TP .BI "-L[" path "]" @@ -414,7 +414,7 @@ Collect data not from files but directly from the master daemon, which is to be contacted via the luxi (an internal Ganeti protocol). An optional \fIpath\fR argument is interpreted as the path to the unix socket on which the master daemon listens; otherwise, the default path -used by ganeti when installed with "--localstatedir=/var" is used. +used by ganeti when installed with \fI--localstatedir=/var\fR is used. .TP .B "-X" @@ -434,12 +434,12 @@ 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. +The maximum virtual\(hyto\(hyphysical 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\(hycpu 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 @@ -483,7 +483,7 @@ with cryptic errors messages in this case. The algorithm is not perfect. The output format is not easily scriptable, and the program should -feed moves directly into Ganeti (either via RAPI or via a gnt-debug +feed moves directly into Ganeti (either via RAPI or via a gnt\-debug input file). .SH EXAMPLE @@ -586,46 +586,46 @@ Cluster score improved from 0.52329131 to 0.00252594 Commands to run to reach the above solution: echo step 1 - echo gnt-instance migrate instance14 - echo gnt-instance replace-disks -n node16 instance14 - echo gnt-instance migrate instance14 + echo gnt\-instance migrate instance14 + echo gnt\-instance replace\-disks \-n node16 instance14 + echo gnt\-instance migrate instance14 echo step 2 - echo gnt-instance migrate instance54 - echo gnt-instance replace-disks -n node16 instance54 - echo gnt-instance migrate instance54 + echo gnt\-instance migrate instance54 + echo gnt\-instance replace\-disks \-n node16 instance54 + echo gnt\-instance migrate instance54 echo step 3 - echo gnt-instance migrate instance4 - echo gnt-instance replace-disks -n node16 instance4 + echo gnt\-instance migrate instance4 + echo gnt\-instance replace\-disks \-n node16 instance4 echo step 4 - echo gnt-instance replace-disks -n node2 instance48 - echo gnt-instance migrate instance48 + echo gnt\-instance replace\-disks \-n node2 instance48 + echo gnt\-instance migrate instance48 echo step 5 - echo gnt-instance replace-disks -n node16 instance93 - echo gnt-instance migrate instance93 + echo gnt\-instance replace\-disks \-n node16 instance93 + echo gnt\-instance migrate instance93 echo step 6 - echo gnt-instance replace-disks -n node2 instance89 - echo gnt-instance migrate instance89 + echo gnt\-instance replace\-disks \-n node2 instance89 + echo gnt\-instance migrate instance89 echo step 7 - echo gnt-instance replace-disks -n node16 instance5 - echo gnt-instance migrate instance5 + echo gnt\-instance replace\-disks \-n node16 instance5 + echo gnt\-instance migrate instance5 echo step 8 - echo gnt-instance migrate instance94 - echo gnt-instance replace-disks -n node16 instance94 + echo gnt\-instance migrate instance94 + echo gnt\-instance replace\-disks \-n node16 instance94 echo step 9 - echo gnt-instance migrate instance44 - echo gnt-instance replace-disks -n node15 instance44 + echo gnt\-instance migrate instance44 + echo gnt\-instance replace\-disks \-n node15 instance44 echo step 10 - echo gnt-instance replace-disks -n node16 instance62 + echo gnt\-instance replace\-disks \-n node16 instance62 echo step 11 - echo gnt-instance replace-disks -n node16 instance13 + echo gnt\-instance replace\-disks \-n node16 instance13 echo step 12 - echo gnt-instance replace-disks -n node7 instance19 + echo gnt\-instance replace\-disks \-n node7 instance19 echo step 13 - echo gnt-instance replace-disks -n node1 instance43 + echo gnt\-instance replace\-disks \-n node1 instance43 echo step 14 - echo gnt-instance replace-disks -n node4 instance1 + echo gnt\-instance replace\-disks \-n node4 instance1 echo step 15 - echo gnt-instance replace-disks -n node17 instance58 + echo gnt\-instance replace\-disks \-n node17 instance58 Final cluster status: N1 Name t_mem f_mem r_mem t_dsk f_dsk pri sec p_fmem p_fdsk @@ -659,7 +659,7 @@ the command list to reach the final solution. In the initial listing, we see which nodes are not N+1 compliant. The algorithm is stable as long as each step above is fully completed, -e.g. in step 8, both the migrate and the replace-disks are +e.g. in step 8, both the migrate and the replace\-disks are done. Otherwise, if only the migrate is done, the input data is changed in a way that the program will output a different solution list (but hopefully will end in the same state). diff --git a/hscan.1 b/hscan.1 index 72cca91f5f14481618df3de7448152d0533de341..82a2dc446ce3c44f5d15c9286b3138cd4fa756d0 100644 --- a/hscan.1 +++ b/hscan.1 @@ -16,7 +16,7 @@ hscan \- Scan clusters via RAPI and save node/instance data 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-line score for each cluster scanned or, if +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. @@ -27,7 +27,7 @@ via the \fB-i\fR and \fB-n\fR options. 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-line output for each cluster will show the following: +The one\(hyline output for each cluster will show the following: .RS .TP .B Name @@ -43,7 +43,7 @@ The number of instances in the cluster The number of nodes failing N+1 .TP .B BInst -The number of instances living on N+1-failed nodes +The number of instances living on N+1\(hyfailed nodes .TP .B t_mem Total memory in the cluster @@ -75,7 +75,7 @@ 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-line +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). @@ -100,7 +100,7 @@ data). The program does not check its input data for consistency, and aborts with cryptic errors messages in this case. -The RAPI collection doesn't deal with non-\fBdrbd\fR instances, and +The RAPI collection doesn't deal with non\(hy\fBdrbd\fR instances, and chokes on input data which has such instances. .SH EXAMPLE @@ -111,8 +111,8 @@ chokes on input data which has such instances. 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.*" --rw-r--r-- 1 root root 163 2009-03-23 07:26 cluster1.instances --rw-r--r-- 1 root root 90 2009-03-23 07:26 cluster1.nodes +\-rw\-r\-\-r\-\- 1 root root 163 2009\-03\-23 07:26 cluster1.instances +\-rw\-r\-\-r\-\- 1 root root 90 2009\-03\-23 07:26 cluster1.nodes .fi .in diff --git a/hspace.1 b/hspace.1 index 075f01dc4c8f609f4c48209388a52ee5b62ad7e9..ae3ac6e9e20fa9e5ff6ad416176bbcb625cdb503 100644 --- a/hspace.1 +++ b/hspace.1 @@ -50,7 +50,7 @@ iallocator plugin. The output of the program is designed to interpreted as a shell fragment (or parsed as a \fIkey=value\fR file). Options which extend -the output (e.g. -p, -v) will output the additional information on +the output (e.g. \-p, \-v) will output the additional information on stderr (such that the stdout is still parseable). The following keys are available in the output of the script (all @@ -97,7 +97,7 @@ RAM). .TP .I INI_MEM_OVERHEAD, FIN_MEM_OVERHEAD -The initial and final memory overhead - memory used for the node +The initial and final memory overhead \(em memory used for the node itself and unacounted memory (e.g. due to hypervisor overhead). .TP @@ -124,7 +124,7 @@ virtual instance CPUs divided by the total physical CPU count. .TP .I INI_MNODE_MEM_AVAIL, FIN_MNODE_MEM_AVAIL -The initial and final maximum per-node available memory. This is not +The initial and final maximum per\(hynode available memory. This is not very useful as a metric but can give an impression of the status of the nodes; as an example, this value restricts the maximum instance size that can be still created on the cluster. @@ -137,7 +137,7 @@ Like the above but for disk. .I TSPEC If the tiered allocation mode has been enabled, this parameter holds the pairs of specifications and counts of instances that can be -created in this mode. The value of the key is a space-separated list +created in this mode. The value of the key is a space\(hyseparated list of values; each value is of the form \fImemory,disk,vcpu=count\fR where the memory, disk and vcpu are the values for the current spec, and count is how many instances of this spec can be created. A @@ -203,12 +203,12 @@ The number of VCPUs of the instances to be placed (defaults to 1). .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. +The maximum virtual\(hyto\(hyphysical 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\(hycpu 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 @@ -222,13 +222,13 @@ Prints the before and after node status, in a format designed to allow the user to understand the node's most important parameters. It is possible to customise the listed information by passing a -comma-separated list of field names to this option (the field list is +comma\(hyseparated list of field names to this option (the field list is currently undocumented). By default, the node list will contain these informations: .RS .TP .B F -a character denoting the status of the node, with '-' meaning an +a character denoting the status of the node, with '\-' meaning an offline node, '*' meaning N+1 failure and blank meaning a good node .TP .B Name @@ -301,7 +301,7 @@ This option (which can be given multiple times) will mark nodes as being \fIoffline\fR, and instances won't be placed on these nodes. Note that hspace will also mark as offline any nodes which are -reported by RAPI as such, or that have "?" in file-based input in any +reported by RAPI as such, or that have "?" in file\(hybased input in any numeric fields. .RE @@ -322,9 +322,9 @@ how to customize the default value via the environment). Collect data not from files but directly from the .I cluster 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 +(:), then it is converted into a fully\(hybuilt URL via prepending https:// and appending the default RAPI port, otherwise it's -considered a fully-specified URL and is used as-is. +considered a fully\(hyspecified URL and is used as\(hyis. .TP .BI "-L[" path "]" @@ -332,13 +332,13 @@ Collect data not from files but directly from the master daemon, which is to be contacted via the luxi (an internal Ganeti protocol). An optional \fIpath\fR argument is interpreted as the path to the unix socket on which the master daemon listens; otherwise, the default path -used by ganeti when installed with "--localstatedir=/var" is used. +used by ganeti when installed with \fI--localstatedir=/var\fR is used. .TP .BI "--simulate " description Instead of using actual data, build an empty cluster given a node -description. The \fIdescription\fR parameter must be a comma-separated -list of four elements, describing in order: +description. The \fIdescription\fR parameter must be a +comma\(hyseparated list of four elements, describing in order: .RS @@ -358,7 +358,7 @@ the cpu core count for the nodes .RE An example description would be \fB20,102400,16384,4\fR describing a -20-node cluster where each node has 100GiB of disk space, 16GiB of +20\(hynode cluster where each node has 100GiB of disk space, 16GiB of memory and 4 CPU cores. Note that all nodes must have the same specs currently. @@ -366,12 +366,12 @@ currently. .TP .BI "--tiered-alloc " spec -Beside the standard, fixed-size allocation, also do a tiered +Beside the standard, fixed\(hysize allocation, also do a tiered allocation scheme where the algorithm starts from the given specification and allocates until there is no more space; then it decreases the specification and tries the allocation again. The decrease is done on the matric that last failed during allocation. The -specification given is similar to the "--simulate" option and it +specification given is similar to the \fI--simulate\fR option and it holds: .RS