Debugging Vagrant Issues

1. Enabling Debug Logging

Option	Values	Description
VAGRANT_LOG	`debug`	Set to `debug` to enable verbose logging
VAGRANT_LOG	`info`	Set to `info` for standard logging level
VAGRANT_LOG	`warn`	Set to `warn` for warning-level logging only
VAGRANT_LOG	`error`	Set to `error` for error-level logging only

Example: Setting Debug Log Level

VAGRANT_LOG=debug vagrant up

Example: Redirecting Logs to File

VAGRANT_LOG=debug vagrant up > vagrant.log 2>&1

Note: Debug logs can contain sensitive information. Ensure logs are handled securely and not shared publicly.

2. Setting Log Level

Adjusting the log level in Vagrant helps control the verbosity of output during operations. By default, Vagrant logs at the INFO level.

Log Level	Description	Usage
DEBUG	Most verbose logging, includes detailed internal operations and debugging information.	Use for troubleshooting complex issues or development of Vagrant plugins.
INFO	Standard logging level, shows normal operation details and progress.	Default setting; suitable for general use and most debugging scenarios.
WARN	Logs warnings and errors only, suppresses informational messages.	Use to reduce noise when running scripts or automated processes.
ERROR	Only logs errors, suppresses all other messages.	Use for minimal logging or when only error reporting is needed.

Example: Setting Log Level via Environment Variable

export VAGRANT_LOG=DEBUG
vagrant up

Example: Setting Log Level via CLI Flag

vagrant up --debug

3. Using Verbose Output

Example: Running Vagrant with Verbose Logging

vagrant up --debug

Option	Description	Usage
--debug	Enables debug mode with detailed logging	`vagrant up --debug`
--verbose	Increases verbosity level for more output	`vagrant up --verbose`

Note: The --debug flag provides the most detailed logs, including internal Vagrant operations and provider-specific messages.

Warning: Verbose output can be extremely long and may include sensitive information. Do not share logs publicly.

4. Checking VM State

Command	Description	Notes
vagrant status	Shows the current state of all Vagrant-managed VMs	Lists VMs in the current directory and their state (running, suspended, etc.)
vagrant global-status	Shows all Vagrant VMs across the system	Useful for managing VMs not in current directory or checking orphaned VMs
vagrant reload --provision	Restarts and re-runs provisioners on a VM	Useful for applying config changes or resetting state after errors

Example: Checking VM status

$ vagrant status
Current machine states:

web1                      running (virtualbox)
db1                       suspended (virtualbox)

$ vagrant global-status
id       name    provider   state    directory
------------------------------------------------------------------------
1234567  web1    virtualbox running  /home/user/myproject
8901234  db1     virtualbox suspended /home/user/myproject

Note: The vagrant status command only shows VMs in the current directory, while vagrant global-status provides a system-wide view of all managed VMs.

5. Validating Vagrantfile

Validation Step	Description	Command	Notes
Syntax Check	Checks for valid Vagrantfile syntax	`vagrant validate`	Runs basic syntax validation without provisioning
Configuration Check	Validates configuration against Vagrant version	`vagrant validate --config`	Ensures all config options are supported in current version
Plugin Compatibility	Checks if required plugins are installed	`vagrant plugin list`	Lists installed plugins and versions

Example: Validating Vagrantfile

vagrant validate

Note: The vagrant validate command checks the syntax and configuration of your Vagrantfile, ensuring it's compatible with the current Vagrant version.

6. Viewing SSH Configuration

Configuration Option	Description	Default Value	Notes
config.ssh.host	Host to connect to via SSH	`127.0.0.1`	Used when connecting to the guest machine via SSH
config.ssh.port	Port to connect to via SSH	`22`	SSH port used to connect to the guest machine
config.ssh.username	Username to use for SSH connection	`vagrant`	Default user for Vagrant-managed machines
config.ssh.private_key_path	Path to the private key for SSH authentication	`~/.vagrant.d/insecure_private_key`	Default insecure key used by Vagrant
config.ssh.shell	Shell to use for SSH commands	`/bin/bash`	Shell used to execute commands in the guest machine

Example: SSH Configuration in Vagrantfile

config.ssh.host = "192.168.10.10"
config.ssh.port = 2222
config.ssh.username = "vagrant"
config.ssh.private_key_path = "/path/to/private/key"

Note: The default private key is insecure and should be replaced in production environments.

7. Accessing Provider Logs

Log Type	Description	Location	Notes
Provider Logs	Logs from the underlying virtualization provider (e.g., VirtualBox, VMware)	`vagrant logs` or provider-specific log paths	Use `vagrant provision` to trigger logs if needed
Vagrant Logs	Internal Vagrant logs for debugging	`.vagrant/` directory in project root	Enable with `VAGRANT_LOG=debug vagrant up`

Example: Enabling Debug Logs

VAGRANT_LOG=debug vagrant up

Note: Provider logs are typically found in the provider's own log directory or via its CLI tools.

8. Debugging Provisioners

Provisioner Type	Debugging Method	Notes
shell	`vagrant provision --debug`	Enables verbose output for shell scripts
ansible	`vagrant provision --debug`	Use `--debug` flag to see Ansible output
chef-solo	`vagrant provision --debug`	Debug Chef runs with `--debug` flag
puppet	`vagrant provision --debug`	Enable Puppet debug mode via `--debug`

Example: Debugging Shell Provisioner

vagrant provision --debug

Note: Use vagrant provision --debug to get detailed logs from provisioners.

Common Debugging Steps

Run vagrant provision --debug
Check logs in /var/log/vagrant/
Verify provisioner script syntax
Ensure required dependencies are installed

9. Testing Network Connectivity

Example: Check VM network configuration

vagrant ssh
ifconfig

Command	Description	Notes
vagrant ssh	Connect to the VM via SSH	Useful for running network commands inside the guest
ping	Test network connectivity to another host	Use `ping google.com` to test external connectivity
ifconfig	Display network interface configuration	Shows IP addresses and network status
netstat	Display network connections and statistics	Use `netstat -tuln` to show listening ports

Note: Ensure that the Vagrant box has proper network configuration (NAT or private network) to allow external connectivity.

10. Inspecting Box Metadata

Property	Description	Example
name	Name of the box	`"ubuntu/focal64"`
version	Version of the box	`"20.04.20230517.1"`
provider	Provider used (virtualbox, libvirt, etc.)	`"virtualbox"`
checksum	Checksum for box integrity	`"sha256:abc123..."`
checksum_type	Type of checksum (sha256, md5)	`"sha256"`

Example: View box metadata

vagrant box list --details

Example: Show box info

vagrant box show ubuntu/focal64

11. Checking Port Conflicts

Port	Service	Usage in Vagrant	Conflict Indicators
22	SSH	Default SSH access to guest VM	Connection timeout or "port 22 already in use" errors
80	HTTP	Forwarded HTTP traffic (if configured)	Browser shows "connection refused" or "port in use"
443	HTTPS	Forwarded HTTPS traffic (if configured)	Browser shows SSL/TLS errors or "port in use"
2222	SSH	Alternative SSH port (if configured)	Connection errors or "port 2222 already in use"

Example: Check Port Usage on Host

# Check if port 22 is in use
lsof -i :22

# Check all forwarded ports
vagrant port

Note: Vagrant uses dynamic port allocation by default, but can conflict with existing services on the host machine.

12. Resolving Guest Additions Mismatch

Issue	Description	Solution
Version Mismatch	Host and guest VM have different VirtualBox Guest Additions versions.	Update Guest Additions on the guest to match host version.
Installation Failure	Guest Additions fail to install or compile due to missing headers.	Install kernel headers and rebuild modules.

Example: Update Guest Additions

vagrant plugin update vagrant-vbguest
vagrant vbguest --status
vagrant vbguest --install

Note: Ensure VirtualBox and Vagrant versions are compatible.

Warning: Manual updates may require VM reboot.