vermin

README

Table of Contents:

• What is Vermin
• Install Vermin
• Usage
  • Create a new VM
  • List VMs
  • Start VM
  • SSH into VM
  • Stop VM
  • Remove VM
  • Transfer Files
  • Port Forward
• More installation options
  • Manual installation
  • Build from source
• Contributors
• Why not Vagrant
• TODO

---

What is Vermin

Vermin is a smart, simple and powerful VM command line tool for Linux, Windows and macOS. It's designed for developers who want a fresh VM environment with a single command. It uses VirtualBox to run the VM. Vermin will fetch images in your behave.

Vermin can be used when you need an easy way to obtain a Linux up and running in minutes.

For example:

• If you want to have an environment to try .NET Core and you don't want to mess with your local own WSL installation.
• Or if you want to try to install a Kafka cluster, and you need something more than just a docker container.

Tutorials using Vermin:

• Install CockroachDB cluster in a Virtual Machine

Also, you can check Why not Vagrant section.

Install Vermin

Vermin uses VirtualBox as the underlying hypervisor to create and run Virtual Machines.

To install/update for macos and linux:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/mhewedy/vermin/master/install.sh)"

To install/update on windows (PowerShell):

# Should run as Adminstarator
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/mhewedy/vermin/master/install.ps1'))

Usage:

$ vermin
Create, control and connect to VirtualBox VM instances

Usage:
  vermin [command]

Examples:

You can use vermin by creating a VM from an image.

To list all images available:
$ vermin images

Then you can create a vm using:
$ vermin create <image>


Available Commands:
  completion  Generates shell completion scripts
  cp          Copy files between a VM and the local filesystem
  create      Create a new VM
  exec        Run a command in a running VM
  help        Help about any command
  images      List remote and cached images
  ip          Show IP address for a running VM
  mount       Mount local filesystem inside the VM
  port        Forward port(s) from a VM to host
  ps          List VMs
  restart     Restart one or more VMs
  rm          Remove one or more VM
  ssh         ssh into a running VM
  start       Start one or more stopped VMs
  stop        Stop one or more running VMs
  tag         Tag a VM

Flags:
  -h, --help      help for vermin
  -v, --version   version for vermin

Use "vermin [command] --help" for more information about a command.

Create a new VM

Use the following command to create a VM

$ vermin create <image name>
# example
$ vermin create ubuntu/focal

Or in case you want to create and provision the VM: (see sample_init_bionic.sh for sample provision script)

$ vermin create <image name> /path/to/provison.sh 
# example
$ vermin create ubuntu/focal ~/sample.sh -cpus 1 -mem 512

To get list of all available images use:

$ vermin images
alpine/3.11		    (cached)
centos/8		    (cached)
ubuntu/focal

The cached flag means, the image has been already downloaded and cached before.

To get the most updated image list (along with images locations) use the -p flag vermin images -p. this will not affect cached images. it will only get the most updated image list (image names along with thier remote locations).

List VMs

$ vermin ps
VM NAME        IMAGE                      CPUS      MEM       DISK         TAGS
vm_01          alpine/3.11                1         1024      0.8GB
vm_02          ubuntu/focal               1         1024      2.6GB
vm_03          centos/8                   1         1024      2.0GB

Start VM

$ vermin start vm_01

SSH into VM

$ vermin ssh vm_03

Stop VM

$ vermin stop vm_03

Remove VM

Will stop and remove listed VMs

$ vermin rm vm_03

Transfer Files:

You can transfer files between host machine and VM.

To copy a remote file on a VM to you local host in the current path:

$ vermin cp vm_01 --r /path/to/file/on/vm

To copy a local file from your host filesystem to the VM's home directory:

$ vermin cp vm_01 -l /path/to/file/on/host

Port Forward:

forward ports from VM to local host (all ports from 8080 to 8090):

$ vermin port vm_01 8080-8090

More installation options:

Manual installation:

It is recommended to use the automatic method to install vermin, However If you prefer to do manual installation then you need to follow these steps:

1. Download the binary matching your OS from releases unzip it and preferably put it in your PATH
2. create the following directory structure in your home dir:

$HOME/.vermin
         ├── images
         └── vms

1. Download vermin private key into $HOME/.vermin/vermin_rsa
2. On windows, you need to add C:\Program Files\Oracle\VirtualBox into you PATH.

Build from Source:

Download the latest released source code archive file from releases then unzip:

go build

You can build using golang docker image:

# replace window by linux or darwin depending on your OS
docker run -it -v $(pwd):/go -e GOPATH='' -e GOOS='windows' golang:latest go build

Why not Vagrant:

• Vagrant uses a Vagrantfile which I think is most suited to be source-controlled inside git , and for some use case it is an overhead to create and maintain such file. In such cases Vermin come to the rescue.
• Vermin is a single binary file that can be easily installed and upgraded.

Contributors

Special thanks to Ahmed Samir for contributing the logo.

TODO

See TODO.md