README.md 3.8 KB

libremanage

libremanage is a simple solution for out-of-band remote management with free software. libremanage enables a sysadmin to remotely access a server's serial console and power state, regardless of the state of the main CPU, useful for resolving early boot issues. It serves an analogous role to IPMI or AMT.

You may also be interested in OpenBMC, another free software project capable of remote management.

Setup

Some setup is needed on the host (the sysadmin's computer), the board (the single-board computer connected to the server), and the managed server itself.

Setup (host)

Clone this repository and add the resulting libremanage directory to your path. Place your fleet configuration in $HOME/.libremanage.json, e.g. /home/admin/.libremanage.json.

The configuration file is JSON, consisting of servers and managers. servers correspond to physical servers to be managed, such as KGPE-D16s. managers correspond to the intermediate single-board computer, such as the Beaglebone Blacks. A physical link between a server and its manager is described by the manager entry of the server descriptor.

Each server has its serial port described by the self-explanatory tty object.

Power management is described in the power object. type refers to the power management scheme; currently, the only supported option is hidusb-relay-cmd, corresponding to the accordingly named USB HID relay driver. For this driver, relay and channel correspond to the relay identifier and the channel number of the corresponding relay. See hidusb-relay-cmd documentation for more details.

Each manager object lists SSH credentials to access the board: host, port, and username. These fields are self-explanatory. Password authentication is not supported; use public-key based login.

Setup (board)

Any standard GNU/Linux distribution or other `nix system should work. Minimally, the system needs to run an ssh daemon for remote access.

Setup (server)

Connecting the serial cable to the "manager" board.

Wire the power switch pins to a manager relay.

Usage

Type libremanage for detailed information.

Why?

With OpenBMC, each server board supporting BMC must be ported individually, a massive task involving reverse-engineering and nontrivial changes across the stack. Consider that the KGPE-D16 OpenBMC port is estimated to cost upwards of $60,000. As such, free software conscious users are de facto locked in to particular server boards, a net negative for freedom in the long-term.

Further, OpenBMC is incredibly complex. While this may be appropriate for advanced use-cases, it is overkill for the simple remote management tasks required in practice (serial and power access). The KGPE-D16 server port, for instance, takes several hours to compile on-board, and binary images are not supplied due to hard-coded passwords. OpenBMC is an embedded GNU/Linux distribution in and of itself, intimately connected with complex parts of the desktop GNU/Linux stack like dbus and systemd; its functionality is exposed over an embedded web server. The interface, requiring an isolated network due to a lack of SSL support, is even planned to be implemented in a JavaScript-heavy HTML5 "webapp".

Whereas OpenBMC takes a maximalist approach, libremanage takes a minimalist approach. Its feature set is comparatively tiny, but it requires almost no specific libremanage code. The vast majority of its functionality is handled by standard, implementation-agnostic *nix tools, a win for maintainability. The drawback is an increase in physical complexity; while OpenBMC runs on a chip embedded in the board itself, libremanage requires a dedicated, external single-board computer with serial cables and relays. Still, in light of the above issues, this is a net win.