# OpenBMC IpKVM Server

The obmc-ikvm application is a VNC server that provides access to the host
graphics output. The application interfaces with the video device on the BMC
that captures the host graphics, and then serves that video data on the RFB
(remote framebuffer, also known as VNC) protocol. The application also
interfaces with the BMC USB gadget device to pass HID events from the BMC to the
host, allowing the user to interact with the host system.

## Usage

Once the host is running and an appropriate HID gadget device is instantiated on
the BMC, the application can be started with the following command:
`obmc-ikvm -v <video device path> -i <HID gadget device path>`

For example:

`obmc-ikvm -v /dev/video0 -i /dev/hidg0`

## Accessing Remote KVM via Web Interface

1. Log in to the BMC Web UI.
2. Navigate to **Operations** > **KVM**.
3. The host's graphical output will be displayed, and you can interact with it
   directly from your browser.

## Accessing Remote KVM via VNC Client

Direct access to the BMC KVM port (usually 5900) is generally blocked to prevent
unencrypted connections. To securely connect to the KVM, use a VNC client over
an SSH tunnel.

**Note:** SSH local port forwarding must be enabled on the BMC. If you are using
Dropbear, make sure it is started without the `-j` option.

1. Create an SSH tunnel to forward the KVM port from the BMC to your local
   machine:

   ```bash
   ssh -L <localport>:localhost:<bmc-kvm-port> <bmc-user>@<bmc-hostname>
   ```

   - `localport`: The port number your VNC client will use locally (e.g., 1234)
   - `bmc-kvm-port`: The port used by the KVM service on the BMC (usually 5900)
   - `bmc-user`: Your SSH username for the BMC
   - `bmc-hostname`: The IP address or hostname of the BMC

   **Example:**

   ```bash
   ssh -L 1234:localhost:5900 root@192.168.1.1
   ```

2. Open your VNC client and connect to `localhost:<localport>`. For example,
   `localhost:1234`.

**Note:** Due to CPU and hardware encoder limitations on some BMC platforms, not
all VNC clients may work reliably. For example, certain clients may experience
display or input issues when connecting to iKVM. If you encounter problems, try
using a different VNC client or refer to your platform's documentation for
compatibility details.

You should now be able to view and interact with the host's graphical output as
if you were using a local monitor, keyboard, and mouse.