From 00a772785d01d434052df27b08475c663cff1907 Mon Sep 17 00:00:00 2001
From: Laurence <laurence@qsplace.co.uk>
Date: Sat, 27 Jun 2026 19:12:18 +0100
Subject: [PATCH] doc/man: add man pages for previously undocumented client
 commands

These commands ship in confluent_client/bin but had no .ronn man page, so
they did not appear in the generated documentation. Add man pages matching
the existing style, with synopsis and options taken from each command's
argument parser:

- confluent2ansible: export node inventory to an Ansible hosts file
- confluent2lxca: export nodes to a Lenovo XClarity Administrator bulk import CSV
- confluent2xcat: export nodes to an xCAT stanza definition (and optional macs.csv)
- dir2img: build a FAT image from a directory for nodemedia upload
- nodecertutil: manage BMC CA certificates and sign BMC certificates
- nodegrouprename: rename a node group
- noderename: rename nodes
---
 .../doc/man/confluent2ansible.ronn            | 35 +++++++++++++
 confluent_client/doc/man/confluent2lxca.ronn  | 30 +++++++++++
 confluent_client/doc/man/confluent2xcat.ronn  | 36 +++++++++++++
 confluent_client/doc/man/dir2img.ronn         | 41 +++++++++++++++
 confluent_client/doc/man/nodecertutil.ronn    | 50 +++++++++++++++++++
 confluent_client/doc/man/nodegrouprename.ronn | 27 ++++++++++
 confluent_client/doc/man/noderename.ronn      | 34 +++++++++++++
 7 files changed, 253 insertions(+)
 create mode 100644 confluent_client/doc/man/confluent2ansible.ronn
 create mode 100644 confluent_client/doc/man/confluent2lxca.ronn
 create mode 100644 confluent_client/doc/man/confluent2xcat.ronn
 create mode 100644 confluent_client/doc/man/dir2img.ronn
 create mode 100644 confluent_client/doc/man/nodecertutil.ronn
 create mode 100644 confluent_client/doc/man/nodegrouprename.ronn
 create mode 100644 confluent_client/doc/man/noderename.ronn

diff --git a/confluent_client/doc/man/confluent2ansible.ronn b/confluent_client/doc/man/confluent2ansible.ronn
new file mode 100644
index 00000000..e9d9a5f1
--- /dev/null
+++ b/confluent_client/doc/man/confluent2ansible.ronn
@@ -0,0 +1,35 @@
+confluent2ansible(8) -- Export confluent node inventory to an Ansible hosts file
+================================================================================
+
+## SYNOPSIS
+
+`confluent2ansible <noderange> -o <ansible.hosts>` [`-a`]
+
+## DESCRIPTION
+
+`confluent2ansible` reads the nodes matched by `<noderange>` from confluent and
+writes a corresponding Ansible inventory (hosts) file, allowing an existing
+confluent inventory to be used directly by Ansible.
+
+## OPTIONS
+
+* `-o FILE`, `--output=FILE`:
+    Write the Ansible hosts file to FILE.
+
+* `-a`, `--append`:
+    Append to an existing hosts file rather than overwriting it.
+
+* `-h`, `--help`:
+  Show help message and exit
+
+## EXAMPLES
+
+* Write an Ansible hosts file for the compute group:
+    `# confluent2ansible compute -o /etc/ansible/hosts`
+
+* Append a rack to an existing hosts file:
+    `# confluent2ansible rack3 -o /etc/ansible/hosts -a`
+
+## SEE ALSO
+
+confluent2xcat(8), confluent2lxca(8), nodelist(8)
diff --git a/confluent_client/doc/man/confluent2lxca.ronn b/confluent_client/doc/man/confluent2lxca.ronn
new file mode 100644
index 00000000..05f09c5e
--- /dev/null
+++ b/confluent_client/doc/man/confluent2lxca.ronn
@@ -0,0 +1,30 @@
+confluent2lxca(8) -- Export confluent nodes to a Lenovo XClarity Administrator bulk import file
+==============================================================================================
+
+## SYNOPSIS
+
+`confluent2lxca <noderange> -o <bulkimport.csv>`
+
+## DESCRIPTION
+
+`confluent2lxca` reads the nodes matched by `<noderange>` from confluent and
+writes a CSV file suitable for bulk import into Lenovo XClarity Administrator
+(LXCA), so that hardware already known to confluent can be brought under LXCA
+management.
+
+## OPTIONS
+
+* `-o FILE`, `--output=FILE`:
+    Write the XClarity Administrator bulk import CSV to FILE.
+
+* `-h`, `--help`:
+  Show help message and exit
+
+## EXAMPLES
+
+* Generate a bulk import file for all nodes:
+    `# confluent2lxca everything -o bulkimport.csv`
+
+## SEE ALSO
+
+confluent2xcat(8), confluent2ansible(8), nodelist(8)
diff --git a/confluent_client/doc/man/confluent2xcat.ronn b/confluent_client/doc/man/confluent2xcat.ronn
new file mode 100644
index 00000000..e6eea202
--- /dev/null
+++ b/confluent_client/doc/man/confluent2xcat.ronn
@@ -0,0 +1,36 @@
+confluent2xcat(8) -- Export confluent nodes to an xCAT stanza definition
+========================================================================
+
+## SYNOPSIS
+
+`confluent2xcat <noderange> -o <xcatnodes.def>` [`-m <macs.csv>`]
+
+## DESCRIPTION
+
+`confluent2xcat` reads the nodes matched by `<noderange>` from confluent and
+writes an xCAT object definition stanza file, easing interoperation with or
+migration to/from an xCAT environment. Optionally it can also write an xCAT
+`macs.csv` file capturing the MAC addresses of the nodes.
+
+## OPTIONS
+
+* `-o FILE`, `--output=FILE`:
+    Write the xCAT stanza definition to FILE.
+
+* `-m FILE`, `--macs=FILE`:
+    Write an xCAT macs.csv file to FILE.
+
+* `-h`, `--help`:
+  Show help message and exit
+
+## EXAMPLES
+
+* Export all nodes to an xCAT stanza file:
+    `# confluent2xcat everything -o xcatnodes.def`
+
+* Also capture MAC addresses:
+    `# confluent2xcat everything -o xcatnodes.def -m macs.csv`
+
+## SEE ALSO
+
+confluent2ansible(8), confluent2lxca(8), nodelist(8)
diff --git a/confluent_client/doc/man/dir2img.ronn b/confluent_client/doc/man/dir2img.ronn
new file mode 100644
index 00000000..6e3dabac
--- /dev/null
+++ b/confluent_client/doc/man/dir2img.ronn
@@ -0,0 +1,41 @@
+dir2img(8) -- Create a disk image from a directory for nodemedia upload
+=======================================================================
+
+## SYNOPSIS
+
+`dir2img` [`-e <extra_mb>`] [`-s <total_mb>`] `<directory> <imagefile>` [`<label>`]
+
+## DESCRIPTION
+
+`dir2img` packages the contents of `<directory>` into a FAT-formatted "big
+floppy" disk image written to `<imagefile>`. The resulting image is suitable
+for upload with nodemedia(8) so that its files are presented to a node as
+removable media. An optional volume `<label>` may be supplied.
+
+By default the image is sized to fit the directory contents. The `-e` and `-s`
+options allow reserving additional free space.
+
+This command relies on `mtools` (specifically `mformat` and `mcopy`) being
+installed.
+
+## OPTIONS
+
+* `-e EXTRA_MB`:
+    Reserve EXTRA_MB megabytes of free space in the image in addition to the
+    space required for the directory contents.
+
+* `-s TOTAL_MB`:
+    Make the image TOTAL_MB megabytes in total, rather than sizing it to the
+    directory contents.
+
+## EXAMPLES
+
+* Create an image from a directory:
+    `# dir2img /var/tmp/drivers drivers.img`
+
+* Create a 64 MB labelled image:
+    `# dir2img -s 64 /var/tmp/drivers drivers.img DRIVERS`
+
+## SEE ALSO
+
+nodemedia(8)
diff --git a/confluent_client/doc/man/nodecertutil.ronn b/confluent_client/doc/man/nodecertutil.ronn
new file mode 100644
index 00000000..ffa49c2a
--- /dev/null
+++ b/confluent_client/doc/man/nodecertutil.ronn
@@ -0,0 +1,50 @@
+nodecertutil(8) -- Manage BMC CA certificates and sign BMC certificates
+=======================================================================
+
+## SYNOPSIS
+
+`nodecertutil <noderange> <command>` [<args>]
+
+## DESCRIPTION
+
+`nodecertutil` manages the certificate authority (CA) certificates trusted by
+the baseboard management controllers (BMCs) of the nodes matched by
+`<noderange>`, and can sign a BMC certificate. One of the subcommands below
+must be supplied.
+
+## COMMANDS
+
+* `installbmccacert <filename>`:
+    Install the CA certificate contained in `<filename>` onto the BMCs.
+
+* `removebmccacert <id>`:
+    Remove the CA certificate identified by `<id>` from the BMCs. Use
+    `listbmccacerts` to discover the identifiers.
+
+* `listbmccacerts`:
+    List the CA certificates currently installed on the BMCs.
+
+* `signbmccert` [`--days <days>`] [`--added-names <names>`]:
+    Sign a BMC certificate. `--days` is required and sets the number of days
+    the certificate is valid for; `--added-names` adds additional subject
+    alternative names to the certificate.
+
+## OPTIONS
+
+* `-h`, `--help`:
+  Show help message and exit
+
+## EXAMPLES
+
+* List the CA certificates installed on a node's BMC:
+    `# nodecertutil n1 listbmccacerts`
+
+* Install a CA certificate on a range of nodes:
+    `# nodecertutil n1-n4 installbmccacert /etc/confluent/myca.pem`
+
+* Sign a BMC certificate valid for one year:
+    `# nodecertutil n1 signbmccert --days 365`
+
+## SEE ALSO
+
+nodeconfig(8), nodeattrib(8)
diff --git a/confluent_client/doc/man/nodegrouprename.ronn b/confluent_client/doc/man/nodegrouprename.ronn
new file mode 100644
index 00000000..a8208996
--- /dev/null
+++ b/confluent_client/doc/man/nodegrouprename.ronn
@@ -0,0 +1,27 @@
+nodegrouprename(8) -- Rename a node group in the confluent management service
+=============================================================================
+
+## SYNOPSIS
+
+`nodegrouprename <group> <newname>`
+
+## DESCRIPTION
+
+`nodegrouprename` changes the name of an existing node group from `<group>` to
+`<newname>`. Group membership and the attributes defined on the group are
+preserved under the new name.
+
+## OPTIONS
+
+* `-h`, `--help`:
+  Show help message and exit
+
+## EXAMPLES
+
+* Rename a group:
+    `# nodegrouprename compute computenodes`
+    `compute: computenodes`
+
+## SEE ALSO
+
+nodegroupdefine(8), nodegroupremove(8), nodegroupattrib(8), nodegrouplist(8)
diff --git a/confluent_client/doc/man/noderename.ronn b/confluent_client/doc/man/noderename.ronn
new file mode 100644
index 00000000..8a13a654
--- /dev/null
+++ b/confluent_client/doc/man/noderename.ronn
@@ -0,0 +1,34 @@
+noderename(8) -- Rename nodes in the confluent management service
+=================================================================
+
+## SYNOPSIS
+
+`noderename <noderange> <newname>`
+
+## DESCRIPTION
+
+`noderename` changes the name of the node or nodes matched by the given
+noderange to `<newname>`. As with other attribute changes, the rename is
+applied through the confluent datastore and does not by itself alter the
+operating system hostname of a running node.
+
+When renaming more than one node, `<newname>` is normally an expression so that
+each matched node receives a distinct name (see noderange(5) and the attribute
+expression syntax).
+
+## OPTIONS
+
+* `-h`, `--help`:
+  Show help message and exit
+
+## EXAMPLES
+
+* Rename a single node:
+    `# noderename n1 n2`
+
+* Rename a range of nodes using an expression:
+    `# noderename n1-n4 'compute{n1}'`
+
+## SEE ALSO
+
+nodedefine(8), noderemove(8), nodeattrib(8), noderange(5)