--- /dev/null
+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
+++ /dev/null
-<!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>
projects / ganeti-local / commitdiff