Skip to content

Releases: zheng1/beefkvm

Release list

v0.1.0

v0.1.0 Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 30 Jul 09:35
v0.1.0
627453a

First release of beefkvm — a browser-based KVM and management console for
Avocent-style BMCs, in pure Go.

Some server BMCs ship a remote console that is a Java applet, needing a JRE
with applet support, TLS 1.0, and legacy renegotiation. On any current OS and
browser it simply doesn't launch, which leaves otherwise-healthy hardware
unmanageable with no vendor fix coming. beefkvm speaks the BMC's wire protocol
(APCP/AVPT — hence the name, after its 0xBEEF frame magic) directly and
renders the console in a normal browser tab.

No Java, no browser plugin, no vendor binaries. One static Go binary plus an
embedded HTML page.

What it does

Console

  • KVM video — the custom DCT codec, reimplemented (4-bit opcode stream, palette
    cache, integer AAN IDCT). Full-rate with sharp text.
  • Keyboard as USB HID reports, including OS auto-repeat (hold a key and it
    repeats — this BMC doesn't repeat held keys on its own, so the client has to)
  • Key macros the browser would otherwise swallow: Ctrl+Alt+Del, Alt+Tab,
    Ctrl+Alt+F1–F6 for Linux VT switching, plus sticky modifiers
  • Clipboard paste, typed into the target as keystrokes
  • Mouse (absolute positioning)

Management (IPMI 2.0 over LAN)

  • Power on / off / reset / soft shutdown / cycle
  • One-time boot device: PXE / CD / HDD / BIOS setup
  • Sensors — temperatures, fans, voltages, with a live stream
  • System event log: view and clear
  • User management: add, edit, set privilege, enable/disable
  • Network configuration: read, plus a guarded write
  • Serial-over-LAN console

Other

  • Virtual media: mount an ISO, USB image, or floppy
  • System info: BMC firmware, IPMI version, FRU inventory
  • BMC TLS certificate inspection (these are usually self-signed and expired)
  • Smart-card (CAC/PIV) redirection
  • Automatic reconnect when the BMC session drops

Install

Homebrew:

brew tap zheng1/beefkvm
brew install beefkvm

Go:

go install github.com/zheng1/beefkvm/cmd/beefkvm@v0.1.0
go install github.com/zheng1/beefkvm/cmd/apcp-probe@v0.1.0

Prebuilt: download an archive below, verify it against SHA256SUMS, and run
beefkvm --version. Binaries are static (CGO_ENABLED=0) with no runtime
dependencies, for Linux (amd64/arm64/arm/riscv64), macOS (arm64/amd64), Windows
(amd64/arm64), and FreeBSD (amd64).

Getting started

The BMC's certificate is self-signed, so it can't be validated against a CA —
beefkvm pins it instead. Learn the pin once, then start the console:

apcp-probe --host <bmc> --learn-pin

beefkvm --host <bmc> --user admin --pass "$BMC_PASS" --pin "$BMC_PIN" \
  --ipmi-user admin --ipmi-pass "$BMC_PASS"

It listens on 127.0.0.1 and prints a URL containing a one-time token.

What's verified, and what isn't

This is worth reading before you rely on it.

  • Hardware: verified end to end on exactly one machine — a GIGABYTE
    GA-6PXSV4 with an AST2300-class BMC (firmware 2.44) running a licensed
    Avocent KVM stack. Everything else in the README's compatibility table,
    including Dell iDRAC6, is a hypothesis based on shared code in the vendor's
    Java clients. Hardware reports
    are the most useful contribution you can make.
  • Platforms: all builds and tests pass in CI on Linux, macOS, and Windows,
    and cross-compile to 15 targets — but beefkvm has only ever been run
    against a BMC from macOS.
  • Mouse: implemented, and the BMC accepts the frames, but the test target
    only ever showed a text console, so pointer movement was never confirmed
    visually.
  • Serial-over-LAN: activates and carries traffic, but SoL only transports
    what the target OS puts on the serial line. A blank screen usually means the
    target has no serial console configured.
  • Smart card: exercised as far as reader detection; no physical CAC/PIV
    reader was available to test APDU redirection. Included in the prebuilt
    binaries on Windows only — macOS needs a cgo build, Linux needs
    -tags pcsc and libpcsclite-dev. Every other feature is on every platform.

Security

The web UI is plain HTTP and defaults to loopback, gated by a random per-run
token. A BMC is total control of a machine, so read the
security section before
binding it to anything other than 127.0.0.1. Vulnerabilities go through
private reporting.

MIT licensed. Reverse-engineered for interoperability with hardware you own; no
vendor code is included or redistributed.

Assets 12
Loading