X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/b74bf80cfedf3c1afeb3f51d665336037205c33c..107102afa6161982c9c9a5c69378e7773b002367:/man/ganeti.rst diff --git a/man/ganeti.rst b/man/ganeti.rst index 97d1832..d31adfc 100644 --- a/man/ganeti.rst +++ b/man/ganeti.rst @@ -99,8 +99,8 @@ vm_capable Node Parameters ~~~~~~~~~~~~~~~ -These parameters are node specific and can be preseeded on node-group -and cluster level. +The ``ndparams`` refer to node parameters. These can be set as defaults +on cluster and node group levels, but they take effect for nodes only. Currently we support the following node parameters: @@ -109,6 +109,69 @@ oob_program the `Ganeti Node OOB Management Framework `_ design document. +spindle_count + This should reflect the I/O performance of local attached storage + (e.g. for "file", "plain" and "drbd" disk templates). It doesn't + have to match the actual spindle count of (any eventual) mechanical + hard-drives, its meaning is site-local and just the relative values + matter. + + +Hypervisor State Parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Using ``--hypervisor-state`` you can set hypervisor specific states as +pointed out in ``Ganeti Resource Model ``. + +The format is: ``hypervisor:option=value``. + +Currently we support the following hypervisor state values: + +mem_total + Total node memory, as discovered by this hypervisor +mem_node + Memory used by, or reserved for, the node itself; note that some + hypervisors can report this in an authoritative way, other not +mem_hv + Memory used either by the hypervisor itself or lost due to instance + allocation rounding; usually this cannot be precisely computed, but + only roughly estimated +cpu_total + Total node cpu (core) count; usually this can be discovered + automatically +cpu_node + Number of cores reserved for the node itself; this can either be + discovered or set manually. Only used for estimating how many VCPUs + are left for instances + +Note that currently this option is unused by Ganeti; values will be +recorded but will not influence the Ganeti operation. + + +Disk State Parameters +~~~~~~~~~~~~~~~~~~~~~ + +Using ``--disk-state`` you can set disk specific states as pointed out +in ``Ganeti Resource Model ``. + +The format is: ``storage_type/identifier:option=value``. Where we +currently just support ``lvm`` as storage type. The identifier in this +case is the LVM volume group. By default this is ``xenvg``. + +Currently we support the following hypervisor state values: + +disk_total + Total disk size (usually discovered automatically) +disk_reserved + Reserved disk size; this is a lower limit on the free space, if such a + limit is desired +disk_overhead + Disk that is expected to be used by other volumes (set via + ``reserved_lvs``); usually should be zero + +Note that currently this option is unused by Ganeti; values will be +recorded but will not influence the Ganeti operation. + Cluster configuration ~~~~~~~~~~~~~~~~~~~~~ @@ -158,17 +221,202 @@ error stopped during the job execution. -Common options --------------- +Common command line features +---------------------------- + +Options +~~~~~~~ Many Ganeti commands provide the following options. The availability for a certain command can be checked by calling the command using the ``--help`` option. -**gnt-...** *command* [--dry-run] [--priority {low | normal | high}] +| **gnt-...** *command* [\--dry-run] [\--priority {low | normal | high}] +| [\--submit] The ``--dry-run`` option can be used to check whether an operation would succeed. The option ``--priority`` sets the priority for opcodes submitted by the command. + +The ``--submit`` option is used to send the job to the master daemon but +not wait for its completion. The job ID will be shown so that it can be +examined using **gnt-job info**. + +Defaults +~~~~~~~~ + +For certain commands you can use environment variables to provide +default command line arguments. Just assign the arguments as a string to +the corresponding environment variable. The format of that variable +name is **binary**_*command*. **binary** is the name of the ``gnt-*`` +script all upper case and dashes replaced by underscores, and *command* +is the command invoked on that script. + +Currently supported commands are ``gnt-node list``, ``gnt-group list`` +and ``gnt-instance list``. So you can configure default command line +flags by setting ``GNT_NODE_LIST``, ``GNT_GROUP_LIST`` and +``GNT_INSTANCE_LIST``. + +Field formatting +---------------- + +Multiple ganeti commands use the same framework for tabular listing of +resources (e.g. **gnt-instance list**, **gnt-node list**, **gnt-group +list**, **gnt-debug locks**, etc.). For these commands, special states +are denoted via a special symbol (in terse mode) or a string (in +verbose mode): + +\*, (offline) + The node in question is marked offline, and thus it cannot be + queried for data. This result is persistent until the node is + de-offlined. + +?, (nodata) + Ganeti expected to receive an answer from this entity, but the + cluster RPC call failed and/or we didn't receive a valid answer; + usually more information is available in the node daemon log (if + the node is alive) or the master daemon log. This result is + transient, and re-running command might return a different result. + +-, (unavail) + The respective field doesn't make sense for this entity; + e.g. querying a down instance for its current memory 'live' usage, + or querying a non-vm_capable node for disk/memory data. This + result is persistent, and until the entity state is changed via + ganeti commands, the result won't change. + +??, (unknown) + This field is not known (note that this is different from entity + being unknown). Either you have mis-typed the field name, or you + are using a field that the running Ganeti master daemon doesn't + know. This result is persistent, re-running the command won't + change it. + +Key-value parameters +~~~~~~~~~~~~~~~~~~~~ + +Multiple options take parameters that are of the form +``key=value,key=value,...`` or ``category:key=value,...``. Examples +are the hypervisor parameters, backend parameters, etc. For these, +it's possible to use values that contain commas by escaping with via a +backslash (which needs two if not single-quoted, due to shell +behaviour):: + + # gnt-instance modify -H kernel_path=an\\,example instance1 + # gnt-instance modify -H kernel_path='an\,example' instance1 + +Query filters +~~~~~~~~~~~~~ + +Most commands listing resources (e.g. instances or nodes) support filtering. +The filter language is similar to Python expressions with some elements from +Perl. The language is not generic. Each condition must consist of a field name +and a value (except for boolean checks), a field can not be compared to another +field. Keywords are case-sensitive. + +Examples (see below for syntax details): + +- List webservers:: + + gnt-instance list --filter 'name =* "web*.example.com"' + +- List instances with three or six virtual CPUs and whose primary + nodes reside in groups starting with the string "rack":: + + gnt-instance list --filter + '(be/vcpus == 3 or be/vcpus == 6) and pnode.group =~ m/^rack/' + +- Nodes hosting primary instances:: + + gnt-node list --filter 'pinst_cnt != 0' + +- Nodes which aren't master candidates:: + + gnt-node list --filter 'not master_candidate' + +- Short version for globbing patterns:: + + gnt-instance list '*.site1' '*.site2' + +Syntax in pseudo-BNF:: + + ::= /* String quoted with single or double quotes, + backslash for escaping */ + + ::= /* Number in base-10 positional notation */ + + ::= /* Regular expression */ + + /* + Modifier "i": Case-insensitive matching, see + http://docs.python.org/library/re#re.IGNORECASE + + Modifier "s": Make the "." special character match any character, + including newline, see http://docs.python.org/library/re#re.DOTALL + */ + ::= /* empty */ | i | s + + ::= | + + ::= + { /* Value comparison */ + { == | != | < | <= | >= | > } + + /* Collection membership */ + | [ not ] in + + /* Regular expressions (recognized delimiters + are "/", "#", "^", and "|"; backslash for escaping) + */ + | { =~ | !~ } m// + + /* Globbing */ + | { =* | !* } + + /* Boolean */ + | + } + + ::= + { [ not ] | ( ) } + [ { and | or } ] + +Operators: + +*==* + Equality +*!=* + Inequality +*<* + Less than +*<=* + Less than or equal +*>* + Greater than +*>=* + Greater than or equal +*=~* + Pattern match using regular expression +*!~* + Logically negated from *=~* +*=\** + Globbing, see **glob**(7), though only * and ? are supported +*!\** + Logically negated from *=\** +*in*, *not in* + Collection membership and negation + + +Common daemon functionality +--------------------------- + +All Ganeti daemons re-open the log file(s) when sent a SIGHUP signal. +**logrotate**(8) can be used to rotate Ganeti's log files. + +.. vim: set textwidth=72 : +.. Local Variables: +.. mode: rst +.. fill-column: 72 +.. End: