[LUDOC-224] Chapter 30 partial review

• Type: Bug
• Resolution: Fixed
• Priority: Minor
• Severity: 3
• Assignee: Richard Henwood (Inactive)
• Reporter: Christopher Morrone (Inactive)

Description

Here is some review of Chapter 30 sections.

The subsection "30.2.1. Provisioning the Build Machine and Installing Dependencies" is in the wrong place. It should be under "30.1. Overview and Prerequisites".

This note need updating:

A patched Linux kernel is NOT required in order to build the Lustre client code. The steps below for building the Linux kernel are only required if a new kernel is needed for a Lustre server.

It should be something like "Patching your kernel is only required if you want to use ldiskfs. A patched kernel is NOT required for Lustre clients or for Lustre servers using ZFS."

Create a user called build with a home directory /home/build:

This is unnecessarily complicated. There is no need to create a special user just to build Lustre. The chapter should be reworked to remove that.

Also in section "30.2.2. Preparing the Lustre Source" there are two different autogen.sh steps, which does not really make sense. One is titled "Resolve any outstanding dependencies.", but autogen.sh does not resolve outstanding dependencies. I think I understand what the author had in mind, but that needs to be redone.

In section "30.2.3. Preparing the Kernel Source" the first step is "Get the kernel source:". And then the commands don't have anything to do with getting the kernel source. Even if you correct the title ("Set up your personal rpm build tree"), I don't we you should advise folks to make a custom rpm development tree just for the kernel. It would be better to make this more generic. You might even suggest that they install the rpmdevtools package, and then they can just use the rpmdev-setuptree command to do the set up.

"30.3. Building the Lustre RPMs" starts out with "30.3.1. Building a New Kernel". That doesn't make any sense organizationally. Building the kernel rpms is building the kernel rpms, not building the lustre rpms.

I would suggest moving "30.3.1. Building a New Kernel" up under 30.2, and renaming 30.2 to "Building a Custom Linux Kernel with Lustre Patches".

In 30.3.2, the very first command is not the method that we should be recommending:

"./configure --with-linux=/home/build/kernel/rpmbuild/BUILD/
kernel-2.6.32-358.14.1.el6_lustre.x86_64/"

We should not have them point to the temporary internal build directory that rpmbuild uses. Instead we should tell them to install the required kernel rpms, and point at the location of the source that they install.

"The resulting RPMs are in ~build/kernel/rpmbuild/RPMS/x86_64"

That needs updating to match changes from my earlier complaint. Now you can see why it is silly to name it "kernel" if we're not just putting the kernel in there.

"30.3.3. Installing the Lustre Kernel" is out of order like I said. Needs to come before the lustre build.

"Create initrd using dracut:

1. /sbin/new-kernel-pkg --package kernel --mkinitrd --dracut
   --depmod --install 2.6.32-358.14.1.el6_lustre.x86_64"

This is odd. I don't think users should need to do this. Perhaps something specific to Intel's build farm? This should probably be removed from the manual.

"A login prompt such as that shown below indicates success:

Red Hat Enterprise Linux Server release 6.0(Santiago)
Kernel 2.6.3-358.14.1.el6_lustre.x86_64 on an x86_64

client-10login:"

Don't include this in the manual. If they don't know what a booted node looks like, they have absolutely no hope of compiling, installing, or configuring a lustre filesystem.

In 30.3.4, the manual is using a kernel path inconsisent with the preceding part of the chapter. "uname -r" is probably bad advice too, if they just built the kernel and haven't rebooted yet.

Comments

[Gerrit Updater]

Richard Henwood ([e-mail]) merged in patch http://review.whamcloud.com/9259/
Subject: LUDOC-224 build: remove redundant build instructions.
Project: doc/manual
Branch: master
Current Patch Set:
Commit: a2060869a7515e40d358fe366f5b32cf7cb794aa

[Richard Henwood (Inactive)]

For future reference, there is indeed a section (8) on installing the Lustre software earlier in the manual:

http://build.whamcloud.com/job/lustre-manual/lastSuccessfulBuild/artifact/lustre_manual.xhtml#installinglustre

[Richard Henwood (Inactive)]

Thanks for you comments here Chris. We will prioritize this work when we do our backlog grooming.

[Christopher Morrone (Inactive)]

Also, lets drop the entire "30.4. Installing and Testing a Lustre File System" subsection, and change the section 30 name to "30. Compiling Lustre". We've surely already told people how to install lustre elsewhere in the book (at least I truly hope so, or this manual is far worse than I thought). Just reference those existing installation instructions. No need to replicate it again here.

[Christopher Morrone (Inactive)]

Some additional changes:

This section first describes how to prepare your machine to serve as a development environment

Drop that sentence. This isn't about development, just about how to build the code.

A patched Linux kernel is NOT required in order to build the Lustre server code provided you use ZFS.

I believe that was possible in 2.4+, not just 2.5+. At least it is with LLNL's branch...

Get the MASTER branch of the Lustre software from the Lustre software git repository:

Perhaps it would be better to show them how to clone, and then checkout a specific tag of lustre rather than master ("master" is all lower-case, by the way).

If autogen.sh completes successfully, a response similar to the following is displayed:

I would drop that output. It is likely to change over time, version numbers will be different for different systems, and we'll never keep the document up to date.

rpm -ivh http://ftp.redhat.com/pub/redhat/linux/enterprise/6Server/en/os/SRPMS/kernel-2.6.32-358.14.1.el6.src.rpm 2>&1 | grep -v mockb

Remove the "2>&1 | grep -v mockb" part. Sounds like that was cut-and-paste from some mystery script (like lbuild ).

Further, why make them manually use rpm and a full URL (which isn't easy to discover, because those directories on the redhat server are all unlistable by a normal anonymous login)? It would probably be better to use yum.

3. Prepare the source using rpmbuild

You are missing steps here. You only installed the src rpm. The spec file in question is not found under ~/kernel/rpmbuild/SPECS. Also, that is no longer the correct path since we switch to using rpmdev-setuptree. Thirdly, there is no reason to "cd" into that directory to issue the rpmbuild command.

The text displayed ends with the following:

Don't show this either. That is subject to change at any time, we'll never keep it up to date, etc. (plus it is embarressing that there is an error displayed in the quoted output). Just explain where the binary rpms should have appeared if the command succeeded.

The kernel source with the Red Hat Enterprise Linux patches applied is now residing in the directory /home/build/kernel/rpmbuild/BUILD/kernel-2.6.32-358.14.1.el6.x86_64/

Still need to change that, but you already mentioned you are going to look into that.

1. cd ~/kernel/rpmbuild/BUILD/kernel-2.6.32-131.2.1.el6/
   linux-2.6.32-131.2.1.el6.x86_64/
2. make oldconfig || make menuconfig
3. make include/asm
4. make include/linux/version.h
5. make SUBDIRS=scripts
6. make include/linux/utsrelease.h
7. make rpm

We need a good explanation of why this weird, non-standard set of procedures is need to build the kernel. This suggests to me that something is wrong with the preceding procedures.

If a request to generate more entropy appears, some disk or keyboard I/O needs to be generated. You can generate entropy by entering the following on another terminal:

1. grep -Ri 'any_text' /usr

I think that is a bad suggestion for entropy. I would remove that. Why do we need to talk about entropy at all? Does "make rpm" try to cryptographically sign the rpm by default?

Text similar to the following is displayed:

...
...
LLCPPFLAGS: -D_arch_lib_ -D_LARGEFILE64_SOURCE=1
CFLAGS: -g -O2 -Werror
EXTRA_KCFLAGS: -include /home/build/lustre-release/config.h -g
-I/home/build/lustre-release
/libcfs/include -I/home/build/lustre-release/lnet/include
-I/home/build/lustre-release/
lustre/include
LLCFLAGS: -g -Wall -fPIC -D_GNU_SOURCE
Type 'make' to build Lustre.

I think we should just remove all entries of this kind from the document.

[Christopher Morrone (Inactive)]

Well, I'm more suggesting that all that user stuff is unnecessary. I'm not clear on why you think it is. Explain to me this: I'm logged in to my Linux box and my username is "morrone". Why do I need to create a clear new user to build Lustre?

[Richard Henwood (Inactive)]

I think you're suggesting: assume all the user stuff is already be understood by the audience and leave it out of the document.

[Christopher Morrone (Inactive)]

My preference is to keep in building as non-root: I don't read it as adding too much additional complexity and I do read it as an example of good or best practice.

Using root and using a new user are not the only two options. You can also just build it. I'm not sure that I understand what gain you think a new user supplies.

[Richard Henwood (Inactive)]

Thanks for this Chris.

I have prepared a partial update:
http://review.whamcloud.com/9259

I have some comments:

+ You can build as root and avoid creating a user. You can also not build as root. My preference is to keep in building as non-root: I don't read it as adding too much additional complexity and I do read it as an example of good or best practice.

+ I agree that the build should not use the temporary patched kernel source. I need to investigate a little more on how to use the built kernel.

+ I needed dracut when I first developed the build steps (on the wiki). I will need to review to check it is not needed any more.

My preference is to close this ticket (provided the patch is reviewed and carry over the remaining tasks to a new ticket.)