Advanced Documentation Retrieval on FreeBSD
On Fri, Jul 16, 2021 at 04:23:20PM -0400, ░▒▓░░ ░▐░▒ wrote:
> Hi Tom.
> I just not realized you've not have your inbox assaulted by our listener
> feedback. Is there a specific address you'd like that routed to?
>
> Anyway, here is a choice one.
>
*sigh*
░▒▓░░ I don't know what we should do about Michael . I spoke to a priest
about an exorcism and he said "I'm not going near that monster, not on your
life", which I thought was pretty alarmist for a priest.
Follows is a rough markdown draft of the article "Advanced Documentation
Retrieval on FreeBSD" as we discussed
- Tom
-----------
Advanced Documentation Retrieval on FreeBSD
FreeBSD is renowned for its very high quality documentation. For many queries the man pages have a wealth of accurate and up to date documentation that is frequently a surprise to uses of other operating systems. It is not uncommon to hear from new FreeBSD users that they have to relearn to try the man pages before searching on the web.
Beyond man pages FreeBSD also has very high quality documentation in the form of the FreeBSD handbook. Only talking about the FreeBSD Handbook actually cuts short the range of really high quality documentation that the FreeBSD project offers.
The FreeBSD Handbook covers installation and day to day usage of a FreeBSD system and it is kept reasonably up to date by the FreeBSD documentation team. The handbook is an amazing document that comes from a time before blog posts and wikis and it contains a mixture of official project direction and tutorial style walkthroughs on how to use different FreeBSD subsystems and third party software. Not everything is covered by the handbook and many times only one path of a piece of software use is covered, but it is an excellent resource to get started using and configuring a FreeBSD system.
Deeper into FreeBSD there are several other 'books' that the FreeBSD project maintains. The full list of books is available from https://docs.freebsd.org/en/books/ , it includes technical information about how the FreeBSD kernel works in the forms of the Design and Implementation of the 4.4BSD Operating System and the Architecture handbook. Documentation on how to contribute to different parts of the operating system as the porters-handbook, the fdp-primer and the developers-handbook.
The FreeBSD project also hosts a wiki which contains less formal and in progress documentation, written by users and developers. The wiki can sometimes be much more like a temporary source of information, but it does contain valuable guides. It is the right place for pages such as the laptop compatibility matrix . The wiki is a unique FreeBSD project resource in that users are also able to have edit access.
What else is there?
Beyond the documentation the project provides there are outside sources of information on how to use and configure a FreeBSD system. Searching the web will bring up a lot of Technical information in the form of blog posts and articles.
Searching the web is not the only way to get more information on FreeBSD
systems. We can use external 'daemonised' resources by using the FreeBSD
base system tool
invoke
. This tool is a little esoteric to use
and sadly it is one of the excellent FreeBSD tools written by developers
that just quite haven't seen the light of day.
invoke
ships in the FreeBSD source tree and is in
src/tools/tools/invoke
.
invoke
isn't built by default, but it is
easy to build on a system using its Makefile:
# cd /usr/src/tools/tools/invoke
# make
# make install
invoke
requires quite a lot of information to be useful, annoying the
author ░▒░░▐░▒@ was in the process of writing a book on invoke when
they went missing travelling in rural Romania. However from reading the
source we can see the list of information or 'principals' required to
correctly invoke documentation.
Principals are information locators which are tied closely to the source of the information. Personal web pages of authors work well and are easy to obtain, more potent sources such as hand written notes or the authors blood work the best, but we can substitute social media accounts to get a similar level familiar information about the author.
XXX more on principals XXX
For our example I have collected the personal web page, blog and twitter account of the source we want to use, we can pass them to invoke as arguments or in a configuration file.
In addition to 'principals' the invoke tool needs to be run from a special environment. A comment in the source code describes this, but it took the author some trial an error to figure it out in practice.
/*
* invoke must be run from either a larger or lesser circle. These
* can be ancient such as the very high quality circle at Midmar,
* however, if you are unable to travel a Ars Theurgia Goetia will
* suffice. You must interface the machine running invoke via a
* galvanic isolator. The transformer in an Ethernet connector with
* magnetics works great, if you only have an SBC you'll have to
* figure out something with transformers
*/
From this comment we can see that we need to create a substitute circle to use with invoke and connect it to our computer, but isolate it from the machine. If we fail to isolate properly we can damage the machine and likely destroy it.
We can create the substitute circle by using our preferred ethereal bonding fluid. Blood works very well, but collection can be legally tricky. Luckily we can use a vegan alternative in the form of beeted oat milk. If your local shops don't carry beeted oat milk you can make your own by mixing oat milk with beetroot juice during a full moon.
With the substitute bonding fluid we need to draw our circle for summoning and holding triangle (you can see a good example here ). In this example we are going to use an Ethernet interface with magnetics, all you really need to do is to plug it into the circle.
With the interface connected to the circle we can check for state using
ifconfig, we need to look for the
ETHER
flag in the list of options.
igb0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> metric 0 mtu 1500
options=e507bb<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,JUMBO_MTU,VLAN_HWCSUM,TSO4,TSO6,LRO,VLAN_HWFILTER,VLAN_HWTSO,RXCSUM_IPV6,TXCSUM_IPV6,ETHER>
ether ac:1f:6b:46:9e:da
inet 11.14.17.13 netmask 0xffffff00 broadcast 137.50.17.255
inet6 fe80::ae1f:6bff:fe46:9eda%igb0 prefixlen 64 scopeid 0x1
media: Ethernet autoselect (1000baseT <full-duplex>)
status: active
nd6 options=23<PERFORMNUD,ACCEPT_RTADV,AUTO_LINKLOCAL>
Running Invoke
With our principals collected, and our link established to the circle we
can run the
invoke
command as follows:
# invoke -p [principals] [-i interface] [question]
We pass in the principals we have gather and tell
invoke
the interface
name. If you hacked together a device you'll need to pass in the gpio
controller and pin using -d, for the gpio controller and -P for the pin
number.
# invoke -p [principals] -d /dev/gpioc0 -P 1 [question]
The final argument to invoke is a quoted string that contains the question.
If you are all set up then you can use
invoke
to summon your
documentation author of choice, for this example I am using
Michael W.
Lucas
:
# invoke -p https://mwl.io https://twitter.com/mwlauthor -i igb0 "How do I configure dummynet with weighted fair queues?"
If all goes well you should hear (an normally quite grumpy) disembodied voice bark the answer to your question back to you.
As great as this is for single questions sometimes you want the author
to hang around and help with protracted debugging sessions. We can
achieve this with the
manifest
option to invoke:
# invoke -p https://mwl.io https://twitter.com/mwlauthor -i igb0 manifest
With this option you will get the author directly summoned into the triangle attached to your summoning circle. Care should be taken with manifestations, the circle and triangle must remain intact for the duration of the session. If you are using a laptop (which I recommend and you need to use with an existing circle). Then make sure to watch the battery life careful.
If you don't properly shutdown the session then you risk getting the spirit of the author trapped in your machine and no one wants that.
Conclusion
FreeBSD has a great range of available documentation, but sometimes you
hit the limits of information that is readily available online. Here we
discussed the
invoke
command and the ways it can be used to get direct
help from the authors of high quality documentation that are a little
too public.
