NAME

SYNOPSIS

DESCRIPTION

Once the guest has been started up successfully, wifibox exposes the wifibox0 bridge(4) networking interface, which needs to be configured further with the help of rc.conf(5), so that the traffic could start flowing through the wireless card.

There is a wifibox system service provided that can be used to start the appliance on boot and stop on shutdown.

CONFIGURATION

By default, PCI pass-through is disabled for AMD-based hardware, hence it must be explicitly enabled via the corresponding syctl(8) variable. This can be done by adding the following line to either /etc/sysctl.conf or /boot/loader.conf depending on whether vmm(4) is going to be loaded by wifibox or it is already loaded at boot.

hw.vmm.amdvi.enable=1

In order to make wifibox work as a system service, the following line has to be added to rc.conf(5).

wifibox_enable="YES"

At the same time, make sure that no FreeBSD driver is configured for the same device and remove all the related settings from there. The devmatch(8) utility might be used to stop any conflicting drivers from loading automatically. For example, the iwm(4) and iwlwifi(4) native drivers could be disabled in rc.conf(5) as shown below.

devmatch_enable="YES"
devmatch_blocklist="if_iwm if_iwlwifi"

Note these settings will only take effect on the next boot. Until then the devmatch service must be started and the drivers should be removed manually by using kldunload(8).

# service devmatch start
# kldunload if_iwm if_iwlwifi

The wifibox service can be then started up as follows.

# service wifibox start

After wifibox started successfully, the IP address for the corresponding networking interface needs to be configured in rc.conf(5). For example, assignment of a dynamic IP address can be requested by adding this line below.

ifconfig_wifibox0="SYNCDHCP"

In addition to this, to reduce boot times, dhclient(8) can be instructed to run in the background and not to wait for a positive link and issuing an IP address after it has been launched.

background_dhclient_wifibox0="YES"
defaultroute_delay="0"

If preferred, static IP address configuration is possible with this method. Assume that wifibox0 is configured as 10.0.0.1/24 on the guest's side, and the host wants to use the 10.0.0.2/24 IP address.

defaultrouter="10.0.0.1"
ifconfig_wifibox0="inet 10.0.0.2/24"

The wifibox0 networking interface can be brought up with the use of the netif service.

# service netif start wifibox0

For static IP address configurations, the routing service has to be restarted as well.

# service routing restart

Note that since wifibox0 becomes managed by netif this way, wifibox has to be restarted every time when the networking interfaces are recreated by netif, otherwise the link will stop working.

# service netif stop
# service wifibox restart
# service netif start

If the devd.conf(5) file is installed, devd(8) must be restarted so the additional configuration file can be read.

# service devd restart

COMMANDS

start

Start wifibox. The wifibox0 interface is created and the guest is attached to the configured PCI wireless network device. The network interface of the FreeBSD driver on the same device must not be configured.

stop

Stop wifibox. The wifibox0 interface is destroyed and the guest is detached from the configured PCI wireless network device. After that, the FreeBSD driver is free to take over the device.

restart [guest | netif | console | vmm]

Restart wifibox, which is the sequential composition of the stop and start commands by default. It is possible to specify a target, therefore limit the scope of this operation in different ways.

guest

Restart the guest only, maintain the console device and the networking interface. This is recommended for applying system-level updates to the guest.

netif

Recreate the networking interface and restart the guest. That latter is required because the networking interface is bound to the virtual machine that runs the guest.

console

Recreate the null-modem device and restart the guest. That latter is required because the null-modem device is bound to the virtual machine that runs the guest. This is recommended when the console support is turned on in the configuration.

vmm

Restart the guest while reloading the vmm(4) kernel module, maintain the console device and the networking interface. This is a workaround for the guest to recover from a state where the wireless device becomes unresponsive after the ACPI resume event.

status

Check and display if wifibox is still running.

console

Attach to the running guest with cu(1) through a virtual serial port, implemented by nmdm(4). This is recommended for troubleshooting problems with the guest in an interactive fashion. It can also be used to perform updates, install or remove packages. This has to be configured specifically in order to work. The actual way of logging into the system as an administrator depends on the VM image in use. Most of the time the root user with a blank password works. See wifibox-guest(5) for more information.

version

Display version of wifibox and the SHA-256 hash of the guest disk image. The output is suitable for reporting errors. Note that custom images are not supported.

DIAGNOSTICS

EXIT STATUS

SEE ALSO

CAVEATS

The restart vmm command should be used with caution, because it may crash the system when it has not been in a sleep state. Hence it is best to use in combination with devd(8).

The restart vmm command will not probably work on systems where other bhyve(8) guests are running in parallel as vmm(4) kernel module could not be unloaded in such cases.

The PCI pass-through implementation of bhyve(8) may not be able to cooperate with the Linux system in the guest due to lack of emulation of certain quirks and features that are required to make the driver work. Sometimes this can cause strange and unexpected error messages. Always try the latest available version of bhyve(8) when this happens.

AUTHORS