acrn-hypervisor/misc/acrn-manager
David B. Kinder a884fa15fb doc: update tools docs to use vm-ubuntu name
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
2020-06-08 20:21:56 -07:00
..
Makefile use variables for installation directories. 2020-06-05 15:25:12 +08:00
README.rst doc: update tools docs to use vm-ubuntu name 2020-06-08 20:21:56 -07:00
acrn_mngr.c HV:Acrn-hypvervisor Root Directory Clean-up and create misc/ folder for Acrn daemons, services and tools. 2019-07-29 22:58:24 +08:00
acrn_mngr.h Tools: cleanup acrn_mngr pause/continue message 2020-05-14 12:52:59 +08:00
acrn_vm_ops.c Tools: cleanup acrnctl support pause/continue cmd 2020-05-14 12:52:59 +08:00
acrnctl.c Tools: cleanup acrnctl support pause/continue cmd 2020-05-14 12:52:59 +08:00
acrnctl.h tools: add force parameter to acrn VM stop operations 2019-07-30 13:27:16 +08:00
acrnd.c vm-manager: fix improper return value check for "strtol()" 2019-10-22 08:57:03 +08:00
acrnd.service HV:Acrn-hypvervisor Root Directory Clean-up and create misc/ folder for Acrn daemons, services and tools. 2019-07-29 22:58:24 +08:00

README.rst

.. _acrnctl:

acrnctl and acrnd
#################


Description
***********

The ``acrnctl`` tool helps users create, delete, launch, and stop a User
OS (UOS).  The tool runs under the Service OS, and UOSs should be based
on ``acrn-dm``. The daemon for acrn-manager is `acrnd`_.



Usage
=====

You can see the available ``acrnctl`` commands by running:

.. code-block:: none

   # acrnctl help
   support:
     list
     start
     stop [--force/-f]
     del
     add
     suspend
     resume
     reset
     blkrescan
   Use acrnctl [cmd] help for details

.. note::
   You must run ``acrnctl`` with root privileges.

Here are some usage examples:

Add a VM
========

The ``add`` command lets you add a VM by specifying a
script that will launch a UOS, for example ``launch_uos.sh``:

.. code-block:: none

   # acrnctl add launch_uos.sh -U 1
   vm1-14:59:30 added

If a ``-C`` option is also specified, the VM is launched in a runC
container::

   # acrnctl add launch_uos.sh -C

.. note:: You can download an `example launch_uos.sh script
   <https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/devicemodel/samples/nuc/launch_uos.sh>`_
   that supports the ``-C``  (``run_container`` function) option. You may refer to :ref:`acrn-dm_qos`
   for more details about this option.

Note that the launch script must only launch one UOS instance.
The VM name is important. ``acrnctl`` searches VMs by their
names so duplicate VM names are not allowed. If the
launch script changes the VM name at launch time, ``acrnctl``
will not recognize it.

Delete VMs
==========

Use the ``delete`` command with a VM name to delete that VM:

.. code-block:: none

   # acrnctl del vm1-14:59:30

List VMs
========

Use the ``list`` command to display VMs and their state:

.. code-block:: none

   # acrnctl list
   vm1-14:59:30            untracked
   vm-ubuntu               stopped
   vm-android              stopped

Start VM
========

If a VM is in a ``stopped`` state, you can start it with the ``start``
command:

.. code-block:: none

   # acrnctl start vm-ubuntu

Stop VM
=======

Use the ``stop`` command to stop one or more running VM:

.. code-block:: none

   # acrnctl stop vm-ubuntu vm1-14:59:30 vm-android

Use the optional ``-f`` or ``--force`` argument to force the stop operation.
This will trigger an immediate shutdown of the User VM by the ACRN Device Model
and can be useful when the User VM is in a bad state and not shutting down
gracefully by itself.

.. code-block:: none

   # acrnctl stop -f vm-ubuntu

RESCAN BLOCK DEVICE
===================

Use the ``blkrescan`` command to trigger a rescan of
virtio-blk device by guest VM, in order to revalidate and
update the backend file.

.. code-block:: none

   # acrnctl blkrescan vmname slot,newfilepath
   vmname:     Name of VM with dummy backend file attached to virtio-blk device.
   slot:       Slot number of the virtio-blk device.
   newfilepath: File path for the backend of virtio-blk device.

   acrnctl blkrescan vm1 6,actual_file.img

.. note:: blkrescan is only supported when VM is launched with
   empty backend file (using **nodisk**) for virtio-blk device.
   Replacing a valid backend file is not supported and will
   result in error.

.. _acrnd:

acrnd
*****

The ``acrnd`` daemon process provides a way for launching or resuming a UOS
should the UOS shut down, either planned or unexpected. A UOS can ask ``acrnd``
to set up a timer to make sure the UOS is running, even if the SOS is
suspended or stopped.

Usage
=====

You can see the available ``acrnd`` commands by running:

.. code-block:: none

   $ acrnd -h
   acrnd - Daemon for ACRN VM Management
   [Usage] acrnd [-t] [-d delay] [-h]
   -t: print messages to stdout
   -d: delay the autostarting of VMs, <0-60> in second (not available in the
       ``RELEASE=1`` build)
   -h: print this message

Normally, ``acrnd`` runs silently (messages are directed to
``/dev/null``).  Use the ``-t`` option to direct messages to ``stdout``,
useful for debugging.

The ``acrnd`` daemon stores pending UOS work to ``/usr/share/acrn/conf/timer_list``
and sets an RTC timer to wake up the SOS or bring the SOS back up again.
When ``acrnd`` daemon is restarted, it restores the previously saved timer
list and launches the UOSs at the right time.

A ``systemd`` service file (``acrnd.service``) is installed by default that will
start the ``acrnd`` daemon when the Service OS comes up.
You can restart/stop acrnd service using ``systemctl``

.. note::
   You must run ``acrnd`` with root privileges.

Build and Install
*****************

Source code for both ``acrnctl`` and ``acrnd`` is in the ``tools/acrn-manager`` folder.
Change to that folder and run:

.. code-block:: none

   # make
   # make install