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
====

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

``orac`` talks to the server's integrated management controller either
from the managed server's operating system over the standard in-band
IPMI interface (``/dev/ipmi0``), or remotely over HTTPS to the
controller'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``.

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

The controller'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

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

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 controller 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 controller 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 controller's own text until then.

The remote transport (``-r`` / ``-u`` / ``-p``, the XMLAPI protocol
over HTTPS to the controller'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 management controller 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``.

