This guide will explore how to create VM with custom machine name in Vagrant. We will also see how to set a custom name for the virtualbox VM using provider-specific configuration. Though this topic will be simple, it is essential to understand what happens behind the scenes when a VM is created using Vagrant. A dedicated section is also available explaining the use of ID and INDEX_UUID files and how vagrant use it to manage the virtual machines.

RELATED ARTICLES: Vagrant Series

Default Vagrant & Virtualbox VM Name

STEP 1: Create a directory to create vagrantfile. In my case, I am creating a directory named vagrant_vm in /tmp.

$ mkdir /tmp/vagrant_vm
$ cd /tmp/vagrant_vm

STEP 2: Create a minimal vagrantfile. I am using ubuntu/jammy64 for demonstration.

$ vagrant init -m ubuntu/jammy64

$ cat Vagrantfile
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"
end

STEP 3: Run the vagrant up command to spin up the virtual machine.

$ vagrant up
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Importing base box 'ubuntu/jammy64'...
==> default: Matching MAC address for NAT networking...
==> default: Setting the name of the VM: vagrant_vm_default_1710442536650_12319

Pay attention to the first and last line from the above command output. Two names are allocated.

1. Vagrant Name – This is the name assigned to the vagrant machine. By default, it will be set to ‘default’ unless you explicitly set a name. Running vagrant global-status –prune will show you the metadata and state about all available VM.

$ vagrant global-status --prune
id       name    provider   state    directory                                               
---------------------------------------------------------------------------------------------
acfcaa5  default virtualbox running  /tmp/vagrant_vm  

2. Virtualbox VM Name – This is the name you will see in the virtualbox. The default format will be ‘DIRECTORY-NAME_VAGRANT-MACHINE-NAME_TIMESTAMP’

Virtualbox UUID & Vagrant UID

Let’s deep dive and understand what happens behind the scenes when a VM is created through vagrant.

The vagrant will create a directory named .vagrant where all metadata and other machine-related objects are stored.

$ tree .vagrant/
.vagrant/
├── bundler
│   └── global.sol
├── machines
│   └── default
│       └── virtualbox
│           ├── action_provision
│           ├── action_set_name
│           ├── box_meta
│           ├── creator_uid
│           ├── id
│           ├── index_uuid
│           ├── private_key
│           ├── synced_folders
│           └── vagrant_cwd
└── rgloader
    └── loader.rb

Under the machines directory, a directory will be created with the vagrant name. In this case, it is set to default. Under the default directory, a new directory will be created with the provider name. In this case, it is virtualbox. Metadata related to the vagrant and VM is stored under this directory.

.vagrant/
├── machines
│   └── default
│       └── virtualbox

When you create a VM in virtualbox with or without vagrant, it will allocate a UUID. The UUID will not be visible in the virtualbox UI but you can run the following command to get the UUID.

$ VBoxManage list vms
"vagrant_vm_default_1710442536650_12319" {6a192de0-d78e-42d2-94a8-0cdf122f7539}

The UUID will be stored in the ‘id’ file under the .vagrant/machines/defaults/virtualbox/ directory. Vagrant uses the UUID to manage the virtual machine.

$ cat .vagrant/machines/defaults/virtualbox/id
6a192de0-d78e-42d2-94a8-0cdf122f7539

The Vagrant also creates one more ID for internal use and maps it with the vagrant machine. It is also stored under the ‘index_uuid’ file under the .vagrant/machines/defaults/virtualbox/ directory.

$ cat .vagrant/machines/defaults/virtualbox/index_uuid
acfcaa5a5f9f422f807cfb54f823f029

Now that you know what happens when behind the scenes, let’s see set custom machine name in Vagrant.

How To Set Custom Machine Name In vagrant

The config.vm.define method allows you to create a VM custom machine name in vagrant. Here the name is set to “ubuntu_server”.

Vagrant.configure("2") do |config|
  config.vm.define "ubuntu_server"
  config.vm.box = "ubuntu/jammy64"
end

If you look at the first line of the below output, the machine is created with the custom name.

$ vagrant up
Bringing machine 'ubuntu_server' up with 'virtualbox' provider...
==> ubuntu_server: Importing base box 'ubuntu/jammy64'...
==> ubuntu_server: Matching MAC address for NAT networking...
==> ubuntu_server: Setting the name of the VM: vagrant_vm_ubuntu_server_1710445771442_30541

Run the ‘vagrant global-status –prune‘ command to check the metadata about the vagrant machine.

$ vagrant global-status --prune
id       name          provider   state    directory                                               
---------------------------------------------------------------------------------------------------
af99041  ubuntu_server virtualbox running  /tmp/vagrant_vm   

As foretold a directory with vagrant machine name will be created under .vagrant/machines.

$ tree .vagrant/machines/
.vagrant/machines/
└── ubuntu_server
    └── virtualbox

To configure the virtual machine, you can also use the config.vm.define method with the do…end block.

Vagrant.configure("2") do |config|
  config.vm.define "ubuntu_server" do |ubuntu|
        ubuntu.vm.box = ubuntu/jammy64
        ubuntu.vbguest.auto_update = false
        ubuntu.vm.box_check_update = false
        ubuntu.vm.hostname = "ubuntu.devrunops.com"
    end
end

How To Set Custom Virtualbox VM Name

The config.vm.provider method allows you to set a custom machine name in vagrant for a specific provider. Here the name of the virtuabox VM is set to “ubuntu_server” same as the vagrant name.

Vagrant.configure("2") do |config|
  config.vm.define "ubuntu_server"
  config.vm.box = "ubuntu/jammy64"
  # Below block sets the Virtualbox VM display name #
  config.vm.provider "virtualbox" do |vbox|
    vbox.name = "ubuntu_server"
  end
end

The first line and the last line of the below output show the vagrant name and virtualbox VM display name set to ubuntu_server.

$ vagrant up
Bringing machine 'ubuntu_server' up with 'virtualbox' provider...
==> ubuntu_server: Importing base box 'ubuntu/jammy64'...
==> ubuntu_server: Matching MAC address for NAT networking...
==> ubuntu_server: Setting the name of the VM: ubuntu_server

Wrap Up

Now you should have a good understanding of how to set a custom machine name in vagrant and virtualbox. We have also seen how Vagrant uses the id and index_uuid files to manage the virtual machine. Tampering the *id file will stop the machine from working properly.