Commit 7faf5110 authored by Michael Hanselmann's avatar Michael Hanselmann

Wrap documentation to max 72 characters per line

Signed-off-by: default avatarMichael Hanselmann <hansmi@google.com>
Reviewed-by: default avatarIustin Pop <iustin@google.com>
parent 558fd122
......@@ -7,8 +7,8 @@ Version 2.0.3
- Added ``--ignore-size`` to the ``gnt-instance activate-disks`` command
to allow using the pre-2.0.2 behaviour in activation, if any existing
instances have mismatched disk sizes in the configuration
- Added ``gnt-cluster repair-disk-sizes`` command to check and update any
configuration mismatches for disk sizes
- Added ``gnt-cluster repair-disk-sizes`` command to check and update
any configuration mismatches for disk sizes
- Added ``gnt-master cluste-failover --no-voting`` to allow master
failover to work on two-node clusters
- Fixed the ‘--net’ option of ``gnt-backup import``, which was unusable
......@@ -61,9 +61,9 @@ Version 2.0.1
- the watcher now also restarts the node daemon and the rapi daemon if
they died
- fixed the watcher to handle full and drained queue cases
- hooks export more instance data in the environment, which helps if hook
scripts need to take action based on the instance's properties (no
longer need to query back into ganeti)
- hooks export more instance data in the environment, which helps if
hook scripts need to take action based on the instance's properties
(no longer need to query back into ganeti)
- instance failovers when the instance is stopped do not check for free
RAM, so that failing over a stopped instance is possible in low memory
situations
......@@ -169,10 +169,10 @@ Version 2.0 beta 1
- all commands are executed by a daemon (``ganeti-masterd``) and the
various ``gnt-*`` commands are just front-ends to it
- all the commands are entered into, and executed from a job queue, see
the ``gnt-job(8)`` manpage
- the RAPI daemon supports read-write operations, secured by basic HTTP
authentication on top of HTTPS
- all the commands are entered into, and executed from a job queue,
see the ``gnt-job(8)`` manpage
- the RAPI daemon supports read-write operations, secured by basic
HTTP authentication on top of HTTPS
- DRBD version 0.7 support has been removed, DRBD 8 is the only
supported version (when migrating from Ganeti 1.2 to 2.0, you need
to migrate to DRBD 8 first while still running Ganeti 1.2)
......@@ -193,8 +193,8 @@ Version 1.2.7
- Change the default reboot type in ``gnt-instance reboot`` to "hard"
- Reuse the old instance mac address by default on instance import, if
the instance name is the same.
- Handle situations in which the node info rpc returns incomplete results
(issue 46)
- Handle situations in which the node info rpc returns incomplete
results (issue 46)
- Add checks for tcp/udp ports collisions in ``gnt-cluster verify``
- Improved version of batcher:
......@@ -218,10 +218,10 @@ Version 1.2.6
- new ``--hvm-nic-type`` and ``--hvm-disk-type`` flags to control the
type of disk exported to fully virtualized instances.
- provide access to the serial console of HVM instances
- instance auto_balance flag, set by default. If turned off it will avoid
warnings on cluster verify if there is not enough memory to fail over
an instance. in the future it will prevent automatically failing it
over when we will support that.
- instance auto_balance flag, set by default. If turned off it will
avoid warnings on cluster verify if there is not enough memory to fail
over an instance. in the future it will prevent automatically failing
it over when we will support that.
- batcher tool for instance creation, see ``tools/README.batcher``
- ``gnt-instance reinstall --select-os`` to interactively select a new
operating system when reinstalling an instance.
......@@ -347,8 +347,8 @@ Version 1.2.1
Version 1.2.0
-------------
- Log the ``xm create`` output to the node daemon log on failure (to help
diagnosing the error)
- Log the ``xm create`` output to the node daemon log on failure (to
help diagnosing the error)
- In debug mode, log all external commands output if failed to the logs
- Change parsing of lvm commands to ignore stderr
......@@ -384,8 +384,8 @@ Version 1.2b2
reboots
- Removed dependency on debian's patched fping that uses the
non-standard ``-S`` option
- Now the OS definitions are searched for in multiple, configurable paths
(easier for distros to package)
- Now the OS definitions are searched for in multiple, configurable
paths (easier for distros to package)
- Some changes to the hooks infrastructure (especially the new
post-configuration update hook)
- Other small bugfixes
......
......@@ -343,7 +343,8 @@ At this point, the machines are ready for a cluster creation; in case
you want to remove Ganeti completely, you need to also undo some of
the SSH changes and log directories:
- ``rm -rf /var/log/ganeti /srv/ganeti`` (replace with the correct paths)
- ``rm -rf /var/log/ganeti /srv/ganeti`` (replace with the correct
paths)
- remove from ``/root/.ssh`` the keys that Ganeti added (check
the ``authorized_keys`` and ``id_dsa`` files)
- regenerate the host's SSH keys (check the OpenSSH startup scripts)
......
This diff is collapsed.
This diff is collapsed.
......@@ -16,8 +16,8 @@ Glossary
the startup of an instance.
OpCode
A data structure encapsulating a basic cluster operation; for example,
start instance, add instance, etc.
A data structure encapsulating a basic cluster operation; for
example, start instance, add instance, etc.
PVM
Para-virtualization mode, where the virtual machine knows it's being
......
......@@ -128,8 +128,9 @@ Adds a node to the cluster.
OP_REMOVE_NODE
++++++++++++++
Removes a node from the cluster. On the removed node the hooks are called
during the execution of the operation and not after its completion.
Removes a node from the cluster. On the removed node the hooks are
called during the execution of the operation and not after its
completion.
:directory: node-remove
:env. vars: NODE_NAME
......@@ -350,7 +351,8 @@ Cluster operations
OP_POST_INIT_CLUSTER
++++++++++++++++++++
This hook is called via a special "empty" LU right after cluster initialization.
This hook is called via a special "empty" LU right after cluster
initialization.
:directory: cluster-init
:env. vars: none
......@@ -360,8 +362,8 @@ This hook is called via a special "empty" LU right after cluster initialization.
OP_DESTROY_CLUSTER
++++++++++++++++++
The post phase of this hook is called during the execution of destroy operation
and not after its completion.
The post phase of this hook is called during the execution of destroy
operation and not after its completion.
:directory: cluster-destroy
:env. vars: none
......
......@@ -225,9 +225,10 @@ nodes
or ``offline`` flags set. More details about these of node status
flags is available in the manpage :manpage:`ganeti(7)`.
.. [*] Note that no run-time data is present for offline or drained nodes;
this means the tags total_memory, reserved_memory, free_memory, total_disk,
free_disk, total_cpus, i_pri_memory and i_pri_up memory will be absent
.. [*] Note that no run-time data is present for offline or drained
nodes; this means the tags total_memory, reserved_memory,
free_memory, total_disk, free_disk, total_cpus, i_pri_memory and
i_pri_up memory will be absent
Response message
......
......@@ -108,20 +108,21 @@ and not just *node1*.
.. admonition:: Why a fully qualified host name
Although most distributions use only the short name in the /etc/hostname
file, we still think Ganeti nodes should use the full name. The reason for
this is that calling 'hostname --fqdn' requires the resolver library to work
and is a 'guess' via heuristics at what is your domain name. Since Ganeti
can be used among other things to host DNS servers, we don't want to depend
on them as much as possible, and we'd rather have the uname() syscall return
the full node name.
We haven't ever found any breakage in using a full hostname on a Linux
system, and anyway we recommend to have only a minimal installation on
Ganeti nodes, and to use instances (or other dedicated machines) to run the
rest of your network services. By doing this you can change the
/etc/hostname file to contain an FQDN without the fear of breaking anything
unrelated.
Although most distributions use only the short name in the
/etc/hostname file, we still think Ganeti nodes should use the full
name. The reason for this is that calling 'hostname --fqdn' requires
the resolver library to work and is a 'guess' via heuristics at what
is your domain name. Since Ganeti can be used among other things to
host DNS servers, we don't want to depend on them as much as
possible, and we'd rather have the uname() syscall return the full
node name.
We haven't ever found any breakage in using a full hostname on a
Linux system, and anyway we recommend to have only a minimal
installation on Ganeti nodes, and to use instances (or other
dedicated machines) to run the rest of your network services. By
doing this you can change the /etc/hostname file to contain an FQDN
without the fear of breaking anything unrelated.
Installing The Hypervisor
......@@ -130,9 +131,9 @@ Installing The Hypervisor
**Mandatory** on all nodes.
While Ganeti is developed with the ability to modularly run on different
virtualization environments in mind the only two currently useable on a live
system are Xen and KVM. Supported Xen versions are: 3.0.3, 3.0.4 and 3.1.
Supported KVM version are 72 and above.
virtualization environments in mind the only two currently useable on a
live system are Xen and KVM. Supported Xen versions are: 3.0.3, 3.0.4
and 3.1. Supported KVM version are 72 and above.
Please follow your distribution's recommended way to install and set
up Xen, or install Xen from the upstream source, if you wish,
......@@ -140,9 +141,9 @@ following their manual. For KVM, make sure you have a KVM-enabled
kernel and the KVM tools.
After installing Xen, you need to reboot into your new system. On some
distributions this might involve configuring GRUB appropriately, whereas others
will configure it automatically when you install the respective kernels. For
KVM no reboot should be necessary.
distributions this might involve configuring GRUB appropriately, whereas
others will configure it automatically when you install the respective
kernels. For KVM no reboot should be necessary.
.. admonition:: Xen on Debian
......@@ -315,8 +316,8 @@ them will already be installed on a standard machine.
You can use this command line to install all needed packages::
# apt-get install lvm2 ssh bridge-utils iproute iputils-arping \
python python-pyopenssl openssl python-pyparsing python-simplejson \
python-pyinotify
python python-pyopenssl openssl python-pyparsing \
python-simplejson python-pyinotify
Setting up the environment for Ganeti
-------------------------------------
......@@ -326,34 +327,38 @@ Configuring the network
**Mandatory** on all nodes.
You can run Ganeti either in "bridge mode" or in "routed mode". In bridge
mode, the default, the instances network interfaces will be attached to a
software bridge running in dom0. Xen by default creates such a bridge at
startup, but your distribution might have a different way to do things, and
you'll definitely need to manually set it up under KVM.
You can run Ganeti either in "bridge mode" or in "routed mode". In
bridge mode, the default, the instances network interfaces will be
attached to a software bridge running in dom0. Xen by default creates
such a bridge at startup, but your distribution might have a different
way to do things, and you'll definitely need to manually set it up under
KVM.
Beware that the default name Ganeti uses is ``xen-br0`` (which was
used in Xen 2.0) while Xen 3.0 uses ``xenbr0`` by default. The default
bridge your Ganeti cluster will use for new instances can be specified
at cluster initialization time.
If you want to run in "routing mode" you need to specify that at cluster init
time (using the --nicparam option), and then no bridge will be needed. In
this mode instance traffic will be routed by dom0, instead of bridged.
If you want to run in "routing mode" you need to specify that at cluster
init time (using the --nicparam option), and then no bridge will be
needed. In this mode instance traffic will be routed by dom0, instead of
bridged.
In order to use "routing mode" under Xen, you'll need to change the relevant
parameters in the Xen config file. Under KVM instead, no config change is
necessary, but you still need to set up your network interfaces correctly.
In order to use "routing mode" under Xen, you'll need to change the
relevant parameters in the Xen config file. Under KVM instead, no config
change is necessary, but you still need to set up your network
interfaces correctly.
By default, under KVM, the "link" parameter you specify per-nic will
represent, if non-empty, a different routing table name or number to use for
your instances. This allows insulation between different instance groups,
and different routing policies between node traffic and instance traffic.
represent, if non-empty, a different routing table name or number to use
for your instances. This allows insulation between different instance
groups, and different routing policies between node traffic and instance
traffic.
You will need to configure your routing table basic routes and rules outside
of ganeti. The vif scripts will only add /32 routes to your instances,
through their interface, in the table you specified (under KVM, and in the
main table under Xen).
You will need to configure your routing table basic routes and rules
outside of ganeti. The vif scripts will only add /32 routes to your
instances, through their interface, in the table you specified (under
KVM, and in the main table under Xen).
.. admonition:: Bridging under Debian
......@@ -512,8 +517,8 @@ that the hostname used for this must resolve to an IP address reserved
**exclusively** for this purpose, and cannot be the name of the first
(master) node.
If you want to use a bridge which is not ``xen-br0``, or no bridge at all, use
the --nicparams
If you want to use a bridge which is not ``xen-br0``, or no bridge at
all, use ``--nicparams``.
If the bridge name you are using is not ``xen-br0``, use the *-b
<BRIDGENAME>* option to specify the bridge name. In this case, you
......
......@@ -11,61 +11,66 @@ It is divided by functional sections
Opcode Execution Locking
------------------------
These locks are declared by Logical Units (LUs) (in cmdlib.py) and acquired by
the Processor (in mcpu.py) with the aid of the Ganeti Locking Library
(locking.py). They are acquired in the following order:
* BGL: this is the Big Ganeti Lock, it exists for retrocompatibility. New LUs
acquire it in a shared fashion, and are able to execute all toghether
(baring other lock waits) while old LUs acquire it exclusively and can only
execute one at a time, and not at the same time with new LUs.
* Instance locks: can be declared in ExpandNames() or DeclareLocks() by an LU,
and have the same name as the instance itself. They are acquired as a set.
Internally the locking library acquired them in alphabetical order.
* Node locks: can be declared in ExpandNames() or DeclareLocks() by an LU, and
have the same name as the node itself. They are acquired as a set.
Internally the locking library acquired them in alphabetical order. Given
this order it's possible to safely acquire a set of instances, and then the
nodes they reside on.
The ConfigWriter (in config.py) is also protected by a SharedLock, which is
shared by functions that read the config and acquired exclusively by functions
that modify it. Since the ConfigWriter calls rpc.call_upload_file to all nodes
to distribute the config without holding the node locks, this call must be able
to execute on the nodes in parallel with other operations (but not necessarily
concurrently with itself on the same file, as inside the ConfigWriter this is
called with the internal config lock held.
These locks are declared by Logical Units (LUs) (in cmdlib.py) and
acquired by the Processor (in mcpu.py) with the aid of the Ganeti
Locking Library (locking.py). They are acquired in the following order:
* BGL: this is the Big Ganeti Lock, it exists for retrocompatibility.
New LUs acquire it in a shared fashion, and are able to execute all
toghether (baring other lock waits) while old LUs acquire it
exclusively and can only execute one at a time, and not at the same
time with new LUs.
* Instance locks: can be declared in ExpandNames() or DeclareLocks()
by an LU, and have the same name as the instance itself. They are
acquired as a set. Internally the locking library acquired them in
alphabetical order.
* Node locks: can be declared in ExpandNames() or DeclareLocks() by an
LU, and have the same name as the node itself. They are acquired as
a set. Internally the locking library acquired them in alphabetical
order. Given this order it's possible to safely acquire a set of
instances, and then the nodes they reside on.
The ConfigWriter (in config.py) is also protected by a SharedLock, which
is shared by functions that read the config and acquired exclusively by
functions that modify it. Since the ConfigWriter calls
rpc.call_upload_file to all nodes to distribute the config without
holding the node locks, this call must be able to execute on the nodes
in parallel with other operations (but not necessarily concurrently with
itself on the same file, as inside the ConfigWriter this is called with
the internal config lock held.
Job Queue Locking
-----------------
The job queue is designed to be thread-safe. This means that its public
functions can be called from any thread. The job queue can be called from
functions called by the queue itself (e.g. logical units), but special
attention must be paid not to create deadlocks or an invalid state.
functions can be called from any thread. The job queue can be called
from functions called by the queue itself (e.g. logical units), but
special attention must be paid not to create deadlocks or an invalid
state.
The single queue lock is used from all classes involved in the queue handling.
During development we tried to split locks, but deemed it to be too dangerous
and difficult at the time. Job queue functions acquiring the lock can be safely
called from all the rest of the code, as the lock is released before leaving
the job queue again. Unlocked functions should only be called from job queue
related classes (e.g. in jqueue.py) and the lock must be acquired beforehand.
The single queue lock is used from all classes involved in the queue
handling. During development we tried to split locks, but deemed it to
be too dangerous and difficult at the time. Job queue functions
acquiring the lock can be safely called from all the rest of the code,
as the lock is released before leaving the job queue again. Unlocked
functions should only be called from job queue related classes (e.g. in
jqueue.py) and the lock must be acquired beforehand.
In the job queue worker (``_JobQueueWorker``), the lock must be released before
calling the LU processor. Otherwise a deadlock can occur when log messages are
added to opcode results.
In the job queue worker (``_JobQueueWorker``), the lock must be released
before calling the LU processor. Otherwise a deadlock can occur when log
messages are added to opcode results.
Node Daemon Locking
-------------------
The node daemon contains a lock for the job queue. In order to avoid conflicts
and/or corruption when an eventual master daemon or another node daemon is
running, it must be held for all job queue operations
The node daemon contains a lock for the job queue. In order to avoid
conflicts and/or corruption when an eventual master daemon or another
node daemon is running, it must be held for all job queue operations
There's one special case for the node daemon running on the master node. If
grabbing the lock in exclusive fails on startup, the code assumes all checks
have been done by the process keeping the lock.
There's one special case for the node daemon running on the master node.
If grabbing the lock in exclusive fails on startup, the code assumes all
checks have been done by the process keeping the lock.
.. vim: set textwidth=72 :
......@@ -28,7 +28,8 @@ principle.
Generic parameters
------------------
A few parameter mean the same thing across all resources which implement it.
A few parameter mean the same thing across all resources which implement
it.
``bulk``
++++++++
......@@ -307,8 +308,8 @@ It supports the following commands: ``GET``.
Requests detailed information about the instance. An optional parameter,
``static`` (bool), can be set to return only static information from the
configuration without querying the instance's nodes. The result will be a job
id.
configuration without querying the instance's nodes. The result will be
a job id.
``/2/instances/[instance_name]/reboot``
......@@ -385,9 +386,9 @@ It supports the following commands: ``POST``.
~~~~~~~~
Takes the parameters ``mode`` (one of ``replace_on_primary``,
``replace_on_secondary``, ``replace_new_secondary`` or ``replace_auto``),
``disks`` (comma separated list of disk indexes), ``remote_node`` and
``iallocator``.
``replace_on_secondary``, ``replace_new_secondary`` or
``replace_auto``), ``disks`` (comma separated list of disk indexes),
``remote_node`` and ``iallocator``.
``/2/instances/[instance_name]/tags``
......@@ -586,8 +587,8 @@ Example::
Change the node role.
The request is a string which should be PUT to this URI. The result will be a
job id.
The request is a string which should be PUT to this URI. The result will
be a job id.
It supports the ``force`` argument.
......@@ -601,8 +602,8 @@ Manages storage units on the node.
Requests a list of storage units on a node. Requires the parameters
``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and
``output_fields``. The result will be a job id, using which the result can be
retrieved.
``output_fields``. The result will be a job id, using which the result
can be retrieved.
``/2/nodes/[node_name]/storage/modify``
+++++++++++++++++++++++++++++++++++++++
......@@ -612,10 +613,11 @@ Modifies storage units on the node.
``PUT``
~~~~~~~
Modifies parameters of storage units on the node. Requires the parameters
``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and ``name`` (name
of the storage unit). Parameters can be passed additionally. Currently only
``allocatable`` (bool) is supported. The result will be a job id.
Modifies parameters of storage units on the node. Requires the
parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
and ``name`` (name of the storage unit). Parameters can be passed
additionally. Currently only ``allocatable`` (bool) is supported. The
result will be a job id.
``/2/nodes/[node_name]/storage/repair``
+++++++++++++++++++++++++++++++++++++++
......@@ -625,9 +627,9 @@ Repairs a storage unit on the node.
``PUT``
~~~~~~~
Repairs a storage unit on the node. Requires the parameters ``storage_type``
(currently only ``lvm-vg`` can be repaired) and ``name`` (name of the storage
unit). The result will be a job id.
Repairs a storage unit on the node. Requires the parameters
``storage_type`` (currently only ``lvm-vg`` can be repaired) and
``name`` (name of the storage unit). The result will be a job id.
``/2/nodes/[node_name]/tags``
+++++++++++++++++++++++++++++
......
......@@ -12,8 +12,8 @@ you need to be root to run the cluster commands.
Host issues
-----------
For a host on which the Ganeti software has been installed, but not joined to a
cluster, there are no changes to the system.
For a host on which the Ganeti software has been installed, but not
joined to a cluster, there are no changes to the system.
For a host that has been joined to the cluster, there are very important
changes:
......@@ -65,11 +65,11 @@ nodes:
The SSH traffic is protected (after the initial login to a new node) by
the cluster-wide shared SSH key.
RPC communication between the master and nodes is protected using SSL/TLS
encryption. Both the client and the server must have the cluster-wide
shared SSL/TLS certificate and verify it when establishing the connection
by comparing fingerprints. We decided not to use a CA to simplify the
key handling.
RPC communication between the master and nodes is protected using
SSL/TLS encryption. Both the client and the server must have the
cluster-wide shared SSL/TLS certificate and verify it when establishing
the connection by comparing fingerprints. We decided not to use a CA to
simplify the key handling.
The DRBD traffic is not protected by encryption, as DRBD does not
support this. It's therefore recommended to implement host-level
......@@ -83,20 +83,20 @@ nodes when configuring the device.
Master daemon
-------------
The command-line tools to master daemon communication is done via an UNIX
socket, whose permissions are reset to ``0600`` after listening but before
serving requests. This permission-based protection is documented and works on
Linux, but is not-portable; however, Ganeti doesn't work on non-Linux system at
the moment.
The command-line tools to master daemon communication is done via an
UNIX socket, whose permissions are reset to ``0600`` after listening but
before serving requests. This permission-based protection is documented
and works on Linux, but is not-portable; however, Ganeti doesn't work on
non-Linux system at the moment.
Remote API
----------
Starting with Ganeti 2.0, Remote API traffic is encrypted using SSL/TLS by
default. It supports Basic authentication as per RFC2617.
Starting with Ganeti 2.0, Remote API traffic is encrypted using SSL/TLS
by default. It supports Basic authentication as per RFC2617.
Paths for certificate, private key and CA files required for SSL/TLS will
be set at source configure time. Symlinks or command line parameters may
be used to use different files.
Paths for certificate, private key and CA files required for SSL/TLS
will be set at source configure time. Symlinks or command line
parameters may be used to use different files.
.. vim: set textwidth=72 :
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment