ifeval::["{backend}" != "manpage"]
= `racksdb` CLI manpage

This section explains all `racksdb` command options available, with
many examples and descriptions of its behaviours. The content of the page this
also available in `racksdb(1)` manpage after installation.

endif::[]

:!example-caption:

== Synopsis

[.cli-opt]#*racksdb*# `[_GENERAL OPTIONS_] COMMAND [_COMMAND OPTIONS_]`

== General Options

[.cli-opt]#*-h, --help*#::
  Show this help message and exit.

[.cli-opt]#*-v, --version*#::
  Show RacksDB version number and exit.

[.cli-opt]#*--debug*#::
  Enable debug mode with more messages in output.

[.cli-opt]#*-b, --db*=#[.cli-optval]##_DB_##::
  Path to database. Both files and directories paths are accepted. If the path
  is a directory, all YAML files in this directory are loaded, recursively. If
  the path does not exist, an error is reported. Default value is
  [.path]#`/var/lib/racksdb/`# directory or environment variable
  [.cli-opt]#*RACKSDB_DB*# if set.

[.cli-opt]#*-s, --schema*=#[.cli-optval]##_SCHEMA_##::
  Path to RacksDB schema YAML file. If the file does not exist, an error is
  reported. Default value is [.path]#`/usr/share/racksdb/schemas/racksdb.yml`#
  or environment variable [.cli-opt]#*RACKSDB_SCHEMA*# if set.

[.cli-opt]#*-e, --ext*=#[.cli-optval]##_EXT_##::
  Path to optional RacksDB schema extensions. If the file does not exist,
  it is silently ignored by RacksDB. Default value is
  [.path]#`/etc/racksdb/extensions.yml`# or environment variable
  [.cli-opt]#*RACKSDB_EXTENSIONS*# if set.

== Commands

All commands accept [.cli-opt]#*-h, --help*# option to get details about
available option for this particular command (_ex:_ `racksdb nodes --help`).
Commands are grouped by functional purpose, and listed in lexicographical order
inside each group.

=== Analysis commands

[.cli-opt]#*dump*#::

  Dump raw data loaded from database on standard output. The generated output
  can be reloaded by RackDB.

[.cli-opt]#*schema*#::

  Dump schema, including optional extensions, on standard output.

=== Search commands

These commands are named after the entities to search in the database.

All search commands accepts the following options:

[.cli-opt]#*--fold*#::
  Fold ranges of objects and names. By default, ranges objects and names are
  expanded. This option produces more concise results.

[.cli-opt]#*--format=*#[.cli-optval]##_FORMAT_##::
  Select alternative format for command output. Possible values are *yaml* and
  *json*. The default value is *yaml* except when *-l, --list* option is
  enabled (see below).

[.cli-opt]#*-l, --list*#::
  List names of selected entities, without detailed information. When this
  option is enabled, the default output format is the raw list of names with
  one name per line. Alternative format can be selected with
  [.cli-opt]#*--format*# option (see above). The list can also be folded with
  [.cli-opt]#*--fold*# option (see above).

[.cli-opt]#*--with-objects-types*#::
  Add object types names in detailed dumps. This option has no effect with
  [.cli-opt]#*-l, --list*#.

The search commands available are the following:

[.cli-opt]#*datacenters*#::

  Dump information about datacenters.
+
--
This command accepts the following options:

*[.cli-opt]#--name*=#[.cli-optval]##_NAME_##::
  Name of the datacenter to search.

*[.cli-opt]#--tags*=#[.cli-optval]##_TAG_ [_TAG_]##::
  Select the datacenters labelled with these tags.
--

[.cli-opt]#*infrastructures*#::

  Dump information about infrastructures.
+
--
This command accepts the following options:

*[.cli-opt]#--name*=#[.cli-optval]##_NAME_##::
  Name of the infrastructure to search.

*[.cli-opt]#--tags*=#[.cli-optval]##_TAG_ [_TAG_]##::
  Select the infrastructures labelled with these tags.
--

[.cli-opt]#*nodes*#::

  Dump information about nodes.
+
--
This command accepts the following options:

*[.cli-opt]#--infrastructure*=#[.cli-optval]##_INFRASTRUCTURE_##::
  Select the nodes in this infrastructure.

*[.cli-opt]#--name*=#[.cli-optval]##_NAME_##::
  Name of the node to search.

*[.cli-opt]#--tags*=#[.cli-optval]##_TAG_ [_TAG_]##::
  Select the nodes labelled with these tags.
--

[.cli-opt]#*racks*#::

  Dump information about racks.
+
--
This command accepts the following options:

[.cli-opt]#*--name*=#[.cli-optval]##_NAME_##::
  Name of the rack to search.
--

[.cli-opt]#*tags*#::

  Get associated to object in database.
+
--
This command accepts the following options:

*[.cli-opt]#--node*=#[.cli-optval]##_NODE_##::
  Get tags associated to a specific node.

*[.cli-opt]#--infrastructure*=#[.cli-optval]##_INFRASTRUCTURE_##::
  Get tags associated to a specific infrastructure. With [.cli-opt]#*--on-nodes*#,
  get the tags associated to nodes in this infrastructure.

*[.cli-opt]#--datacenter*=#[.cli-optval]##_DATACENTER_##::
  Get tags associated to a specific datacenter. With [.cli-opt]#*--on-racks*#,
  get the tags associated to racks in this datacenter.

*[.cli-opt]#--on-nodes*#::
  With [.cli-opt]#*--infrastructure*#, get tags associated to nodes in an
  infrastructure.

*[.cli-opt]#--on-racks*#::
  With [.cli-opt]#*--datacenter*#, get tags associated to racks in a datacenter.

Either [.cli-opt]#*--node*#, [.cli-opt]#*--infrastructure*# or
[.cli-opt]#*--datacenter*# argument is required.
--

.Examples
====
[source,console]
$ racksdb datacenters

[.cli-example-desc]
Dump information about all the datacenters with their rooms and racks in YAML
format.

[source,console]
$ racksdb datacenters --tags tier2 --format json

[.cli-example-desc]
Dump information about all the datacenters that have the _tier2_ tag in JSON
format.

[source,console]
$ racksdb infrastructures

[.cli-example-desc]
Dump information about all the infrastructures with their parts and equipments.

[source,console]
$ racksdb infrastructures --tags hpc cluster

[.cli-example-desc]
Dump information about all the infrastructures that have both the _hpc_ and
_cluster_ tags.

[source,console]
$ racksdb infrastructures --list

[.cli-example-desc]
List names of all infrastructures in database.

[source,console]
$ racksdb nodes --name cn001

[.cli-example-desc]
Dump information node named _cn001_.

[source,console]
$ racksdb nodes --tags compute

[.cli-example-desc]
Dump information of all nodes that have the _compute_ tag.

[source,console]
$ racksdb nodes --tags compute --list --fold

[.cli-example-desc]
Folded names of all nodes that have the _compute_ tag.

[source,console]
$ racksdb nodes --infrastructure tiger --tags server --list --format json

[.cli-example-desc]
List of names of all nodes in _tiger_ infrastructure that also have the _server_
tag in JSON format.

[source,console]
$ racksdb racks

[.cli-example-desc]
Dump information about all racks with their equipments.

[source,console]
$ racksdb racks --name R7-06 --fold

[.cli-example-desc]
Dump information about rack _R7-A06_ with folded node range.

[source,console]
$ racksdb tags --node cn001

[.cli-example-desc]
Get all tags associated to node _cn001_.

[source,console]
$ racksdb tags --infrastructure tiger

[.cli-example-desc]
Get all tags associated to infrastructure _tiger_.

[source,console]
$ racksdb tags --infrastructure tiger --on-nodes

[.cli-example-desc]
Get all tags associated to nodes in infrastructure _tiger_.

[source,console]
$ racksdb tags --datacenter paris

[.cli-example-desc]
Get all tags associated to datacenter _paris_.

[source,console]
$ racksdb tags --datacenter paris --on-racks

[.cli-example-desc]
Get all tags associated to racks in datacenter _paris_.
====

[#draw]
=== Draw commands

The [.cli-opt]#*draw*# command is used to generate image file with graphical
representations of database entities. This command is used in combination with a
sub-command to indicate the type of database entity.

This command accepts the following options:

[.cli-opt]#*--name*=#[.cli-optval]##_NAME_##::
  Name of the entity to represent. This option is required.

[.cli-opt]#*--format*=#[.cli-optval]##_FORMAT_##::
  File format of the generated image file. Possible values are _png_, _svg_ and
  _pdf_. Default value is _png_.

[.cli-opt]#*--parameters*=#[.cli-optval]##_PARAMETERS_##::
  Path to YAML xref:drawparams.adoc[drawing parameters] file. With special value
  `-`, drawings parameters are read on standard input.

[.cli-opt]#*--drawings-schema*=#[.cli-optval]##_DRAWINGS_SCHEMA_##::
  Path to drawing parameters schema YAML file. Default value is
  [.path]#`/usr/share/racksdb/drawings.yml`#.

[.cli-opt]#*-c, --coordinates*=#[.cli-optval]##_COORDINATES_##::
  Dump pixels coordinates of equipment and racks in the graphical
  representations in an additional file. The value of the option is the path of
  the generated coordiantes file. This value is optional. When this option is
  used without value, coordinates are dumped into a file named
  `coordinates.FORMAT` where `FORMAT` is the coordinates format (_ex:_ `json`).

[.cli-opt]#*--coordinates-format*=#[.cli-optval]##_COORDINATES_FORMAT_##::
  Format of coordinates files. Possible values are `json` and `yaml`. Default
  value is `json`.

The following sub-commands are available:

[.cli-opt]#*infrastructure*#::

  Draw racks of an infrastructure, grouped by rows. The front side of the racks
  are represented with the equipments of the infrastructure.

[.cli-opt]#*room*#::

  Draw datacenter room map with its racks. The room is represented from the top
  view with rows and racks at their position in this room.

.Examples
====
[source,console]
$ racksdb draw room --name=atlas

[.cli-example-desc]
Generate the map of datacenter room _atlas_ with all its racks in PNG image file
`atlas.png`.

[source,console]
$ racksdb draw infrastructure --name=tiger --format=svg

[.cli-example-desc]
Generate SVG image file `tiger.svg` with racks and equipments used in _tiger_
infrastructure.

[source,console]
$ racksdb draw infrastructure --name=tiger --format=pdf --parameters=custom.yaml

[.cli-example-desc]
Generate PDF image file `tiger.pdf` with racks and equipments used in _tiger_
infrastructure with custom xref:drawparams.adoc[drawing parameters] defined in
`custom.yaml`.

[source,console]
$ racksdb draw room --name=noisy --parameters=- < custom.yaml

[.cli-example-desc]
Generate the map of datacenter room _noisy_ with custom drawing parameters read
on standard input fed with content of `custom.yaml`.

[source,console]
$ racksdb draw infrastructure --name=mercury --coordinates

[.cli-example-desc]
Generate graphical representation of _mercury_ infrastructure and dump
coordinates of equipment in JSON format in a file named `coordinates.json`.

[source,console]
$ racksdb draw infrastructure --name=tiger --coordinates --coordinates-format yaml

[.cli-example-desc]
Generate graphical representation of _tiger_ infrastructure and dump
coordinates of equipment in YAML format in a file named `coordinates.yaml`.

[source,console]
$ racksdb draw room --name=noisy --coordinates=noisy-coordinates.json

[.cli-example-desc]
Generate graphical representation of _noisy_ datacenter room and dump
coordinates of racks in JSON format in a file named `noisy-coordinates.json`.
====

== Environment variables

When a command-line option above is omitted, `racksdb` uses the following
environment variables if they are set to a non-empty value:

[.cli-opt]#*RACKSDB_SCHEMA*#::
  Path to the RacksDB schema YAML file.

[.cli-opt]#*RACKSDB_EXTENSIONS*#::
  Path to optional schema extensions.

[.cli-opt]#*RACKSDB_DB*#::
  Path to the database.

Command-line options always override environment variables.

== Exit status

*0*::
  `racksdb` has processed command with success.

*1*::
  `racksdb` encountered an error.
