Quote filename in gnt-instance.8

[ganeti-local] / man / ganeti.rst

diff --git a/man/ganeti.rst b/man/ganeti.rst
index 97d1832..52721d4 100644 (file)
--- a/man/ganeti.rst
+++ b/man/ganeti.rst
@@ -158,8 +158,11 @@ error
     stopped during the job execution.
 
 
-Common options
---------------
+Common command line features
+----------------------------
+
+Options
+~~~~~~~
 
 Many Ganeti commands provide the following options. The
 availability for a certain command can be checked by calling the
@@ -172,3 +175,57 @@ would succeed.
 
 The option ``--priority`` sets the priority for opcodes submitted
 by the command.
+
+Field formatting
+----------------
+
+Multiple ganeti commands use the same framework for tabular listing of
+resources (e.g. **gnt-instance list**, **gnt-node list**, **gnt-group
+list**, **gnt-debug locks**, etc.). For these commands, special states
+are denoted via a special symbol (in terse mode) or a string (in
+verbose mode):
+
+*, (offline)
+    The node in question is marked offline, and thus it cannot be
+    queried for data. This result is persistent until the node is
+    de-offlined.
+
+?, (nodata)
+    Ganeti expected to receive an answer from this entity, but the
+    cluster RPC call failed and/or we didn't receive a valid answer;
+    usually more information is available in the node daemon log (if
+    the node is alive) or the master daemon log. This result is
+    transient, and re-running command might return a different result.
+
+-, (unavail)
+    The respective field doesn't make sense for this entity;
+    e.g. querying a down instance for its current memory 'live' usage,
+    or querying a non-vm_capable node for disk/memory data. This
+    result is persistent, and until the entity state is changed via
+    ganeti commands, the result won't change.
+
+??, (unknown)
+    This field is not known (note that this is different from entity
+    being unknown). Either you have mis-typed the field name, or you
+    are using a field that the running Ganeti master daemon doesn't
+    know. This result is persistent, re-running the command won't
+    change it.
+
+Key-value parameters
+~~~~~~~~~~~~~~~~~~~~
+
+Multiple options take parameters that are of the form
+``key=value,key=value,...`` or ``category:key=value,...``. Examples
+are the hypervisor parameters, backend parameters, etc. For these,
+it's possible to use values that contain commas by escaping with via a
+backslash (which needs two if not single-quoted, due to shell
+behaviour)::
+
+  # gnt-instance modify -H kernel_path=an\\,example instance1
+  # gnt-instance modify -H kernel_path='an\,example' instance1
+
+Common daemon functionality
+---------------------------
+
+All Ganeti daemons re-open the log file(s) when sent a SIGHUP signal.
+**logrotate**(8) can be used to rotate Ganeti's log files.