Metadata-Version: 2.4
Name: orac
Version: 0.1.0
Summary: Free software client for the server management controller
Author: orac authors
License: GPL-2.0-or-later
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.6
License-File: LICENSE
Requires-Dist: cliff>=3.4
Requires-Dist: oslo.config>=9.0.0
Requires-Dist: oslo.log>=5.0.0
Dynamic: author
Dynamic: description
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

====
orac
====

.. contents::

What is orac?
-------------

Free software client for the local (in-band) management interface of
rack servers, aiming for command-line compatibility with the
baseboard management controller's (BMC) original management tools.

``orac`` talks to the server's BMC either from the managed server's
operating system over the standard in-band IPMI interface
(``/dev/ipmi0``), or remotely over HTTPS to the BMC's web server
(``orac -r <host> -u <user> -p <password> <command>``, the original
client's remote mode).  Both transports use a protocol that was
established by clean-room reverse engineering of the documented
behaviour of the hardware interface.  It contains no code from, and
is not affiliated with, the original vendor.

The command line tool is installed as ``orac``.
The command line is parsed with ``oslo.config`` and logs through
``oslo.log``: global options come first (``--device``, the remote-mode
options ``-r`` / ``-u`` / ``-p``, ``--debug``, ``--config-file``,
``--version``), followed by a subcommand and its verbatim arguments::

    orac get idrac.info
    orac set iDRAC.Users.2.Enable Enabled
    orac jobqueue create BIOS.Setup.1-1
    orac -r bmc.example -u root -p calvin getsysinfo

A bash completion script is installed into
``share/bash-completion/completions``.

Why a new tool?
---------------

A server that can only be managed through the vendor's proprietary
software is a server its owner does not fully control.  We consider
it unacceptable that hardware is sold this way: the BMC is an
integral part of the machine one paid for, and driving it should
never depend on a closed, vendor-licensed client.

On top of the licensing problem, the original tool is not convenient
to use.  It renders everything as text meant for a person sitting at
a terminal, offers no structured output, no completion and no
reusable library, and scripting around it becomes an exercise in
screen scraping.

``orac`` is our answer: the same commands for automation parity,
plus what a modern tool should offer — an object-verb command line
with the usual structured formatters (CSV, JSON, YAML), a bash
completion that knows the whole target grammar, and a full screen
browser for interactive work.  We believe the result is a better
client than the original, not merely an open one.

And because ``orac`` is free software (GPL-2+), that value
compounds: anyone can study it, fix it, package it, and integrate it
into other software.  A management tool should be a building block,
not a locked box.

The friendly CLI
----------------

A second, object-verb command line shares the same binary: an
OpenStack-style surface on top of ``cliff``.  The first positional
token picks the surface; the legacy pass-through CLI above is
untouched.  The friendly commands render structured tables through the
standard formatters (``-f csv|json|table|value|shell|yaml``,
``--column``, ``--sort-column``) and both transports are available
through the same global options::

    orac system show
    orac log list --type sel --severity Critical --latest 10
    orac sensor list
    orac inventory list [--software]
    orac job list
    orac job create BIOS.Setup.1-1 --reset-type graceful
    orac job delete --job JID_XXX --yes-i-really-mean-it
    orac raw racdump

With the table formatter, that reads::

    $ orac system show
    +--------------+------------+
    | Attribute    | Value      |
    +--------------+------------+
    | #build       | 5          |
    | #cpldversion | 1.1.4      |
    | #servergen   | 15G        |
    | #version     | 7.20.60.50 |
    +--------------+------------+

    $ orac bios sysprofilesettings show
    +-----------------+------------------------+
    | Attribute       | Value                  |
    +-----------------+------------------------+
    | procpwrperf     | OsDbpm                 |
    | procturbomode   | Enabled                |
    | sysprofile      | PerfPerWattOptimizedOs |
    | workloadprofile | NotConfigured          |
    +-----------------+------------------------+

    $ orac idrac nic selection show
    +-----------+-----------+
    | Attribute | Value     |
    +-----------+-----------+
    | selection | Dedicated |
    +-----------+-----------+

    $ orac log list --type sel --severity Critical --latest 10
    +--------+---------------------+--------+----------+---------------------------------------------+
    | Record | Date/Time           | Source | Severity | Description                                 |
    +--------+---------------------+--------+----------+---------------------------------------------+
    | 2      | 11/01/2021 14:29:30 | system | Critical | The chassis is open while the power is off. |
    +--------+---------------------+--------+----------+---------------------------------------------+

The leading ``#`` marks the attributes the BMC reports as
read-only.

The BMC's ``get`` / ``set`` grammar is offered with the verbs
appended, in lowercase, so command lines read the same way they
complete.  Path words resolve against the full target table of the
bash completion, case-insensitively, and a group-name component may be
elided from its word (``bootsettings`` matches
``BiosBootSettings``)::

    orac bios bootsettings setbootorderen show
    orac bios bootsettings setbootorderen set On

The command help of a target path re-uses the BMC's own help
text for the attribute, and where the BMC documents an
enumeration, the value of ``set`` completes from it (``orac idrac nic
autoconfig set <TAB>`` offers ``0 1 2 Disabled``).

Every BMC subcommand without a dedicated friendly command stays
reachable through ``orac raw`` verbatim, which also propagates the
BMC's own exit status.

The terminal UI
---------------

``orac tui`` is a full screen (curses) browser of the same grammar,
in the Molokai style: attributes render as a two column table with
the names aligned right and the values in their own column, the
cursor bar covers the value only, entries opening another screen
sit in the same frame, left aligned and carrying ``...`` (teal),
editable values are green, read-only values (the BMC marks
them with ``#``) are purple and values changed in this session are
orange.  On top, above the path indicator, the first line leads
with the server's hostname in the shell's teal and closes with the
grey GPL notice right aligned; under it, a system header gathered
in the background and only shown once complete: the BMC version,
the server model, the service tag, the current IPv4 address of the
iDRAC and the port in use (dedicated, LOM1, ...), the values in a
muted orange.  While a list overflows its area, a proportional
scrollbar rides the right edge and the rules carry the scroll
markers (``v 12 more`` / ``^ 14 above``); PgUp and PgDn page
through the rows and Home/End jump to the ends.
Enter descends, Esc goes back
one screen (the cursor returns to the entry row), Ctrl-C leaves;
confirmed values apply immediately, ordered device lists (the boot
sequences) edit in a reordering widget, and settings the BMC
holds pending are offered as a jobqueue entry when leaving the
browser.  The editors open with the value currently in use
preselected: enumerations offer one entry per documented value,
shown by its label (``None``, ``LOM1``) and applying the value
itself.  Record targets the grammar carries without attribute paths
(sysinformation, the iDRAC info and telemetry records) open their
rendering: the attributes the BMC does not mark read-only
edit in place (sysprofile and friends), the others stay read-only.

.. image:: orac-tui.png
   :alt: the orac terminal UI editing a BIOS enumeration

Status
------

Work in progress.  The in-band transport and the ``get`` / ``set`` /
``jobqueue`` command families are implemented: the full grammar of the
``get`` and ``set`` subcommands (device, group, indexed group and
attribute targets, as listed in the bash completion) runs over the
in-band pass-through channel, with the BMC rendering the output
server-side.  Every ``get`` target of the bash completion was verified
byte-identical to the original client (output and exit status) against
live BMC firmware.

On the friendly surface, ``system show``, ``log list``, ``sensor
list``, ``inventory list``, ``job list`` / ``create`` / ``delete``,
``raw`` and the whole reversed ``get`` / ``set`` target grammar are
implemented over both transports; the structured rendering of the
sensor and inventory listings is pending a captured sample of that
rendering and shows the BMC's own text until then.

The remote transport (``-r`` / ``-u`` / ``-p``, the XMLAPI protocol
over HTTPS to the BMC's web server) is implemented and covered
by unit tests; live differential verification against the original
client is pending.

Legal basis
-----------

This software was written exclusively by lawful black-box observation
and interoperability analysis, in exercise of the rights described
below.

Article 5(3) of Directive 2009/24/EC says that a person entitled to use
a copy of a program may observe, study or test the functioning of the
program.

The activities that have been used to write this software were
exclusively:

- running the management utility of the BMC against
  our own servers through black-box experiments;
- capturing the utility's management commands;
- recording commands and responses;
- changing input parameters and observing resulting traffic;
- documenting the protocol and packet formats;
- writing an independent implementation from observations.

The rules that were respected throughout:

- no technical protection measure (encryption, DRM, server-side
  licensing, ...) was bypassed;
- no code from the proprietary software was used: this tool is an
  original clean-room reimplementation based on observing and studying
  the protocol;
- where information was obtained from the original client's binary
  itself, this was done strictly under the conditions of Article 6 of
  the same Directive: to obtain the information necessary to achieve
  interoperability of this independently created program, and for no
  other purpose;
- the general prohibition on reverse engineering in the end-user licence
  agreement of the vendor of the server does not automatically override
  the right to observe and study software operation under EU law;
- software functionality, programming languages and data-file formats
  are not protected by copyright as expression of a computer program,
  as confirmed by the CJEU judgment C-406/10, paragraphs 47–62
  (judgment and operative ruling).

Swiss law provides a direct statutory basis for black-box observation:
Article 17(1)(b) of the Swiss Copyright Ordinance expressly permits
observing, studying and testing a program's functioning to determine
the ideas and principles underlying its elements, when doing so in the
course of authorized use.

Official texts:

- Swiss Copyright Act (Fedlex), Article 21 — Decoding of computer programs
- Swiss Copyright Ordinance, Article 17

License
-------

GNU General Public License, version 2 or later (GPL-2+).  See ``LICENSE``.

