[PC-BSD Public] port path

Christian Baer christian.baer at uni-dortmund.de
Sat Jul 20 04:58:50 PDT 2013

On 19.07.2013 22:26, Lars Engels wrote:

>> Excellent! I wouldn't have guessed it on my own but it does the job more
>> than well!

> FreeBSD is well documented. You have manpages for most programs and
> functions. For ports use "man ports". :-)

Sorry for jumping into the discussion like this, but this is something I 
have an urge to comment. :-)

The over-documentation-myth of open source software is still around as I 
see. FreeBSD is well documented in comparison with other systems 
(especially Linux) but looked at on it's own, the documentation still is 
not exactly "a burner", as German people tend to say nowadays.

The FreeBSD Handbook is more like a collection of howtos (Linux style) 
which tell a user to do this then press that and have a coffee but give 
very little background knowledge - if any. Sure, all the steps are 
(usually) there, but if you want to vary the setup (because your own 
position happens to be a little different than the authors), you find 
next to nothing that can help you.

Take chapter 19.14 in the Handbook as an example...

gbde and geli are both just thrown at the (probably novice) user. Why is 
gbde still on the top? Why are the differences not explained? The really 
big difference lies in this one sentence:

   geli is fast as it performs simple sector-to-sector encryption

But I doubt that any normal user can grasp the fundamental meaning 
behind this. All other listed features of geli could also be added to gbde.

One of the features listed ist the choice of algorithm - but there is no 
mention that a user should never user blowfish on a modern drive and 
especially not triple-DES, unless he *really* knows what he is doing.

The sector size of 4K is mentioned with one sentence but only 
recommended for better performance. This is actually an improvement! The 
last time I looked at this text there was just an init -s 4096

When the file system is created, a dd is run over the device first. The 
user is not told why. And frankly I don't know why if=/dev/random is 
set. Either you fill /dev/da2 with random numbers or you fill 
/dev/da2.eli with zeros. Filling /dev/da2.eli with random numbers is 
pretty redundant and only slows down the whole thing. A novice who has 
never run dd over a disc before might think the system (or the process) 
has crashed.

There is no mention of onetime, what XTS and CBC are or any other 
features of geli - that are listed in the sector on geli. Sure, you can 
read the manpage on geli but if you argue like that, you don't have to 
bother with a handbook at all.

The section is too short to be of any use to just about 
anyone. The same basicly goes for 19.15. (encrypted swap space). In There is actually a reference to read 12.7. for more info and 
this can be very frustrating for a user, because that section is very 
short, hard to grasp and contains absolulely no information on or 
reference to geli.

I know, I know, if I don't like it, I can go and write better 
documentation - and I have in the past. But this is not about that. This 
is about the myth that everything is so well documented. I like FreeBSD 
and I use it all day. But I see problems and without that, we will never 
try to solve them.

Best regards,

More information about the Public mailing list