Suggested man page improvement -- spell out guest vs host better

Description

A clear and concise description of what the problem is. What is expected from the application?

Before I start, I want to say I love wifibox. My comments below are ways I think will make it more accessible to a wider audience.

The configuration paragraph

     After the installation to the system, check the sample configuration
     files provided in the /usr/local/etc/wifibox directory and follow the
     instructions to create a working configuration, otherwise wifibox will
     refuse to start.

is too vague. Specifically, the following items should be mentioned somewhere:

All wifi connection is 100% handled by the Linux guest, so one must copy any working wpa_supplicant.conf to `/usr/local/etc/wifibox/wpa_supplicant/wpa_supplicant.conf. The host's wpa_supplicant.conf is unused. One option might be to have an option that uses the host's wpa_supplicant.conf though.
This connection is an IP NAT using 10/24 as the network. That's already my home network, so it caused some confusion when I first started. One must edit the following files in /usr/local/etc/wifibox/appliance to change this: interfaces.conf, udhcpd.conf, uds_passthru.conf. As someone unfamiliar with Linux networking, it took a while to find these.
I'd also mention that this isn't a drop in replacement for any wifi card you're using in FreeBSD (it is obvious to me now that I dug in and found the hidden NAT).
Cross reference to ip, iw commands, ideally with the most useful ones spelled out to aid in debugging the problem. Also an explicit not of NO-CARRIER -> you don't setup wpa_supplicant.conf right in the manual would be helpful.
A note on the bhyve passthru setup would be good. Especially the format it goes in. People that have done this before know, but newbies won't know to translate (yes, I know there's a note in bhyve.conf that says to, but having it in both places would be helpful). Strangely, despite my extensive FreeBSD and bhyve experience, I'd not setup a PCI passthru before.
A note about core.conf controlling the debugging level and the suggestion to change it to debug if you encounter problems.
A note about USB. No clue if it works, could work, etc.

so, having been super picky, I'd like to end this on the following note: In not too much time i was able to get this up and working. My RTL8822BE card works well under linux. I was able to hit fast.com and it told me I had a 200Mbps connection (the mac next to this laptop gets 300Mbps). Still, this is way better than the usb stick which had troubles hitting 1Mbps some days.

thank you so much for climbing this hill and sharing it with the world.

Host operating system

Output of `uname -a`.

Wireless NIC

Relevant output of `pciconf -lv`.

Wifibox version

Output of `wifibox version`.  Note that only the latest version is supported.

Disk image type and version

The kind of VM image in use, e.g. Wifibox/Alpine, and its version.

Changes to the default configuration files

Include relevant sections from all the configuration files that contain local changes and may help to reproduce the problem.

Logs

Please copy and paste any relevant log output from the following sources:

- /var/log/wifibox.log (with DEBUG logging verbosity)
- /var/run/wifibox/appliance/log/dmesg
- /var/run/wifibox/appliance/log/messages

Additional context

Add any other context about the problem here that might help the investigation.

Have you tried to turn it on and off?

[X] Yes, I have read all the manual pages first!

Thanks @bsdimp for reporting all these problems back and not giving up on Wifibox! The problem of documentation was raised in #82 where I have followed up in a generic, high-level answer which touches upon many of these points.

Here I would like to get into the details along answering each of the points. But first of all, let me agree with you: the sentence in question in the "Configuration" section of the manual page is indeed too vague. This could have been more elaborated but I could not come up with better at the time of writing and there are a couple of design principles that had to be taken into consideration. I would like to still do that while improving on the clarity.

Wifibox is only responsible for managing and supervising the Linux guest. Due to its design, it does not really have any knowledge about WPA Supplicant and its configuration. This is handled entirely by the guest, therefore information like that should be presented on the manual page of the guest itself. This is currently wifibox-alpine(5), which tries to give the users a relatively detailed description on how it is constructed and how it should be used. There are at least two reasons not to allow using /etc/wpa_supplicant.conf directly: 9P-based file-system passthrough for bhyve does not implement file-level sharing (like Docker containers could do) therefore the whole /etc directory would need to be shared, which I do not consider secure. It is not guaranteed that the Linux guest would run exactly the same version of WPA Supplicant as the FreeBSD host and it may use different configuration options or layout. But I agree that it should be emphasized better that the wireless connection is handled exclusively by the Linux guest.
This is somewhat a chicken-and-egg problem. I did not want Wifibox to be too overwhelming to the users and I filled out the example configuration files with defaults that could work for users most of the time. In my books, "check" includes reviewing and revisiting the files as actions required to create a working configuration but I accept that reviewing and revisiting as specific actions should have to be spelled out. For interfaces.conf, udhcpd.conf, and such there are links planted pointing to the corresponding manual pages. The uds_passthru.conf is a Wifibox-specific file, wifibox-alpine(5) and the comments there should be enough to assist the users about its contents. In my opinion, none of these are really about Linux networking but using the specific third-party tools. The rest is just classical IPv4 and IPv6 networking, the use of iptables(8) might be the only exception.
Right, this is not a drop-in replacement for FreeBSD wireless networking. But there is still the potential though. It only depends if we could somehow solve the bridging problem in the virtual machine. Projects like wlan_kabel might give some hope, I was actually make it work to some degree with Wifibox as well. At the moment, we have to stick to NAT and accept its consequences. Note that the title of wifibox(8) says "embedded (virtualized) wireless router" but this theme is not carried on later through the document. I thought that being not a drop-in replacement is evident, but I can see that the possibility of importing the WPA Supplicant configuration from the host may confuse users about there might be NAT in use.
I believe these are all described on wifibox-alpine(5) or wifibox-guest(5) and general guidance is provided for troubleshooting at the "Diagnostics" section. But I admit there is an explicit reference is missing that would orientate the users towards this specific page, it is only mentioned for the console command.
I do not see why the information about the byhve PCI pass-through configuration in the main wifibox(8) document would have to be replicated. It is the configuration file where this piece of information has to be utilized, the syntactical specifics would not add too much value to the document. Note that rc.conf(5) is discussed there only because the port/package does not modify its contents on installation, hence it is the place where the related information could be provided. For all the configuration files, where Wifibox has the control over, it is enough to plant the hints in the specific files.
I agree, the "Diagnostics" section could explicitly tell where to the increase the log level for troubleshooting. I would not go into the details though, as the details of that may change and it is better to keep them encapsulated in core.conf.
Sure, there could be a note added about the lack of support for USB to the "Caveats" section. This has not occurred to me. It is definitely better to be more explicit on this.

All in all, this is a small, one-developer project basically, therefore the review process is rather light. I was trying to do my best to catch many of such oddities in the documentation, but apparently a single pair of eyes is not enough for that. That said, I really appreciate your comments and hopefully I will be soon back with a PR with the proposed fixes.

pgj / freebsd-wifibox