Bug 213175

Summary:

[handbook] Precisions/caveat for 30.8 Diskless Operation

Product:

Documentation

Reporter:

Natacha Porté <natbsd>

Component:

Books & Articles

Assignee:

Rodrigo Osorio <rodrigo>

Status:

Closed FIXED

Severity:

Affects Only Me

CC:

allanjude, dru, rodrigo

Priority:

---

Version:

Latest

Hardware:

Any

OS:

Any

Attachments:

Description	Flags
Proposition of documentation improvement	none

Description Natacha Porté 2016-10-03 17:08:29 UTC

Hello,

a few days ago I found myself exactly in the situation solved by the Handbook in chapter 30.8 "Diskless Operation with PXE". I'm as impressed as usual with the quality and efficiency of FreeBSD documentation, which made the few slightly-harder points stand out. I'm proposing to help fix these points. I think I will try to submit a patch in a few days, but there could be some helpful discussion prior to making it, so I'm submitting the bug without a patch for now.

In case it matters, my situation is that I've been trying to build a silent desktop, in the idea of "NUC" or "nettops", with a fanless low-power CPU, a fanless power unit, and something other than a hard drive for the OS. It seems to get a bit hot in there though (~50°C on the cores) so I'm a bit afraid to burn my SSD, so I decided to try a diskless operation, by having the OS on a NAS in another room. I don't know yet how to deal with /home, as an unauthenticated read-write NFS makes me a bit uneasy even on a wired LAN.

The first issue I encountered is in paragraph 30.8.1 "Setting Up the PXE Environment", at step 14. I installed some packages in the root served over NFS. With pkg-ng, that means updating the repository and (by default) keeping a copy of the packages. That made my /var over 130MB. Proceeding to make conf/base/var.cpio.gz, I didn't realize that /var would end-up in a 5MB mfs, which causes enough problems to prevent booting altogether.

I would suggest at least mentioning conf/base/var/md_size around the end of 30.8.1

The second issue I encountered is in the same paragraph, step 3 (but it manifests after having solved the previous one. I don't know enough of NFS to be sure of what is going on, but it seems `-maproot=root` is needed to have a working system. The symptoms were weird, like the mfs still being at 5 MB (but the system boots completely), and not having the permission to run /sbin/shutdown. If I hadn't read diskless(8), which mentions `-maproot=0`, and hadn't thought it weird root not having some execute permission, I might still be scratching my head on this.

Lastly, I used 10.3-RELEASE .txz archives instead of make buildworld/buildkernel/installworld/installkernel/distribution, but I'm not sure whether it's worth talking about this alternative in the handbook.

Hoping this helps,
Natasha

Comment 1 Sevan Janiyan freebsd_committer

2016-10-04 13:48:21 UTC

Hi Natacha,

Comment 2 Sevan Janiyan freebsd_committer

2016-10-04 13:57:06 UTC

(In reply to Sevan Janiyan from comment #1)
derp
I hit take with the intent to finish a reply later, after writing hello & realising I need some more time to write a reply because I should read the article you mention. Any way, as I've already started I'll go on.

The points you raised seem valid & sensible however I've not had a chance to read the article. I would prefer to opt to direct readers to the official archives as a primary rather than walk them through the buildworld step as it saves considerable time. however it should mention the ability to use buildworld also, perhaps pointing to the necessary handbook article[1] to avoid duplicate instructions & noting a DESTDIR suffix if needed.

[1] https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html

Comment 3 Natacha Porté 2016-10-10 15:38:03 UTC

Thanks Sevan for your review.

I was hoping for more discussion, so I could stand more confidently behind my proposed patch. As a result it is likely not optimal, but at least it is a proposition.

I added the option `-maproot=root`, removed the details of how to rebuilding the world, added a reference to the official archives as a primary mode of seeding the base filesystem, and hinted to the use of md_size for /var.

The patch is against the current head of `master` branch in freebsd-doc github repository [1], but hopefully this chapter is static enough to be easily merged.

[1]: https://github.com/freebsd/freebsd-doc/commit/3e755a3d2d7dff3dc3ada70588eff6953f52eb4c

Comment 4 Natacha Porté 2016-10-10 15:39:21 UTC

Created attachment 175606 [details]
Proposition of documentation improvement

Comment 5 Sevan Janiyan freebsd_committer

2016-11-12 15:52:30 UTC

(In reply to Natacha Porté from comment #3)

Hi Natacha,
Apologies for the delay in replying, what's the reason for specifying -maproot=root??

Comment 6 Natacha Porté 2016-11-12 16:46:22 UTC

(In reply to Sevan Janiyan from comment #5)

`-maproot=root` is needed because otherwise root on the PXE machine (NFS client) is mapped to nobody on the NFS server, which makes it impossible to execute /sbin/shutdown (and therefore switch off cleanly the PXE machine), to read /etc/spwd.db (and therefore authenticate users), and a few other useful system things.

Comment 7 ann mariya 2016-12-09 04:28:50 UTC

MARKED AS SPAM

Comment 8 Oliver 2017-06-09 08:32:52 UTC

MARKED AS SPAM

Comment 9 gloriawin 2017-10-10 06:12:53 UTC

MARKED AS SPAM

Comment 10 gloriawin 2017-10-10 06:13:29 UTC

MARKED AS SPAM

Comment 11 Rodrigo Osorio freebsd_committer

2018-02-02 16:39:06 UTC

time-out, take this ticket into my basket

Comment 12 Rodrigo Osorio freebsd_committer

2018-02-08 11:20:13 UTC

Natacha :

-maproot=root : Agree, even if is not visible, without this option you can't perform a shutdown. Nevertheless reboot works.

The part about the md allocation should be rephrased : by default the size should be expressed in 512 bytes unit or a unit can be at the end of the numbers.
Maybe you can just reuse the manpage sentence.

10240 means 5m

Also the manpage share/man/man8/diskless.8 needs to be updates, at least for the file size :)

The diskless scripts create memory file systems to hold the
overridden directories.  Only a 2MB partition is created by default,
which may not be sufficient for your purposes.  To override this, you
can create the file /conf/base/etc/md_size containing the size, in
512 byte sectors, of the memory disk to create for that directory.

Comment 13 Rodrigo Osorio freebsd_committer

2018-02-12 20:41:36 UTC

Natacha,

I create a review with your patch, and including the modifications I suggest,
let me know if it's fine for you or if it requires changes.

Comment 14 Rodrigo Osorio freebsd_committer

2018-02-12 21:46:06 UTC

(In reply to Rodrigo Osorio from comment #13)
https://reviews.freebsd.org/D14336

Comment 15 commit-hook freebsd_committer

2018-03-05 15:51:18 UTC

A commit references this bug:

Author: rodrigo
Date: Mon Mar  5 15:50:48 UTC 2018
New revision: 51461
URL: https://svnweb.freebsd.org/changeset/doc/51461

Log:
  update/correct the Handbook Diskless operations chapter

  - Add the -maproot=root to the NFS export configuration
  - Mention base archive from the ftp server as an alternative way to install the base system
  - Fix the <command> usage
  - Add details about how to use md_size files to increase the default mfs size for /var and /etc

  PR:		213175
  Submitted by:   Natacha Porte <natbsd@instinctive.eu>
  Reviewed by:	sevan bcr ian
  Approved by:	ian sevan
  Sponsored by:	The FreeBSD Foundation
  Differential Revision:	https://reviews.freebsd.org/D14336

Changes:
  head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml

Comment 16 Rodrigo Osorio freebsd_committer

2018-03-05 15:52:44 UTC

committed with minor changes, tanks