diff --git a/Makefile.am b/Makefile.am index 3d9b34bbfd1617618f929ce848fa028ca2f9eae7..5aeeff903ce2f2a462dd6220ca1e8a4306930342 100644 --- a/Makefile.am +++ b/Makefile.am @@ -108,13 +108,13 @@ http_PYTHON = \ docsgml = \ - doc/hooks.sgml \ doc/install.sgml \ doc/rapi.sgml docrst = \ doc/admin.rst \ doc/design-2.0.rst \ + doc/hooks.rst \ doc/iallocator.rst \ doc/security.rst diff --git a/doc/hooks.rst b/doc/hooks.rst new file mode 100644 index 0000000000000000000000000000000000000000..7df231cf7201dfd450fc4724ed7d65ccd05cc67b --- /dev/null +++ b/doc/hooks.rst @@ -0,0 +1,511 @@ +Ganeti customisation using hooks +================================ + +Documents ganeti version 2.0 + +.. contents:: + +Introduction +------------ + + +In order to allow customisation of operations, ganeti runs scripts +under ``/etc/ganeti/hooks`` based on certain rules. + + +This is similar to the ``/etc/network/`` structure present in Debian +for network interface handling. + +Organisation +------------ + +For every operation, two sets of scripts are run: + +- pre phase (for authorization/checking) +- post phase (for logging) + +Also, for each operation, the scripts are run on one or more nodes, +depending on the operation type. + +Note that, even though we call them scripts, we are actually talking +about any executable. + +*pre* scripts +~~~~~~~~~~~~~ + +The *pre* scripts have a definite target: to check that the operation +is allowed given the site-specific constraints. You could have, for +example, a rule that says every new instance is required to exists in +a database; to implement this, you could write a script that checks +the new instance parameters against your database. + +The objective of these scripts should be their return code (zero or +non-zero for success and failure). However, if they modify the +environment in any way, they should be idempotent, as failed +executions could be restarted and thus the script(s) run again with +exactly the same parameters. + +Note that if a node is unreachable at the time a hooks is run, this +will not be interpreted as a deny for the execution. In other words, +only an actual error returned from a script will cause abort, and not +an unreachable node. + +Therefore, if you want to guarantee that a hook script is run and +denies an action, it's best to put it on the master node. + +*post* scripts +~~~~~~~~~~~~~~ + +These scripts should do whatever you need as a reaction to the +completion of an operation. Their return code is not checked (but +logged), and they should not depend on the fact that the *pre* scripts +have been run. + +Naming +~~~~~~ + +The allowed names for the scripts consist of (similar to *run-parts* ) +upper and lower case, digits, underscores and hyphens. In other words, +the regexp ``^[a-zA-Z0-9_-]+$``. Also, non-executable scripts will be +ignored. + + +Order of execution +~~~~~~~~~~~~~~~~~~ + +On a single node, the scripts in a directory are run in lexicographic +order (more exactly, the python string comparison order). It is +advisable to implement the usual *NN-name* convention where *NN* is a +two digit number. + +For an operation whose hooks are run on multiple nodes, there is no +specific ordering of nodes with regard to hooks execution; you should +assume that the scripts are run in parallel on the target nodes +(keeping on each node the above specified ordering). If you need any +kind of inter-node synchronisation, you have to implement it yourself +in the scripts. + +Execution environment +~~~~~~~~~~~~~~~~~~~~~ + +The scripts will be run as follows: + +- no command line arguments + +- no controlling *tty* + +- stdin is actually */dev/null* + +- stdout and stderr are directed to files + +- PATH is reset to ``/sbin:/bin:/usr/sbin:/usr/bin`` + +- the environment is cleared, and only ganeti-specific variables will + be left + + +All informations about the cluster is passed using environment +variables. Different operations will have sligthly different +environments, but most of the variables are common. + +Operation list +-------------- + +Node operations +~~~~~~~~~~~~~~~ + +OP_ADD_NODE ++++++++++++ + +Adds a node to the cluster. + +:directory: node-add +:env. vars: NODE_NAME, NODE_PIP, NODE_SIP +:pre-execution: all existing nodes +:post-execution: all nodes plus the new node + + +OP_REMOVE_NODE +++++++++++++++ + +Removes a node from the cluster. + +:directory: node-remove +:env. vars: NODE_NAME +:pre-execution: all existing nodes except the removed node +:post-execution: all existing nodes except the removed node + +OP_NODE_SET_PARAMS +++++++++++++++++++ + +Changes a node's parameters. + +:directory: node-modify +:env. vars: MASTER_CANDIDATE, OFFLINE, DRAINED +:pre-execution: master node, the target node +:post-execution: master node, the target node + + +Instance operations +~~~~~~~~~~~~~~~~~~~ + +All instance operations take at least the following variables: +INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES, +INSTANCE_OS_TYPE, INSTANCE_DISK_TEMPLATE, INSTANCE_MEMORY, +INSTANCE_DISK_SIZES, INSTANCE_VCPUS, INSTANCE_NIC_COUNT, +INSTANCE_NICn_IP, INSTANCE_NICn_BRIDGE, INSTANCE_NICn_MAC, +INSTANCE_DISK_COUNT, INSTANCE_DISKn_SIZE, INSTANCE_DISKn_MODE. + +The INSTANCE_NICn_* and INSTANCE_DISKn_* variables represent the +properties of the *n* -th NIC and disk, and are zero-indexed. + + +OP_INSTANCE_ADD ++++++++++++++++ + +Creates a new instance. + +:directory: instance-add +:env. vars: ADD_MODE, SRC_NODE, SRC_PATH, SRC_IMAGES +:pre-execution: master node, primary and secondary nodes +:post-execution: master node, primary and secondary nodes + +OP_INSTANCE_REINSTALL ++++++++++++++++++++++ + +Reinstalls an instance. + +:directory: instance-reinstall +:env. vars: only the standard instance vars +:pre-execution: master node, primary and secondary nodes +:post-execution: master node, primary and secondary nodes + +OP_BACKUP_EXPORT +++++++++++++++++ + +Exports the instance. + + +:directory: instance-export +:env. vars: EXPORT_NODE, EXPORT_DO_SHUTDOWN +:pre-execution: master node, primary and secondary nodes +:post-execution: master node, primary and secondary nodes + +OP_INSTANCE_START ++++++++++++++++++ + +Starts an instance. + +:directory: instance-start +:env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES, FORCE +:pre-execution: master node, primary and secondary nodes +:post-execution: master node, primary and secondary nodes + +OP_INSTANCE_SHUTDOWN +++++++++++++++++++++ + +Stops an instance. + +:directory: instance-shutdown +:env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES +:pre-execution: master node, primary and secondary nodes +:post-execution: master node, primary and secondary nodes + +OP_INSTANCE_REBOOT +++++++++++++++++++ + +Reboots an instance. + +:directory: instance-reboot +:env. vars: IGNORE_SECONDARIES, REBOOT_TYPE +:pre-execution: master node, primary and secondary nodes +:post-execution: master node, primary and secondary nodes + +OP_INSTANCE_MODIFY +++++++++++++++++++ + +Modifies the instance parameters. + +:directory: instance-modify +:env. vars: INSTANCE_NAME, MEM_SIZE, VCPUS, INSTANCE_IP +:pre-execution: master node, primary and secondary nodes +:post-execution: master node, primary and secondary nodes + +OP_INSTANCE_FAILOVER +++++++++++++++++++++ + +Failovers an instance. + +:directory: instance-failover +:env. vars: IGNORE_CONSISTENCY +:pre-execution: master node, secondary node +:post-execution: master node, secondary node + +OP_INSTANCE_MIGRATE +++++++++++++++++++++ + +Migrates an instance. + +:directory: instance-failover +:env. vars: INSTANCE_MIGRATE_LIVE, INSTANCE_MIGRATE_CLEANUP +:pre-execution: master node, secondary node +:post-execution: master node, secondary node + + +OP_INSTANCE_REMOVE +++++++++++++++++++ + +Remove an instance. + +:directory: instance-remove +:env. vars: INSTANCE_NAME, INSTANCE_PRIMARY, INSTANCE_SECONDARIES +:pre-execution: master node +:post-execution: master node + +OP_INSTANCE_REPLACE_DISKS ++++++++++++++++++++++++++ + +Replace an instance's disks. + +:directory: mirror-replace +:env. vars: MODE, NEW_SECONDARY, OLD_SECONDARY +:pre-execution: master node, primary and secondary nodes +:post-execution: master node, primary and secondary nodes + +OP_INSTANCE_GROW_DISK ++++++++++++++++++++++ + +Grows the disk of an instance. + +:directory: disk-grow +:env. vars: DISK, AMOUNT +:pre-execution: master node, primary node +:post-execution: master node, primary node + +OP_INSTANCE_RENAME +++++++++++++++++++ + +Renames an instance. + +:directory: instance-rename +:env. vars: INSTANCE_NEW_NAME +:pre-execution: master node, primary and secondary nodes +:post-execution: master node, primary and secondary nodes + +Cluster operations +~~~~~~~~~~~~~~~~~~ + +OP_CLUSTER_VERIFY ++++++++++++++++++ + +Verifies the cluster status. This is a special LU with regard to +hooks, as the result of the opcode will be combined with the result of +post-execution hooks, in order to allow administrators to enhance the +cluster verification procedure. + +:directory: cluster-verify +:env. vars: CLUSTER, MASTER +:pre-execution: none +:post-execution: all nodes + +OP_CLUSTER_RENAME ++++++++++++++++++ + +Renames the cluster. + +:directory: cluster-rename +:env. vars: NEW_NAME +:pre-execution: master-node +:post-execution: master-node + +OP_CLUSTER_SET_PARAMS ++++++++++++++++++++++ + +Modifies the cluster parameters. + +:directory: cluster-modify +:env. vars: NEW_VG_NAME +:pre-execution: master node +:post-execution: master node + + +Obsolete operations +~~~~~~~~~~~~~~~~~~~ + +The following operations are no longer present or don't execute hooks +anymore in Ganeti 2.0: + +- OP_INIT_CLUSTER +- OP_MASTER_FAILOVER +- OP_INSTANCE_ADD_MDDRBD +- OP_INSTANCE_REMOVE_MDDRBD + + +Environment variables +--------------------- + +Note that all variables listed here are actually prefixed with +*GANETI_* in order to provide a clear namespace. + +Common variables +~~~~~~~~~~~~~~~~ + +This is the list of environment variables supported by all operations: + +HOOKS_VERSION + Documents the hooks interface version. In case this doesnt match + what the script expects, it should not run. The documents conforms + to the version 2. + +HOOKS_PHASE + One of *PRE* or *POST* denoting which phase are we in. + +CLUSTER + The cluster name. + +MASTER + The master node. + +OP_CODE + One of the *OP_* values from the list of operations. + +OBJECT_TYPE + One of ``INSTANCE``, ``NODE``, ``CLUSTER``. + +DATA_DIR + The path to the Ganeti configuration directory (to read, for + example, the *ssconf* files). + + +Specialised variables +~~~~~~~~~~~~~~~~~~~~~ + +This is the list of variables which are specific to one or more +operations. + +INSTANCE_NAME + The name of the instance which is the target of the operation. + +INSTANCE_DISK_TEMPLATE + The disk type for the instance. + +INSTANCE_DISK_COUNT + The number of disks for the instance. + +INSTANCE_DISKn_SIZE + The size of disk *n* for the instance. + +INSTANCE_DISKn_MODE + Either *rw* for a read-write disk or *ro* for a read-only one. + +INSTANCE_NIC_COUNT + The number of NICs for the instance. + +INSTANCE_NICn_BRIDGE + The bridge to which the *n* -th NIC of the instance is attached. + +INSTANCE_NICn_IP + The IP (if any) of the *n* -th NIC of the instance. + +INSTANCE_NICn_MAC + The MAC address of the *n* -th NIC of the instance. + +INSTANCE_OS_TYPE + The name of the instance OS. + +INSTANCE_PRIMARY + The name of the node which is the primary for the instance. + +INSTANCE_SECONDARIES + Space-separated list of secondary nodes for the instance. + +INSTANCE_MEMORY + The memory size (in MiBs) of the instance. + +INSTANCE_VCPUS + The number of virtual CPUs for the instance. + +INSTANCE_STATUS + The run status of the instance. + +NODE_NAME + The target node of this operation (not the node on which the hook + runs). + +NODE_PIP + The primary IP of the target node (the one over which inter-node + communication is done). + +NODE_SIP + The secondary IP of the target node (the one over which drbd + replication is done). This can be equal to the primary ip, in case + the cluster is not dual-homed. + +FORCE + This is provided by some operations when the user gave this flag. + +IGNORE_CONSISTENCY + The user has specified this flag. It is used when failing over + instances in case the primary node is down. + +ADD_MODE + The mode of the instance create: either *create* for create from + scratch or *import* for restoring from an exported image. + +SRC_NODE, SRC_PATH, SRC_IMAGE + In case the instance has been added by import, these variables are + defined and point to the source node, source path (the directory + containing the image and the config file) and the source disk image + file. + +NEW_SECONDARY + The name of the node on which the new mirror component is being + added. This can be the name of the current secondary, if the new + mirror is on the same secondary. + +OLD_SECONDARY + The name of the old secondary in the replace-disks command Note that + this can be equal to the new secondary if the secondary node hasn't + actually changed. + +EXPORT_NODE + The node on which the exported image of the instance was done. + +EXPORT_DO_SHUTDOWN + This variable tells if the instance has been shutdown or not while + doing the export. In the "was shutdown" case, it's likely that the + filesystem is consistent, whereas in the "did not shutdown" case, + the filesystem would need a check (journal replay or full fsck) in + order to guarantee consistency. + +Examples +-------- + +The startup of an instance will pass this environment to the hook +script:: + + GANETI_CLUSTER=cluster1.example.com + GANETI_DATA_DIR=/var/lib/ganeti + GANETI_FORCE=False + GANETI_HOOKS_PATH=instance-start + GANETI_HOOKS_PHASE=post + GANETI_HOOKS_VERSION=2 + GANETI_INSTANCE_DISK0_MODE=rw + GANETI_INSTANCE_DISK0_SIZE=128 + GANETI_INSTANCE_DISK_COUNT=1 + GANETI_INSTANCE_DISK_TEMPLATE=drbd + GANETI_INSTANCE_MEMORY=128 + GANETI_INSTANCE_NAME=instance2.example.com + GANETI_INSTANCE_NIC0_BRIDGE=xen-br0 + GANETI_INSTANCE_NIC0_IP= + GANETI_INSTANCE_NIC0_MAC=aa:00:00:a5:91:58 + GANETI_INSTANCE_NIC_COUNT=1 + GANETI_INSTANCE_OS_TYPE=debootstrap + GANETI_INSTANCE_PRIMARY=node3.example.com + GANETI_INSTANCE_SECONDARIES=node5.example.com + GANETI_INSTANCE_STATUS=down + GANETI_INSTANCE_VCPUS=1 + GANETI_MASTER=node1.example.com + GANETI_OBJECT_TYPE=INSTANCE + GANETI_OP_CODE=OP_INSTANCE_STARTUP + GANETI_OP_TARGET=instance2.example.com diff --git a/doc/hooks.sgml b/doc/hooks.sgml deleted file mode 100644 index 6afbb6b4f5424b9040cba613291d23e43b13ce47..0000000000000000000000000000000000000000 --- a/doc/hooks.sgml +++ /dev/null @@ -1,587 +0,0 @@ -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [ -]> - <article class="specification"> - <articleinfo> - <title>Ganeti customisation using hooks</title> - </articleinfo> - <para>Documents ganeti version 1.2</para> - <section> - <title>Introduction</title> - - <para> - In order to allow customisation of operations, ganeti will run - scripts under <filename - class="directory">/etc/ganeti/hooks</filename> based on certain - rules. - </para> - - <para>This is similar to the <filename - class="directory">/etc/network/</filename> structure present in - Debian for network interface handling.</para> - - </section> - - <section> - <title>Organisation</title> - - <para>For every operation, two sets of scripts are run: - - <itemizedlist> - <listitem> - <simpara>pre phase (for authorization/checking)</simpara> - </listitem> - <listitem> - <simpara>post phase (for logging)</simpara> - </listitem> - </itemizedlist> - </para> - - <para>Also, for each operation, the scripts are run on one or - more nodes, depending on the operation type.</para> - - <para>Note that, even though we call them scripts, we are - actually talking about any executable.</para> - - <section> - <title><emphasis>pre</emphasis> scripts</title> - - <para>The <emphasis>pre</emphasis> scripts have a definite - target: to check that the operation is allowed given the - site-specific constraints. You could have, for example, a rule - that says every new instance is required to exists in a - database; to implement this, you could write a script that - checks the new instance parameters against your - database.</para> - - <para>The objective of these scripts should be their return - code (zero or non-zero for success and failure). However, if - they modify the environment in any way, they should be - idempotent, as failed executions could be restarted and thus - the script(s) run again with exactly the same - parameters.</para> - - <para> - Note that if a node is unreachable at the time a hooks is run, - this will not be interpreted as a deny for the execution. In - other words, only an actual error returned from a script will - cause abort, and not an unreachable node. - </para> - - <para> - Therefore, if you want to guarantee that a hook script is run - and denies an action, it's best to put it on the master node. - </para> - - </section> - - <section> - <title><emphasis>post</emphasis> scripts</title> - - <para>These scripts should do whatever you need as a reaction - to the completion of an operation. Their return code is not - checked (but logged), and they should not depend on the fact - that the <emphasis>pre</emphasis> scripts have been - run.</para> - - </section> - - <section> - <title>Naming</title> - - <para>The allowed names for the scripts consist of (similar to - <citerefentry> <refentrytitle>run-parts</refentrytitle> - <manvolnum>8</manvolnum> </citerefentry>) upper and lower - case, digits, underscores and hyphens. In other words, the - regexp - <computeroutput>^[a-zA-Z0-9_-]+$</computeroutput>. Also, - non-executable scripts will be ignored. - </para> - </section> - - <section> - <title>Order of execution</title> - - <para>On a single node, the scripts in a directory are run in - lexicographic order (more exactly, the python string - comparison order). It is advisable to implement the usual - <emphasis>NN-name</emphasis> convention where - <emphasis>NN</emphasis> is a two digit number.</para> - - <para>For an operation whose hooks are run on multiple nodes, - there is no specific ordering of nodes with regard to hooks - execution; you should assume that the scripts are run in - parallel on the target nodes (keeping on each node the above - specified ordering). If you need any kind of inter-node - synchronisation, you have to implement it yourself in the - scripts.</para> - - </section> - - <section> - <title>Execution environment</title> - - <para>The scripts will be run as follows: - <itemizedlist> - <listitem> - <simpara>no command line arguments</simpara> - </listitem> - <listitem> - <simpara>no controlling <acronym>tty</acronym></simpara> - </listitem> - <listitem> - <simpara><varname>stdin</varname> is - actually <filename>/dev/null</filename></simpara> - </listitem> - <listitem> - <simpara><varname>stdout</varname> and - <varname>stderr</varname> are directed to - files</simpara> - </listitem> - <listitem> - <simpara>the <varname>PATH</varname> is reset to - <literal>/sbin:/bin:/usr/sbin:/usr/bin</literal></simpara> - </listitem> - <listitem> - <simpara>the environment is cleared, and only - ganeti-specific variables will be left</simpara> - </listitem> - </itemizedlist> - - </para> - - <para>All informations about the cluster is passed using - environment variables. Different operations will have sligthly - different environments, but most of the variables are - common.</para> - - </section> - - - <section> - <title>Operation list</title> - <table> - <title>Operation list</title> - <tgroup cols="7"> - <colspec> - <colspec> - <colspec> - <colspec> - <colspec> - <colspec colname="prehooks"> - <colspec colname="posthooks"> - <spanspec namest="prehooks" nameend="posthooks" - spanname="bothhooks"> - <thead> - <row> - <entry>Operation ID</entry> - <entry>Directory prefix</entry> - <entry>Description</entry> - <entry>Command</entry> - <entry>Supported env. variables</entry> - <entry><emphasis>pre</emphasis> hooks</entry> - <entry><emphasis>post</emphasis> hooks</entry> - </row> - </thead> - <tbody> - <row> - <entry>OP_INIT_CLUSTER</entry> - <entry><filename class="directory">cluster-init</filename></entry> - <entry>Initialises the cluster</entry> - <entry><computeroutput>gnt-cluster init</computeroutput></entry> - <entry><constant>CLUSTER</constant>, <constant>MASTER</constant></entry> - <entry spanname="bothhooks">master node, cluster name</entry> - </row> - <row> - <entry>OP_MASTER_FAILOVER</entry> - <entry><filename class="directory">master-failover</filename></entry> - <entry>Changes the master</entry> - <entry><computeroutput>gnt-cluster master-failover</computeroutput></entry> - <entry><constant>OLD_MASTER</constant>, <constant>NEW_MASTER</constant></entry> - <entry>the new master</entry> - <entry>all nodes</entry> - </row> - <row> - <entry>OP_ADD_NODE</entry> - <entry><filename class="directory">node-add</filename></entry> - <entry>Adds a new node to the cluster</entry> - <entry><computeroutput>gnt-node add</computeroutput></entry> - <entry><constant>NODE_NAME</constant>, <constant>NODE_PIP</constant>, <constant>NODE_SIP</constant></entry> - <entry>all existing nodes</entry> - <entry>all existing nodes plus the new node</entry> - </row> - <row> - <entry>OP_REMOVE_NODE</entry> - <entry><filename class="directory">node-remove</filename></entry> - <entry>Removes a node from the cluster</entry> - <entry><computeroutput>gnt-node remove</computeroutput></entry> - <entry><constant>NODE_NAME</constant></entry> - <entry spanname="bothhooks">all existing nodes except the removed node</entry> - </row> - <row> - <entry>OP_INSTANCE_ADD</entry> - <entry><filename class="directory">instance-add</filename></entry> - <entry>Creates a new instance</entry> - <entry><computeroutput>gnt-instance add</computeroutput></entry> - <entry><constant>INSTANCE_NAME</constant>, <constant>INSTANCE_PRIMARY</constant>, <constant>INSTANCE_SECONDARIES</constant>, <constant>DISK_TEMPLATE</constant>, <constant>MEM_SIZE</constant>, <constant>DISK_SIZE</constant>, <constant>SWAP_SIZE</constant>, <constant>VCPUS</constant>, <constant>INSTANCE_IP</constant>, <constant>INSTANCE_ADD_MODE</constant>, <constant>SRC_NODE</constant>, <constant>SRC_PATH</constant>, <constant>SRC_IMAGE</constant></entry> - <entry spanname="bothhooks" morerows="4">master node, primary and - secondary nodes</entry> - </row> - <row> - <entry>OP_BACKUP_EXPORT</entry> - <entry><filename class="directory">instance-export</filename></entry> - <entry>Export the instance</entry> - <entry><computeroutput>gnt-backup export</computeroutput></entry> - <entry><constant>INSTANCE_NAME</constant>, <constant>EXPORT_NODE</constant>, <constant>EXPORT_DO_SHUTDOWN</constant></entry> - </row> - <row> - <entry>OP_INSTANCE_START</entry> - <entry><filename class="directory">instance-start</filename></entry> - <entry>Starts an instance</entry> - <entry><computeroutput>gnt-instance start</computeroutput></entry> - <entry><constant>INSTANCE_NAME</constant>, <constant>INSTANCE_PRIMARY</constant>, <constant>INSTANCE_SECONDARIES</constant>, <constant>FORCE</constant></entry> - </row> - <row> - <entry>OP_INSTANCE_SHUTDOWN</entry> - <entry><filename class="directory">instance-shutdown</filename></entry> - <entry>Stops an instance</entry> - <entry><computeroutput>gnt-instance shutdown</computeroutput></entry> - <entry><constant>INSTANCE_NAME</constant>, <constant>INSTANCE_PRIMARY</constant>, <constant>INSTANCE_SECONDARIES</constant></entry> - </row> - <row> - <entry>OP_INSTANCE_MODIFY</entry> - <entry><filename class="directory">instance-modify</filename></entry> - <entry>Modifies the instance parameters.</entry> - <entry><computeroutput>gnt-instance modify</computeroutput></entry> - <entry><constant>INSTANCE_NAME</constant>, <constant>MEM_SIZE</constant>, <constant>VCPUS</constant>, <constant>INSTANCE_IP</constant></entry> - </row> - <row> - <entry>OP_INSTANCE_FAILOVER</entry> - <entry><filename class="directory">instance-failover</filename></entry> - <entry>Failover an instance</entry> - <entry><computeroutput>gnt-instance start</computeroutput></entry> - <entry><constant>INSTANCE_NAME</constant>, <constant>INSTANCE_PRIMARY</constant>, <constant>INSTANCE_SECONDARIES</constant>, <constant>IGNORE_CONSISTENCY</constant></entry> - </row> - <row> - <entry>OP_INSTANCE_REMOVE</entry> - <entry><filename class="directory">instance-remove</filename></entry> - <entry>Remove an instance</entry> - <entry><computeroutput>gnt-instance remove</computeroutput></entry> - <entry><constant>INSTANCE_NAME</constant>, <constant>INSTANCE_PRIMARY</constant>, <constant>INSTANCE_SECONDARIES</constant></entry> - <entry spanname="bothhooks">master node</entry> - </row> - <row> - <entry>OP_INSTANCE_ADD_MDDRBD</entry> - <entry><filename class="directory">mirror-add</filename></entry> - <entry>Adds a mirror component</entry> - <entry><computeroutput>gnt-instance add-mirror</computeroutput></entry> - <entry><constant>INSTANCE_NAME</constant>, <constant>NEW_SECONDARY</constant>, <constant>DISK_NAME</constant></entry> - </row> - <row> - <entry>OP_INSTANCE_REMOVE_MDDRBD</entry> - <entry><filename class="directory">mirror-remove</filename></entry> - <entry>Removes a mirror component</entry> - <entry><computeroutput>gnt-instance remove-mirror</computeroutput></entry> - <entry><constant>INSTANCE_NAME</constant>, <constant>OLD_SECONDARY</constant>, <constant>DISK_NAME</constant>, <constant>DISK_ID</constant></entry> - </row> - <row> - <entry>OP_INSTANCE_REPLACE_DISKS</entry> - <entry><filename class="directory">mirror-replace</filename></entry> - <entry>Replace all mirror components</entry> - <entry><computeroutput>gnt-instance replace-disks</computeroutput></entry> - <entry><constant>INSTANCE_NAME</constant>, <constant>OLD_SECONDARY</constant>, <constant>NEW_SECONDARY</constant></entry> - - </row> - <row> - <entry>OP_CLUSTER_VERIFY</entry> - <entry><filename class="directory">cluster-verify</filename></entry> - <entry>Verifies the cluster status</entry> - <entry><computeroutput>gnt-cluster verify</computeroutput></entry> - <entry><constant>CLUSTER</constant>, <constant>MASTER</constant></entry> - <entry>NONE</entry> - <entry>all nodes</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section> - <title>Environment variables</title> - - <para>Note that all variables listed here are actually prefixed - with <constant>GANETI_</constant> in order to provide a - different namespace.</para> - - <section> - <title>Common variables</title> - - <para>This is the list of environment variables supported by - all operations:</para> - - <variablelist> - <varlistentry> - <term>HOOKS_VERSION</term> - <listitem> - <para>Documents the hooks interface version. In case this - doesnt match what the script expects, it should not - run. The documents conforms to the version - <literal>1</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>HOOKS_PHASE</term> - <listitem> - <para>one of <constant>PRE</constant> or - <constant>POST</constant> denoting which phase are we - in.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>CLUSTER</term> - <listitem> - <para>the cluster name</para> - </listitem> - </varlistentry> - <varlistentry> - <term>MASTER</term> - <listitem> - <para>the master node</para> - </listitem> - </varlistentry> - <varlistentry> - <term>OP_ID</term> - <listitem> - <para>one of the <constant>OP_*</constant> values from - the table of operations</para> - </listitem> - </varlistentry> - <varlistentry> - <term>OBJECT_TYPE</term> - <listitem> - <para>one of <simplelist type="inline"> - <member><constant>INSTANCE</constant></member> - <member><constant>NODE</constant></member> - <member><constant>CLUSTER</constant></member> - </simplelist>, showing the target of the operation. - </para> - </listitem> - </varlistentry> - <!-- commented out since it causes problems in our rpc - multi-node optimised calls - <varlistentry> - <term>HOST_NAME</term> - <listitem> - <para>The name of the node the hook is run on as known by - the cluster.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>HOST_TYPE</term> - <listitem> - <para>one of <simplelist type="inline"> - <member><constant>MASTER</constant></member> - <member><constant>NODE</constant></member> - </simplelist>, showing the role of this node in the cluster. - </para> - </listitem> - </varlistentry> - --> - </variablelist> - </section> - - <section> - <title>Specialised variables</title> - - <para>This is the list of variables which are specific to one - or more operations.</para> - <variablelist> - <varlistentry> - <term>INSTANCE_NAME</term> - <listitem> - <para>The name of the instance which is the target of - the operation.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>INSTANCE_DISK_TYPE</term> - <listitem> - <para>The disk type for the instance.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>INSTANCE_DISK_SIZE</term> - <listitem> - <para>The (OS) disk size for the instance.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>INSTANCE_OS</term> - <listitem> - <para>The name of the instance OS.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>INSTANCE_PRIMARY</term> - <listitem> - <para>The name of the node which is the primary for the - instance.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>INSTANCE_SECONDARIES</term> - <listitem> - <para>Space-separated list of secondary nodes for the - instance.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>NODE_NAME</term> - <listitem> - <para>The target node of this operation (not the node on - which the hook runs).</para> - </listitem> - </varlistentry> - <varlistentry> - <term>NODE_PIP</term> - <listitem> - <para>The primary IP of the target node (the one over - which inter-node communication is done).</para> - </listitem> - </varlistentry> - <varlistentry> - <term>NODE_SIP</term> - <listitem> - <para>The secondary IP of the target node (the one over - which drbd replication is done). This can be equal to - the primary ip, in case the cluster is not - dual-homed.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>OLD_MASTER</term> - <term>NEW_MASTER</term> - <listitem> - <para>The old, respectively the new master for the - master failover operation.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>FORCE</term> - <listitem> - <para>This is provided by some operations when the user - gave this flag.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>IGNORE_CONSISTENCY</term> - <listitem> - <para>The user has specified this flag. It is used when - failing over instances in case the primary node is - down.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>MEM_SIZE, DISK_SIZE, SWAP_SIZE, VCPUS</term> - <listitem> - <para>The memory, disk, swap size and the number of - processor selected for the instance (in - <command>gnt-instance add</command> or - <command>gnt-instance modify</command>).</para> - </listitem> - </varlistentry> - <varlistentry> - <term>INSTANCE_IP</term> - <listitem> - <para>If defined, the instance IP in the - <command>gnt-instance add</command> and - <command>gnt-instance set</command> commands. If not - defined, it means that no IP has been defined.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>DISK_TEMPLATE</term> - <listitem> - <para>The disk template type when creating the instance.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>INSTANCE_ADD_MODE</term> - <listitem> - <para>The mode of the create: either - <constant>create</constant> for create from scratch or - <constant>import</constant> for restoring from an - exported image.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>SRC_NODE, SRC_PATH, SRC_IMAGE</term> - <listitem> - <para>In case the instance has been added by import, - these variables are defined and point to the source - node, source path (the directory containing the image - and the config file) and the source disk image - file.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>DISK_NAME</term> - <listitem> - <para>The disk name (either <filename>sda</filename> or - <filename>sdb</filename>) in mirror operations - (add/remove mirror).</para> - </listitem> - </varlistentry> - <varlistentry> - <term>DISK_ID</term> - <listitem> - <para>The disk id for mirror remove operations. You can - look this up using <command>gnt-instance - info</command>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>NEW_SECONDARY</term> - <listitem> - <para>The name of the node on which the new mirror - componet is being added. This can be the name of the - current secondary, if the new mirror is on the same - secondary.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>OLD_SECONDARY</term> - <listitem> - <para>The name of the old secondary. This is used in - both <command>replace-disks</command> and - <command>remove-mirror</command>. Note that this can be - equal to the new secondary (only - <command>replace-disks</command> has both variables) if - the secondary node hasn't actually changed).</para> - </listitem> - </varlistentry> - <varlistentry> - <term>EXPORT_NODE</term> - <listitem> - <para>The node on which the exported image of the - instance was done.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>EXPORT_DO_SHUTDOWN</term> - <listitem> - <para>This variable tells if the instance has been - shutdown or not while doing the export. In the "was - shutdown" case, it's likely that the filesystem is - consistent, whereas in the "did not shutdown" case, the - filesystem would need a check (journal replay or full - fsck) in order to guarantee consistency.</para> - </listitem> - </varlistentry> - </variablelist> - - </section> - - </section> - - </section> - </article>