FreeBSD Handbook section 2.6.5 update please!

I have been using FreeBSD now for almost exactly 2 years (I think it was a few months before 7.0 was released), after it was recommended to me by a co-worker who had been using it since version 2 or 3. I had previously been using Ubuntu. When I first started using FreeBSD I read about 80% of the entire Handbook (maybe a little less, but I did spend a week going through it several hours per day) and one thing I noticed that was missing was specific mention of the version of FreeBSD that was available when a section was last updated.

I know in section 2.6.5 it specifically states that non-advanced users should use the automatic settings for slice sizes and assignment, and I learned the hard way that creating a separate mount for /boot will keep FreeBSD from even finishing the install (returns error code -0 I think, when it attempts to install most files, I think /opt does the same, can't recall right now. both of which are commonly created during linux installations nowadays) and does the same if you add too many separately mountable file systems. Maybe that issue can be resolved, maybe it cannot, that is not my point. The point is there is not a warning for new users who are trying to figure out the manual method, nor is the detailed information up to date. I think I tried a few times when 7.2 first launched in RELEASE, but I do not believe that a 512 meg / slice is even compatible with the current FreeBSD installation, and this is what it shows in the Handbook.

I think it is past time with the launch of FreeBSD 8.0 to update this section, I do not see how it would take someone who knows a good bit about the installation of FreeBSD more than 2-3 hours to post on the handbook the absolute minimum slice size and to note the ONLY mount points you can specify during install for individual file systems. It would be nice post recommended sizes and possibly a "there is no reason currently that you should need to create this slice at a size greater than..."

I do not see a negative issue with maintaining a chart of each slice and the minimum/recommended size for each version, that way you can just add a new line to the chart when there is a new release, possibly even doing a column header "for Releases" and data "5.0-6.2" "7.0-8.2" instead of listing each separately. Jus to mark out where there were installation size changes making the minimums change. This will also help people out that are trying to install FreeBSD in the smallest space possible, like a Just Enough 2 Run (JE2R)
 
You know what the best part about FreeBSD is? Even you can submit changes :e
The handbook is also part of FreeBSD and is actively maintained.

But it's probably best to address this on the freebsd-doc@ mailinglist.
 
Putting a statement in each section about what release version a section was written is of no real value as most of the handbook stays unchanged release after release. Now its very turn that changes get made to the base release and the handbook is not updated with those changes before the new release is published to the public. Some times things just slip through the fingers of the doc group. You as a regular user can do your part to support Freebsd by submitting problem reports about the handbook contents, Past the original paragraphs you want to change followed by the changed paragraphs. Your changes will be considered as you wrote them or something different will be written by the doc group that covers the intent of what you were trying to document. The main point is you brought to the attention of the doc group some thing that needs changing. Posting here is not going to get anything changed in the handbook.
 
I agree that this section is in need of updating.

Maybe for my next FreeBSD Friday post, I should finish my in draft article on how to submit changes to the FreeBSD handbook.

Honestly, I have never done actually done it. I plan to actually submit a documentation change to the handbook and post my steps.

Basically, this is the process I plan to follow, but a nice walk-thru for doing this is the goal, so it is easier for others to do it in the future.

  1. Email FreeBSD-doc mailing list announcing the change or addition you want to make and make sure someone isn't already doing it.
  2. Download the handbook (I think in single page per file form)
  3. Backup the file you are going to change.
  4. Make the changes to the html.
  5. Do a diff.
  6. Submit the new version of the doc file and the diff to FreeBSD-doc mailing list.

There is a lot of things you need to know for each of these steps, which is why I have started such a walk-thru.

Maybe I should update section 2.6.5 and use it as my example in my walk-thru.
 
Handbook updates...

I knew there would be a specific process like that, but the main reason why I did not just submit the changes is that I have absolutely no idea what the real recommended file system size per slice during install is. I have basically been guessing. I do a lot of installations (most over top of each other or in VM's) but I normally give BSD a 40-80 GB total size and split it up as such

25% to root "/"
25% to "/usr"
25% to "/var"
5% to "/tmp"
5%-10% to swap
15% free space to add where I need or to make a separate mount point for specific data that needs to be easily and quickly backed up.


Having started in Linux I used to try and create a /boot at 512MB but this causes an installation failure with BSD, I also learned creating a slice for /opt will cause an installation failure. (might have mentioned that in the first post)


So, if you want to do a submission and post the specific steps/method, I think that would help with things that users who like me, know just enough to get in to trouble, will be able to submit useful information for the handbook.
 
Got not problem with a 512MB /.

The contents of / are pretty much stale. Of course if you want make several kernels it can seem small. But for the typical user its plenty as long as you keep with the traditional partitions for /, /tmp, /usr and /var.
 
And slices can be named anything (well, within reason), so creating a slice for /opt should never pose a problem.
 
finndo,

You actually do know what the recommended values are...If you choose to Auto-partition, you get what the FreeBSD dev team has determined that "Auto" should provide, which are the recommended values for an standard install with one disk.

You could simply give an example of how to recreate the same settings you get with Auto. Or/And you could describe how to setup a two drive system. Often Raid systems have many drives but only two logical drives (for example a 10 disk server might have one logical drive that is actually two drives in RAID 0 or 1 for the system, and the other eight drives in a RAID 10), but the install only sees two drives. In such a situation a neat trick is to press Auto (and I believe it populates everything to the first logical drive). Then you create another one additional partition that spans the whole RAID 10 logical disk (/data or /raid10 or whatever you want to name it because it doesn't really matter).
 
setting up slices...

since FreeBSD 6.2 (when I started using it) I have never gotten an installation to successfully complete if I create more slices than stated above (/ /usr /var /tmp swap) additionally if I make root "/" smaller than 2 GB I have 1 of 2 problems, installation fails with a file system full message or it works and the first time I do a freebsd-update, pkgb -F, and portupgrade -ra I end up getting a file system full message. I am doing the installation for a personal use, general purpose / daily use machine, not for a specified task, as such a large portion of ports are installed. I know the ports are stored in /usr/ports by default)

as for the auto setting, I used it once (6.2 or 7.0) and it just skipped up and did an installation instead of showing me the settings, then after I chose all the config options I believe I still had that problem, do not currently have a spare HDD to test that on now though...

My current plan is to use
30GB - /
30GB /usr
10GB /var
5GB /tmp
5GB swap

(which I actually am using at this time)
and in say 8-12 months I'll check my usage levels and adjust from there for my next install/restore. I would hope 12 months of daily use will show me where my storage usage lies. I did install FreeBSD on a 500GB drive, so I have plenty of room to bump any slice as needed. Thanks for all the advice, I guess I put too much info in this thread and it turned into a suggestion box for me instead of a request for handbook update... I do feel there should be a reference in small font and maybe italicized for all future updates stating the FreeBSD version number and date for each section. This at least will allow someone with lots of free time the opportunity to check if something needs updating based off it's age.
 
rhyous said:
  1. Email FreeBSD-doc mailing list announcing the change or addition you want to make and make sure someone isn't already doing it.

I don't know if the docs team works the same way, and tracks all their work via PR's, but with ports I begin by searching the PR database for anything related to what I have in mind.

currently open PR's for the docs category

Adding this step will avoid bothering the mailing list about anything that turns up in the search. ;)
 
finndo said:
since FreeBSD 6.2 (when I started using it) I have never gotten an installation to successfully complete if I create more slices than stated above (/ /usr /var /tmp swap) additionally if I make root "/" smaller than 2 GB I have 1 of 2 problems, installation fails with a file system full message or it works and the first time I do a freebsd-update, pkgb -F, and portupgrade -ra I end up getting a file system full message. I am doing the installation for a personal use, general purpose / daily use machine, not for a specified task, as such a large portion of ports are installed. I know the ports are stored in /usr/ports by default)

as for the auto setting, I used it once (6.2 or 7.0) and it just skipped up and did an installation instead of showing me the settings, then after I chose all the config options I believe I still had that problem, do not currently have a spare HDD to test that on now though...

My current plan is to use
30GB - /
30GB /usr
10GB /var
5GB /tmp
5GB swap

(which I actually am using at this time)
and in say 8-12 months I'll check my usage levels and adjust from there for my next install/restore. I would hope 12 months of daily use will show me where my storage usage lies. I did install FreeBSD on a 500GB drive, so I have plenty of room to bump any slice as needed. Thanks for all the advice, I guess I put too much info in this thread and it turned into a suggestion box for me instead of a request for handbook update... I do feel there should be a reference in small font and maybe italicized for all future updates stating the FreeBSD version number and date for each section. This at least will allow someone with lots of free time the opportunity to check if something needs updating based off it's age.

We're deviating from the topic. I'm sorry to say this you've messed up somehwere (most likely in the created partitions and /etc/fstab) because both the ports tree and installed ports use /usr and freebsd-update files are stored and extracted in /var.
 
rhyous said:
I agree that this section is in need of updating.

Maybe for my next FreeBSD Friday post, I should finish my in draft article on how to submit changes to the FreeBSD handbook.

Honestly, I have never done actually done it. I plan to actually submit a documentation change to the handbook and post my steps.

Basically, this is the process I plan to follow, but a nice walk-thru for doing this is the goal, so it is easier for others to do it in the future.

  1. Email FreeBSD-doc mailing list announcing the change or addition you want to make and make sure someone isn't already doing it.
  2. Download the handbook (I think in single page per file form)
  3. Backup the file you are going to change.
  4. Make the changes to the html.
  5. Do a diff.
  6. Submit the new version of the doc file and the diff to FreeBSD-doc mailing list.

There is a lot of things you need to know for each of these steps, which is why I have started such a walk-thru.

Maybe I should update section 2.6.5 and use it as my example in my walk-thru.

The proper way would be to download a copy of the doc section of the tree via cvs / svn (svn preferred as it's actually patchable without a lot of monkeying around) for 2. and just call cvs diff -u // svn diff on the changed files.
 
ckester said:
I don't know if the docs team works the same way, and tracks all their work via PR's, but with ports I begin by searching the PR database for anything related to what I have in mind.

currently open PR's for the docs category

Adding this step will avoid bothering the mailing list about anything that turns up in the search. ;)

A lot of people `ignore' PR emails (on purpose or by accident... not sure...), so it's best to approach someone directly via email, IRC, etc about your request so that it can get put in motion down the correct path.
 
finndo said:
since FreeBSD 6.2 (when I started using it) I have never gotten an installation to successfully complete if I create more slices than stated above (/ /usr /var /tmp swap) additionally if I make root "/" smaller than 2 GB I have 1 of 2 problems, installation fails with a file system full message or it works and the first time I do a freebsd-update, pkgb -F, and portupgrade -ra I end up getting a file system full message. I am doing the installation for a personal use, general purpose / daily use machine, not for a specified task, as such a large portion of ports are installed. I know the ports are stored in /usr/ports by default)

as for the auto setting, I used it once (6.2 or 7.0) and it just skipped up and did an installation instead of showing me the settings, then after I chose all the config options I believe I still had that problem, do not currently have a spare HDD to test that on now though...

My current plan is to use
30GB - /
30GB /usr
10GB /var
5GB /tmp
5GB swap

(which I actually am using at this time)
and in say 8-12 months I'll check my usage levels and adjust from there for my next install/restore. I would hope 12 months of daily use will show me where my storage usage lies. I did install FreeBSD on a 500GB drive, so I have plenty of room to bump any slice as needed. Thanks for all the advice, I guess I put too much info in this thread and it turned into a suggestion box for me instead of a request for handbook update... I do feel there should be a reference in small font and maybe italicized for all future updates stating the FreeBSD version number and date for each section. This at least will allow someone with lots of free time the opportunity to check if something needs updating based off it's age.

YMMV, but here's what I generally use as a rule of thumb:

1. swap - equal or greater than physical memory (RAM) so that you can store a complete kernel panic if necessary.
2. /var - same criteria as above.
3. /tmp - comfortable enough that you won't have to go cleaning it out all of the time.
4. / - somewhere in the neighborhood of a few hundred MBs to a few GBs (depending on what you're doing on the machine). I have it set to 19GB because I was going to use /compat for Linux stuff too.
5. /usr - at least 20GB if you're going to have a ports tree and source tree.
6. /usr/home - use your better judgment, but I use 30GB today.
7. Whatever else your heart desires :).

You can get an entire FreeBSD install in under 1GB (that includes the base system, stripped down X11, etc), but it's tight. It all depends on what your end use case is and how you use the space...
 
Please do not make changes to the HTML file itself. Please read http://www.freebsd.org/doc/en_US.ISO...mer/index.html. If you want to submit a documentation patch for handbook, you need to download the source of the documentation and make the desired changes to the SGML/XML/XSLT/Make files.

Hmmm....no wonder hardly anybody actually reaches a point where they can submit documentation.

I my opinion, requiring development skills (however simple they may appear to us long time FreeBSD users) is a poor design for documentation, and immediately excludes a lot of would-be contributors. Didn't we just have a discussion on this forum about the fact that people can't even use the editor on this forum with the proper tags but that doesn't mean they cannot write good online documentation? I would love to see the handbook become simple to submit changes for. Like if you login, you get an edit button and you can change/add something, hit submit and an approver can review it and accept or reject the change (more Wiki like). There would be a nice backend that would store each version, so different versions could be viewed/restored. I have contributed to other sites in seconds that use this technology.

Alas, that is not how it is...

However, according to this site:
http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributing/index.html
...Read through the FAQ and Handbook periodically. If anything is badly explained, out of date or even just completely wrong, let us know. Even better, send us a fix (SGML is not difficult to learn, but there is no objection to ASCII submissions).

So yes, it is best if you can learn SGML, but their are multiple levels of "good": Not good, Good, Better, Best. It is not good to have wrong or outdated information. It is best if you can learn SGML, download the documentation source, and edit it there, but it is still good to submit text changes until one can learn SGML.

Anyway, the proper way is the proper way, even if in my opinion it should be much easier.
 
As the Contributing article states -- it is fine to submit plain text version of your revision, although the diff against SGML files is more preffered. However plaintext is still better than a diff against HTML files. I see your point in having a wiki-style documentation resource, unfortunately we still haven't reached this point in the doc team :/ Both sides of the coin have its own advantages as well as disadvantages and our sysadmin team still prefers static files on their web servers due to security. BTW we have wiki.freebsd.org which might serve this purpose one day...

Anyway, it was quiet hard do get this forum up and running :)
 
Back
Top