<commit_before># ciao-down

## Introduction

ciao-down is a small utility that simplifies the task of creating,
managing and connecting to virtual machines.  All you need to have
installed on your machine is:

- Go 1.8 or greater

Then simply type

```
go get github.com/01org/ciao/testutil/ciao-down
$GOPATH/bin/ciao-down create xenial
```

to create a new Ubuntu 16.04 VM.  ciao-down will install some needed
dependencies on your local PC such as qemu and xorriso. It will then
download an Ubuntu Cloud Image and create a VM based on this image.
It will boot the VM, create an account for you, with the same
name as your account on your host, and optionally update the default
packages.

Once it's finished you'll be able to connect to the the VM via SSH
using the following command.

```
ciao-down connect
```

The command above assumes that either $GOPATH/bin or ~/go/bin is in
your PATH.

ciao-down will cache the Ubuntu image locally so the next time you
create another xenial based VM you won't have to wait very long.
It also knows about HTTP proxies and will mirror your host computer's proxy
settings inside the VMs it creates.

You can delete the VM you've just created by running,

```
ciao-down delete
```

## Workloads

Each VM is created from a workload. A workload is a text file which contains
a set of instructions for initialising the VM.  A workload, among other things,
can specify:

- The hostname of the VM.
- The resources to be consumed by the VM
- The base image from which the VM is to be created
- The folders that should be shared between the host and the VM
- An annotated cloud-init file that contains the set of instructions
  to run on the first boot of the VM.  This file is used to create
  user accounts, install packages and configure the VM.

ciao-down ships with a number of workloads for creating VMs based on standard images,
such as Ubuntu 16.04 and Fedora 25.  Users are also free to create their own workloads.
Standard workloads are stored in $GOPATH/src/github.com/01org/ciao/testutil/ciao-down/workloads.
User created workloads are stored in ~/.ciao-down/workloads.  ciao-down always checks the
~/.ciao-down/workloads directory first so if a workload exists in both directories
with the same name, ciao-down will use the workload in ~/.ciao-down/workloads.

You can tell ciao-down which workload to use when creating the VM with the
create command.  This is done via the --vmtype option.  You specify the file name
of the workload without the .yaml extension.  The workload must be present in either
of the two directories mentioned above.  For example, the create command in the
introduction section used the option --vmtype xenial.  This caused ciao-down to
load the workload definition in
$GOPATH/src/github.com/01org/ciao/testutil/ciao-down/workloads/xenial.yaml.

The default workload is called ciao and this workload is used if no --vmtype option is
specified.  Selecting the ciao workloads sets up a [ciao](https://github.com/01org/ciao)
development environment inside a xenial VM.  ciao-down was original created as a tool to
automatically set up a development environment for ciao.  It still serves this purpose
but is no longer tied to ciao.  For more information about running ciao with ciao-down
please see the [Ciao Developer Quick Start](https://github.com/01org/ciao/blob/master/DeveloperQuickStart.md).

As the majority of the ciao-down workloads are cloud-init files, ciao-down only
works with images that are designed to run cloud-init on their first boot.  Typically,
these are the cloud images, e.g.,. the [Ubuntu Cloud Images](https://cloud-images.ubuntu.com/).

## Creating new Workloads

ciao-down workloads are multi-doc YAML files.  The first document contains invariants
about the VM created from the workload such as the image off which it is based and its
hostname.  The second contains dynamic instance data that can be altered on every boot,
such as the number of CPUs the VM uses and the ports mapped.  The final document contains
the cloud-init file.  If only one section is present it is assumed to the be cloud-init
file and default values are used for the other two sections.

An example workload is shown below:

```
---
base_image_url: https://cloud-images.ubuntu.com/xenial/current/xenial-server-cloudimg-amd64-disk1.img
base_image_name: Ubuntu 16.04
...
---
mem_gib: 2<commit_msg>ciao-down: Remove the last mentions of --vmtype<commit_after># ciao-down

## Introduction

ciao-down is a small utility that simplifies the task of creating,
managing and connecting to virtual machines.  All you need to have
installed on your machine is:

- Go 1.8 or greater

Then simply type

```
go get github.com/01org/ciao/testutil/ciao-down
$GOPATH/bin/ciao-down create xenial
```

to create a new Ubuntu 16.04 VM.  ciao-down will install some needed
dependencies on your local PC such as qemu and xorriso. It will then
download an Ubuntu Cloud Image and create a VM based on this image.
It will boot the VM, create an account for you, with the same
name as your account on your host, and optionally update the default
packages.

Once it's finished you'll be able to connect to the the VM via SSH
using the following command.

```
ciao-down connect
```

The command above assumes that either $GOPATH/bin or ~/go/bin is in
your PATH.

ciao-down will cache the Ubuntu image locally so the next time you
create another xenial based VM you won't have to wait very long.
It also knows about HTTP proxies and will mirror your host computer's proxy
settings inside the VMs it creates.

You can delete the VM you've just created by running,

```
ciao-down delete
```

## Workloads

Each VM is created from a workload. A workload is a text file which contains
a set of instructions for initialising the VM.  A workload, among other things,
can specify:

- The hostname of the VM.
- The resources to be consumed by the VM
- The base image from which the VM is to be created
- The folders that should be shared between the host and the VM
- An annotated cloud-init file that contains the set of instructions
  to run on the first boot of the VM.  This file is used to create
  user accounts, install packages and configure the VM.

ciao-down ships with a number of workloads for creating VMs based on standard images,
such as Ubuntu 16.04 and Fedora 25.  Users are also free to create their own workloads.
Standard workloads are stored in $GOPATH/src/github.com/01org/ciao/testutil/ciao-down/workloads.
User created workloads are stored in ~/.ciao-down/workloads.  ciao-down always checks the
~/.ciao-down/workloads directory first so if a workload exists in both directories
with the same name, ciao-down will use the workload in ~/.ciao-down/workloads.

Which workload to use is specified when creating the VM with the create
command.  This is the name the workload file without the .yaml extension.  The
workload must be present in either of the two directories mentioned above.  For
example, the create command in the introduction section creates an Ubuntu 16.04
workload (xenial).  This caused ciao-down to load the workload definition in
$GOPATH/src/github.com/01org/ciao/testutil/ciao-down/workloads/xenial.yaml.

As the majority of the ciao-down workloads are cloud-init files, ciao-down only
works with images that are designed to run cloud-init on their first boot.  Typically,
these are the cloud images, e.g.,. the [Ubuntu Cloud Images](https://cloud-images.ubuntu.com/).

## Creating new Workloads

ciao-down workloads are multi-doc YAML files.  The first document contains invariants
about the VM created from the workload such as the image off which it is based and its
hostname.  The second contains dynamic instance data that can be altered on every boot,
such as the number of CPUs the VM uses and the ports mapped.  The final document contains
the cloud-init file.  If only one section is present it is assumed to the be cloud-init
file and default values are used for the other two sections.

An example workload is shown below:

```
---
base_image_url: https://cloud-images.ubuntu.com/xenial/current/xenial-server-cloudimg-amd64-disk1.img
base_image_name: Ubuntu 16.04
...
---
mem_gib: 2
{'fraction_non_alphanumeric': 0.056555269922879174, 'fraction_numerical': 0.007344840249724568, 'mean_word_length': 3.9485160508782555, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6411312', 'n_tokens_mistral': 2409, 'n_tokens_neox': 2243, 'n_words': 1220}