bvm.8

.Dd December 26, 2024
.Dt BVM 8
.Os
.Sh NAME
.Nm bvm
.Nd "Bhyve Virtual machines Management tool"
.Sh SYNOPSIS
.Nm
.Cm --help
.Nm
.Cm --version
.Pp
.Nm
.Cm --create
.Ar name
.Op Cm from Ar template-name
.Nm
.Cm --config
.Ar name
.Nm
.Cm --vminfo
.Ar name
.Nm
.Cm --showstats
.Ar name
.Nm
.Cm --os
.Pp
.Nm
.Cm --ls
.Op Ar byname | byos | bystatus | online
.Nm
.Cm --ll
.Op Ar byname | byip | byos | bystatus | online
.Nm
.Cm --login
.Ar name
.Nm
.Cm --start
.Ar name
.Nm
.Cm --restart
.Ar name
.Nm
.Cm --stop
.Ar name
.Nm
.Cm --poweroff
.Ar name
.Pp
.Nm
.Cm --clone
.Ar name new-name
.Nm
.Cm --remove
.Ar name
.Nm
.Cm --rename
.Ar name new-name
.Pp
.Nm
.Cm --encrypt
.Ar name
.Nm
.Cm --decrypt
.Ar name
.Pp
.Nm
.Cm --lock
.Ar name
.Nm
.Cm --unlock
.Ar name
.Nm
.Cm --lockall
.Nm
.Cm --unlockall
.Pp
.Nm
.Cm --addisk
.Ar name
.Nm
.Cm --deldisk
.Ar name
.Pp
.Nm
.Cm --abinfo
.Nm
.Cm --autoboot
.Pp
.Nm
.Cm --reload-nat
.Pp
.Nm
.Cm --setnat
.Ar Nat ip/mask
.Nm
.Cm --setsw
.Ar Switch ip/mask
.Nm
.Cm --unsetsw
.Ar Switch
.Pp
.Nm
.Cm --setpr
.Ar ip
.Nm
.Cm --showpr
.Pp
.Nm
.Cm --showdhcp
.Pp
.Nm
.Cm --showdev
.Nm
.Cm --showdevuse
.Nm
.Cm --showdevall
.Pp
.Nm
.Cm --snapshot
.Ar name
.Nm
.Cm --rollback
.Ar name
.Nm
.Cm --showsnap
.Ar name
.Nm
.Cm --showsnapall
.Pp
.Nm
.Cm --netstat
.Pp
.\" ============ DESCRIPTION =============
.Sh DESCRIPTION
The
.Nm
is a 
.Xr bhyve 8
virtual machine management tool based on FreeBSD that 
allows you to easily manage virtual machines.
.Pp
The virtual machine's network is handled by one or more virtual switches. 
Each switch has a simple name, which is stored in the corresponding 
configuration file and can be modified by the 
.Nm
create one or more 
.Xr bridge 4 
devices for each virtual switch and dynamically assign them to the 
virtual machine 
.Xr tap 4 
interface. When the virtual machine is shut down normally, the 
.Nm
will automatically clean up the useless network devices.
.Pp
The 
.Nm
supports multiple network cards and multiple hard disks. 
Each virtual machine can have multiple network cards or multiple hard disks, 
and can easily add, delete, and modify network cards or hard disks.
.\" ============ BASIC SETUP ============
.Sh BASIC SETUP
Once
.Nm
is installed, the first thing you have to do is set up the virtual 
machine's storage directory.
.Pp
Edit the value of 
.Pa vmdir 
in
.Pa /usr/local/etc/bvm/bvm.conf 
.Bd -literal -offset indent
vmdir=/your/vm/dir/
.Ed
.Pp
If you want to automatically boot the specified list of virtual machines 
in order while the host is booting, add the following 
lines to 
.Pa /etc/rc.conf 
to enable:
.Bd -literal -offset indent
bvmd_enable="YES"
.Ed
.\" ============ OPTIONS =============
.Sh OPTIONS
.Bl -tag -width indent
.It Cm --abinfo
Show information for all auto-bootstrap virtual machines.
.It Cm --addisk Ar name
Add a hard disk to the virtual machine.
.It Cm --autoboot
Start the automatic booting virtual machine in order.
Boot option, which is usually not required in administrator manual 
maintenance mode. Sometimes the host is powered on again after shutdown 
or unexpected downtime. 
At this time, the administrator-set virtual machine can be automatically 
started by the rc script. The method is to use 
.Nm Cm --config 
to modify the default value of the auto boot menu to yes.

In self-start mode, 
.Nm
will refer to the boot level and delay options of vm. The boot level is 
the boot priority. When there are multiple self-starting virtual machines, 
the lower the startup priority, the more the virtual machine starts. 
Back to front. Boot time (boot time) 
After starting the current virtual machine, it can also be said that 
the number of seconds is tentative before starting the next virtual machine. 
The reason for designing these two parameters is because some services may 
need to be activated first to ensure normal business.

For example, the relationship between the database and the web service, 
if the data virtual machine library is not prioritized, 
it may cause the web service to be abnormal! 

The correct way to use this option is to add the startup script:
.Bd -literal -offset indent
# sysrc bvmd_enable=yes
.Ed 
.It Cm --clone Ar name Ar new-name
Clone a new virtual machine from an existing virtual machine.
.It Cm --config Ar name
Edit the configuration of the virtual machine.
This option needs to be used in the case of a virtual machine. Options that 
allow users to configure independently are: cpus, ram, iso path, boot from, 
hostbridge, uefi, auto boot, disk config, and network config.
.Bl -tag -width 17n
.It cpus
The number of CPUs (non-cores) used by the current virtual machine.
.It ram
The size of the memory requested by the current virtual machine, 
the unit of which can be M/G, etc.
.It iso path
The directory where the iso disc image is located (is the directory, 
non-iso absolute address). When the directory is specified, 
.Nm
will automatically list the iso files contained in the current directory. 
The user can select the menu number.
.It boot from
This is an important option. When the system is first installed, 
.Nm
will automatically adjust this option to hd0 for system startup. 
When you need to use iso disc for system maintenance, you can change 
this option to cd0.
.It uefi
This option is mostly used by the operating system that installs the graphical 
interface. It needs to be used with VNC to get the desktop. In addition, 
this option will invalidate the 
.Cm --login 
option because 
.Cm --login 
is a text console and does not have graphical interface operating conditions.
.It auto boot
See 
.Cm --autoboot 
for details.
.It hostbridge
This is a schema attribute whose attribute value should be hostbridge when 
using the Intel system CPU; its attribute value should be amd_hostbridge when 
using the AMD series CPU.
.It disk config
The option can add or delete the hard disk of the current virtual machine. 
If you only want to add the hard disk, it is recommended to use 
.Nm
.Cm --addisk 
shortcut command.
.It network config
This option allows you to configure the networking or networking of 
virtual machines.
.El
.It Cm --create Ar name Op Cm from Ar template-name
Create a new virtual machine.
.Bd -literal -offset indent
# bvm --create vm1
# bvm --create vm2 from vm1
.Ed
.It Cm --deldisk Ar name
Delete the disks in the virtual machine.
.It Cm --decrypt Ar name
Decrypt the virtual machine.
.It Cm --encrypt Ar name
Encrypt the virtual machine.
.It Cm --help
Show all options and descriptions.
.It Cm --login Ar name
Login to a running virtual machine from console, the boot loader of this 
virtual machine must be grub, and the uefi mode needs to log in using 
the VNC client.
.It Cm --ls Op Ar byname | byos | bystatus | online
Show a list and status of all virtual machines.
By default, the output is sorted in ascending order by name, 
or one of the following options is specified.
.Bl -tag -width 17n
.It Ar byname
Output list in ascending order by name.
.It Ar byos
Output list in ascending order by OS.
.It Ar bystatus
Output list in ascending order by virtual machine status.
.It Ar online
Only show running virtual machines.
.El
.Pp
.Bd -literal -offset indent
# bvm --ls byos
NAME        GUEST           CPU     MEMORY  DISK        STATE
c           Debian          1       512M    [2]5.5G     off
d           Debian          1       512M    [1]5G       off *
abc         Debian          1       512M    [1]10G      on
b           FreeBSD         1       1G      [1]10G      off
bb          FreeBSD         1       1G      [1]10G      off

# bvm --ls
NAME        GUEST           CPU     MEMORY  DISK        STATE
abc         Debian          1       512M    [1]10G      on
b           FreeBSD         1       1G      [1]10G      off
bb          FreeBSD         1       1G      [1]10G      off
c           Debian          1       512M    [2]5.5G     off
d           Debian          1       512M    [1]5G       off *
.Ed
.Pp
.Bl -tag -width 17n
The meaning of the list items is as follows:
.It Ar NAME
The name of the virtual machine.
.It Ar GUEST
Virtual machine operating system.
.It Ar CPU
Number of CPUs.
.It Ar MEMORY
Size of memory.
.It Ar DISK
Disk capacity, the number in square brackets represents the number of disks, 
and the capacity is the sum of all disk capacities.
.It Ar STATE
The state of the virtual machine, off or on, if the virtual machine is locked, 
a yellow symbol '*' is also displayed, if the virtual machine is encrypted, 
a red symbol '*' is also displayed.
.El
.It Cm --ll Op Ar byname | byip | byos | bystatus | online
Show a list and status of all virtual machines in long format.
By default, the output is sorted in ascending order by name,
or one of the following options is specified.
.Bl -tag -width 17n
.It Ar byname
Output list in ascending order by name.
.It Ar byip
Output list in ascending order by IP-addr.
.It Ar byos
Output list in ascending order by OS.
.It Ar bystatus
Output list in ascending order by virtual machine status.
.It Ar online
Only show running virtual machines.
.El
.Pp
The added list items have the following meanings:
.Bl -tag -width 17n
.It Ar IP
The IP address of the virtual machine.
.It Ar LOADER
The boot loader for the virtual machine.
.It Ar AUTOSTART
The state in which the virtual machine is automatically started, "Yes" is 
automatically started, and the number next to it is the startup sequence.
.El
.It Cm --lock Ar name
Locks the specified virtual machine, and can't 
.Cm --config
, 
.Cm --remove
,
.Cm --start
, and so on. 
Only simple read operations can be performed, such as 
.Cm --vminfo
, 
.Cm --ls
,
this option also prevents the risk of virtual machine files being accidentally deleted.
.It Cm --lockall
Lock all virtual machines, behaving the same as 
.Cm --lock .
.It Cm --netstat
Show all network configuration information of virtual machines, 
including NIC, mode, IP address, gateway, port forwarding, bridge, 
and TAP device, etc.
.It Cm --os
Show a list of operating systems supported by 
.Nm .
.It Cm --poweroff Ar name
Force the virtual machine to power off. When there are some special reasons 
that prevent the virtual machine from shutting down properly, you need to use 
this option to force the virtual machine to power off.
.It Cm --reload-nat
Reload the NAT port redirect. In general, you do not need to use this option, 
.Nm 
will automatically handle port redirection, this option is manual mode.
.It Cm --remove Ar name
Destroy a virtual machine and it cannot be recovered.
Note that the virtual machine cannot be running when you run this command.
.It Cm --rename Ar name new-name
Rename the virtual machine.
.It Cm --restart Ar name
Restart a virtual machine.
.It Cm --rollback Ar name
Roll back to the snapshot point.
.It Cm --setnat Ar nat ip/mask
Set the IP address and mask of the NAT.
.Bd -literal -offset indent
# bvm --setnat nat0 172.16.1.1/24
.Ed
.It Cm --setpr Ar ip
Port redirection is set dynamically with immediate effect. 
In general, the virtual machine must be turned off to set the 
virtual machine parameters, but this option can set the port redirection 
at any time in the virtual machine on state, and take effect immediately.
.Bd -literal -offset indent
# bvm --setpr 10.10.30.10
.Ed
.It Cm --showpr
Show all list of port redirect.
.Bd -literal -offset indent
# bvm --showpr
PROTO   VM IP:PORT            HOST PORT   VM NAME
tcp     172.16.1.10:22        2224        freebsd-14
tcp     172.16.1.10:80        8080        freebsd-14
udp     192.168.1.254:53      9953        abc
tcp     10.10.30.10:22        3322        ob
.Ed
.It Cm --setsw Ar switch ip/mask
Set the ip address and mask of the virtual switch.
The same method as 
.Cm --setnat .
.It Cm --showdev
Select a network device and show its relationship to the virtual machine NIC.
.It Cm --showdevall
Show a relationship table for all network devices.
.It Cm --showdevuse
Show a relational table of all network devices in use.
.It Cm --showdhcp
Show all DHCP clients.
.It Cm --showsnap Ar name
Show snapshots list of the virtual machine.
.It Cm --showsnapall
Show snapshots list of the all virtual machines.
.It Cm --showstats Ar name
Show the statistics of the virtual machine.
.It Cm --snapshot Ar name
Generating snapshots for the virtual machine.
.It Cm --start Ar name
Start a virtual machine.
.It Cm --stop Ar name
Shut down a virtual machine.
.It Cm --unlock Ar name
Unlock a virtual machine.
.It Cm --unlockall
Unlock all virtual machines.
.It Cm --unsetsw Ar switch
Delete the IP address of the virtual switch.
.It Cm --version
Show the version number of 
.Nm
installed.
.It Cm --vminfo Ar name
Shows the configuration of the virtual machine.
.\" ============ CONFIGURE FILES =============
.Sh CONFIGURE FILES
.Pa /usr/local/etc/bvm/bvm.conf
.Bd -literal -offset indent
This file records the virtual machine's directory and a list of all supported 
operating systems.
.Ed
.Pp
.Pa /usr/local/etc/bvm/nat.conf
.Bd -literal -offset indent
This file records the configuration information for all NAT.
.Pp
nat0=172.16.1.1/24
nat1=10.10.30.1/24
nat2=192.168.1.1/24
.Ed
.Pp
.Pa /usr/local/etc/bvm/switch.conf
.Bd -literal -offset indent
This file records the configuration information of all virtual switches. 
The default 0-2 sets the IP address, and 3-7 is not set.
.Pp
switch0=10.0.1.0/24
switch1=10.0.2.0/24
switch2=10.0.3.0/24
switch3=
switch4=
switch5=
switch6=
switch7=
.Ed
.Pp
.Pa /usr/local/etc/bvm/dhcp.conf
.Bd -literal -offset indent
This file records DHCP configuration information, including lease time,
DNS, IP address pool, etc.
.Ed
.\" ============ SEE ALSO =============
.Sh SEE ALSO
.Xr tmux 1 ,
.Xr bridge 4 ,
.Xr tap 4 ,
.Xr bhyve 8 ,
.Xr bhyveload 8 ,
.Xr zfs 8
.\" ============ BUGS =============
.Sh BUGS
Please report all bugs/issues/feature requests to the GitHub project at
.Lk https://github.com/bigdragonsoft/bvm
.\" ============ AUTHOR =============
.Sh AUTHORS
.An Qiang Guo Aq Mt bigdragonsoft@gmail.com