1.. _acrnctl:
2
3Acrnctl and Acrnd
4#################
5
6
7Description
8***********
9
10The ``acrnctl`` tool helps users create, delete, launch, and stop a User
11VM (aka UOS).  The tool runs under the Service VM, and User VMs should be based
12on ``acrn-dm``. The daemon for acrn-manager is `acrnd`_.
13
14Usage
15=====
16
17You can see the available ``acrnctl`` commands by running:
18
19.. code-block:: none
20
21   # acrnctl help
22   support:
23     list
24     start
25     stop [--force/-f]
26     del
27     add
28     reset
29     blkrescan
30   Use acrnctl [cmd] help for details
31
32.. note::
33   You must run ``acrnctl`` with root privileges, and make sure the ``acrnd``
34   service has been started before running ``acrnctl``.
35
36Here are some usage examples:
37
38Add a VM
39========
40
41The ``add`` command lets you add a VM by specifying a
42script that will launch a User VM, for example ``launch_uos.sh``:
43
44.. code-block:: none
45
46   # acrnctl add launch_uos.sh -U 1
47   vm1-14:59:30 added
48
49If a ``-C`` option is also specified, the VM is launched in a runC
50container::
51
52   # acrnctl add launch_uos.sh -C
53
54.. note:: You can download an :acrn_raw:`example launch_uos.sh script
55   <misc/config_tools/data/sample_launch_scripts/nuc/launch_uos.sh>`
56   that supports the ``-C``  (``run_container`` function) option.
57
58Note that the launch script must only launch one User VM instance.
59The VM name is important. ``acrnctl`` searches VMs by their
60names so duplicate VM names are not allowed. If the
61launch script changes the VM name at launch time, ``acrnctl``
62will not recognize it.
63
64Delete VMs
65==========
66
67Use the ``delete`` command with a VM name to delete that VM:
68
69.. code-block:: none
70
71   # acrnctl del vm1-14:59:30
72
73List VMs
74========
75
76Use the ``list`` command to display VMs and their state:
77
78.. code-block:: none
79
80   # acrnctl list
81   vm1-14:59:30            untracked
82   vm-ubuntu               stopped
83   vm-android              stopped
84
85Start VM
86========
87
88If a VM is in a stopped state, you can start it with the ``start`` command. The
89``acrnd`` service automatically loads the launch script under
90``/usr/share/acrn/conf/add/`` to boot the VM.
91
92.. code-block:: none
93
94   # acrnctl start vm-ubuntu
95
96Stop VM
97=======
98
99Use the ``stop`` command to stop one or more running VMs:
100
101.. code-block:: none
102
103   # acrnctl stop vm-ubuntu vm1-14:59:30 vm-android
104
105Use the optional ``-f`` or ``--force`` argument to force the stop operation.
106This will trigger an immediate shutdown of the User VM by the ACRN Device Model
107and can be useful when the User VM is in a bad state and not shutting down
108gracefully by itself.
109
110.. code-block:: none
111
112   # acrnctl stop -f vm-ubuntu
113
114Rescan Block Device
115===================
116
117Use the ``blkrescan`` command to trigger a rescan of
118virtio-blk device by guest VM, in order to revalidate and
119update the backend file.
120
121.. code-block:: none
122
123   # acrnctl blkrescan vmname slot,newfilepath
124   vmname:     Name of VM with dummy backend file attached to virtio-blk device.
125   slot:       Slot number of the virtio-blk device.
126   newfilepath: File path for the backend of virtio-blk device.
127
128   acrnctl blkrescan vm1 6,actual_file.img
129
130.. note:: blkrescan is only supported when VM is launched with
131   empty backend file (using **nodisk**) for virtio-blk device.
132   Replacing a valid backend file is not supported and will
133   result in error.
134
135.. _acrnd:
136
137Acrnd
138*****
139
140The ``acrnd`` daemon process provides a way for launching or resuming a User VM
141should the User VM shut down, either in a planned manner or unexpectedly. A User
142VM can ask ``acrnd`` to set up a timer to make sure the User VM is running, even
143if the Service VM is suspended or stopped.
144
145Usage
146=====
147
148You can see the available ``acrnd`` commands by running:
149
150.. code-block:: none
151
152   $ acrnd -h
153   acrnd - Daemon for ACRN VM Management
154   [Usage] acrnd [-t] [-d delay] [-h]
155   -t: print messages to stdout
156   -d: delay the autostarting of VMs, <0-60> in second (not available in the
157       ``RELEASE=1`` build)
158   -h: print this message
159
160.. note::
161   You must run ``acrnd`` with root privileges.
162
163Normally, ``acrnd`` runs silently (messages are directed to
164``/dev/null``).  Use the ``-t`` option to direct messages to ``stdout``,
165useful for debugging.
166
167The ``acrnd`` daemon stores pending User VM work to ``/usr/share/acrn/conf/timer_list``
168and sets an RTC timer to wake up the Service VM or bring the Service VM back up again.
169When ``acrnd`` daemon is restarted, it restores the previously saved timer
170list and launches the User VMs at the right time.
171
172A ``systemd`` service file (``acrnd.service``) is installed by default.
173You can enable, restart or stop acrnd service using ``systemctl``.
174
175.. code-block:: none
176
177   systemctl enable --now acrnd.service
178
179Build and Install
180*****************
181
182Source code for both ``acrnctl`` and ``acrnd`` is in the ``misc/acrn-manager`` folder.
183Change to that folder and run:
184
185.. code-block:: none
186
187   $ make
188   $ sudo make install
189