Skip to content

Commit 3a3746c

Browse files
committed
docs: [#10] add DHCP lease behavior explanation to libvirt setup guide
- Add new section explaining why multiple DHCP leases appear - Clarify that this is normal behavior when VMs are created/destroyed - Provide example output and explanation of active vs expired leases - Add verification commands to check active VMs - Include DHCP lease cleanup instructions - Explain impact on development workflow - Add DHCP lease information to diagnostic commands section This helps users understand the expected behavior when running 'virsh net-dhcp-leases default' and seeing multiple lease entries.
1 parent b272f1b commit 3a3746c

File tree

1 file changed

+70
-0
lines changed

1 file changed

+70
-0
lines changed

infrastructure/docs/third-party/libvirt-setup.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -439,10 +439,80 @@ ip link show virbr0
439439
virsh list --all
440440
virsh pool-list --all
441441

442+
# DHCP lease information
443+
virsh net-dhcp-leases default
444+
442445
# Log analysis
443446
sudo journalctl -u libvirtd --since "1 hour ago"
444447
```
445448

449+
## 🌐 Understanding DHCP Lease Behavior
450+
451+
### Why Multiple DHCP Leases Appear
452+
453+
When you run `virsh net-dhcp-leases default`, you might see multiple entries
454+
even if you're only using one VM. This is **normal behavior** for the
455+
following reasons:
456+
457+
1. **Lease Persistence**: DHCP leases don't immediately disappear when VMs are
458+
destroyed - they persist until their natural expiry time
459+
2. **VM Lifecycle**: Each time you run `make apply` and `make destroy`, a new
460+
VM is created with a different MAC address
461+
3. **Unique MAC Addresses**: Each VM deployment gets a fresh MAC address,
462+
creating a new DHCP lease entry
463+
464+
### Example Output Explanation
465+
466+
```console
467+
$ virsh net-dhcp-leases default
468+
Expiry Time MAC address Protocol IP address
469+
--------------------------------------------------------------------------------
470+
2025-07-04 18:03:22 52:54:00:02:c2:8b ipv4 192.168.122.51/24
471+
2025-07-04 18:12:03 52:54:00:76:41:06 ipv4 192.168.122.172/24
472+
2025-07-04 17:57:29 52:54:00:ea:19:a4 ipv4 192.168.122.161/24
473+
```
474+
475+
In this example:
476+
477+
- **192.168.122.172** - Current active VM (has hostname "torrust-tracker-demo")
478+
- **192.168.122.51** and **192.168.122.161** - Previous VM deployments
479+
(expired/inactive)
480+
481+
### Verifying Active VMs
482+
483+
To see which VMs are actually running:
484+
485+
```bash
486+
# Check running VMs
487+
virsh list --all
488+
489+
# Check if any VMs are consuming the leased IPs
490+
ping -c 1 192.168.122.172 # Should respond if VM is active
491+
ping -c 1 192.168.122.51 # Should timeout if VM is destroyed
492+
```
493+
494+
### DHCP Lease Cleanup
495+
496+
- **Automatic**: Leases automatically expire based on their expiry time
497+
- **Manual**: You can restart the libvirt network to clear expired leases:
498+
499+
```bash
500+
# Restart default network to clean up expired leases
501+
virsh net-destroy default
502+
virsh net-start default
503+
```
504+
505+
**Note**: This will interrupt network connectivity for running VMs, so only do
506+
this when no VMs are active.
507+
508+
### Impact on Development
509+
510+
This behavior **does not affect** your development workflow:
511+
512+
- New VM deployments get fresh IP addresses
513+
- Old leases don't conflict with new deployments
514+
- The infrastructure works correctly regardless of lease history
515+
446516
## 🆘 Emergency Reset
447517

448518
If nothing else works, completely reset libvirt:

0 commit comments

Comments
 (0)