Lunar Linux is a revolutionary linux distribution in that it is not binary based, as are most distributions, but is instead built entirely by compiling sourcecode, using your own custom optimizations.
Essentially, it installs a complete bootstrap development system on your machine, and then you tell the Lunar package manager what tools you want, and it builds the entire system by downloading current source code and locally compiling an optimized system tailored toward your specific needs.
The result is a leaner, meaner, refreshingly uncluttered, and strikingly faster operating system than most linux distributions.
This installation guide is designed to get you through the installation process as painlessly as possible. It assumes that you have some experience with linux or another Unix variant, and have a general idea of what you are doing. If you are unfamiliar with such things as partitions, or have never used linux before, Lunar may not be the best introduction for you into the world of open source. There are always Lunar gods available on irc.freenode.net in the #lunar channel to answer any questions that this manual may not make quite clear enough.
With that said, we hope you enjoy using Lunar!
About this installation manual
Unfortunately, this manual is very incomplete and inspecific. You will see examples that are not tailored towards your to-be built server or workstation, optimizations that are overly broad or too specific, and examples that don't apply to any real situations. We tried hard to give you the idea of how much power you have over how you can setup your system, but we are forgetting to tell you how to run your own server or desktop (or other system) at all. That means that the examples and steps taken most probably do not apply to your situation at all.
Do not dispair: if you understand what is going on and you get the idea, the installer will allow you to do pretty much everything you want to do with your system. There are really (almost) no limits.
Getting the ISO
The primary site for retrieving the ISO is lunar-linux.org. There, you will find links to our US, EU, and Internet2 mirrors, as well as a Bittorrent link. As of this writing, the current version of the Lunar ISO is version 1.5.0. (Check the main site for the actual latest version!)
Locate and retrieve the file lunar-1.5.0-i686.iso.bz2. After downloading this file, you will need to unpack the ISO using bzip2. Windows users will need a program that can extract bzip2 archives, like WinZip (also capable of extracting bzip2 archives under windows are Winrar, powerarchiver and 7-Zip). Mac should unzip the file by itself. Then all that is left to do is use your favorite program to burn the ISO to a cdrom and begin the installation. Lunar can also be installed without using a CD. If you need to do it this way, our FAQ provides simple instructions.
It should be noted that this ISO and Lunar use devfs for device management. If you prefer the "old-school" method of manually installing devices, there is an ISO available with this option at thing.fwsystems.com.
We are assuming the you are installing Lunar as your primary OS. Make sure you have a backup of any important data that you need to retain. The Lunar Linux Project and its developers are not responsible in any way for any loss of data on your system!
Booting the ISO
Upon booting the ISO, the first thing you will see are options for booting the ISO kernel, or for performing RAM tests. There is even a safe mode which will disable DMA, MTRR, RAID, LVM, USB keyboards, NTFS, HPFS, Advanced Partitions, and Firewire. Most folks, however, will be just fine pressing enter at the boot prompt and loading the default kernel.
To boot the iso with support for your usb keyboard: linux uhci-hcd ehci-hcd
After loading the kernel, the first screen presents you with a few options. If there are extra modules you need to load in order continue with the install, they can be loaded here. There is also a shell option. However, if you are using this ISO for rescue purposes, you do not want to shell out here; rather continue booting and shell out in the next section. Most people will select "continue booting" here.
It should be noted that since 1.5.0, the iso tries to autodetect some hardware (mostly scsi drivers and network interfaces) during this stage. This will help you establish a network connection if you desire so during installation. For this reason the prorams 'dhcpcd' and 'ftp' are already available at this stage.
Once the ISO has booted into the installer, you can immediately shell out or switch to one of the other virtual consoles. These will have ready to go root shells and are available throughout the installer sequence. With these you can start rescue actions, setup networking or double check the install progress and make manual adjustments.
Language and keyboard interface Settings
After reading the introduction, you will be presented with options for choosing the proper font, keymap, and language for your install. You will also need to choose an editor, as you are going to need one later on in the installation for setting up your lilo or grub configuration. The three choices available are vi, joe, and nano. If you have never used a text editor in linux before, nano is the best choice for you. If you skip the Native Language Support option, the system will install the default editor, nano, for you. When you have finished setting up your options, press cancel to return to the main setup menu. Less important for most people is the ability to choose the console font, although it may help display some non-english characters. Most people will want to set the system-default language variable and editor though. All these values are unset by default, so make sure you set them now. The keymap table allows people to use azerty and dvorak keyboards, and much more. This is especially required for non-english keyboards which provide many accented characters. All these language and keymap settings might not apply to the lunar code itself, which (currently) does not have any international support, but most programs that run during the installer sequence, and after booting into your new system, will be affected properly.
Creating or editing Partitions
The next step is to set up partitions on your hard drive. Upon selecting the "Partition Drive" option, you will be shown a list of all the discs the kernel has detected. For this guide, we will assume that you have one hard drive connected via an IDE channel, which will show up in the menu as "disc0". After selecting the disc to partition, you are given the option of using one of three partitioning programs. They are:
- cfdisk -- A menu driven partitioner, and very easy to use. If you are unfamiliar with various partitioning programs, this is the best option for you.
- fdisk -- Text based partitioner that requires a little more know-how than cfdisk. More experienced users will probably use this program. However new users should not be daunted, as it does have help offered at every step.
- parted -- Text based partitioner that is good for advanced users. Parted is excellent for resizing current partitions on your hard disk, however be forewarned that resizing partitions is an excellent way to hose your entire disc.
For our example, we have a 40GB IDE drive and we'll set up six partitions; /, /boot, /home, /usr, /var, and a swap partition. It's a good idea to keep certain directories, such as /var and /usr on separate partitions, as this can save you a lot of headache in the future incase your disk ever completely fails on you and you need to recover data (god forbid!). Also, when you have a separate /boot partition as we have in our example, you need to have your partitioning program mark that partion as active or bootable. In our example, if we were using fdisk, you would press "a" at the command line, and then select part1 as the active partition.
You might also want to install a /tmp partition. By default, Lunar will create a tempfs filesystem mounted on /tmp (tempfs minimizes filesystem fragmentation because it resides in volatile memory). This can be a good choice if you have a lot of memory on your machine. If memory is tight, we recommend creating a /tmp partition to minimize filesystem fragmentation.
It is important to note that you can not mount the directories /etc, /bin, /sbin, /dev, /lib and /proc on separate partitions. These directories need to be contained within the root ("/") directory. The installation program should block you from doing this, but it's best not to try.
Here's our partition setup:
1 /boot 100MB 2 / 4GB 3 swap 1GB 5 /usr 10GB 6 /var 10GB 7 /home 15GB
(If you're wondering about this choice of partitions: it's really just an example. Read the FAQ on what makes sense in the real world))
You'll notice that there is no fourth partition in our list above. In order for you to have more than four partitions on a single drive, the fourth partition is made into what is known as an extended or logical partition in which the fifth, sixth, and seventh (etc, etc) partitions reside. For our example above, if we were using fdisk, we would make the fourth partition an extended/logical partition that was 35GB, and then the fifth, sixth, and seventh partitions in our scheme resided within it. However, if we used cfdisk, we would just worry about creating six partitions, making sure that the first three are the primary type, and the last three logical.
Note that the names and mount points for these partitions will be assigned during the next step of this process, when you mount the partitions. Write down exactly what partitions you are planning to create because it can otherwise get confusing!
Lunar offers two choices when it comes to swap. You can set up a swap partition, as we have in our example, or you can set up a swapfile in the root directory. We recommend setting up a swap partition, as you will get better performance with it than with the swapfile. However, there may be a need for you to set up the swapfile instead, which can be setup and activated after you have mounted your other partitions.
Selecting Partitions and Filesystems
After creating your partitions, you need to select them and assign file systems. Select the menu option "Select Filesystems" and verify that you are indeed done creating partitions.
The partitions can be selected in random order with the new installer. First select the partition and then assign a filesystem and mountpoint to it. The installer will add this to the job queue and formatting and mounting takes place later so you can edit your selection. Here's a list of filesystems that are currently supported:
- ext2 (Second Extended File System) -- Version 2 of the Extended File System, which was designed for linux as a replacement for the Minix Filesystem. Ext2 is not a journaled filesystem, which means that you'll need to perform disc recovery operations after a power failure or other such system crash. This filesystem is available with all kernels on the ISO.
- ext3 (Third Extended File System) -- Version 3 of the Extended File System, which is essentially just the journaled version of ext2. This filesystem is available with all kernels on the ISO.
- reiserfs (Reiser Filesystem) -- Journaled filesystem created by Hans Reiser that is excellent for use with extremely small files. This filesystem is available with all kernels on the ISO.
- jfs (Journaled File System) -- Created by IBM for AIX, IBM's brand of Unix, and later ported to linux by IBM under the GPL. A journaled filesystem that is very good at handling high throughput issues. This filesystem is available with all kernels on the ISO.
- xfs -- Created by SGI for IRIX, SGI's brand of Unix, and later ported to linux under the GPL. A journaled filesystem that SGI claims is better than any other at handling extremely large files and sparse files. This filesystem is only available with the lunar or grsec patched kernels, which we will come to in a few steps.
After selecting the filesystem type you wish to use, you will be prompted through a series of steps to initialize the partition. You'll notice that the prompts are quite redundant in nature in order to be absolutely positive that you will not inadvertantly erase crucial data that you might have on a working filesystem. In addition, if you have more than four partitions, as we do in our example, you don't want to select any file systems on the fourth partition, as it is the extended partition that houses the fifth, sixth (and so on) partitions. (The installer will try to detect this and skip the extended partition from the list).
As we mentioned earlier, there is an option in the installation process to set up a swap file in the root partition instead of a swap partition as we have done in our example. The next option after selecting your filesystems is to select a swapfile if you so desire. If you have set up a swap partition already, as we have done, you can skip this step. Otherwise, you can set up your swap file here, and the only thing you need to tell the installer is how large you want the file to be. Running without swap completely is also possible of course.
Please note during this step, no modifications are made to your filesystem!
Next, we need to format your partitions, mount them in the right place, create swap and transfer the entire Lunar system to the partitions that you now have created. This happens all in one single step.
Select Install Lunar, and the system will proceed to transfer all of the neccessary files for you. The installer will display progress as packages are transferred to your system and you'll have some idea how long it will take. On normal machines, this should take about 5 minutes.
At the end of this step, the installer sets various system parameters like language, timezone and vital package configuration files in order for your machine.
Setting Up Your GCC Architecture Optimizations
The architecture optimizations is a crucial step, since what you choose will make your system fly! However, it is important that you do not overdo it on you optimization settings, as certain selections can, in some instances, break code while compiling.
The first step is to choose your preferred compiler. The default choice here is GCC 3.x, and is the preferred choice as GCC 2.x is no longer under development, and GCC 3.x is known to make compiled code run faster. For our example, we are going to use GCC 3.x.
Next are options for the C and C++ compiler, called -pipe, that have already been checked off. Very few people, if any, would need to turn off the -pipe option, so in our example we are going to leave them checked.
Next we have the platform selection. This question would seem to be rather silly, since our ISO only boots up on x86 systems, but we like to plan for the future. You'll want to say x86 here.
Now we move onto the Basic Optimization screen. As you can see, the options speak for themselves. Your choice depends on what your needs are. Most folks will want to use -O2 here, as it is the wisest choice. More advanced users may want to use the -O3 option, but it's not for everyone. If you're short on disk space, you would take the -Os Small option. (As an example, we used -Os for the ISO since we were working within a confined amount of disc space.) Those of you with older or slower systems that wouldn't be able to take advantage of faster optimizations may choose a more conservative setting like -O1. For our example system, we will choose -O2.
After choosing your basic optimization level, you'll need to tell the compiler what type of processor you have. This may seem unimportant, however the GCC 3.x compiler has ways of optimizing code for certain processors, even though they all may be x86 based. For example, GCC 3.x has certain optimizations it can perform on code for Pentium 4 machines, but not for Pentium 3. Our example machine is a Pentium 3, so we are going to select that.
We could also select i686, as a Pentium 3 or Pentium Pro falls within that architecture. Choosing i686 is a more conservative choice than Pentium 3, as GCC 3.x will not try certain optimizations with a more general choice like i686.
Adding Additional GCC Optimizations
You can safely SKIP this entire step!
Next up are some extra speed optimizations you can add in to tweak your code even futher. There are too many to go into much detail here, but suffice to say that you should choose carefully. As we mentioned in the prior section, certain optimizations will cause compilation errors or even failures. An optimization such as "-ffast-math" is very risky because it breaks certain rules to get faster code, and would only be used by the bravest of souls looking to endure lots of pain. More information about GCC 3.x optimization strings can be found on the gnu.org website.
The same rule applies on the next screen, where you are asked about some extra features that you may want further optimized, and on the following screen asking about floating point math optimizations. Some options may not pose a problem at all, while others may break things.
Moving on to the next few screens, we have options to enable or disable C and C++ compiler warnings. Most people will want to leave these boxes unchecked as deprecation warnings can be very useful some of the time. Following that is the screen for linker options, where you will find that "-s Strip" has already been checked off. Very few people will want to uncheck this option, so we will leave this screen as is. After that, we have some addons for compiler caching and distributed compiler support. Most folks will not need either one of these.
The final few steps involve setting up the number of concurrent makes and stack parameters. As the hint mentions on the "Concurrent Makes" screen, you'll want to enter in the number of cpu's your machine has. Unless you have a machine with more than one processor, you'll want to leave this field blank. The stack parameters is also fairly straightforward. The warning on that screen says that this field is best left empty, and so that is exactly what we will do with our example.
We are now finished setting up our GCC optimizations! When you have you lunar system up and running, you can always change and tweak these GCC settings by typing "lunar" at the commandline prompt, and going to "Optimization Settings". In addition, if you aren't that familiar with what your processor is capable of using for optimizations, you can go to the shell out option on the ISO and type
at the prompt and the system will show you all the optimizations that the processor reports it can handle.
Configuring Your Bootloader
If you chose to use lilo and also said yes to automatically configuring and running lilo, then most of the work is done for you. If you chose not to hand edit lilo.conf, however, be warned that the default configuration has the system set up to be password protected on boot. You can change this by selecting the option from the menu "Reconfigure LILO".
To turn off password protection, you will need to comment out (with the symbol "#") or delete two lines in your lilo.conf file. The first is "password=lunar", which is found in the top section of the file, and the other is "restricted" which is found right below the name of your kernel in the second section.
The other item of note is whether you want lilo to reside in your MBR (Master Boot Record) or on the first sector of your /boot partition. The line in your lilo.conf file to edit for this purpose is
To make lilo get installed on the first sector of your /boot partition, you would leave this line as it is. If you want lilo to be written to your MBR, which is the recommended method, you would change the line to read
Of course, these examples are pertinent to our setup that we have been using thoughout this manual. Your actual lilo.conf file may be different.
If you chose grub as your bootloader, you will need to set up the configuration file entirely on your own. An example would be:
default 0 timeout 30 color white/blue white/black title linux-2.4.20 root (hd0,0) kernel /vmlinubz-2.4.25-r5.0.0 root=/dev/hda2 devfs=nomount
As we mentioned earlier in the partitioning section, you would want to mark your /boot partition as active. With grub it is imperative that you mark your /boot partition as active, otherwise grub will not work at all when you are finished with the installation and reboot to your new system.
Installing a precompiled kernel
The ISO's come with a variation of precompiled kernels and modules that should work for most people. If you have problems getting your kernel to compile, install or getting the right drivers, or just want to get a quick start at lunar, we suggest that you use this option instead of compiling your own kernel. You can later of course compile as many kernels as you want.
Building Your Customized Linux Kernel
We have now come to the most important part of the installation; the configuration of the kernel. The kernel is the heart of linux, and without it, nothing would work. Configuration is, actually, a rather simple process. All you need to remember is to not panic, and that lunar is going to do most of the work for you. Here are a few pointers that will make the configuration a breeze for you.
- Help is a click away! The people working on creating and maintaining the linux kernel have help placed throughout the entire configuration process. If you're not sure what something does, just look at the help file for whatever item you're on, and it will almost certainly explain what it is and what it does. The most handy thing is that every help file will suggest whether you should really use the item or not. Many help files end with "If you're not sure, it is safe to say N here", thus letting you know that it is safe to leave that particular item out of the kernel.
- You can use the ISO kernel! The configuration used to make the kernel for the ISO is the same configuration you'll see when you start your kernel customization. If you leave the configuration the way it is, the only thing you truly have to worry about is your network and, if you want it, sound. There are also two additional default configurations available on the ISO that are available to you called "config.safe" and "config.server". We'll show you how to load these configurations in just a little bit.
- Never build filesystems or core components as modules! Make sure that whatever filesystems you decided to use for your partitions earlier are built into the kernel, and are not separate modules. Likewise, make sure that certain crucial things like ide and scsi drivers are not modules, as this will make your machine unbootable. (This rule doesn't apply to the scsi low level drivers though; they can be modules.) Modules are kernel drivers that can be manually activated and deactivated after the system has been booted, but not during boot time. The kernel from the ISO already has all the filesystems available during the installation built into the kernel, so if you don't change anything there, you will be fine.
You will be shown two screens of information before you actually begin you kernel configuration, letting you know that you are going to need a few things built into the kernel in order to have Lunar run properly, and what options you have for boot loaders. Lunar comes with both lilo (LInux LOader) and grub (GRand Unified Bootloader).
If you don't have much experience with bootloaders, we suggest using lilo for now, as the installation program will set up the configuration file for you. If you would prefer to use grub, and we encourage folks to learn how to use it, be forewarned that the installation program does not set up any configuration at all for you.
There are serveral kernels for you to choose from. They are:
- linux-2.4 -- The default kernel for Lunar which is the Linus tree with some handy patches for the xfs filesystem, firewire, ext3, and several other fixes.
- linux-2.4-agr -- The aggressive patch includes everything from the standard patchset as well as the low latency, pre-emptive, and gcc 3.x architecture type patches.
- linux-2.4-grsec -- This is almost the same as linux, but with grsecurity, cpu frequency scaling, gcc 3.x architecture types, and crypto support.
- linux-2.4-stable -- This is the Linus tree with only critical patches for certain drivers that were created after the 2.4.20 kernel was released.
- linux-2.4-vanilla -- A completely unpatched kernel tree.
- linux-2.4-om -- A kernel specifically meant for clustering use.
For our example, we are going to use linux-2.4-agr.
Before you begin is which type of configuration method you would like to use.
- config -- The original way to configure the linux kernel. It is completely text based, and assumes you know what everything is. Unless you've been using linux since its inception, you probably don't want to use this method.
- menuconfig -- As the name implies, a menu driven version of the kernel configuration. This is the easiest, and by far the most popular way of configurating your kernel.
- xconfig -- If you have an X server running, you can use this option to configure your kernel using a nifty GUI interface. You won't be able to use this on the ISO, but once your system is up and running with X, you can use this option. If you do choose this option while installing from the ISO, the system will fall back to next available configuration method, in this case menuconfig, so there is no harm in selecting it if you do.
For our example, we are going to use menuconfig. Once Lunar is finished applying the patches for the kernel, which can take a minute or two, you'll be brought to the configuration screen for the linux kernel.
As we mentioned earlier, the configuration that was used to build the kernel for the ISO is the same configuration that you'll be presented with when you start. However, as we also mentioned earlier, there are two alternate kernel configurations available to you that you may want to use; config.safe and config.server. Both of there configurations can be found on the ISO, along with the original default config file, in /etc/lunar/local. When you are looking at the kernel menuconfig main page, scroll all the way to bottom, and you will find an option called "Load an Alternate Configuration File". Select this and then give the absolute path to the alternate configuration file, i.e. /etc/lunar/local/.config.server. As with all kernel configuration files, they are hidden files preceeded with a ".", so make sure to not forget it.
Once you have completed configuring your kernel, you'll get one more prompt from the installer asking if you want to go back to the configuration in case you exited by mistake or forgot something. If everything is good to go, say no here and sit back for a few minutes while your kernel compiles.
Setting Up Networking
The final step is to set up networking. When you select the "Set Up Networking" option, you'll be prompted by a series of questions as to what kind of card you have (only needed if you built your networking device as a module, and not part of the kernel), if you need to set up wireless or not, and whether you'll need to use dhcp or not. You should be familiar enough with your network to set this up on your own, as the questions put to you are very straightforward.
The installer will prompt you now for some more settings. You should set a root password and generate ssh host keys to identify your box uniquely for later. You might also want to administrate services on the newly installed machine.
Once you have completed setting up your networking, you are finished installing Lunar Linux! Congratulations! Select the option "Done" and remove the cd from the drive when it ejects. Your Lunar system is now ready to go!
Lunar Installation Manual and Harassment of Lunar Developers by Drew Swayze (drew AT lunar-linux DOT org).
Edits and Nitpicking by Suzanne Burns (sburns AT lunar-linux DOT org).