.. _user-guide:

User Guide
==========

Create VM
---------

The following command would create a Virtual Machine (name: meow)
with following specs

* CPU: 1
* RAM: 1GB
* OS-SSD: 4GB
* OS: Alpine Linux

.. code-block:: sh

    ucloud-cli vm create --vm-name meow --cpu 1 --ram '1gb' --os-ssd '4gb' --image images:alpine


.. _how-to-check-vm-status:

Check VM Status
---------------

.. code-block:: sh

    ucloud-cli vm status --vm-name meow

.. code-block:: json

    {
        "hostname": "/v1/host/74c21c332f664972bf5078e8de080eea",
        "image_uuid": "3f75bd20-45d6-4013-89c4-7fceaedc8dda",
        "in_migration": null,
        "log": [
            "2019-11-12T09:11:09.800798 - Started successfully"
        ],
        "metadata": {
            "ssh-keys": []
        },
        "name": "meow",
        "network": [],
        "owner": "admin",
        "owner_realm": "ungleich-admin",
        "specs": {
            "cpu": 1,
            "hdd": [],
            "os-ssd": "4.0 GB",
            "ram": "1.0 GB"
        },
        "status": "RUNNING",
        "vnc_socket": "/tmp/tmpj1k6sdo_"
    }


Connect to VM using VNC
-----------------------

We would need **socat** utility and a remote desktop client
e.g Remmina, KRDC etc. We can get the vnc socket path by getting
its status, see :ref:`how-to-check-vm-status`.


.. code-block:: sh

    socat TCP-LISTEN:1234,reuseaddr,fork UNIX-CLIENT:/tmp/tmpj1k6sdo_


Then, launch your remote desktop client and connect to vnc://localhost:1234.

Create Network
--------------

Layer 2 Network with sample IPv6 range fd00::/64 (without IPAM and routing)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: sh

    ucloud-cli network create --network-name mynet --network-type vxlan


Layer 2 Network with /64 network with automatic IPAM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: sh

    ucloud-cli network create --network-name mynet --network-type vxlan --user True

Attach Network to VM
--------------------

Currently, user can only attach network to his/her VM at
the time of creation. A sample command to create VM with
a network is as follow

.. code-block:: sh

    ucloud-cli vm create --vm-name meow2 --cpu 1 --ram '1gb' --os-ssd '4gb' --image images:alpine --network mynet

.. _get-list-of-hosts:

Get List of Hosts
-----------------

.. code-block:: sh

    ucloud-cli host list


Migrate VM
----------

.. code-block:: sh

    ucloud-cli vm migrate --vm-name meow --destination server1.place10


.. option:: --destination

   The name of destination host. You can find a list of host
   using :ref:`get-list-of-hosts`