Skip to content

DOCTEAM-1776: intro to crmsh #769

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tahliar wants to merge 11 commits into
base: main
Choose a base branch
from
Open

DOCTEAM-1776: intro to crmsh #769

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
b7ef372
Basic migration of topics
tahliar Jul 10, 2026
76ce066
Add cluster status topic
tahliar Jul 14, 2026
565224d
Editing
tahliar Jul 16, 2026
9bdae43
Remove cluster diagram; dotty deprecated
tahliar Jul 17, 2026
1275b9f
Editing
tahliar Jul 17, 2026
5f73729
Editing
tahliar Jul 21, 2026
80ce9d0
Editing
tahliar Jul 24, 2026
eb3d896
Add snippets
tahliar Aug 11, 2026
b895ed2
Editing
tahliar Aug 13, 2026
495c4a5
Add intro abstract
tahliar Aug 14, 2026
b45cc6b
Remove unused file
tahliar Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions DC-HA-crmsh-introduction
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
MAIN="ha-crmsh-introduction.asm.xml"
SRC_DIR="articles"
IMG_SRC_DIR="images"

## Profiling
PROFOS="sleha"
#PROFCONDITION="PRODUCTNUMBER"
# Use the STRUCTID if there are several structures in one assembly file
#STRUCTID="STRUCTURE-ID"
#PROFARCH="x86_64;zseries;power;aarch64"

DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat"

STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns"
143 changes: 143 additions & 0 deletions articles/ha-crmsh-introduction.asm.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE assembly
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>

<!-- refers to legacy doc: https://github.com/SUSE/doc-sleha/blob/main/xml/ha_config_cli.xml -->

<assembly version="5.2" xml:lang="en"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns="http://docbook.org/ns/docbook">

<!-- R E S O U R C E S -->
<!-- Glue files
<resources>
<resource xml:id="_glue-example" href="../glues/glue.xml"/>
</resources> -->
<!-- Concept files -->
<resources>
<resource xml:id="_ha-crmsh-what-is" href="../concepts/ha-crmsh-what-is.xml"/>
</resources>
<!-- Tasks -->
<resources>
<resource xml:id="_ha-crmsh-using-interactive-mode" href="../tasks/ha-crmsh-using-interactive-mode.xml"/>
<resource xml:id="_ha-crmsh-using-shell-scripts" href="../tasks/ha-crmsh-using-shell-scripts.xml"/>
<resource xml:id="_ha-crmsh-using-cluster-scripts" href="../tasks/ha-crmsh-using-cluster-scripts.xml"/>
<resource xml:id="_ha-crmsh-testing-with-shadow-configuration" href="../tasks/ha-crmsh-testing-with-shadow-configuration.xml"/>
<resource xml:id="_ha-crmsh-debugging-cluster-configuration-changes" href="../tasks/ha-crmsh-debugging-cluster-configuration-changes.xml"/>
<resource xml:id="_ha-crmsh-managing-sensitive-parameters" href="../tasks/ha-crmsh-managing-sensitive-parameters.xml"/>
</resources>
<!-- References -->
<resources>
<resource xml:id="_ha-crmsh-help-commands" href="../references/ha-crmsh-help-commands.xml"/>
<resource xml:id="_ha-crmsh-status-commands" href="../references/ha-crmsh-status-commands.xml"/>
<resource xml:id="_ha-glossary" href="../references/ha-glossary.xml"/>
</resources>
<!-- Legal -->
<resources>
<resource href="../common/legal.xml" xml:id="_legal">
<description>Legal Notice</description>
</resource>
<resource href="../common/license_gfdl1.2.xml" xml:id="_gfdl">
<description>GNU Free Documentation License</description>
</resource>
</resources>

<!-- S T R U C T U R E -->
<structure renderas="article" xml:id="ha-crmsh-introduction" xml:lang="en">
<merge>
<title>Introduction to the &crmshell;</title>
<revhistory xml:id="rh-ha-crmsh-introduction">
<revision><date>2026-07-10</date><!-- Change date after review -->
<revdescription>
<para>
Initial version
</para>
</revdescription>
</revision>
</revhistory>
<meta name="maintainer" content="tahlia.richardson@suse.com" its:translate="no"/>
<meta name="architecture">
<phrase>&x86-64;</phrase>
<phrase>&power;</phrase>
<phrase>&zseries;</phrase>
</meta>
<meta name="productname" its:translate="no">
<productname version="&productnumber;" os="sleha">&productname;</productname>
</meta>
<meta name="title" its:translate="yes">Introduction to the &crmshell;</meta>
<meta name="description" its:translate="yes">How to install, configure and manage &ha; clusters using the &crmshell; command-line interface</meta>
<meta name="social-descr" its:translate="yes">Manage &ha; clusters with the &crmshell;</meta>
<meta name="category" its:translate="no">
<phrase>Administration</phrase>
</meta>
<meta name="task" its:translate="no">
<phrase>Administration</phrase>
<phrase>Clustering</phrase>
<phrase>High Availability</phrase>
</meta>
<meta name="series" its:translate="no">Products &amp; Solutions</meta>
<dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
<dm:bugtracker>
<dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
<dm:component>Documentation</dm:component>
<dm:product>SUSE Linux Enterprise High Availability &productnumber;</dm:product>
<dm:assignee>tahlia.richardson@suse.com</dm:assignee>
</dm:bugtracker>
<dm:translation>yes</dm:translation>
</dm:docmanager>
<abstract>
<para>
The &crmshell; (&crmsh;) is a command-line interface for installing, configuring and
managing &sleha; clusters. It simplifies complex cluster operations by providing a more
readable line-based syntax for interacting with &pace;'s XML configuration format.
This article introduces some of the &crmshell;'s basic concepts and usage.
</para>
<para><emphasis>Requirements:</emphasis></para>
<itemizedlist>
<listitem><para>Access to a cluster node with &rootuser; privileges or &sudo; authorization</para></listitem>
<listitem><para>Passwordless SSH key authentication between the cluster nodes</para></listitem>
</itemizedlist>
</abstract>
</merge>
<module resourceref="_ha-crmsh-what-is" renderas="section"/>
<module resourceref="_ha-crmsh-help-commands" renderas="section">
<merge>
<title>Help commands</title>
</merge>
</module>
<module resourceref="_ha-crmsh-status-commands" renderas="section">
<merge>
<title>Status commands</title>
</merge>
</module>
<module resourceref="_ha-crmsh-using-interactive-mode" renderas="section">
<merge>
<title>Using interactive mode</title>
</merge>
</module>
<module resourceref="_ha-crmsh-using-shell-scripts" renderas="section">
<merge>
<title>Using shell scripts</title>
</merge>
</module>
<module resourceref="_ha-crmsh-using-cluster-scripts" renderas="section">
<merge>
<title>Using cluster scripts</title>
</merge>
</module>
<module resourceref="_ha-crmsh-testing-with-shadow-configuration" renderas="section"/>
<module resourceref="_ha-crmsh-debugging-cluster-configuration-changes" renderas="section"/>
<module resourceref="_ha-crmsh-managing-sensitive-parameters" renderas="section"/>
<module resourceref="_legal"/>
<module resourceref="_gfdl">
<output renderas="appendix"/>
</module>
<module resourceref="_ha-glossary" renderas="glossary"/>
</structure>
</assembly>
139 changes: 139 additions & 0 deletions concepts/ha-crmsh-what-is.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>

<!-- refers to legacy doc: https://github.com/SUSE/doc-sleha/blob/main/xml/ha_config_cli.xml -->

<topic xml:id="ha-crmsh-what-is"
role="concept" xml:lang="en"
xmlns="http://docbook.org/ns/docbook" version="5.2"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion">
<info>
<title>What is the &crmshell;?</title>
<meta name="maintainer" content="tahlia.richardson@suse.com" its:translate="no"/>
<abstract>
<para>
The &crmshell; (&crmsh;) is a command-line interface for installing, configuring and
managing &sleha; clusters. It simplifies complex cluster operations by providing a more
readable line-based syntax for interacting with &pace;'s XML configuration format.
</para>
<para>
The top level of the &crmshell; is the <command>crm</command> command.
The <command>crm</command> command includes multiple subcommands to manage resources, CIBs,
nodes, resource agents, and others. It also has a thorough help system with embedded
examples. You can run most <command>crm</command> commands from any node in the cluster.
</para>
<para>
&crmshell; events are logged to <filename>/var/log/crmsh/crmsh.log</filename>.
</para>
</abstract>
</info>

<section xml:id="ha-crmsh-what-is-using">
<title>Using the &crmshell;</title>
<para>
You can use the &crmshell; in multiple ways:
</para>
<variablelist>
<varlistentry>
<term>Command line (single-shot)</term>
<listitem>
<para>
Run a single <command>crm</command> command in full, including a subcommand
and parameters. Tab completion is supported. For example,
<command>crm config</command><keycap function="tab"/> completes the word, and
<command>crm configure</command><keycap function="tab"/><keycap function="tab"/>
lists the available subcommands.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Interactive mode</term>
<listitem>
<xi:include href="../snippets/ha-crmsh-interactive-mode.xml"/>
</listitem>
</varlistentry>
<varlistentry>
<term>Shell scripts</term>
<listitem>
<xi:include href="../snippets/ha-crmsh-shell-scripts.xml"/>
</listitem>
</varlistentry>
<varlistentry>
<term>Cluster scripts</term>
<listitem>
<xi:include href="../snippets/ha-crmsh-cluster-scripts.xml"/>
</listitem>
</varlistentry>
</variablelist>
</section>

<section xml:id="ha-crmsh-what-is-authentication">
<title>User privileges</title>
<para>
Managing a cluster requires sufficient privileges. The following users can run the
<command>crm</command> command and its subcommands:
</para>
<itemizedlist>
<listitem>
<para>
The &rootuser; user or a user with <command>sudo</command> privileges. These users have
full privileges for &crmsh; operations such as <command>crm cluster init</command>
and <command>crm report</command>. They can also make changes to the CIB, such as adding
resources and constraints.
</para>
</listitem>
<listitem>
<para>
The CRM owner user. This is typically the user <systemitem>hacluster</systemitem>, which
is created by default if you install the cluster with <command>crm cluster init</command>.
This user can make changes to the CIB but has limited privileges for operations that use
SSH, such as <command>crm report</command>.
</para>
</listitem>
</itemizedlist>
</section>

<section xml:id="ha-crmsh-what-is-ssh-key-authentication">
<title>SSH key authentication</title>
<para>
For operations that use SSH, the cluster uses passwordless SSH access for communication
between the nodes. If you install the cluster with <command>crm cluster init</command>, the
script checks for SSH keys and generates them if they don't already exist. If you install
the cluster manually, you must configure the SSH keys yourself.
</para>
<para>
In most cases, the &rootuser; or <command>sudo</command> user's SSH keys must exist (or be
generated) on the node. Alternatively, a <command>sudo</command> user's SSH keys can exist
on a local machine and be passed to the node via SSH agent forwarding. This can be useful
if you need to avoid storing SSH keys on the nodes.
</para>
</section>

<section xml:id="ha-crmsh-what-is-more-info">
<title>For more information</title>
<itemizedlist>
<listitem>
<para>
<command>man crm</command>
</para>
</listitem>
<listitem>
<para>
<command>crm help overview</command>
</para>
</listitem>
<listitem>
<para>
<link xlink:href="https://crmsh.github.io/documentation"/>
</para>
</listitem>
</itemizedlist>
</section>
</topic>
12 changes: 6 additions & 6 deletions concepts/ha-what-is.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,21 +158,21 @@
<term>User-friendly administration tools</term>
<listitem>
<para>
&sleha; includes tools for configuration and administration:
&sleha; includes the following tools for configuration and administration:
</para>
<itemizedlist>
<listitem>
<para>
The <emphasis>&crmshell;</emphasis> (&crmsh;) is a command-line interface for
installing and setting up &ha; clusters, configuring resources, and performing
monitoring and administration tasks.
installing, configuring and managing &sleha; clusters. You can run most &crmshell;
commands from any node in the cluster.
</para>
</listitem>
<listitem>
<para>
<emphasis>&hawk;</emphasis> is a Web-based graphical interface for monitoring and
administration of &ha; clusters. It can be accessed using a Web browser from any
Linux or non-Linux machine that can connect to the cluster nodes.
<emphasis>&hawk;</emphasis> is a Web-based graphical interface for configuring and
managing &ha; clusters. You can use &hawk; on any Linux or non-Linux machine with a
Web browser and network access to the cluster nodes.
</para>
</listitem>
</itemizedlist>
Expand Down
68 changes: 68 additions & 0 deletions references/ha-crmsh-help-commands.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>

<!-- refers to legacy doc: https://github.com/SUSE/doc-sleha/blob/main/xml/ha_config_cli.xml -->

<topic xml:id="ha-crmsh-help-commands"
role="reference" xml:lang="en"
xmlns="http://docbook.org/ns/docbook" version="5.2"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion">
<info>
<title>&crmshell; help commands</title>
<meta name="maintainer" content="tahlia.richardson@suse.com" its:translate="no"/>
<abstract>
<para>
The <command>crm</command> command has multiple options for showing help text:
</para>
</abstract>
</info>

<itemizedlist>
<listitem>
<para>
Show the usage of <command>crm</command> and its command-line options:
</para>
<screen>&prompt.user;<command>sudo crm --help</command></screen>
</listitem>
<listitem>
<para>
List the conceptual help topics:
</para>
<screen>&prompt.user;<command>sudo crm help topics</command></screen>
</listitem>
<listitem>
<para>
List all the available subcommands:
</para>
<screen>&prompt.user;<command>sudo crm help</command></screen>
</listitem>
<listitem>
<para>
Show the help text for a subcommand. For example:
</para>
<screen>&prompt.user;<command>sudo crm configure help</command></screen>
</listitem>
<listitem>
<para>
Show the syntax, usage, and examples for a command within a subcommand. For example:
</para>
<screen>&prompt.user;<command>sudo crm configure help group</command></screen>
<para>
This command also has the same result:
</para>
<screen>&prompt.user;<command>sudo crm help configure group</command></screen>
</listitem>
</itemizedlist>
<para>
Unlike the <option>--help</option> option, the <command>help</command> subcommand opens a text
viewer. The text viewer allows you to scroll up or down and read the output more comfortably.
To leave the text viewer, press the <keycap>Q</keycap> key.
</para>
</topic>
Loading