
How to use VirtualBMC
=====================

For the VirtualBMC tool to operate you first need to create libvirt
domain(s) for example, via ``virsh``.

The VirtualBMC tool is a client-server system where ``vbmcd`` server
does all the heavy-lifting (speaks IPMI, calls libvirt) while ``vbmc``
client is merely a command-line tool sending commands to the server and
rendering responses to the user.

You should set up your systemd to launch the ``vbmcd`` server on system
start up or you can just run ``vbmcd`` from command line if you do not need
the tool running persistently on the system. Once the server is up and
running, you can use the ``vbmc`` tool to configure your libvirt domains as
if they were physical hardware servers.

The ``vbmc`` client can only communicate with ``vbmcd`` server if both are
running on the same host. However ``vbmcd`` can manage libvirt domains
remotely.

By this moment you should be able to have the ``ipmitool`` managing
VirtualBMC instances over the network.

Configuring virtual servers
---------------------------

Use the ``vbmc`` command-line tool to create, delete, list, start and
stop virtual BMCs for the virtual machines being managed over IPMI.

* In order to see all command options supported by the ``vbmc`` tool
  do::

    $ vbmc --help


  It's also possible to list the options from a specific command. For
  example, in order to know what can be provided as part of the ``add``
  command do::

    $ vbmc add --help


* Adding a new virtual BMC to control libvirt domain called ``node-0``::

    $ vbmc add node-0


* Adding a new virtual BMC to control libvirt domain called ``node-1``
  that will listen for IPMI commands on port ``6230``::

    $ vbmc add node-1 --port 6230


  Alternatively, libvirt can be configured to ssh into a remote machine
  and manage libvirt domain through ssh connection:

    $ vbmc add node-1 --port 6230 \
        --libvirt-uri qemu+ssh://username@192.168.122.1/system node-1

.. note::

   Binding a network port number below 1025 is restricted and only users
   with privilege will be able to start a virtual BMC on those ports.


* Starting the virtual BMC to control libvirt domain ``node-0``::

    $ vbmc start node-0


* Stopping the virtual BMC that controls libvirt domain ``node-0``::

    $ vbmc stop node-0


* Getting the list of virtual BMCs including their libvirt domains and
  IPMI network endpoints they are reachable at::

    $ vbmc list
    +-------------+---------+---------+------+
    | Domain name |  Status | Address | Port |
    +-------------+---------+---------+------+
    |    node-0   | running |    ::   | 623  |
    |    node-1   | running |    ::   | 6230 |
    +-------------+---------+---------+------+

* To view configuration information for a specific virtual BMC::

    $ vbmc show node-0
    +-----------------------+----------------+
    |        Property       |     Value      |
    +-----------------------+----------------+
    |        address        |       ::       |
    |      domain_name      |     node-0     |
    | libvirt_sasl_password |      ***       |
    | libvirt_sasl_username |      None      |
    |      libvirt_uri      | qemu:///system |
    |        password       |      ***       |
    |          port         |      623       |
    |         status        |    running     |
    |        username       |     admin      |
    +-----------------------+----------------+


Server simulation
-----------------

Once the virtual BMC for a specific domain has been created and started
you can then issue IPMI commands against the address and port of that
virtual BMC to control the libvirt domain. For example:

* To power on the virtual machine::

    $ ipmitool -I lanplus -U admin -P password -H 127.0.0.1 -p 6230 power on

* To check its power status::

    $ ipmitool -I lanplus -U admin -P password -H 127.0.0.1 -p 6230 power status

* To set the boot device to disk::

    $ ipmitool -I lanplus -U admin -P password -H 127.0.0.1 -p 6230 chassis bootdev disk

* To get the current boot device::

    $ ipmitool -I lanplus -U admin -P password -H 127.0.0.1 -p 6230 chassis bootparam get 5

Backward compatible behaviour
-----------------------------

In the past the ``vbmc`` tool was the only part of the vBMC system. To help
users keeping their existing server-less workflows, the ``vbmc`` tool
attempts to spawn the ``vbmcd`` piece whenever it figures server is not
running.

.. warning::

   The backward compabible behaviour will be removed in two-cycle time past
   Queens.
