This set of notes track the steps I followed to install Gentoo Linux on an HP DL380 G8 server. The goal is is simply to get a bare system up and running on the hardware with encrypted LVM, booted from BIOS. Updates and configuring for use come later, perhaps in another post.
The server is powered on, and has booted from the latest Gentoo Minimal Installation CD ISO, downloaded from here and written to a USB thumb drive. At the server console I took the following actions:
Set root password using passwd command.
Ran net-setup and set one of the NICs to get an address automatically via DHCP.
Started SSH by issuing /etc/init.d/sshd start command.
After doing the above, all of the steps that follow below were done through an SSH session to the server from my workstation, at the point in the Gentoo Handbook equivalent to the “Preparing the Disks”.
Preparing Disk and File Systems
So this will be a BIOS boot build with the simple partitioning scheme outlined in the table below.
Rest of the disk
Always make sure you are working against the correct storage device. I am using the lsblk command below to confirm the storage in the server I want to install Gentoo onto is actually recognized as /dev/sda, and it is. Device dev/sdb is the USB thumb drive with livecd image I used to boot the server.
Some math is required to identify the optimal partition alignment. We will take the disk’s optimal_io_size, add the alignment_offset if any, and divide the total by the physical_block_size to get the sector we should start partitioning at. The Gentoo live CD environment conveniently has bc available for doing the calculation and the solution for me was to start at sector 1536. Them math helped me avoid parted giving me Warning: The resulting partition is not properly aligned for best performance. messages.
This is where the actual changes are made to the disk and from which point. The below is what worked for me, your mileage may vary. The important part is to get the disk partitioned in the way that you want.
One last check before moving on.
Data Partition Encryption (sda3)
Here I use cryptsetup to create a LUKS encrypted partition on my data partition dev/sda3. Eventually I plan to use a key file stored externally to the server to decrypt the luks partition. Doing that will require a customized initramfs which will not be covered in these notes, so I will also add a pass phrase to unlock LUKS in addition to the key file.
Create Key File
I use dd to write random data to the key file. The usual warning applies, always be extremely cautions when using dd, mistakes can result in data loss. It is a powerful tool and you own the responsibility or using it, whether the outcome is good or ill.
Create Encrypted Partition Using Key File
Add Pass Phrase
By default, the genkernel tool used below to build the initramfs for the server expects to decrypt the server’s LUKS partition using a pass phrase it prompts for during boot. It is important to add a pass phrase to unlock the LUKS partition as it will be a default requirement until the initramfs is customized. It can be removed at a later time if desired.
Make Encrypted Partition Available as /dev/mapper/lvm
Being able to open the LUKS partition is an important milestone, things are going well so far when this works.
Backup LUKS Header
Having a backup will be the only chance of restoring access to the LUKS partition in the event of corruption.
Copy enc.key and luks-header.img to Another Device
It is critical that you copy the enc.key file to an external device before rebooting the system as it will be lost on reboot with all other file system changes in the live CD environment. It mad sens to me that I should copy the LUKS header backup off at the same time.
I used scp to copy the files from the server to the workstation I am building the server from, but there are other methods to stash the files as well. What is important is only that the files are copied to some persistent storage outside of the server itself.
Setup LVM Within Encrypted Partition
Standard LVM commands are used to set up the logical volumes within the LUKS partition as follows.
The volume group name I chose to use is vg0.
I created a swap partition, and a root partition using the lvcreate commands below.
Make File Systems
Below I format and apply file systems as indicated in the following table.
Boot Partition /dev/sda2
Swap Partition vg0-swap
Root Partition vg0-root
Mount File Systems
The first step into entering the environment which ultimately be the server setup I am building is to mount the eventual root file system at /mnt/gentoo.
Mount root Partition to /mnt/gentoo
Activate swap Partition
Next I activate the swap partition so it can be used.
Base System Install
Set Time on Server
Starting out with accurate time will always make an install go smoother. The ntpd time server is used for this as below, but you could also set using date command and likely other methods.
Retrieve a Stage3 File from Nearby Mirror
Find a nearby mirror, and pick a stage3 file that suits your needs. The systemd stage3 file I picked below was my choice and may not be what you are looking for. The Gentoo Handbook has additional detail on how to select and retrieve a stage3 file.
Extract Stage3 File
If the tar command does not work, check the compression type of the file retrieved and adjust the decompression switch as appropriate.
Remove Stage3 File After Extraction
No need to leave the stage3 file laying about after extraction as its relevance degrades as time passes, and likely there will be a new one for retrieval if required for some reason.
Configure Compile Options
See the guidance from the Gentoo Handbook for mor information. I essentially went with the default recommendation as below. Use your favorite text editor to make any needful changes.
Set Mirrors in make.conf File
Pick a few nearby, or not, mirros from which updates will be retrieved and add them to portage’s make.conf file.
There are just a few more things to set up before we can chroot into the environment which will become the servers operating system environment.
Copy DNS information
Copy the, presumably, working DNS information from the live CD server environment into the environment being built.
Mount Needed Server File Systems
Like the DNS information, some of the server’s file systems created at boot of live CD environment need to be made available in the environment being built after chroot.
Enter Chroot Environment
Mount Boot Partition
We mounted the root file system and activated swap before entering the chroot environment. Now it is time to mount the boot partition, /dev/sda2.
Download and Install Portage Files
The nonexistent directory message in the output below is expected as the directory does not exist until the first time the command is run and the path is created.
Choose Desired Machine Profile
List, then select. What I select may not be right for you. More information on portage profiles.
I am in the US Central timezone, so that is what I use.
Configure and Set Locales
I have simple US locale needs, so en_US.UTF-8 UTF-8 are fine for me. Sadly, no vi available in chroot environment, so nano :<.
Update to pick up new locale settings, then restore the chroot prompt to keep track of which environment I am working in.
Configure fstab File
I am going to use UUIDs to specify my drive partitions, so I use the blkid command to list all the UUIDs, and then I select the ones I need to use, those for vg0-swap, vg0-root and /dev/sda2 (boot).
So I have:
And the /etc/fstab file looks as below, when I finished being angry that nano is not vim.
Kernel Configure and Build
It’s time to start installing things, starting with the kernel sources, the genkernel tool, and the cryptsetup tools.
The Portage package manager tool is emerge. It is similar too and different from package managers in other distributions, and will be used in the remainder of these notes to install additional software starting with kernel source.
Genkernel is a utility which automates the kernel build steps and initramfs build. Sadly the install did not go as smoothly as it should have, and I am starting to think I should have read the news items.
It seems the default Gentoo licensing profile has become more restrictive. As a result the linux-firmware dependency pulled in by the genkernel build did not go immediately as expected. I don’t think this will be a problem. The below may be useful for when you find yourself in a similar situation where more than minimal interaction is needed to get a package installed.
Let’s do as instructed and run the install command again with the –autounmask-write switch to prompt for and add the needed modifications.
Changes have been added, but now we need to accept the modified configuration files. I believe etc-update is the only option until I get around to installing gentoolkit package. Let’s give it a try. I haven’t used etc-update in a while, but pressing 1 took me to a view of the proposed change, pressing q exited the view, and finally pressing 1 again replaced the original license file with the updated file.
At this point we are ready to run the install again, and this time it should work, and indeed does. The install ran successfully to completion.
These will be needed in the initramfs during boot to deal with decryption of the LUKS partition.
Purely optional, but not for me as there are more files to edit, and I have had about all I want to do with nano for the day. An unfortunate side effect of learning to use vim is that I find myself angered when it is not available and I have to use something else. It is not that other editors are bad, just that I am always using vim instructions only to discover they do nothing but pollute the file I am editing.
Building the Kernel, at Last
As a short cut for coming up with a kernel configuration file, I am going to jumpstart things by simply copying the configuration of the kernel the live CD environment booted the system with. It is convenient, is known to produce a kernel that can actually boot the server and saves this post from becoming even longer than it is now.
I did make one change to the Gentoo specific features, changing the init system from OpenRC used in the Live CD environment to Systemd which I want to use in my finished server. Other than that I made no changes to the configuration I extracted from the booted kernel.
Once past the build process and when I have a server that boot successfully, I will revisit the configuration in detail removing unnecessary components, and adding anything needed which is missing.
GRUB is the boot loader I am going to be using, so now is the time to install and configure it.
To configure GRUB to boot properly, I need to specify the UUID of LUKS partition, /dev/sda3 as well as the UUID of the LVM rootdrive vg0-root. As before, I turn to blkid command to identify UUID, but any other method will likely do fine.
So, the LUKS partition UUID in this case is 94a30c4c-0c67-4847-ada5-6e68eb1d8c73. From earlier work setting up fstab, i have the UUID of the actual root partition, vg0-root, as f90eca20-efcd-4cf2-ad2a-02d640a82362. Now let’s Backup and edit /etc/default/grub config file as follows.
In an ideal world, the following grub command should pick up the installed kernel, initramfs and create a boot loader entry capable of decrypting the LUKS partition to use the root and swap volumes within.
Set Root Password
Set the password for the root account within the chroot environment before rebooting as below. This is also a good time to add non-root users to the system if you choose, I’ve opted to do that later after the server can boot on it’s own.
Now is the point I need to reboot and see if I have a working server. My expectation is the server will boot after prompting for pass phrase to decrypt the LUKS partition.
First I need to exit and close the chroot environment.
Unmount File Systems and Reboot
Finally it is time to unmount the file systems and reboot.
Hopefully none of this is needed, but just in case here are some notes about going about fixing things if the server does not boot as expected. It essentially comes down to understanding what went wrong and then reentering the chroot environment after booting from USB to fix the issue.
Boot system from ISO
Open LUKS parttition
Mount vg0-root on __/mnt/gentoo
Enter chroot environment
Mount boot drive
Fix what is broken
Repeat as needed
As you may have inferred from the screenshot at the top of the post and the lack of detailed troubleshooting information, server booted up fine. I was able to login on the console as root and begin the working on setting up systemd services and other software needed to make this into the KVM host it one day will be.
It is probably worth mentioning that the system built following the steps above will come up without network connectivity or ssh running. So you will need to be comfortable configuring a NIC using ip or ifconfig and route. If you plan on using DHCP to provide network addresses, you should consider emerging a DHCP client package before rebooting.
Finally, as should be clear if you read the far, the server is using systemd for its init system. If that is not what you want, then these are not the instructions you should be looking at.
While I have used Gentoo as my primary operating system for many years now, it’s been many years since I have had the opportunity to run through a fresh install. Rolling releases keep on working if you keep on updating and the only reason to start from scratch is when you have new hardware. It was a long process to document the steps, but it is nice to have current notes to replace my seven year old notes.
As always, many of my notes and steps I followed were inspired by the work of others who have been kind enough to share their experience on the web. I encourage review of the sources listed in the reference section, especially guidance from the Gentoo Handbook when unsure of what really should be done.
Chrls is currently a technology transformation leader at one of the oldest American investment banking services holding companies, headquartered in New York City. Previous roles at current employer include project manager, front office support, retail and enterprise global Windows server support. Currently residing in Tennessee on the Cumberland Plateau and enjoying life, family and open source.