README.md

Intel's Clear Linux guest boxes for Vagrant

Pre-requisites

These boxes require the most recent vagrant-guests-clearlinux plugin release, which a priori will be installed automatically when you use them

You can also manually install the vagrant-guests-clearlinux plugin by...

vagrant plugin install vagrant-guests-clearlinux

TL;DR

currently supported are the VirtualBox, VMware and, up from 26510, libvirt providers.

In an empty directory:

vagrant init AntonioMeireles/ClearLinux
vagrant up

if you happen to be running multiple providers in the same vagrant host just specify which one you want to actually consume when invoking vagrant...

vagrant up --provider (virtualbox|vmware|libvirt)

Going Full Circle - Vagrant, Packer and... Terraform natively on top of Clear Linux

on your Clear Linux setup just run ...

• setup libvirt

  curl -O https://raw.githubusercontent.com/AntonioMeireles/ClearLinux-packer/master/extras/clearlinux/setup/libvirtd.sh
  chmod +x libvirtd.sh
  ./libvirtd.sh

• install Vagrant

  curl -O https://raw.githubusercontent.com/AntonioMeireles/ClearLinux-packer/master/extras/clearlinux/setup/vagrant.sh
  chmod +x vagrant.sh
  ./vagrant.sh

• install Packer

  curl -O https://raw.githubusercontent.com/AntonioMeireles/ClearLinux-packer/master/extras/clearlinux/setup/packer.sh
  chmod +x packer.sh
  ./packer.sh

• install Terraform (plus terraform-provider-libvirt)

  curl -O https://raw.githubusercontent.com/AntonioMeireles/ClearLinux-packer/master/extras/clearlinux/setup/terraform.sh
  chmod +x terraform.sh
  ./terraform.sh

... and that's it :-)

Tips & Tricks

• take a deep look at the guest plugin available features and capabilities by reading its documentation in order to take maximum advantage of this.

• By default boxes are loaded in headless mode.

  When using Virtualbox or VMware if you wish to have access to the boot console you can boot them in graphical mode by invoking vagrant with HEADLESS=false set in your environment.

• when using the libvirt provider by default it is assumed that the libvirt host is the same as the vagrant host (localhost).

  If you want Vagrant to target a remote libvirt host you will need to set it in LIBVIRT_HOST when invoking vagrant up.

  It is also assumed, by default, that the remote libvirt host is running Clear Linux what may or not be the case... If it isn't then the LIBVIRT_USERNAME will also need to be set.

  So, in order to target a remote, say Ubuntu, host what one would need to do would be along...

  LIBVIRT_HOST=libvirt-host.ubuntu.local LIBVIRT_USERNAME=someUsername vagrant up --provider=libvirt

  regarding libvirt: if running Vagrant over a macOS host the vagrant-libvirt won't install correctly out of the box. You'll need to ensure in advance that libvirt is installed locally (for its headers) by running:

  brew install libvirt

  and then install the plugin but only after pointing it the right locations...

  CONFIGURE_ARGS='with-ldflags=-L/opt/vagrant/embedded/lib with-libvirt-include=/usr/local/include/libvirt with-libvirt-lib=/usr/local/lib' vagrant plugin install vagrant-libvirt

• if you want to consume additional Vagrant plugins from your Vagrantfile the preferred way to do it is along the snippet bellow...

  additional_plugins = {
    'vagrant-compose' => {
      'version' => '>= 0.7.5'
    },
    'vagrant-reload' => {
      'version' => '>= 0.0.1'
    }
  }
  
  Vagrant.configure(2) do |config|
    config.vagrant.plugins = additional_plugins
  
  ...

• the available Clear Linux boxes, post 31660, ship with UTC as their default timezone. Previously, the default was Europe/Lisbon, since the Author is based in Porto, Portugal.

  Here's how to programmatically set a custom timezone straight from the Vagrantfile:

  config.vm.provision :set_timezone, timezone: 'Asia/Dili'

• The boxes expect the UEFI bios to be found on the host filesystem, where libvirt sits, at /usr/share/qemu/OVMF.fd which is its canonical location on major OSs.

  If you are consuming the boxes over a OS that has OVMF.fd placed elsewhere please adapt your Vagrantfile accordingly:

  config.vm.provider :libvirt do |libvirt, override|
    libvirt.loader = '/NON_DEFAULT_LOCATION/OVMF.fd'
  end

Vagrant Cloud

This project Vagrant boxes are hosted on Vagrant Cloud at AntonioMeireles/Clearlinux

What else do you need to know?

• the default password of the default user (clear) is V@grant!

• a ready to use, over Vagrant, native Clear Linux libvirt setup is available inside extras/libvirt.native

• All boxes use para-virtualized drivers by default, when possible, for optimal performance.

• Both the VMware and VirtualBox boxes ship with a 40GB partition size. libvirt boxes ship, since mid August/2020, with a 5GB one (to resolve #24). In order to increase the partition size in libvirt boxes just mod your Vagrantfile along...

    Vagrant.configure(2) do |config|
       ...
       config.machine_virtual_size = DESIRED_GIGABYTES_AS_INTEGER
       # so in order to create a 15GB instance one would add ...
       # config.machine_virtual_size = 15
       ...
    end

• Graphical/Desktop performance optimization wasn't originally a primary concern as the Author's primary use case was towards headless use.

  Things changed, as the user base increased and spoken, and now desktop focused user cases are first class citizens too.

  Inside extras/gnome-desktop there is a sample Vagrantfile that will fully setup and boot Gnome Desktop on top of Clear Linux.

  • Over a VMware hypervisor just make sure that you are using a box post 29520
    • shared clipboard (copy/paste to/from host) works out of the box since 29780.
  • Over VirtualBox just make sure you are using a box post 29610
    • shared clipboard (copy/paste to/from host) works out of the box.

  So, if you happen to have a desktop oriented use case and something isn't still working as you'd expect just tell!

release schedule

By default these boxes are updated around once a week, unless:

• key functionality, bug fix or whatever, is added either to the guest plugin (changelog) or to the box itself (changelog).
• key features are added to ClearLinux upstream (say - refreshed VirtualBox drivers, key bug fixes, etc).

contributing

This is an open source project released under the Apache License, Version 2.0. Contributions and suggestions are gladly welcomed!