Suggestion for Help Manual

[Gibson]

Nice product! However, as more and more people migrate to Linux-type systems, not being super-familiar with CLI to start with, I think it will be increasingly important your Help manual is given its share of attention. Things need to be made as painfully clear as possible (pretend you're trying to explain things to a 9 year old). I'm stubborn enough it won't turn me off your product just because of having to teach myself things, but I'd sure hate for people to get a bad impression just because they were missing some minor point.

Specifically, but I'm sure only by way of example, as someone new to Linux and VBox, when I read in your User Manual:

"Note that the user who is going to run VirtualBox needs read and write permission on the VirtualBox kernel module device node /dev/vboxdrv. You can either define a vboxusers group by entering

groupadd vboxusers
chgrp vboxusers /dev/vboxdrv
chmod 660 /dev/vboxdrv

or, alternatively, simply give all users access (insecure, not recommended!"

chmod 666 /dev/vboxdrv
...."

I suspect the writer knew exactly what he or she was talking about, but I hope you realize this is not only not as helpful as it could be, it is actually a bit misleading (is still causing me heartburn).

Assume for a moment you're an idiot--okay, a noob--like me. You've just installed VBox, diddled around a bit, tried to re-start or whatever and are told to get lost, you're not a recognized user. Scouring the User Guide, you come to the above passage, which seems to address the issue, but...I feel surely something more is needed to be input, some input of my user name, but it doesn't say so. Maybe just the doing of it allows user detection. Well no, of course it doesnt, but that doesn't stop you from trying inputting the above a couple of times and feeling the pain of rejection. Finally you throw up your hands and input the "666" line, and it lets you continue. Cool, only it keeps resetting every time you re-boot, and you know it just ain't right, so after Googling for a while (mostly to hear everyone taunt you with "Then be sure to add yourself to the usergroup, and you're done!!") But you eventually get it, fix it, and then find out you've just pooch-screwed everything you've done before (see General thread on losing Setup). Oh, then you find the cleverly hidden reference on the website FAQ. Annoyed, yet?

Not trying to be too hard on you guys, but my point is that something as simple as updating the first place everyone is going to look, the User Manual, with info you have already typed into cyberspace--especially on information without which you cannot run the program--should be considered a drugery but very important chore, to be done regularly.

Please add the following, far more explanatory info from your FAQ to the User Manual:

"If you get a message saying "VirtualBox kernel driver not accessible, permission problem" when starting VirtualBox right after installation, make sure that your user account is listed in the vboxusers group. The installation takes care creating that group, but you will need to manually add all users to it that should be allowed to run VirtualBox. As root, for each such user, run usermod -G vboxusers -a <userid>. If any of the affected users are currently logged in, they need to log out for the changes to take effect. In case any user already attempted to start VirtualBox before logging out (which launches the VBoxSVC service process with incorrect permissions), that user additionally needs to run VirtualBox shutdown from the command line to terminate the service. This solves the permission problems. (Alternatively, a reboot will help as well.) "

And one could be even more thorough, to avoid re-boot adventures. The following (which seemed to work, but feel free to correct) is what I wrote in my little IdiotGuide of notes to myself, and for providing any friends I talk into using VBox:

"Next we create the group vboxusers and add our desktop user (here, e.g. greg) to it:

sudo groupadd vboxusers
sudo usermod -G vboxusers -a greg
Now we must change the permissions of /dev/vboxdrv so that it can be accessed by the vboxusers group:

sudo chmod 660 /dev/vboxdrv
sudo chgrp vboxusers /dev/vboxdrv
In order to prevent the permissions from being reset every re-boot, we must edit /etc/udev/rules.d/40-permissions.rules to add a line to the end of that file; so:

sudo gedit /etc/udev/rules.d/40-permissions.rules
then in the opened file:
[...]
KERNEL==”vboxdrv”, GROUP=”vboxusers”, MODE=”0660”
and save the file and exit.
Now you have to re-boot the computer for all this crap to take effect."

If any of these suggestions are helpful, feel free to alter or use. And thanks for making a great product available.

[Technologov]

Well, I believe, that a better solution to the problem above is to build a better VirtualBox installer for Linux. See my idea:

http://www.virtualbox.org/ticket/45

-Technologov