path: root/doc/website-v1/man-1.2.adoc

:man source:   crm
:man version:  1.2.6
:man manual:   crmsh documentation

crm(8)
======

NOTE: This is the documentation for stable release 1.2.6 of `crmsh`.


NAME
----
crm - Pacemaker command line interface for configuration and management


SYNOPSIS
--------
*crm* [-D output_type] [-f file] [-c cib] [-H hist_src] [-hFRDw] [--version] [args]


[[topics_Description,Program description]]
DESCRIPTION
-----------
Pacemaker configuration is stored in a CIB file (Cluster
Information Base). The CIB is a set of instructions coded in XML.
Editing the CIB is a challenge, not only due to its complexity
and a wide variety of options, but also because XML is more
computer than user friendly. The `crm` shell alleviates this
issue significantly by introducing small and simple configuration
language. The CIB is translated into this language on the fly.

`crm` is also a management tool. For management tasks it relies
almost exclusively on other command line tools, such as
`crm_resource(8)` or `crm_attribute(8)`.  Use of these programs
is, however, plagued by the notorious weakness common to all UNIX
tools: a multitude of options, necessary for operation and yet
very hard to remember. `crm` tries to present a consistent
interface to the user and to hide the arcane detail.

It may be used either as an interactive shell or for single
commands directly on the shell's command line. It is also
possible to feed it a set of commands from standard input or a
file, thus turning it into a scripting tool. Templates with ready
made configurations may help newbies learn about the cluster
configuration or facilitate testing procedures.

The `crm` shell is line oriented: every command must start and
finish on the same line. It is possible to use a continuation
character (`\`) to write one command in two or more lines. The
continuation character is commonly used when displaying
configurations.

OPTIONS
-------
*-f, --file*='FILE'::
	Load commands from the given file. If the file is `-` then
    use terminal `stdin`.

*-c, --cib*='CIB'::
    Start the session with the given shadow CIB file.
    Equivalent to `cib use`.

*-D, --display=*'OUTPUT_TYPE'::
	Choose one of the output options: `plain`, `color`, or
    `uppercase`. The default is `color` if the terminal emulation
    supports colors. Otherwise, `plain` is used.

*-F, --force*::
    Make `crm` proceed with doing changes even though it would
    normally ask user to confirm some of them. Mostly useful in
    scripts.

*-w, --wait*::
    Make `crm` wait for the cluster transition to finish (for the
    changes to take effect) after each processed line.

*-H, --history*='DIR|FILE'::
    The `history` commands can examine either live cluster
    (default) or a report generated by `hb_report`. Use this
    option to specify a directory or file containing the report.

*-h, --help*::
    Print help page.

*--version*::
    Print crmsh version and build information (Mercurial Hg
    changeset hash).

*-R, --regression-tests*::
    Run in the regression test mode. Used mainly by the
    regression testing suite.

*-d, --debug*::
    Print some debug information. Used by developers. [Not yet
    refined enough to print useful information for other users.]

[[topics_Introduction,Introduction to the user interface]]
== Introduction to the user interface

Arguably the most important aspect of `crm` is the user
interface. We begin with an informal introduction so that the
reader may get acquainted with it and get a general feeling of
the tool. It is probably best just to give some examples:

1. Command line (one-shot) use:

        # crm resource stop www_app

2. Interactive use:

        # crm
        crm(live)# resource
        crm(live)resource# unmanage tetris_1
        crm(live)resource# end
        crm(live)# node standby node4

3. Cluster configuration:

    # crm configure<<EOF
      #
      # resources
      #
      primitive disk0 iscsi \
        params portal=192.168.2.108:3260 target=iqn.2008-07.com.suse:disk0
      primitive fs0 Filesystem \
        params device=/dev/disk/by-label/disk0 directory=/disk0 fstype=ext3
      primitive internal_ip IPaddr params ip=192.168.1.101
      primitive apache apache \
        params configfile=/disk0/etc/apache2/site0.conf
      primitive apcfence stonith:apcsmart \
        params ttydev=/dev/ttyS0 hostlist="node1 node2" \
        op start timeout=60s
      primitive pingd pingd \
        params name=pingd dampen=5s multiplier=100 host_list="r1 r2"
      #
      # monitor apache and the UPS
      #
      monitor apache 60s:30s
      monitor apcfence 120m:60s
      #
      # cluster layout
      #
      group internal_www \
        disk0 fs0 internal_ip apache
      clone fence apcfence \
        meta globally-unique=false clone-max=2 clone-node-max=1
      clone conn pingd \
        meta globally-unique=false clone-max=2 clone-node-max=1
      location node_pref internal_www \
        rule 50: #uname eq node1 \
        rule pingd: defined pingd
      #
      # cluster properties
      #
      property stonith-enabled=true
      commit
    EOF

If you've ever done a CRM style configuration, you should be able
to understand the above examples without much difficulties.  The
shell should provide a means to manage the cluster efficiently or
put together a configuration in a concise manner.

The `(live)` string in the prompt signifies that the current CIB
in use is the cluster live configuration. It is also possible to
work with the so-called shadow CIBs, i.e. configurations which
are stored in files and aren't active, but may be applied at any
time to the cluster.

Since the CIB is hierarchical such is the interface too. There
are several levels and entering each of them enables the user to
use a certain set of commands.

[[topics_Shadows,Shadow CIB usage]]
== Shadow CIB usage

Shadow CIB is a normal cluster configuration stored in a file.
They may be manipulated in the same way like the _live_ CIB, but
these changes have no effect on the cluster resources. The
administrator may choose to apply any of them to the cluster,
thus replacing the running configuration with the one which is in
the shadow CIB. The `crm` prompt always contains the name of the
configuration which is currently in use or string _live_ if we
are using the current cluster configuration.

At the configure level no changes take place before the `commit`
command. Sometimes though, the administrator may start working
with the running configuration, but change mind and instead of
committing the changes to the cluster save them to a shadow CIB.
This short `configure` session excerpt shows how:
...............
    crm(live)configure# cib new test-2
    INFO: test-2 shadow CIB created
    crm(test-2)configure# commit
...............

[[topics_Templates,Configuration templates]]
== Configuration templates

Configuration templates are ready made configurations created by
cluster experts. They are designed in such a way so that users
may generate valid cluster configurations with minimum effort.
If you are new to Pacemaker, templates may be the best way to
start.

We will show here how to create a simple yet functional Apache
configuration:
...............
    # crm configure
    crm(live)configure# template
    crm(live)configure template# list templates
    apache       filesystem   virtual-ip   
    crm(live)configure template# new web <TAB><TAB>
    apache       filesystem   virtual-ip   
    crm(live)configure template# new web apache
    INFO: pulling in template apache
    INFO: pulling in template virtual-ip
    crm(live)configure template# list
    web2-d       web2         vip2         web3         vip          web
...............

We enter the `template` level from `configure`. Use the `list`
command to show templates available on the system. The `new`
command creates a configuration from the `apache` template. You
can use tab completion to pick templates. Note that the apache
template depends on a virtual IP address which is automatically
pulled along. The `list` command shows the just created `web`
configuration, among other configurations (I hope that you,
unlike me, will use more sensible and descriptive names).

The `show` command, which displays the resulting configuration,
may be used to get an idea about the minimum required changes
which have to be done. All `ERROR` messages show the line numbers
in which the respective parameters are to be defined:
...............
    crm(live)configure template# show
    ERROR: 23: required parameter ip not set
    ERROR: 61: required parameter id not set
    ERROR: 65: required parameter configfile not set
    crm(live)configure template# edit
...............

The `edit` command invokes the preferred text editor with the
`web` configuration. At the top of the file, the user is advised
how to make changes. A good template should require from the user
to specify only parameters. For example, the `web` configuration
we created above has the following required and optional
parameters (all parameter lines start with `%%`):
...............
    $ grep -n ^%% ~/.crmconf/web
    23:%% ip 
    31:%% netmask 
    35:%% lvs_support 
    61:%% id 
    65:%% configfile 
    71:%% options 
    76:%% envfiles 
...............

These lines are the only ones that should be modified. Simply
append the parameter value at the end of the line. For instance,
after editing this template, the result could look like this (we
used tabs instead of spaces to make the values stand out):
...............
    $ grep -n ^%% ~/.crmconf/web
    23:%% ip                192.168.1.101
    31:%% netmask 
    35:%% lvs_support 
    61:%% id                websvc
    65:%% configfile        /etc/apache2/httpd.conf
    71:%% options 
    76:%% envfiles 
...............

As you can see, the parameter line format is very simple:
...............
    %% <name> <value>
...............

After editing the file, use `show` again to display the
configuration:
...............
    crm(live)configure template# show
    primitive virtual-ip ocf:heartbeat:IPaddr \
            params ip="192.168.1.101"
    primitive apache ocf:heartbeat:apache \
            params configfile="/etc/apache2/httpd.conf"
    monitor apache 120s:60s
    group websvc \
            apache virtual-ip
...............

The target resource of the apache template is a group which we
named `websvc` in this sample session.

This configuration looks exactly as you could type it at the
`configure` level. The point of templates is to save you some
typing. It is important, however, to understand the configuration
produced.

Finally, the configuration may be applied to the current
crm configuration (note how the configuration changed slightly,
though it is still equivalent, after being digested at the
`configure` level):
...............
    crm(live)configure template# apply 
    crm(live)configure template# cd ..
    crm(live)configure# show
    node xen-b
    node xen-c
    primitive apache ocf:heartbeat:apache \
        params configfile="/etc/apache2/httpd.conf" \
        op monitor interval="120s" timeout="60s"
    primitive virtual-ip ocf:heartbeat:IPaddr \
        params ip="192.168.1.101"
    group websvc apache virtual-ip
...............

Note that this still does not commit the configuration to the CIB
which is used in the shell, either the running one (`live`) or
some shadow CIB. For that you still need to execute the `commit`
command.

To complete our example, we should also define the preferred node
to run the service:
...............
    crm(live)configure# location websvc-pref websvc 100: xen-b
...............

If you are not happy with some resource names which are provided
by default, you can rename them now:
...............
    crm(live)configure# rename virtual-ip intranet-ip
    crm(live)configure# show
    node xen-b
    node xen-c
    primitive apache ocf:heartbeat:apache \
            params configfile="/etc/apache2/httpd.conf" \
            op monitor interval="120s" timeout="60s"
    primitive intranet-ip ocf:heartbeat:IPaddr \
            params ip="192.168.1.101"
    group websvc apache intranet-ip
    location websvc-pref websvc 100: xen-b
...............

To summarize, working with templates typically consists of the
following steps:

- `new`: create a new configuration from templates
- `edit`: define parameters, at least the required ones
- `show`: see if the configuration is valid
- `apply`: apply the configuration to the `configure` level

[[topics_Testing,Resource testing]]
== Resource testing

The amount of detail in a cluster makes all configurations prone
to errors. By far the largest number of issues in a cluster is
due to bad resource configuration. The shell can help quickly
diagnose such problems. And considerably reduce your keyboard
wear.

Let's say that we entered the following configuration:
...............
    node xen-b
    node xen-c
    node xen-d
    primitive fencer stonith:external/libvirt \
            params hypervisor_uri="qemu+tcp://10.2.13.1/system" \
                hostlist="xen-b xen-c xen-d" \
            op monitor interval="2h"
    primitive svc ocf:heartbeat:Xinetd \
            params service="systat" \
            op monitor interval="30s"
    primitive intranet-ip ocf:heartbeat:IPaddr2 \
            params ip="10.2.13.100" \
            op monitor interval="30s"
    primitive apache ocf:heartbeat:apache \
            params configfile="/etc/apache2/httpd.conf" \
            op monitor interval="120s" timeout="60s"
    group websvc apache intranet-ip
    location websvc-pref websvc 100: xen-b
...............

Before typing `commit` to submit the configuration to the cib we
can make sure that all resources are usable on all nodes:
...............
    crm(live)configure# rsctest websvc svc fencer
...............

It is important that resources being tested are not running on
any nodes. Otherwise, the `rsctest` command will refuse to do
anything. Of course, if the current configuration resides in a
CIB shadow, then a `commit` is irrelevant. The point being that
resources are not running on any node.

.Note on stopping all resources
****************************
Alternatively to not committing a configuration, it is also
possible to tell Pacemaker not to start any resources:

...............
    crm(live)configure# property stop-all-resources="yes"
...............
Almost none---resources of class stonith are still started. But
shell is not as strict when it comes to stonith resources.
****************************

Order of resources is significant insofar that a resource depends
on all resources to its left. In most configurations, it's
probably practical to test resources in several runs, based on
their dependencies.

Apart from groups, `crm` does not interpret constraints and
therefore knows nothing about resource dependencies. It also
doesn't know if a resource can run on a node at all in case of an
asymmetric cluster. It is up to the user to specify a list of
eligible nodes if a resource is not meant to run on every node.

[[topics_Completion,Tab completion]]
== Tab completion

The `crm` makes extensive use of tab completion. The completion
is both static (i.e. for `crm` commands) and dynamic. The latter
takes into account the current status of the cluster or
information from installed resource agents. Sometimes, completion
may also be used to get short help on resource parameters. Here a
few examples:
...............
    crm(live)# resource
    crm(live)resource# <TAB><TAB>
    bye           failcount     move          restart       unmigrate 
    cd            help          param         show          unmove 
    cleanup       list          promote       start         up 
    demote        manage        quit          status utilization 
    end           meta          refresh       stop          
    exit          migrate       reprobe       unmanage      
    crm(live)resource# end
    crm(live)# configure 
    crm(live)configure# primitive fence-1 <TAB><TAB>
    heartbeat:  lsb:        ocf:        stonith:    
    crm(live)configure# primitive fence-1 stonith:<TAB><TAB>
    apcmaster                external/ippower9258     fence_legacy 
    apcmastersnmp            external/kdumpcheck      ibmhmc 
    apcsmart                 external/libvirt         ipmilan 
    baytech                  external/nut             meatware 
    bladehpi                 external/rackpdu         null 
    cyclades                 external/riloe           nw_rpc100s 
    drac3                    external/sbd             rcd_serial 
    external/drac5           external/ssh             rps10 
    external/dracmc-telnet   external/ssh-bad         ssh 
    external/hmchttp         external/ssh-slow        suicide 
    external/ibmrsa          external/vmware          wti_mpc 
    external/ibmrsa-telnet   external/xen0            wti_nps 
    external/ipmi            external/xen0-ha         
    crm(live)configure# primitive fence-1 stonith:ipmilan params <TAB><TAB>
    auth=      hostname=  ipaddr=    login=     password=  port=      priv=
    crm(live)configure# primitive fence-1 stonith:ipmilan params auth=<TAB><TAB>
    auth* (string)
        The authorization type of the IPMI session ("none", "straight", "md2", or "md5")
    crm(live)configure# primitive fence-1 stonith:ipmilan params auth=
...............

[[topics_Checks,Configuration semantic checks]]
== Configuration semantic checks

Resource definitions may be checked against the meta-data
provided with the resource agents. These checks are currently
carried out:

- are required parameters set
- existence of defined parameters
- timeout values for operations

The parameter checks are obvious and need no further explanation.
Failures in these checks are treated as configuration errors.

The timeouts for operations should be at least as long as those
recommended in the meta-data. Too short timeout values are a
common mistake in cluster configurations and, even worse, they
often slip through if cluster testing was not thorough. Though
operation timeouts issues are treated as warnings, make sure that
the timeouts are usable in your environment. Note also that the
values given are just _advisory minimum_---your resources may
require longer timeouts.

User may tune the frequency of checks and the treatment of errors
by the <<cmdhelp_options_check-frequency,`check-frequency`>> and
<<cmdhelp_options_check-mode,`check-mode`>> preferences.

Note that if the `check-frequency` is set to `always` and the
`check-mode` to `strict`, errors are not tolerated and such
configuration cannot be saved.

[[topics_Security,Access Control Lists (ACL)]]
== Access Control Lists (ACL)

By default, the users from the `haclient` group have full access
to the cluster (or, more precisely, to the CIB). Access control
lists allow for finer access control to the cluster.

Access control lists consist of an ordered set of access rules.
Each rule allows read or write access or denies access
completely. Rules are typically combined to produce a specific
role. Then, users may be assigned a role.

For instance, this is a role which defines a set of rules
allowing management of a single resource:

...............
    role bigdb_admin \
        write meta:bigdb:target-role \
        write meta:bigdb:is-managed \
        write location:bigdb \
        read ref:bigdb
...............

The first two rules allow modifying the `target-role` and
`is-managed` meta attributes which effectively enables users in
this role to stop/start and manage/unmanage the resource. The
constraints write access rule allows moving the resource around.
Finally, the user is granted read access to the resource
definition.

For proper operation of all Pacemaker programs, it is advisable
to add the following role to all users:

...............
    role read_all \
        read cib
...............

For finer grained read access try with the rules listed in the
following role:

...............
    role basic_read \
        read node attribute:uname \
        read node attribute:type \
        read property \
        read status
...............

It is however possible that some Pacemaker programs (e.g.
`ptest`) may not function correctly if the whole CIB is not
readable.

Some of the ACL rules in the examples above are expanded by the
shell to XPath specifications. For instance,
`meta:bigdb:target-role` is a shortcut for
`//primitive[@id='bigdb']/meta_attributes/nvpair[@name='target-role']`.
You can see the expansion by showing XML:

...............
    crm(live) configure# show xml bigdb_admin
    ...
    <acls>
      <acl_role id="bigdb_admin">
          <write id="bigdb_admin-write"
          xpath="//primitive[@id='bigdb']/meta_attributes/nvpair[@name='target-role']"/>
...............

Many different XPath expressions can have equal meaning. For
instance, the following two are equal, but only the first one is
going to be recognized as shortcut:

...............
      //primitive[@id='bigdb']/meta_attributes/nvpair[@name='target-role']
      //resources/primitive[@id='bigdb']/meta_attributes/nvpair[@name='target-role']
...............

XPath is a powerful language, but you should try to keep your ACL
xpaths simple and the builtin shortcuts should be used whenever
possible.

[[topics_Reference,Command reference]]
== Command reference

We define a small and simple language. Most commands consist of
just a list of simple tokens. The only complex constructs are
found at the `configure` level.

The syntax is described in a somewhat informal manner: `<>`
denotes a string, `[]` means that the construct is optional, the
ellipsis (`...`) signifies that the previous construct may be
repeated, `|` means pick one of many, and the rest are literals
(strings, `:`, `=`).

=== `status`

Show cluster status. The status is displayed by `crm_mon`. Supply
additional arguments for more information or different format.
See `crm_mon(8)` for more details.

Usage:
...............
        status [<option> ...]

        option :: bynode | inactive | ops | timing | failcounts
...............

[[cmdhelp_cib,CIB shadow management]]
=== `cib` (shadow CIBs)

This level is for management of shadow CIBs. It is available both
at the top level and the `configure` level.

All the commands are implemented using `cib_shadow(8)` and the
`CIB_shadow` environment variable. The user prompt always
includes the name of the currently active shadow or the live CIB.

[[cmdhelp_cib_new,create a new shadow CIB]]
==== `new`

Create a new shadow CIB. The live cluster configuration and
status is copied to the shadow CIB. Specify `withstatus` if you
want to edit the status section of the shadow CIB (see the
<<cmdhelp_cibstatus,cibstatus section>>). Add `force` to force overwriting the
existing shadow CIB.

To start with an empty configuration that is not copied from the live
CIB, specify the `empty` keyword. (This also allows a shadow CIB to be
created in case no cluster is running.)

Usage:
...............
        new <cib> [withstatus] [force] [empty]
...............

[[cmdhelp_cib_delete,delete a shadow CIB]]
==== `delete`

Delete an existing shadow CIB.

Usage:
...............
        delete <cib>
...............

[[cmdhelp_cib_reset,copy live cib to a shadow CIB]]
==== `reset`

Copy the current cluster configuration into the shadow CIB.

Usage:
...............
        reset <cib>
...............

[[cmdhelp_cib_commit,copy a shadow CIB to the cluster]]
==== `commit`

Apply a shadow CIB to the cluster.

Usage:
...............
        commit <cib>
...............

[[cmdhelp_cib_use,change working CIB]]
==== `use`

Choose a CIB source. If you want to edit the status from the
shadow CIB specify `withstatus` (see <<cmdhelp_cibstatus,`cibstatus`>>).
Leave out the CIB name to switch to the running CIB.

Usage:
...............
        use [<cib>] [withstatus]
...............

[[cmdhelp_cib_diff,diff between the shadow CIB and the live CIB]]
==== `diff`

Print differences between the current cluster configuration and
the active shadow CIB.

Usage:
...............
        diff
...............

[[cmdhelp_cib_list,list all shadow CIBs]]
==== `list`

List existing shadow CIBs.

Usage:
...............
        list
...............

[[cmdhelp_cib_import,import a CIB or PE input file to a shadow]]
==== `import`

At times it may be useful to create a shadow file from the
existing CIB. The CIB may be specified as file or as a PE input
file number. The shell will look up files in the local directory
first and then in the PE directory (typically `/var/lib/pengine`).
Once the CIB file is found, it is copied to a shadow and this
shadow is immediately available for use at both `configure` and
`cibstatus` levels.

If the shadow name is omitted then the target shadow is named
after the input CIB file.

Note that there are often more than one PE input file, so you may
need to specify the full name.

Usage:
...............
        import {<file>|<number>} [<shadow>]
...............
Examples:
...............
        import pe-warn-2222
        import 2289 issue2
...............

[[cmdhelp_cib_cibstatus,CIB status management and editing]]
==== `cibstatus`

Enter edit and manage the CIB status section level. See the
<<cmdhelp_cibstatus,CIB status management section>>.

[[cmdhelp_ra,Resource Agents (RA) lists and documentation]]
=== `ra`

This level contains commands which show various information about
the installed resource agents. It is available both at the top
level and at the `configure` level.

[[cmdhelp_ra_classes,list classes and providers]]
==== `classes`

Print all resource agents' classes and, where appropriate, a list
of available providers.

Usage:
...............
        classes
...............

[[cmdhelp_ra_list,list RA for a class (and provider)]]
==== `list`

List available resource agents for the given class. If the class
is `ocf`, supply a provider to get agents which are available
only from that provider.

Usage:
...............
        list <class> [<provider>]
...............
Example:
...............
        list ocf pacemaker
...............

[[cmdhelp_ra_meta,show meta data for a RA]]
==== `meta` (`info`)

Show the meta-data of a resource agent type. This is where users
can find information on how to use a resource agent. It is also
possible to get information from some programs: `pengine`,
`crmd`, `cib`, and `stonithd`. Just specify the program name
instead of an RA.

Usage:
...............
        info [<class>:[<provider>:]]<type>
        info <type> <class> [<provider>] (obsolete)
...............
Example:
...............
        info apache
        info ocf:pacemaker:Dummy
        info stonith:ipmilan
        info pengine
...............

[[cmdhelp_ra_providers,show providers for a RA and a class]]
==== `providers`

List providers for a resource agent type. The class parameter
defaults to `ocf`.

Usage:
...............
        providers <type> [<class>]
...............
Example:
...............
        providers apache
...............

[[cmdhelp_resource,Resource management]]
=== `resource`

At this level resources may be managed.

All (or almost all) commands are implemented with the CRM tools
such as `crm_resource(8)`.

[[cmdhelp_resource_status,show status of resources]]
==== `status` (`show`, `list`)

Print resource status. If the resource parameter is left out
status of all resources is printed.

Usage:
...............
        status [<rsc>]
...............

[[cmdhelp_resource_start,start a resource]]
==== `start`

Start a resource by setting the `target-role` attribute. If there
are multiple meta attributes sets, the attribute is set in all of
them. If the resource is a clone, all `target-role` attributes
are removed from the children resources.

For details on group management see <<cmdhelp_options_manage-children,`options manage-children`>>.

Usage:
...............
        start <rsc>
...............

[[cmdhelp_resource_stop,stop a resource]]
==== `stop`

Stop a resource using the `target-role` attribute. If there
are multiple meta attributes sets, the attribute is set in all of
them. If the resource is a clone, all `target-role` attributes
are removed from the children resources.

For details on group management see <<cmdhelp_options_manage-children,`options manage-children`>>.

Usage:
...............
        stop <rsc>
...............

[[cmdhelp_resource_restart,restart a resource]]
==== `restart`

Restart a resource. This is essentially a shortcut for resource
stop followed by a start. The shell is first going to wait for
the stop to finish, that is for all resources to really stop, and
only then to order the start action. Due to this command
entailing a whole set of operations, informational messages are
printed to let the user see some progress.

For details on group management see <<cmdhelp_options_manage-children,`options manage-children`>>.

Usage:
...............
        restart <rsc>
...............
Example:
...............
        # crm resource restart g_webserver
        INFO: ordering g_webserver to stop
        waiting for stop to finish .... done
        INFO: ordering g_webserver to start
        # 
...............

[[cmdhelp_resource_promote,promote a master-slave resource]]
==== `promote`

Promote a master-slave resource using the `target-role`
attribute.

Usage:
...............
        promote <rsc>
...............

[[cmdhelp_resource_demote,demote a master-slave resource]]
==== `demote`

Demote a master-slave resource using the `target-role`
attribute.

Usage:
...............
        demote <rsc>
...............

[[cmdhelp_resource_manage,put a resource into managed mode]]
==== `manage`

Manage a resource using the `is-managed` attribute. If there
are multiple meta attributes sets, the attribute is set in all of
them. If the resource is a clone, all `is-managed` attributes are
removed from the children resources.

For details on group management see <<cmdhelp_options_manage-children,`options manage-children`>>.

Usage:
...............
        manage <rsc>
...............

[[cmdhelp_resource_unmanage,put a resource into unmanaged mode]]
==== `unmanage`

Unmanage a resource using the `is-managed` attribute. If there
are multiple meta attributes sets, the attribute is set in all of
them. If the resource is a clone, all `is-managed` attributes are
removed from the children resources.

For details on group management see <<cmdhelp_options_manage-children,`options manage-children`>>.

Usage:
...............
        unmanage <rsc>
...............

[[cmdhelp_resource_migrate,migrate a resource to another node]]
==== `migrate` (`move`)

Migrate a resource to a different node. If node is left out, the
resource is migrated by creating a constraint which prevents it from
running on the current node. Additionally, you may specify a
lifetime for the constraint---once it expires, the location
constraint will no longer be active.

Usage:
...............
        migrate <rsc> [<node>] [<lifetime>] [force]
...............

[[cmdhelp_resource_unmigrate,unmigrate a resource to another node]]
==== `unmigrate` (`unmove`)

Remove the constraint generated by the previous migrate command.

Usage:
...............
        unmigrate <rsc>
...............

[[cmdhelp_resource_param,manage a parameter of a resource]]
==== `param`

Show/edit/delete a parameter of a resource.

Usage:
...............
        param <rsc> set <param> <value>
        param <rsc> delete <param>
        param <rsc> show <param>
...............
Example:
...............
        param ip_0 show ip
...............

[[cmdhelp_resource_secret,manage sensitive parameters]]
==== `secret`

Sensitive parameters can be kept in local files rather than CIB
in order to prevent accidental data exposure. Use the `secret`
command to manage such parameters. `stash` and `unstash` move the
value from the CIB and back to the CIB respectively. The `set`
subcommand sets the parameter to the provided value. `delete`
removes the parameter completely. `show` displays the value of
the parameter from the local file. Use `check` to verify if the
local file content is valid.

Usage:
...............
        secret <rsc> set <param> <value>
        secret <rsc> stash <param>
        secret <rsc> unstash <param>
        secret <rsc> delete <param>
        secret <rsc> show <param>
        secret <rsc> check <param>
...............
Example:
...............
        secret fence_1 show password
        secret fence_1 stash password
        secret fence_1 set password secret_value
...............

[[cmdhelp_resource_meta,manage a meta attribute]]
==== `meta`

Show/edit/delete a meta attribute of a resource. Currently, all
meta attributes of a resource may be managed with other commands
such as `resource stop`.

Usage:
...............
        meta <rsc> set <attr> <value>
        meta <rsc> delete <attr>
        meta <rsc> show <attr>
...............
Example:
...............
        meta ip_0 set target-role stopped
...............

[[cmdhelp_resource_utilization,manage a utilization attribute]]
==== `utilization`

Show/edit/delete a utilization attribute of a resource. These
attributes describe hardware requirements. By setting the
`placement-strategy` cluster property appropriately, it is
possible then to distribute resources based on resource
requirements and node size. See also <<cmdhelp_node_utilization,node utilization attributes>>.

Usage:
...............
        utilization <rsc> set <attr> <value>
        utilization <rsc> delete <attr>
        utilization <rsc> show <attr>
...............
Example:
...............
        utilization xen1 set memory 4096
...............

[[cmdhelp_resource_failcount,manage failcounts]]
==== `failcount`

Show/edit/delete the failcount of a resource.

Usage:
...............
        failcount <rsc> set <node> <value>
        failcount <rsc> delete <node>
        failcount <rsc> show <node>
...............
Example:
...............
        failcount fs_0 delete node2
...............

[[cmdhelp_resource_cleanup,cleanup resource status]]
==== `cleanup`

Cleanup resource status. Typically done after the resource has
temporarily failed. If a node is omitted, cleanup on all nodes.
If there are many nodes, the command may take a while.

Usage:
...............
        cleanup <rsc> [<node>]
...............

[[cmdhelp_resource_refresh,refresh CIB from the LRM status]]
==== `refresh`

Refresh CIB from the LRM status.

Usage:
...............
        refresh [<node>]
...............

[[cmdhelp_resource_reprobe,probe for resources not started by the CRM]]
==== `reprobe`

Probe for resources not started by the CRM.

Usage:
...............
        reprobe [<node>]
...............

[[cmdhelp_resource_trace,start RA tracing]]
==== `trace`

Start tracing RA for the given operation. The trace files are
stored in `$HA_VARLIB/trace_ra`. If the operation to be traced is
monitor, note that the number of trace files can grow very
quickly.

Usage:
...............
        trace <rsc> <op> [<interval>]
...............
Example:
...............
        trace fs start
...............

[[cmdhelp_resource_untrace,stop RA tracing]]
==== `untrace`

Stop tracing RA for the given operation.

Usage:
...............
        untrace <rsc> <op> [<interval>]
...............
Example:
...............
        untrace fs start
...............

[[cmdhelp_node,Nodes management]]
=== `node`

Node management and status commands.

[[cmdhelp_node_status,show nodes' status as XML]]
==== `status`

Show nodes' status as XML. If the node parameter is omitted then
all nodes are shown.

Usage:
...............
        status [<node>]
...............

[[cmdhelp_node_show,show node]]
==== `show`

Show a node definition. If the node parameter is omitted then all
nodes are shown.

Usage:
...............
        show [<node>]
...............

[[cmdhelp_node_standby,put node into standby]]
==== `standby`

Set a node to standby status. The node parameter defaults to the
node where the command is run. Additionally, you may specify a
lifetime for the standby---if set to `reboot`, the node will be
back online once it reboots. `forever` will keep the node in
standby after reboot.

Usage:
...............
        standby [<node>] [<lifetime>]

        lifetime :: reboot | forever
...............

[[cmdhelp_node_online,set node online]]
==== `online`

Set a node to online status. The node parameter
defaults to the node where the command is run.

Usage:
...............
        online [<node>]
...............

[[cmdhelp_node_maintenance,put node into maintenance mode]]
==== `maintenance`

Set the node status to maintenance. This is equivalent to the
cluster-wide `maintenance-mode` property but puts just one node
into the maintenance mode. The node parameter defaults to the
node where the command is run.

Usage:
...............
        maintenance [<node>]
...............

[[cmdhelp_node_ready,put node into ready mode]]
==== `ready`

Set the node's maintenance status to `off`. The node should be
now again fully operational and capable of running resource
operations.

Usage:
...............
        ready [<node>]
...............

[[cmdhelp_node_fence,fence node]]
==== `fence`

Make CRM fence a node. This functionality depends on stonith
resources capable of fencing the specified node. No such stonith
resources, no fencing will happen.

Usage:
...............
        fence <node>
...............

[[cmdhelp_node_clearstate,Clear node state]]
==== `clearnodestate`

Resets and clears the state of the specified node. This node is
afterwards assumed clean and offline. This command can be used to
manually confirm that a node has been fenced (e.g., powered off).

Be careful! This can cause data corruption if you confirm that a node is
down that is, in fact, not cleanly down - the cluster will proceed as if
the fence had succeeded, possibly starting resources multiple times.

Usage:
...............
        clearstate <node>
...............

[[cmdhelp_node_delete,delete node]]
==== `delete`

Delete a node. This command will remove the node from the CIB
and, in case the cluster stack is running, use the appropriate
program (`crm_node` or `hb_delnode`) to remove the node from the
membership.

If the node is still listed as active and a member of our
partition we refuse to remove it. With the global force option
(`-F`) we will try to delete the node anyway.

Usage:
...............
        delete <node>
...............

[[cmdhelp_node_attribute,manage attributes]]
==== `attribute`

Edit node attributes. This kind of attribute should refer to
relatively static properties, such as memory size.

Usage:
...............
        attribute <node> set <attr> <value>
        attribute <node> delete <attr>
        attribute <node> show <attr>
...............
Example:
...............
        attribute node_1 set memory_size 4096
...............

[[cmdhelp_node_utilization,manage utilization attributes]]
==== `utilization`

Edit node utilization attributes. These attributes describe
hardware characteristics as integer numbers such as memory size
or the number of CPUs. By setting the `placement-strategy`
cluster property appropriately, it is possible then to distribute
resources based on resource requirements and node size. See also
<<cmdhelp_resource_utilization,resource utilization attributes>>.

Usage:
...............
        utilization <node> set <attr> <value>
        utilization <node> delete <attr>
        utilization <node> show <attr>
...............
Examples:
...............
        utilization node_1 set memory 16384
        utilization node_1 show cpu
...............

[[cmdhelp_node_status-attr,manage status attributes]]
==== `status-attr`

Edit node attributes which are in the CIB status section, i.e.
attributes which hold properties of a more volatile nature. One
typical example is attribute generated by the `pingd` utility.

Usage:
...............
        status-attr <node> set <attr> <value>
        status-attr <node> delete <attr>
        status-attr <node> show <attr>
...............
Example:
...............
        status-attr node_1 show pingd
...............

[[cmdhelp_site,site support]]
=== `site`

A cluster may consist of two or more subclusters in different and
distant locations. This set of commands supports such setups.

[[cmdhelp_site_ticket,manage site tickets]]
==== `ticket`

Tickets are cluster-wide attributes. They can be managed at the
site where this command is executed.

It is then possible to constrain resources depending on the
ticket availability (see the <<cmdhelp_configure_rsc_ticket,`rsc_ticket`>> command
for more details).

Usage:
...............
        ticket {grant|revoke|standby|activate|show|time|delete} <ticket>
...............
Example:
...............
        ticket grant ticket1
...............

[[cmdhelp_options,user preferences]]
=== `options`

The user may set various options for the crm shell itself.

[[cmdhelp_options_skill-level,set skill level]]
==== `skill-level`

Based on the skill-level setting, the user is allowed to use only
a subset of commands. There are three levels: operator,
administrator, and expert. The operator level allows only
commands at the `resource` and `node` levels, but not editing
or deleting resources. The administrator may do that and may also
configure the cluster at the `configure` level and manage the
shadow CIBs. The expert may do all.

Usage:
...............
        skill-level <level>
        
        level :: operator | administrator | expert
...............

.Note on security
****************************
The `skill-level` option is advisory only. There is nothing
stopping any users change their skill level (see
<<topics_Security,Access Control Lists (ACL)>> on how to enforce
access control).
****************************

[[cmdhelp_options_user,set the cluster user]]
==== `user`

Sufficient privileges are necessary in order to manage a
cluster: programs such as `crm_verify` or `crm_resource` and,
ultimately, `cibadmin` have to be run either as `root` or as the
CRM owner user (typically `hacluster`). You don't have to worry
about that if you run `crm` as `root`. A more secure way is to
run the program with your usual privileges, set this option to
the appropriate user (such as `hacluster`), and setup the
`sudoers` file.

Usage:
...............
        user system-user
...............
Example:
...............
        user hacluster
...............

[[cmdhelp_options_editor,set preferred editor program]]
==== `editor`

The `edit` command invokes an editor. Use this to specify your
preferred editor program. If not set, it will default to either
the value of the `EDITOR` environment variable or to one of the
standard UNIX editors (`vi`,`emacs`,`nano`).

Usage:
...............
        editor program
...............
Example:
...............
        editor vim
...............

[[cmdhelp_options_pager,set preferred pager program]]
==== `pager`

The `view` command displays text through a pager. Use this to
specify your preferred pager program. If not set, it will default
to either the value of the `PAGER` environment variable or to one
of the standard UNIX system pagers (`less`,`more`,`pg`).

[[cmdhelp_options_sort-elements,sort CIB elements]]
==== `sort-elements`

`crm` by default sorts CIB elements. If you want them appear in
the order they were created, set this option to `no`.

Usage:
...............
        sort-elements {yes|no}
...............
Example:
...............
        sort-elements no
...............

[[cmdhelp_options_wait,synchronous operation]]
==== `wait`

In normal operation, `crm` runs a command and gets back
immediately to process other commands or get input from the user.
With this option set to `yes` it will wait for the started
transition to finish. In interactive mode dots are printed to
indicate progress.

Usage:
...............
        wait {yes|no}
...............
Example:
...............
        wait yes
...............

[[cmdhelp_options_output,set output type]]
==== `output`

`crm` can adorn configurations in two ways: in color (similar to
for instance the `ls --color` command) and by showing keywords in
upper case. Possible values are `plain`, `color`, and
'uppercase'. It is possible to combine the latter two in order to
get an upper case xmass tree. Just set this option to
`color,uppercase`.

[[cmdhelp_options_colorscheme,set colors for output]]
==== `colorscheme`

With `output` set to `color`, a comma separated list of colors
from this option are used to emphasize:

- keywords
- object ids
- attribute names
- attribute values
- scores
- resource references

`crm` can show colors only if there is curses support for python
installed (usually provided by the `python-curses` package). The
colors are whatever is available in your terminal. Use `normal`
if you want to keep the default foreground color.

This user preference defaults to
`yellow,normal,cyan,red,green,magenta` which is good for
terminals with dark background. You may want to change the color
scheme and save it in the preferences file for other color
setups.

Example:
...............
    colorscheme yellow,normal,blue,red,green,magenta
...............

[[cmdhelp_options_check-frequency,when to perform semantic check]]
==== `check-frequency`

Semantic check of the CIB or elements modified or created may be
done on every configuration change (`always`), when verifying
(`on-verify`) or `never`. It is by default set to `always`.
Experts may want to change the setting to `on-verify`.

The checks require that resource agents are present. If they are
not installed at the configuration time set this preference to
`never`.

See <<topics_Checks,Configuration semantic checks>> for more details.

[[cmdhelp_options_check-mode,how to treat semantic errors]]
==== `check-mode`

Semantic check of the CIB or elements modified or created may be
done in the `strict` mode or in the `relaxed` mode. In the former
certain problems are treated as configuration errors. In the
`relaxed` mode all are treated as warnings. The default is `strict`.

See <<topics_Checks,Configuration semantic checks>> for more details.

[[cmdhelp_options_add-quotes,add quotes around parameters containing spaces]]
==== `add-quotes`

The shell (as in `/bin/sh`) parser strips quotes from the command
line. This may sometimes make it really difficult to type values
which contain white space. One typical example is the configure
filter command. The crm shell will supply extra quotes around
arguments which contain white space. The default is `yes`.

.Note on quotes use
****************************
Adding quotes around arguments automatically has been introduced
with version 1.2.2 and it is technically a regression. Being a
regression is the only reason the `add-quotes` option exists. If
you have custom shell scripts which would break, just set the
`add-quotes` option to `no`.

For instance, with adding quotes enabled, it is possible to do
the following:
...............
    # crm configure primitive d1 ocf:heartbeat:Dummy meta description="some description here"
    # crm configure filter 'sed "s/hostlist=./&node-c /"' fencing
...............
****************************

[[cmdhelp_options_manage-children,how to handle children resource attributes]]
==== `manage-children`

Some resource management commands, such as `resource stop`, when
the target resource is a group, may not always produce desired
result. Each element, group and the primitive members, can have a
meta attribute and those attributes may end up with conflicting
values. Consider the following construct:
...............
    crm(live)# configure show svc fs virtual-ip
    primitive fs ocf:heartbeat:Filesystem \
            params device="/dev/drbd0" directory="/srv/nfs" fstype="ext3" \
            op monitor interval="10s" \
            meta target-role="Started"
    primitive virtual-ip ocf:heartbeat:IPaddr2 \
            params ip="10.2.13.110" iflabel="1" \
            op monitor interval="10s" \
            op start interval="0" \
            meta target-role="Started"
    group svc fs virtual-ip \
            meta target-role="Stopped"
...............

Even though the element `svc` should be stopped, the group is
actually running because all its members have the `target-role`
set to `Started`:
...............
    crm(live)# resource show svc
    resource svc is running on: xen-f 
...............

Hence, if the user invokes `resource stop svc` the intention is
not clear. This preference gives the user an opportunity to
better control what happens if attributes of group members have
values which are in conflict with the same attribute of the group
itself.

Possible values are `ask` (the default), `always`, and `never`.
If set to `always`, the crm shell removes all children attributes
which have values different from the parent. If set to `never`,
all children attributes are left intact. Finally, if set to
`ask`, the user will be asked for each member what is to be done.

[[cmdhelp_options_show,show current user preference]]
==== `show`

Display all current settings.

[[cmdhelp_options_save,save the user preferences to the rc file]]
==== `save`

Save current settings to the rc file (`$HOME/.config/crm/rc`). On
further `crm` runs, the rc file is automatically read and parsed.

[[cmdhelp_options_reset,reset user preferences to factory defaults]]
==== `reset`

This command resets all user options to the defaults. If used as
a single-shot command, the rc file (`$HOME/.config/crm/rc`) is
reset to the defaults too.

[[cmdhelp_configure,CIB configuration]]
=== `configure`

This level enables all CIB object definition commands.

The configuration may be logically divided into four parts:
nodes, resources, constraints, and (cluster) properties and
attributes.  Each of these commands support one or more basic CIB
objects.

Nodes and attributes describing nodes are managed using the
`node` command.

Commands for resources are:

- `primitive`
- `monitor`
- `group`
- `clone`
- `ms`/`master` (master-slave)

In order to streamline large configurations, it is possible to
define a template which can later be referenced in primitives:

- `rsc_template`

In that case the primitive inherits all attributes defined in the
template.

There are three types of constraints:

- `location`
- `colocation`
- `order`

It is possible to define fencing order (stonith resource
priorities):

- `fencing_topology`

Finally, there are the cluster properties, resource meta
attributes defaults, and operations defaults. All are just a set
of attributes. These attributes are managed by the following
commands:

- `property`
- `rsc_defaults`
- `op_defaults`

In addition to the cluster configuration, the Access Control
Lists (ACL) can be setup to allow access to parts of the CIB for
users other than `root` and `hacluster`. The following commands
manage ACL:

- `user`
- `role`

The changes are applied to the current CIB only on ending the
configuration session or using the `commit` command.

Comments start with `#` in the first line. The comments are tied
to the element which follows. If the element moves, its comments
will follow.

[[cmdhelp_configure_node,define a cluster node]]
==== `node`

The node command describes a cluster node. Nodes in the CIB are
commonly created automatically by the CRM. Hence, you should not
need to deal with nodes unless you also want to define node
attributes. Note that it is also possible to manage node
attributes at the `node` level.

Usage:
...............
        node <uname>[:<type>]
          [attributes <param>=<value> [<param>=<value>...]]
          [utilization <param>=<value> [<param>=<value>...]]

        type :: normal | member | ping
...............
Example:
...............
        node node1
        node big_node attributes memory=64
...............

[[cmdhelp_configure_primitive,define a resource]]
==== `primitive`

The primitive command describes a resource. It may be referenced
only once in group, clone, or master-slave objects. If it's not
referenced, then it is placed as a single resource in the CIB.

Operations may be specified in three ways. "Anonymous" as a
simple list of "op" specifications. Use that if you don't want to
reference the set of operations elsewhere. That's by far the most
common way to define operations. If reusing operation sets is
desired, use the "operations" keyword along with the id to give
the operations set a name and the id-ref to reference another set
of operations.

Operation's attributes which are not recognized are saved as
instance attributes of that operation. A typical example is
`OCF_CHECK_LEVEL`.

For multistate resources, roles are specified as `role=<role>`.

A template may be defined for resources which are of the same
type and which share most of the configuration. See 
<<cmdhelp_configure_rsc_template,`rsc_template`>> for more information.

Usage:
...............
        primitive <rsc> {[<class>:[<provider>:]]<type>|@<template>}
          [params attr_list]
          [meta attr_list]
          [utilization attr_list]
          [operations id_spec]
            [op op_type [<attribute>=<value>...] ...]

        attr_list :: [$id=<id>] <attr>=<val> [<attr>=<val>...] | $id-ref=<id>
        id_spec :: $id=<id> | $id-ref=<id>
        op_type :: start | stop | monitor
...............
Example:
...............
        primitive apcfence stonith:apcsmart \
          params ttydev=/dev/ttyS0 hostlist="node1 node2" \
          op start timeout=60s \
          op monitor interval=30m timeout=60s

        primitive www8 apache \
          params configfile=/etc/apache/www8.conf \
          operations $id-ref=apache_ops

        primitive db0 mysql \
          params config=/etc/mysql/db0.conf \
          op monitor interval=60s \
          op monitor interval=300s OCF_CHECK_LEVEL=10

        primitive r0 ocf:linbit:drbd \
          params drbd_resource=r0 \
          op monitor role=Master interval=60s \
          op monitor role=Slave interval=300s

        primitive xen0 @vm_scheme1 \
          params xmfile=/etc/xen/vm/xen0
...............

[[cmdhelp_configure_monitor,add monitor operation to a primitive]]
==== `monitor`

Monitor is by far the most common operation. It is possible to
add it without editing the whole resource. Also, long primitive
definitions may be a bit uncluttered. In order to make this
command as concise as possible, less common operation attributes
are not available. If you need them, then use the `op` part of
the `primitive` command.

Usage:
...............
        monitor <rsc>[:<role>] <interval>[:<timeout>]
...............
Example:
...............
        monitor apcfence 60m:60s
...............

Note that after executing the command, the monitor operation may
be shown as part of the primitive definition.

[[cmdhelp_configure_group,define a group]]
==== `group`

The `group` command creates a group of resources. This can be useful
when resources depend on other resources and require that those
resources start in order on the same node. A common use of resource
groups is to ensure that a server and a virtual IP are located
together, and that the virtual IP is started before the server.

Grouped resources are started in the order they appear in the group,
and stopped in the reverse order. If a resource in the group cannot
run anywhere, resources following it in the group will not start.

`group` can be passed the "container" meta attribute, to indicate that
it is to be used to group VM resources monitored using Nagios. The
resource referred to by the container attribute must be of type
`ocf:heartbeat:Xen`, `ocf:heartbeat:VirtualDomain` or `ocf:heartbeat:lxc`.

Usage:
...............
        group <name> <rsc> [<rsc>...]
          [meta attr_list]
          [params attr_list]

        attr_list :: [$id=<id>] <attr>=<val> [<attr>=<val>...] | $id-ref=<id>
...............
Example:
...............
        group internal_www disk0 fs0 internal_ip apache \
          meta target_role=stopped

        group vm-and-services vm vm-sshd meta container="vm"
...............

[[cmdhelp_configure_clone,define a clone]]
==== `clone`

The `clone` command creates a resource clone. It may contain a
single primitive resource or one group of resources.

Usage:
...............
        clone <name> <rsc>
          [meta attr_list]
          [params attr_list]

        attr_list :: [$id=<id>] <attr>=<val> [<attr>=<val>...] | $id-ref=<id>
...............
Example:
...............
        clone cl_fence apc_1 \
          meta clone-node-max=1 globally-unique=false
...............

[[cmdhelp_configure_ms,define a master-slave resource]]
==== `ms` (`master`)

The `ms` command creates a master/slave resource type. It may contain a
single primitive resource or one group of resources.

Usage:
...............
        ms <name> <rsc>
          [meta attr_list]
          [params attr_list]

        attr_list :: [$id=<id>] <attr>=<val> [<attr>=<val>...] | $id-ref=<id>
...............
Example:
...............
        ms disk1 drbd1 \
          meta notify=true globally-unique=false
...............

.Note on `id-ref` usage
****************************
Instance or meta attributes (`params` and `meta`) may contain
a reference to another set of attributes. In that case, no other
attributes are allowed. Since attribute sets' ids, though they do
exist, are not shown in the `crm`, it is also possible to
reference an object instead of an attribute set. `crm` will
automatically replace such a reference with the right id:

...............
    crm(live)configure# primitive a2 www-2 meta $id-ref=a1
    crm(live)configure# show a2
    primitive a2 ocf:heartbeat:apache \
        meta $id-ref="a1-meta_attributes"
        [...]
...............
It is advisable to give meaningful names to attribute sets which
are going to be referenced.
****************************

[[cmdhelp_configure_rsc_template,define a resource template]]
==== `rsc_template`

The `rsc_template` command creates a resource template. It may be
referenced in primitives. It is used to reduce large
configurations with many similar resources.

Usage:
...............
        rsc_template <name> [<class>:[<provider>:]]<type>
          [params attr_list]
          [meta attr_list]
          [utilization attr_list]
          [operations id_spec]
            [op op_type [<attribute>=<value>...] ...]

        attr_list :: [$id=<id>] <attr>=<val> [<attr>=<val>...] | $id-ref=<id>
        id_spec :: $id=<id> | $id-ref=<id>
        op_type :: start | stop | monitor
...............
Example:
...............
        rsc_template public_vm ocf:heartbeat:Xen \
          op start timeout=300s \
          op stop timeout=300s \
          op monitor interval=30s timeout=60s \
          op migrate_from timeout=600s \
          op migrate_to timeout=600s
        primitive xen0 @public_vm \
          params xmfile=/etc/xen/xen0
        primitive xen1 @public_vm \
          params xmfile=/etc/xen/xen1
...............

[[cmdhelp_configure_location,a location preference]]
==== `location`

`location` defines the preference of nodes for the given
resource. The location constraints consist of one or more rules
which specify a score to be awarded if the rule matches.

Usage:
...............
        location <id> <rsc> {node_pref|rules}

        node_pref :: <score>: <node>

        rules ::
          rule [id_spec] [$role=<role>] <score>: <expression>
          [rule [id_spec] [$role=<role>] <score>: <expression> ...]

        id_spec :: $id=<id> | $id-ref=<id>
        score :: <number> | <attribute> | [-]inf
        expression :: <simple_exp> [bool_op <simple_exp> ...]
        bool_op :: or | and
        simple_exp :: <attribute> [type:]<binary_op> <value>
                      | <unary_op> <attribute>
                      | date <date_expr>
        type :: string | version | number
        binary_op :: lt | gt | lte | gte | eq | ne
        unary_op :: defined | not_defined

        date_expr :: lt <end>
                     | gt <start>
                     | in_range start=<start> end=<end>
                     | in_range start=<start> <duration>
                     | date_spec <date_spec>
        duration|date_spec ::
                     hours=<value>
                     | monthdays=<value>
                     | weekdays=<value>
                     | yearsdays=<value>
                     | months=<value>
                     | weeks=<value>
                     | years=<value>
                     | weekyears=<value>
                     | moon=<value>
...............
Examples:
...............
        location conn_1 internal_www 100: node1

        location conn_1 internal_www \
          rule 50: #uname eq node1 \
          rule pingd: defined pingd

        location conn_2 dummy_float \
          rule -inf: not_defined pingd or pingd number:lte 0
...............

[[cmdhelp_configure_colocation,colocate resources]]
==== `colocation` (`collocation`)

This constraint expresses the placement relation between two
or more resources. If there are more than two resources, then the
constraint is called a resource set.

The score is used to indicate the priority of the constraint. A
positive score indicates that the resources should run on the same
node. A negative score that they should not run on the same
node. Values of positive or negative `infinity` indicate a mandatory
constraint.

In the two resource form, the cluster will place `<with-rsc>` first,
and then decide where to put the `<rsc>` resource.

Collocation resource sets have an extra attribute (`sequential`)
to allow for sets of resources which don't depend on each other
in terms of state. The shell syntax for such sets is to put
resources in parentheses.

Sets cannot be nested.

The optional `node-attribute` references an attribute in nodes'
instance attributes.

Usage:
...............
        colocation <id> <score>: <rsc>[:<role>] <with-rsc>[:<role>]
          [node-attribute=<node_attr>]

        colocation <id> <score>: <rsc>[:<role>] <rsc>[:<role>] ...
          [node-attribute=<node_attr>]
...............
Example:
...............
        colocation never_put_apache_with_dummy -inf: apache dummy
        colocation c1 inf: A ( B C )
...............

[[cmdhelp_configure_order,order resources]]
==== `order`

This constraint expresses the order of actions on two resources
or more resources. If there are more than two resources, then the
constraint is called a resource set.

Ordered resource sets have an extra attribute to allow for sets
of resources whose actions may run in parallel. The shell syntax
for such sets is to put resources in parentheses.

If the subsequent resource can start or promote after any one of the
resources in a set has done, enclose the set in brackets (`[` and `]`).

Sets cannot be nested.

Three strings are reserved to specify a kind of order constraint:
`Mandatory`, `Optional`, and `Serialize`. It is preferred to use
one of these settings instead of score. Previous versions mapped
scores `0` and `inf` to keywords `advisory` and `mandatory`.
That is still valid but deprecated.

.Note on resource sets' XML attributes
****************************
The XML attribute `require-all` controls whether all resources in
a set are, well, required. The bracketed sets actually have this
attribute as well as `sequential` set to `false`. If you need a
different combination, for whatever reason, just set one of the
attributes within the set. Something like this:

...............
    crm(live)configure# order o1 Mandatory: [ A B sequential=true ] C
...............
It is up to you to find out whether such a combination makes
sense.
****************************

Usage:
...............
        order <id> {kind|<score>}: <rsc>[:<action>] <rsc>[:<action>] ...
          [symmetrical=<bool>]

        kind :: Mandatory | Optional | Serialize
...............
Example:
...............
        order c_apache_1 Mandatory: apache:start ip_1
        order o1 Serialize: A ( B C )
        order order_2 Mandatory: [ A B ] C
...............

[[cmdhelp_configure_rsc_ticket,resources ticket dependency]]
==== `rsc_ticket`

This constraint expresses dependency of resources on cluster-wide
attributes, also known as tickets. Tickets are mainly used in
geo-clusters, which consist of multiple sites. A ticket may be
granted to a site, thus allowing resources to run there.

The `loss-policy` attribute specifies what happens to the
resource (or resources) if the ticket is revoked. The default is
either `stop` or `demote` depending on whether a resource is
multi-state.

See also the <<cmdhelp_site_ticket,`site`>> set of commands.

Usage:
...............
        rsc_ticket <id> <ticket_id>: <rsc>[:<role>] [<rsc>[:<role>] ...]
          [loss-policy=<loss_policy_action>]

        loss_policy_action :: stop | demote | fence | freeze
...............
Example:
...............
        rsc_ticket ticket-A_public-ip ticket-A: public-ip
        rsc_ticket ticket-A_bigdb ticket-A: bigdb loss-policy=fence
        rsc_ticket ticket-B_storage ticket-B: drbd-a:Master drbd-b:Master
...............


[[cmdhelp_configure_property,set a cluster property]]
==== `property`

Set the cluster (`crm_config`) options.

Usage:
...............
        property [$id=<set_id>] <option>=<value> [<option>=<value> ...]
...............
Example:
...............
        property stonith-enabled=true
...............

[[cmdhelp_configure_rsc_defaults,set resource defaults]]
==== `rsc_defaults`

Set defaults for the resource meta attributes.

Usage:
...............
        rsc_defaults [$id=<set_id>] <option>=<value> [<option>=<value> ...]
...............
Example:
...............
        rsc_defaults failure-timeout=3m
...............

[[cmdhelp_configure_fencing_topology,node fencing order]]
==== `fencing_topology`

If multiple fencing (stonith) devices are available capable of
fencing a node, their order may be specified by `fencing_topology`.
The order is specified per node.

Stonith resources can be separated by `,` in which case all of
them need to succeed. If they fail, the next stonith resource (or
set of resources) is used. In other words, use comma to separate
resources which all need to succeed and whitespace for serial
order. It is not allowed to use whitespace around comma.

If the node is left out, the order is used for all nodes.
That should reduce the configuration size in some stonith setups.

Usage:
...............
        fencing_topology stonith_resources [stonith_resources ...]
        fencing_topology fencing_order [fencing_order ...]

        fencing_order :: <node>: stonith_resources [stonith_resources ...]

        stonith_resources :: <rsc>[,<rsc>...]
...............
Example:
...............
        fencing_topology poison-pill power
        fencing_topology \
            node-a: poison-pill power
            node-b: ipmi serial
...............

[[cmdhelp_configure_role,define role access rights]]
==== `role`

An ACL role is a set of rules which describe access rights to
CIB. Rules consist of an access right `read`, `write`, or `deny`
and a specification denoting part of the configuration to which
the access right applies. The specification can be an XPath or a
combination of tag and id references. If an attribute is
appended, then the specification applies only to that attribute
of the matching element.

There is a number of shortcuts for XPath specifications. The
`meta,` `params`, and `utilization` shortcuts reference resource
meta attributes, parameters, and utilization respectively. The
`location` may be used to specify location constraints most of
the time to allow resource `move` and `unmove` commands. The
`property` references cluster properties. The `node` allows
reading node attributes. `nodeattr` and `nodeutil` reference node
attributes and node capacity (utilization). The `status` shortcut
references the whole status section of the CIB. Read access to
status is necessary for various monitoring tools such as
`crm_mon(8)` (aka `crm status`).

Usage:
...............
        role <role-id> rule [rule ...]

        rule :: acl-right cib-spec [attribute:<attribute>]

        acl-right :: read | write | deny

        cib-spec :: xpath-spec | tag-ref-spec
        xpath-spec :: xpath:<xpath> | shortcut
        tag-ref-spec :: tag:<tag> | ref:<id> | tag:<tag> ref:<id>

        shortcut :: meta:<rsc>[:<attr>]
                    params:<rsc>[:<attr>]
                    utilization:<rsc>
                    location:<rsc>
                    property[:<attr>]
                    node[:<node>]
                    nodeattr[:<attr>]
                    nodeutil[:<node>]
                    status
...............
Example:
...............
        role app1_admin \
            write meta:app1:target-role \
            write meta:app1:is-managed \
            write location:app1 \
            read ref:app1
...............

[[cmdhelp_configure_user,define user access rights]]
==== `user`

Users which normally cannot view or manage cluster configuration
can be allowed access to parts of the CIB. The access is defined
by a set of `read`, `write`, and `deny` rules as in role
definitions or by referencing roles. The latter is considered
best practice.

Usage:
...............
        user <uid> {roles|rules}

        roles :: role:<role-ref> [role:<role-ref> ...]
        rules :: rule [rule ...]
...............
Example:
...............
        user joe \
            role:app1_admin \
            role:read_all
...............

[[cmdhelp_configure_op_defaults,set resource operations defaults]]
==== `op_defaults`

Set defaults for the operations meta attributes.

Usage:
...............
        op_defaults [$id=<set_id>] <option>=<value> [<option>=<value> ...]
...............
Example:
...............
        op_defaults record-pending=true
...............

[[cmdhelp_configure_schema,set or display current CIB RNG schema]]
==== `schema`

CIB's content is validated by a RNG schema. Pacemaker supports
several, depending on version. Currently supported schemas are
`pacemaker-1.0`, `pacemaker-1.1`, and `pacemaker-1.2`.

Use this command to display or switch to another RNG schema.

Usage:
...............
        schema [<schema>]
...............
Example:
...............
        schema pacemaker-1.1
...............

[[cmdhelp_configure_show,display CIB objects]]
==== `show`

The `show` command displays objects. It may display all objects
or a set of objects. The user may also choose to see only objects
which were changed.
Optionally, the XML code may be displayed instead of the CLI
representation.

Usage:
...............
        show [xml] [<id> ...]
        show [xml] changed
...............

[[cmdhelp_configure_edit,edit CIB objects]]
==== `edit`

This command invokes the editor with the object description. As
with the `show` command, the user may choose to edit all objects
or a set of objects.

If the user insists, he or she may edit the XML edition of the
object. If you do that, don't modify any id attributes.

Usage:
...............
        edit [xml] [<id> ...]
        edit [xml] changed
...............

.Note on renaming element ids
****************************
The edit command sometimes cannot properly handle modifying
element ids. In particular for elements which belong to group or
ms resources. Group and ms resources themselves also cannot be
renamed. Please use the `rename` command instead.
****************************

[[cmdhelp_configure_filter,filter CIB objects]]
==== `filter`

This command filters the given CIB elements through an external
program. The program should accept input on `stdin` and send
output to `stdout` (the standard UNIX filter conventions). As
with the `show` command, the user may choose to filter all or
just a subset of elements.

It is possible to filter the XML representation of objects, but
probably not as useful as the configuration language. The
presentation is somewhat different from what would be displayed
by the `show` command---each element is shown on a single line,
i.e. there are no backslashes and no other embelishments.

Don't forget to put quotes around the filter if it contains
spaces.

Usage:
...............
        filter <prog> [xml] [<id> ...]
        filter <prog> [xml] changed
...............
Examples:
...............
        filter "sed '/^primitive/s/target-role=[^ ]*//'"
        # crm configure filter "sed '/^primitive/s/target-role=[^ ]*//'"
...............

[[cmdhelp_configure_delete,delete CIB objects]]
==== `delete`

Delete one or more objects. If an object to be deleted belongs to
a container object, such as a group, and it is the only resource
in that container, then the container is deleted as well. Any
related constraints are removed as well.

Usage:
...............
        delete <id> [<id>...]
...............

[[cmdhelp_configure_default-timeouts,set timeouts for operations to minimums from the meta-data]]
==== `default-timeouts`

This command takes the timeouts from the actions section of the
resource agent meta-data and sets them for the operations of the
primitive.

Usage:
...............
        default-timeouts <id> [<id>...]
...............

.Note on `default-timeouts`
****************************
You may be happy using this, but your applications may not. And
it will tell you so at the worst possible moment. You have been
warned.
****************************

[[cmdhelp_configure_rename,rename a CIB object]]
==== `rename`

Rename an object. It is recommended to use this command to rename
a resource, because it will take care of updating all related
constraints and a parent resource. Changing ids with the edit
command won't have the same effect.

If you want to rename a resource, it must be in the stopped state.

Usage:
...............
        rename <old_id> <new_id>
...............

[[cmdhelp_configure_modgroup,modify group]]
==== `modgroup`

Add or remove primitives in a group. The `add` subcommand appends
the new group member by default. Should it go elsewhere, there
are `after` and `before` clauses.

Usage:
...............
        modgroup <id> add <id> [after <id>|before <id>]
        modgroup <id> remove <id>
...............
Examples:
...............
        modgroup share1 add storage2 before share1-fs
...............

[[cmdhelp_configure_refresh,refresh from CIB]]
==== `refresh`

Refresh the internal structures from the CIB. All changes made
during this session are lost.

Usage:
...............
        refresh
...............

[[cmdhelp_configure_erase,erase the CIB]]
==== `erase`

The `erase` clears all configuration. Apart from nodes. To remove
nodes, you have to specify an additional keyword `nodes`.

Note that removing nodes from the live cluster may have some
strange/interesting/unwelcome effects.

Usage:
...............
        erase [nodes]
...............

[[cmdhelp_configure_ptest,show cluster actions if changes were committed]]
==== `ptest` (`simulate`)

Show PE (Policy Engine) motions using `ptest(8)` or
`crm_simulate(8)`.

A CIB is constructed using the current user edited configuration
and the status from the running CIB. The resulting CIB is run
through `ptest` (or `crm_simulate`) to show changes which would
happen if the configuration is committed.

The status section may be loaded from another source and modified
using the <<cmdhelp_cibstatus,`cibstatus`>> level commands. In that case, the
`ptest` command will issue a message informing the user that the
Policy Engine graph is not calculated based on the current status
section and therefore won't show what would happen to the
running but some imaginary cluster.

If you have graphviz installed and X11 session, `dotty(1)` is run
to display the changes graphically.

Add a string of `v` characters to increase verbosity. `ptest`
can also show allocation scores. `utilization` turns on
information about the remaining capacity of nodes. With the
`actions` option, `ptest` will print all resource actions.

The `ptest` program has been replaced by `crm_simulate` in newer
Pacemaker versions. In some installations both could be
installed. Use `simulate` to enfore using `crm_simulate`.

Usage:
...............
        ptest [nograph] [v...] [scores] [actions] [utilization]
...............
Examples:
...............
        ptest scores
        ptest vvvvv
        simulate actions
...............

[[cmdhelp_configure_rsctest,test resources as currently configured]]
==== `rsctest`

Test resources with current resource configuration. If no nodes
are specified, tests are run on all known nodes.

The order of resources is significant: it is assumed that later
resources depend on earlier ones.

If a resource is multi-state, it is assumed that the role on
which later resources depend is master.

Tests are run sequentially to prevent running the same resource
on two or more nodes. Tests are carried out only if none of the
specified nodes currently run any of the specified resources.
However, it won't verify whether resources run on the other
nodes.

Superuser privileges are obviously required: either run this as
root or setup the `sudoers` file appropriately.

Note that resource testing may take some time.

Usage:
...............
        rsctest <rsc_id> [<rsc_id> ...] [<node_id> ...]
...............
Examples:
...............
        rsctest my_ip websvc
        rsctest websvc nodeB
...............

[[cmdhelp_configure_cib,CIB shadow management]]
=== `cib` (shadow CIBs)

This level is for management of shadow CIBs. It is available at
the `configure` level to enable saving intermediate changes to a
shadow CIB instead of to the live cluster. This short excerpt
shows how:
...............
    crm(live)configure# cib new test-2
    INFO: test-2 shadow CIB created
    crm(test-2)configure# commit
...............
Note how the current CIB in the prompt changed from `live` to
`test-2` after issuing the `cib new` command. See also the
<<cmdhelp_cib,CIB shadow management>> for more information.

[[cmdhelp_configure_cibstatus,CIB status management and editing]]
==== `cibstatus`

Enter edit and manage the CIB status section level. See the
<<cmdhelp_cibstatus,CIB status management section>>.

[[cmdhelp_configure_template,edit and import a configuration from a template]]
==== `template`

The specified template is loaded into the editor. It's up to the
user to make a good CRM configuration out of it. See also the
<<cmdhelp_template,template section>>.

Usage:
...............
        template [xml] url
...............
Example:
...............
        template two-apaches.txt
...............

[[cmdhelp_configure_commit,commit the changes to the CIB]]
==== `commit`

Commit the current configuration to the CIB in use. As noted
elsewhere, commands in a configure session don't have immediate
effect on the CIB. All changes are applied at one point in time,
either using `commit` or when the user leaves the configure
level. In case the CIB in use changed in the meantime, presumably
by somebody else, the crm shell will refuse to apply the changes.
If you know that it's fine to still apply them add `force`.

Usage:
...............
        commit [force]
...............

[[cmdhelp_configure_verify,verify the CIB with crm_verify]]
==== `verify`

Verify the contents of the CIB which would be committed.

Usage:
...............
        verify
...............

[[cmdhelp_configure_upgrade,upgrade the CIB to version 1.0]]
==== `upgrade`

If you get the `CIB not supported` error, which typically means
that the current CIB version is coming from the older release,
you may try to upgrade it to the latest revision. The command
to perform the upgrade is:
...............
    # cibadmin --upgrade --force
...............

If we don't recognize the current CIB as the old one, but you're
sure that it is, you may force the command.

Usage:
...............
        upgrade [force]
...............

[[cmdhelp_configure_save,save the CIB to a file]]
==== `save`

Save the current configuration to a file. Optionally, as XML. Use
`-` instead of file name to write the output to `stdout`.

Usage:
...............
        save [xml] <file>
...............
Example:
...............
        save myfirstcib.txt
...............

[[cmdhelp_configure_load,import the CIB from a file]]
==== `load`

Load a part of configuration (or all of it) from a local file or
a network URL. The `replace` method replaces the current
configuration with the one from the source. The `update` tries to
import the contents into the current configuration.
The file may be a CLI file or an XML file.

Usage:
...............
        load [xml] <method> URL

        method :: replace | update
...............
Example:
...............
        load xml update myfirstcib.xml
        load xml replace http://storage.big.com/cibs/bigcib.xml
...............

[[cmdhelp_configure_graph,generate a directed graph]]
==== `graph`

Create a graphviz graphical layout from the current cluster
configuration.

Currently, only `dot` (directed graph) is supported. It is
essentially a visualization of resource ordering.

The graph may be saved to a file which can be used as source for
various graphviz tools (by default it is displayed in the user's
X11 session). Optionally, by specifying the format, one can also
produce an image instead.

For more or different graphviz attributes, it is possible to save
the default set of attributes to an ini file. If this file exists
it will always override the builtin settings. The `exportsettings`
subcommand also prints the location of the ini file.

Usage:
...............
        graph [<gtype> [<file> [<img_format>]]]
        graph exportsettings

        gtype :: dot
        img_format :: `dot` output format (see the `-T` option)
...............
Example:
...............
        graph dot
        graph dot clu1.conf.dot
        graph dot clu1.conf.svg svg
...............

[[cmdhelp_configure_xml,raw xml]]
==== `xml`

Even though we promissed no xml, it may happen, but hopefully
very very seldom, that an element from the CIB cannot be rendered
in the configuration language. In that case, the element will be
shown as raw xml, prefixed by this command. That element can then
be edited like any other. If the shell finds out that after the
change it can digest it, then it is going to be converted into
the normal configuration language. Otherwise, there is no need to
use `xml` for configuration.

Usage:
...............
        xml <xml>
...............

[[cmdhelp_template,edit and import a configuration from a template]]
=== `template`

User may be assisted in the cluster configuration by templates
prepared in advance. Templates consist of a typical ready
configuration which may be edited to suit particular user needs.

This command enters a template level where additional commands
for configuration/template management are available.

[[cmdhelp_template_new,create a new configuration from templates]]
==== `new`

Create a new configuration from one or more templates. Note that
configurations and templates are kept in different places, so it
is possible to have a configuration name equal a template name.

If you already know which parameters are required, you can set
them directly on the command line.

The parameter name `id` is set by default to the name of the
configuration.

Usage:
...............
        new <config> <template> [<template> ...] [params name=value ...]"
...............
Examples:
...............
        new vip virtual-ip
        new bigfs ocfs2 params device=/dev/sdx8 directory=/bigfs
...............

[[cmdhelp_template_load,load a configuration]]
==== `load`

Load an existing configuration. Further `edit`, `show`, and
`apply` commands will refer to this configuration.

Usage:
...............
        load <config>
...............

[[cmdhelp_template_edit,edit a configuration]]
==== `edit`

Edit current or given configuration using your favourite editor.

Usage:
...............
        edit [<config>]
...............

[[cmdhelp_template_delete,delete a configuration]]
==== `delete`

Remove a configuration. The loaded (active) configuration may be
removed by force.

Usage:
...............
        delete <config> [force]
...............

[[cmdhelp_template_list,list configurations/templates]]
==== `list`

List existing configurations or templates.

Usage:
...............
        list [templates]
...............

[[cmdhelp_template_apply,process and apply the current configuration to the current CIB]]
==== `apply`

Copy the current or given configuration to the current CIB. By
default, the CIB is replaced, unless the method is set to
"update".

Usage:
...............
        apply [<method>] [<config>]

        method :: replace | update
...............

[[cmdhelp_template_show,show the processed configuration]]
==== `show`

Process the current or given configuration and display the result.

Usage:
...............
        show [<config>]
...............

[[cmdhelp_cibstatus,CIB status management and editing]]
=== `cibstatus`

The `status` section of the CIB keeps the current status of nodes
and resources. It is modified _only_ on events, i.e. when some
resource operation is run or node status changes. For obvious
reasons, the CRM has no user interface with which it is possible
to affect the status section. From the user's point of view, the
status section is essentially a read-only part of the CIB. The
current status is never even written to disk, though it is
available in the PE (Policy Engine) input files which represent
the history of cluster motions. The current status may be read
using the `cibadmin -Q` command.

It may sometimes be of interest to see how status changes would
affect the Policy Engine. The set of `cibstatus` level commands
allow the user to load status sections from various sources and
then insert or modify resource operations or change nodes' state.

The effect of those changes may then be observed by running the
<<cmdhelp_configure_ptest,`ptest`>> command at the `configure` level
or `simulate` and `run` commands at this level. The `ptest`
runs with the user edited CIB whereas the latter two commands
run with the CIB which was loaded along with the status section.

The `simulate` and `run` commands as well as all status
modification commands are implemented using `crm_simulate(8)`.

[[cmdhelp_cibstatus_load,load the CIB status section]]
==== `load`

Load a status section from a file, a shadow CIB, or the running
cluster. By default, the current (`live`) status section is
modified. Note that if the `live` status section is modified it
is not going to be updated if the cluster status changes, because
that would overwrite the user changes. To make `crm` drop changes
and resume use of the running cluster status, run `load live`.

All CIB shadow configurations contain the status section which is
a snapshot of the status section taken at the time the shadow was
created. Obviously, this status section doesn't have much to do
with the running cluster status, unless the shadow CIB has just
been created. Therefore, the `ptest` command by default uses the
running cluster status section.

Usage:
...............
        load {<file>|shadow:<cib>|live}
...............
Example:
...............
        load bug-12299.xml
        load shadow:test1
...............

[[cmdhelp_cibstatus_save,save the CIB status section]]
==== `save`

The current internal status section with whatever modifications
were performed can be saved to a file or shadow CIB.

If the file exists and contains a complete CIB, only the status
section is going to be replaced and the rest of the CIB will
remain intact. Otherwise, the current user edited configuration
is saved along with the status section.

Note that all modifications are saved in the source file as soon
as they are run.

Usage:
...............
        save [<file>|shadow:<cib>]
...............
Example:
...............
        save bug-12299.xml
...............

[[cmdhelp_cibstatus_origin,display origin of the CIB status section]]
==== `origin`

Show the origin of the status section currently in use. This
essentially shows the latest `load` argument.

Usage:
...............
        origin
...............

[[cmdhelp_cibstatus_show,show CIB status section]]
==== `show`

Show the current status section in the XML format. Brace yourself
for some unreadable output. Add `changed` option to get a human
readable output of all changes.

Usage:
...............
        show [changed]
...............

[[cmdhelp_cibstatus_node,change node status]]
==== `node`

Change the node status. It is possible to throw a node out of
the cluster, make it a member, or set its state to unclean.

`online`:: Set the `node_state` `crmd` attribute to `online`
and the `expected` and `join` attributes to `member`. The effect
is that the node becomes a cluster member.

`offline`:: Set the `node_state` `crmd` attribute to `offline`
and the `expected` attribute to empty. This makes the node
cleanly removed from the cluster.

`unclean`:: Set the `node_state` `crmd` attribute to `offline`
and the `expected` attribute to `member`. In this case the node
has unexpectedly disappeared.

Usage:
...............
        node <node> {online|offline|unclean}
...............
Example:
...............
        node xen-b unclean
...............

[[cmdhelp_cibstatus_op,edit outcome of a resource operation]]
==== `op`

Edit the outcome of a resource operation. This way you can
tell CRM that it ran an operation and that the resource agent
returned certain exit code. It is also possible to change the
operation's status. In case the operation status is set to
something other than `done`, the exit code is effectively
ignored.

Usage:
...............
        op <operation> <resource> <exit_code> [<op_status>] [<node>]

        operation :: probe | monitor[:<n>] | start | stop |
           promote | demote | notify | migrate_to | migrate_from
        exit_code :: <rc> | success | generic | args | 
           unimplemented | perm | installed | configured | not_running | 
           master | failed_master
        op_status :: pending | done | cancelled | timeout | notsupported | error

        n :: the monitor interval in seconds; if omitted, the first
           recurring operation is referenced
        rc :: numeric exit code in range 0..9
...............
Example:
...............
        op start d1 xen-b generic
        op start d1 xen-b 1
        op monitor d1 xen-b not_running
        op stop d1 xen-b 0 timeout
...............

[[cmdhelp_cibstatus_quorum,set the quorum]]
==== `quorum`

Set the quorum value.

Usage:
...............
        quorum <bool>
...............
Example:
...............
        quorum false
...............

[[cmdhelp_cibstatus_ticket,manage tickets]]
==== `ticket`

Modify the ticket status. Tickets can be granted and revoked.
Granted tickets could be activated or put in standby.

Usage:
...............
        ticket <ticket> {grant|revoke|activate|standby}
...............
Example:
...............
        ticket ticketA grant
...............

[[cmdhelp_cibstatus_run,run policy engine]]
==== `run`

Run the policy engine with the edited status section.

Add a string of `v` characters to increase verbosity. Specify
`scores` to see allocation scores also. `utilization` turns on
information about the remaining capacity of nodes.

If you have graphviz installed and X11 session, `dotty(1)` is run
to display the changes graphically.

Usage:
...............
        run [nograph] [v...] [scores] [utilization]
...............
Example:
...............
        run
...............

[[cmdhelp_cibstatus_simulate,simulate cluster transition]]
==== `simulate`

Run the policy engine with the edited status section and simulate
the transition.

Add a string of `v` characters to increase verbosity. Specify
`scores` to see allocation scores also. `utilization` turns on
information about the remaining capacity of nodes.

If you have graphviz installed and X11 session, `dotty(1)` is run
to display the changes graphically.

Usage:
...............
        simulate [nograph] [v...] [scores] [utilization]
...............
Example:
...............
        simulate
...............

[[cmdhelp_history,cluster history]]
=== `history`

Examining Pacemaker's history is a particularly involved task.
The number of subsystems to be considered, the complexity of the
configuration, and the set of various information sources, most
of which are not exactly human readable, keep analyzing resource
or node problems accessible to only the most knowledgeable. Or,
depending on the point of view, to the most persistent. The
following set of commands has been devised in hope to make
cluster history more accessible.

Of course, looking at _all_ history could be time consuming
regardless of how good tools at hand are. Therefore, one should
first say which period he or she wants to analyze. If not
otherwise specified, the last hour is considered. Logs and other
relevant information is collected using `hb_report`. Since this
process takes some time and we always need fresh logs,
information is refreshed in a much faster way using `pssh(1)`. If
`python-pssh` is not found on the system, examining live cluster
is still possible though not as comfortable.

Apart from examining live cluster, events may be retrieved from a
report generated by `hb_report` (see also the `-H` option). In
that case we assume that the period stretching the whole report
needs to be investigated. Of course, it is still possible to
further reduce the time range.

If you think you may have found a bug or just need clarification
from developers or your support, the `session pack` command can
help create a report. This is an example:
...............
    crm(live)history# limit "Jul 18 12:00" "Jul 18 12:30"
    crm(live)history# session save strange_restart
    crm(live)history# session pack
    Report saved in .../strange_restart.tar.bz2
    crm(live)history# 
...............
In order to reduce report size and allow developers to
concentrate on the issue, you should beforehand limit the time
frame. Giving a meaningful session name helps too.

==== `info`

The `info` command shows most important information about the
cluster.

Usage:
...............
        info
...............
Example:
...............
        info
...............

[[cmdhelp_history_latest,show latest news from the cluster]]
==== `latest`

The `latest` command shows a bit of recent history, more
precisely whatever happened since the last cluster change (the
latest transition). If the transition is running, the shell will
first wait until it finishes.

Usage:
...............
        latest
...............
Example:
...............
        latest
...............

[[cmdhelp_history_limit,limit timeframe to be examined]]
==== `limit` (`timeframe`)

All history commands look at events within certain period. It
defaults to the last hour for the live cluster source. There is
no limit for the `hb_report` source. Use this command to set the
timeframe.

The time period is parsed by the dateutil python module. It
covers wide range of date formats. For instance:

- 3:00          (today at 3am)
- 15:00         (today at 3pm)
- 2010/9/1 2pm  (September 1st 2010 at 2pm)

We won't bother to give definition of the time specification in
usage below. Either use common sense or read the
http://labix.org/python-dateutil[dateutil] documentation.

If dateutil is not available, then the time is parsed using
strptime and only the kind as printed by `date(1)` is allowed:

- Tue Sep 15 20:46:27 CEST 2010

Usage:
...............
        limit [<from_time> [<to_time>]]
...............
Examples:
...............
        limit 10:15
        limit 15h22m 16h
        limit "Sun 5 20:46" "Sun 5 22:00"
...............

[[cmdhelp_history_source,set source to be examined]]
==== `source`

Events to be examined can come from the current cluster or from a
`hb_report` report. This command sets the source. `source live`
sets source to the running cluster and system logs. If no source
is specified, the current source information is printed.

In case a report source is specified as a file reference, the file
is going to be unpacked in place where it resides. This directory
is not removed on exit.

Usage:
...............
        source [<dir>|<file>|live]
...............
Examples:
...............
        source live
        source /tmp/customer_case_22.tar.bz2
        source /tmp/customer_case_22
        source
...............

[[cmdhelp_history_refresh,refresh live report]]
==== `refresh`

This command makes sense only for the `live` source and makes
`crm` collect the latest logs and other relevant information from
the logs. If you want to make a completely new report, specify
`force`.

Usage:
...............
        refresh [force]
...............

[[cmdhelp_history_detail,set the level of detail shown]]
==== `detail`

How much detail to show from the logs.

Usage:
...............
        detail <detail_level>

        detail_level :: small integer (defaults to 0)
...............
Example:
...............
        detail 1
...............

[[cmdhelp_history_setnodes,set the list of cluster nodes]]
==== `setnodes`

In case the host this program runs on is not part of the cluster,
it is necessary to set the list of nodes.

Usage:
...............
        setnodes node <node> [<node> ...]
...............
Example:
...............
        setnodes node_a node_b
...............

[[cmdhelp_history_resource,resource events]]
==== `resource`

Show actions and any failures that happened on all specified
resources on all nodes. Normally, one gives resource names as
arguments, but it is also possible to use extended regular
expressions. Note that neither groups nor clones or master/slave
names are ever logged. The resource command is going to expand
all of these appropriately, so that clone instances or resources
which are part of a group are shown.

Usage:
...............
        resource <rsc> [<rsc> ...]
...............
Example:
...............
        resource bigdb public_ip
        resource my_.*_db2
        resource ping_clone
...............

[[cmdhelp_history_node,node events]]
==== `node`

Show important events that happened on a node. Important events
are node lost and join, standby and online, and fence. Use either
node names or extended regular expressions.

Usage:
...............
        node <node> [<node> ...]
...............
Example:
...............
        node node1
...............

[[cmdhelp_history_log,log content]]
==== `log`

Show messages logged on one or more nodes. Leaving out a node
name produces combined logs of all nodes. Messages are sorted by
time and, if the terminal emulations supports it, displayed in
different colours depending on the node to allow for easier
reading.

The sorting key is the timestamp as written by syslog which
normally has the maximum resolution of one second. Obviously,
messages generated by events which share the same timestamp may
not be sorted in the same way as they happened. Such close events
may actually happen fairly often.

Usage:
...............
        log [<node>]
...............
Example:
...............
        log node-a
...............

[[cmdhelp_history_exclude,exclude log messages]]
==== `exclude`

If a log is infested with irrelevant messages, those messages may
be excluded by specifying a regular expression. The regular
expressions used are Python extended. This command is additive.
To drop all regular expressions, use `exclude clear`. Run
`exclude` only to see the current list of regular expressions.
Excludes are saved along with the history sessions.

Usage:
...............
        exclude [<regex>|clear]
...............
Example:
...............
        exclude kernel.*ocfs2
...............

[[cmdhelp_history_peinputs,list or get PE input files]]
==== `peinputs`

Every event in the cluster results in generating one or more
Policy Engine (PE) files. These files describe future motions of
resources. The files are listed as full paths in the current
report directory. Add `v` to also see the creation time stamps.

Usage:
...............
        peinputs [{<range>|<number>} ...] [v]

        range :: <n1>:<n2>
...............
Example:
...............
        peinputs
        peinputs 440:444 446
        peinputs v
...............

[[cmdhelp_history_transition,show transition]]
==== `transition`

This command will print actions planned by the PE and run
graphviz (`dotty`) to display a graphical representation of the
transition. Of course, for the latter an X11 session is required.
This command invokes `ptest(8)` in background.

The `showdot` subcommand runs graphviz (`dotty`) to display a
graphical representation of the `.dot` file which has been
included in the report. Essentially, it shows the calculation
produced by `pengine` which is installed on the node where the
report was produced. In optimal case this output should not
differ from the one produced by the locally installed `pengine`.

The `log` subcommand shows the full log for the duration of the
transition.

A transition can also be saved to a CIB shadow for further
analysis or use with `cib` or `configure` commands (use the
`save` subcommand). The shadow file name defaults to the name of
the PE input file.

If the PE input file number is not provided, it defaults to the
last one, i.e. the last transition. The last transition can also
be referenced with number 0. If the number is negative, then the
corresponding transition relative to the last one is chosen.

If there are warning and error PE input files or different nodes
were the DC in the observed timeframe, it may happen that PE
input file numbers collide. In that case provide some unique part
of the path to the file.

After the `ptest` output, logs about events that happened during
the transition are printed.

Usage:
...............
        transition [<number>|<index>|<file>] [nograph] [v...] [scores] [actions] [utilization]
        transition showdot [<number>|<index>|<file>]
        transition log [<number>|<index>|<file>]
        transition save [<number>|<index>|<file> [name]]
...............
Examples:
...............
        transition
        transition 444
        transition -1
        transition pe-error-3.bz2
        transition node-a/pengine/pe-input-2.bz2
        transition showdot 444
        transition log
        transition save 0 enigma-22
...............

[[cmdhelp_history_show,show status or configuration of the PE input file]]
==== `show`

Every transition is saved as a PE file. Use this command to
render that PE file either as configuration or status. The
configuration output is the same as `crm configure show`.

Usage:
...............
        show <pe> [status]

        pe :: <number>|<index>|<file>|live
...............
Examples:
...............
        show 2066
        show pe-input-2080.bz2 status
...............

[[cmdhelp_history_graph,generate a directed graph from the PE file]]
==== `graph`

Create a graphviz graphical layout from the PE file (the
transition). Every transition contains the cluster configuration
which was active at the time. See also <<cmdhelp_configure_graph,generate a directed graph
from configuration>>.

Usage:
...............
        graph <pe> [<gtype> [<file> [<img_format>]]]

        gtype :: dot
        img_format :: `dot` output format (see the `-T` option)
...............
Example:
...............
        graph -1
        graph 322 dot clu1.conf.dot
        graph 322 dot clu1.conf.svg svg
...............

[[cmdhelp_history_diff,cluster states/transitions difference]]
==== `diff`

A transition represents a change in cluster configuration or
state. Use `diff` to see what has changed between two
transitions.

If you want to specify the current cluster configuration and
status, use the string `live`.

Normally, the first transition specified should be the one which
is older, but we are not going to enforce that.

Note that a single configuration update may result in more than
one transition.

Usage:
...............
        diff <pe> <pe> [status] [html]

        pe :: <number>|<index>|<file>|live
...............
Examples:
...............
        diff 2066 2067
        diff pe-input-2080.bz2 live status
...............

[[cmdhelp_history_session,manage history sessions]]
==== `session`

Sometimes you may want to get back to examining a particular
history period or bug report. In order to make that easier, the
current settings can be saved and later retrieved.

If the current history being examined is coming from a live
cluster the logs, PE inputs, and other files are saved too,
because they may disappear from nodes. For the existing reports
coming from `hb_report`, only the directory location is saved
(not to waste space).

A history session may also be packed into a tarball which can
then be sent to support.

Leave out subcommand to see the current session.

Usage:
...............
        session [{save|load|delete} <name> | pack [<name>] | update | list]
...............
Examples:
...............
        session save bnc966622
        session load rsclost-2
        session list
...............

=== `end` (`cd`, `up`)

The `end` command ends the current level and the user moves to
the parent level. This command is available everywhere.

Usage:
...............
        end
...............

=== `help`

The `help` command prints help for the current level or for the
specified topic (command). This command is available everywhere.

Usage:
...............
        help [<topic>]
...............

=== `quit` (`exit`, `bye`)

Leave the program.

BUGS
----
Even though all sensible configurations (and most of those that
are not) are going to be supported by the crm shell, I suspect
that it may still happen that certain XML constructs may confuse
the tool. When that happens, please file a bug report.

The crm shell will not try to update the objects it does not
understand. Of course, it is always possible to edit such objects
in the XML format.

AUTHOR
------
Dejan Muhamedagic, <dejan@suse.de>
and many OTHERS

SEE ALSO
--------
crm_resource(8), crm_attribute(8), crm_mon(8), cib_shadow(8),
ptest(8), dotty(1), crm_simulate(8), cibadmin(8)


COPYING
-------
Copyright \(C) 2008-2011 Dejan Muhamedagic. Free use of this
software is granted under the terms of the GNU General Public License (GPL).

//////////////////////
 vim:ts=4:sw=4:expandtab:
//////////////////////