search

sciapp / nojava-ipmi-kvm

nojava-ipmi-kvm is a utility to access Java based ipmi kvm consoles without a local java installation.
MIT License
81 stars 28 forks source link

readme

NoJava-IPMI-KVM

Version incompatibility notice (upgrading from v0.8.1)

Users upgrading from version v0.8.1 or earlier must rewrite their config files. The previously used ini format was not flexible enough for adding HTML5 KVM support and was replaced with a YAML file.

Use the converter script convert_config_file.py to convert your old ini config file to the new YAML format.

Introduction

nojava-ipmi-kvm is a tool for running Java-based IPMI-KVM consoles without a local Java installation. It runs a Docker container in the background, starts a suitable Java Webstart version (from OpenJDK or Oracle) and connects to the container with noVNC. By using Docker, Java Webstart is sandboxed automatically and you don't need to install old Java versions on your Desktop machines.

Starting with version v0.9.0, nojava-ipmi-kvm also supports HTML5 based kvm viewers.

This project is based on ideas from solarkennedy/ipmi-kvm-docker.

Deploying as a web service

If you would like to access IPMI-KVM consoles with a browser only (without Java plugins and a local installation of nojava-impi-kvm), see nojava-ipmi-kvm-server which encapsulates nojava-ipmi-kvm in a web service.

Local Installation

The latest version can be obtained from PyPI and runs with Python 3.5+:

python3 -m pip install nojava-ipmi-kvm

Install Docker on your local machine if not done already (or Podman with Docker emulation).

If you run an Arch-based system, you can also install nojava-ipmi-kvm from the AUR:

yay -S nojava-ipmi-kvm-docker

If you prefer Podman to Docker use the Podman version instead:

yay -S nojava-ipmi-kvm-podman

Usage

Configuration file

First, create a file ~/.nojava-ipmi-kvmrc.yaml and add a template for each kvm host type you want to connect to, for example:

templates:
  kvm-openjdk-7u51:
    skip_login: False
    login_user: ADMIN
    login_endpoint: rpc/WEBSES/create.asp
    allow_insecure_ssl: False
    user_login_attribute_name: WEBVAR_USERNAME
    password_login_attribute_name: WEBVAR_PASSWORD
    send_post_data_as_json: False
    session_cookie_key: SessionCookie
    download_endpoint: Java/jviewer.jnlp
    java_version: 7u51
    format_jnlp: False

Then, add a definition for every single kvm host by reusing the previously defined templates:

hosts:
  mykvmhost:
    based_on: kvm-openjdk-7u51
    full_hostname: mykvmhost.org

Template configuration values can be overwritten in the host section.

In addition, you can create a general section to configure more general settings, e.g.:

general:
  run_docker_with_sudo: False
  x_resolution: 1600x1200

Unless you want to use custom docker images, you can omit the config keys java_docker_image and html5_docker_image.

Using the command line tool

After configuring, you can call nojava-ipmi-kvm from the command line:

nojava-ipmi-kvm mykvmhost

You can start nojava-ipmi-kvm multiple times to connect to different machines in parallel. The background Docker container will be shutdown automatically after to you closed the VNC window (if invoked with the --use-gui flag) or sent <Ctrl-C> on the command line.

Options:

usage: nojava-ipmi-kvm [-h] [--debug] [-f CONFIG_FILEPATH] [-g]
                       [--print-default-config] [-V]
                       [hostname]

nojava-ipmi-kvm is a utility to access Java based ipmi kvm consoles without a local java installation.

positional arguments:
  hostname              short hostname of the server machine; must be
                        identical with a hostname in `.nojava-ipmi-kvmrc` (for
                        example `mykvmserver`)

optional arguments:
  -h, --help            show this help message and exit
  --debug               print debug messages
  -f CONFIG_FILEPATH, --config-file CONFIG_FILEPATH
                        login user (default: ~/.nojava-ipmi-kvmrc)
  -g, --use-gui         automatically open a PyQt5 browser window. Requires
                        PyQt5 to be installed
  --print-default-config
                        print the default config to stdout and exit
  -V, --version         print the version number and exit

Using Oracle Java

Because of license restrictions we cannot provide pre-built docker images for Oracle Java. However, you can build an Oracle Java image yourself:

  1. Clone this repository:

    git clone git@github.com:sciapp/nojava-ipmi-kvm.git

  2. Visit the Java download page and get the Linux x64 tar archive of Oracle Java version 8u251. Save it to the docker subdirectory of the previously cloned repository as jre-8u251-linux-x64.tar.gz. If you would like to also use Oracle Java 7, get jre-7u80-linux-x64.tar.gz from Oracle's Java archive (this requires an free Oracle account).

  3. Open a terminal and go to the root of the project clone. Run

    git pull
make build-oracle

    to build a Docker image with Oracle Java. When you install an updated version of nojava-ipmi-kvm repeat these commands.

  4. Use java_version: 8u251-oracle (or 7u80-oracle) in your ~/.nojava-ipmi-kvmrc.yaml configuration.

Command line completion

This repository offers a completion script for bash and zsh (only hostnames currently, no options).

Bash

Download the Bash completion file and source it in your .bashrc, for example by running:

curl -o .nojava-ipmi-kvm-completion.bash -L https://raw.githubusercontent.com/sciapp/nojava-ipmi-kvm/master/completion/bash/nojava-ipmi-kvm-completion.bash
echo '[ -r "${HOME}/.nojava-ipmi-kvm-completion.bash" ] && source "${HOME}/.nojava-ipmi-kvm-completion.bash"' >> ~/.bashrc

Zsh

You can install the completion script with zplug or manually.

Using zplug

Add zplug "sciapp/nojava-ipmi-kvm" to your .zshrc, open a new shell and run

zplug install

Manual

Clone this repository and source nojava_ipmi_kvm_completion.plugin.zsh in your .zshrc.

Acknowledgement