vermin

README

Vermin: The smart virtual machines manager

Create, control and connect to VirtualBox VM instances.

Menu

• Prerequisites
• Installation
  • Automatic Installation
  • Manual installation
  • Build from source
• Use cases
• Usage
  • Create a new VM
  • List VMs
  • Start VM
  • SSH into VM
  • Stop VM
  • Remove VM
  • Transfer Files
  • Port Forward
• Why not Vagrant
• Contributors
• TODO

---

Prerequisites

• VirtualBox

Installation

Automatic installation:

To install or update for macos and linux:

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

To install or update on windows (PowerShell):

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

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

Use cases:

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 own WSL installation, so you can create a VM to do whatever you want to do then remove it.

Or if you want to try to install a Kafka cluster, and you need something more than just a docker container, so you can work with its different commands or want to practice setting up a cluster manually.

Also, you can check Why not Vagrant section.

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 --remote-file /path/to/file/on/vm

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

$ vermin cp vm_01 --local-file /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

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 removed.

Contributors

Special thanks to Ahmed Samir for contributing the logo.

TODO

See TODO.md