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 source code, 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!
WARNING: Here be Dragons!
The 1.6.5 ISO is now almost two years old, and there have been major updates of the kernel, gcc, glibc, and a host of other key modules. The development team is currently in the middle of the switch from sysvinit to systemd in preparation for the next ISO image. In addition, the single project repository is being split to provide improved system integrity and cohesion, and re-hosted at github, so you might find that your favourite utility is not yet available in the new configuration.
If you can't wait a couple of months for the new ISO, and really do want to install 1.6.5, please make sure that you connect to #Lunar on Freenode.net and ask for the latest guide to installation. This temporary guide from 2012-09-23 may quickly become outdated. Be warned: you may break your box!
About this installation manual
Although this manual is not intended to be a full and complete overview of any situation you may be confronted with, given the wide diversity of hardware available these days, it is intended to be an introduction to the world of Lunar Linux. 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 despair: 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.
- A note: please read "Jump to 3.X kernel + Tips" section which belongs to "Known Problem" chapter. It would help you make Lunar Linux recognize the latest hardware
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.6.5-rc1, codename Mare Ingenii (20100709). (Check the main site for the actual latest version!)
Locate and retrieve the file lunar-1.6.5-rc1-i686.iso.bz2 (or lunar-1.6.5-rc1-x86_64.iso.bz2 if you have a 64-bit system). 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 IZarc, 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 the 1.6.5 ISO and Lunar use udev for device management. The devfs system, and the "old-school" method of manually installing devices, are no longer supported.
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 [Note: MemTest is not available on x86_64]. 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 the 1.6.5 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 programs '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 choices available are e3, [e3/emacs], joe, nano, vi, and zile. 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.
Warning: the keymap entry appears to default to ANSI-dvorak so make sure that you really select what you want.
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.
Note: under the <Settings> option on the main menu there is an option to configure the fstab mount style as DEV, LABEL or UUID. The first is the traditional Linux method, but can sometimes give problems if a kernel update causes the disk to be renamed. The default is UUID, which uses a unique marker on the partition to avoid this problem.
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 in case 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 partition 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:
- ext4 (Fourth Extended File System) -- Version 4 of the Extended File System, which was ... TO BE COMPLETED.
- 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.
- 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.
- 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.
- 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.
- 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.
- swap Swap (Virtual memory or paging filesystem) for swap partitions only!
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 necessary 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 Compiler Optimizations
The compiler 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. There is only one version on the 1.6.5 ISO, so the only option here is GCC 4.4. However, once the main system installation is complete, it is possible to install GCC 3.x -- and even the deprecated GCC 2.x! If you don't intend to install those, you should go to the GCC_4_4 submenu now and set GCC 4.4 as the default compiler.
The GCC_4_4 menu also allows you to change other options:
- safe : allows you to turn off optimization safety, so you should leave this well alone unless you really know what you are doing. Turning this off will result in many more options appearing than are described below.
- bopt : allows you to change the base compile-time optimization. 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.
- cpu : allows you to set your processor type. This may seem unimportant, but the GCC 4.x [and GCC 3.x] compiler has ways of optimizing code for certain processors
- cc_opt : allows you to set some limited C/C++ compiler settings. Very few people, if any, would need to turn off the -pipe option.
The unsafe optimizations are:
- xtra : CPU extensions
- spd : Specialized optimizations
- fpm : Floating point optimizations
- stack : Stack optimizations
Adding Other Compiler Toolchain Optimizations
You can safely SKIP this entire step!
The GNU_LD menu shows 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.
The GNU_MAKE menu allows you to set the number of concurrent makes. 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.
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.25 root (hd0,0) kernel /vmlinubz-2.4.25-r5.0.0 root=/dev/sda2 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.
NOTE: The option to install grub is not available on the 1.6.5-rc1-x86_64 ISO because grub is not yet fully stable on 64-bit systems. If you really know what you are doing, the source tarball is saved to disk, so you can configure it manually once the main installation is complete.
Installing a precompiled kernel
The ISO comes with a selection 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, and indeed the first lunar update after the main installation might ask whether you want to update the kernel too. Why do it twice if you don't need to?
There are several kernels for you to choose from. They are:
- 220.127.116.11 -- Normal kernel (SMP, 4GB memory max) (RECOMMENDED).
- 18.104.22.168-safe -- Very safe non-optimized minimal kernel (no ACPI, DMA, SMP, 1GB).
- 22.214.171.124-server -- Server optimized (SELINUX, SMP, 64GB, no preempt).
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. [TODO: check these files]
- 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.
[On the 1.6.5-rc1-x86_64 ISO] There is only one kernel available for you to choose from:
- linux-2.6. -- Latest 2.6 kernel with minor patchlevel patches (2.6.x.Y)
For our example, we are going to use linux-2.6.
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 these 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 preceded 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.
- if you use dhcp, you don't need to set up the default gateway or DNS because dhcp will take care of them for you.
- you are using a wireless connection with wpa_supplicant, you might want to run "wpa_passphrase" to set up a simple /etc/wpa_supplicant.conf rather than try to edit the example file.
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!
After the initial installation and reboot, please follow the instructions given in man lfirsttime to bring your system up-to-date.
Congratulations! You now have a minimal system as a foundation on which to build.
You need to run 'lin linux-2.6' explicitly before running 'lunar update'
WARNING: the pre-compiled 126.96.36.199 kernel on the ISO is now out-of-date compared to the linux-2.6 module in the moonbase, but you will need to build it explicitly using lin linux-2.6 because it won't be rebuilt as part of the first lunar update. If you didn't recompile the kernel as part of the ISO installation, or if you experience problems with ALSA or NVIDIA, you should run lin linux-2.6 to rebuild the kernel explicitly. After you have built the kernel once, lunar update should then detect and install a newer versions of the kernel as they become available in the moonbase.
configure: error: C compiler cannot create executables
WARNING: the ISO installs gcc-4.4 on your system, but gcc-4.6 will be installed as part of the man lfirsttime and lunar update process. You will then need to run lunar, select the Options / Optimize Architecture menu and set the gcc-4.5 options. Failure to do so may result in "configure: error: C compiler cannot create executables" messages when building modules later.
Jump to 3.X kernel + Tips
These are some problems you'll encounter with the outdated 1.6.5 installation ISO of Lunar Linux. For example: - Lunar Linux doesn't recognize the most recent network hardware correctly, but it still recognizes a few USB tethering from your smartphone (e.g. hTC Evo 4G+). The tricky part is that lin(package installer) tries to connect via dial-up modem if it doesn't find any ethX. - If you try to use Linux kernel 3.X udev would not start because Lunar's initscript would treat it as 2.4 kernel. It is due to initscript design pitfall then where there was no 3.X kernels.
Of course these issues are all resolved with current updates. To solve the issues following modules should be updated: - linux: Of course, Linux kernel, to support the most recent hardware. Please refer to Moonbase for details. - lunar / theedge: Lunar Linux utilities(including "package managers"), for lin(module installer) to work in any network condition(e.g. connected to the Internet without ethX) - lunar-init: the initscript of Lunar Linux to correctly recognize and work - Though deprecated, module-init-tools would work with 3.X kernels anyway. Or you can replace it with kmod.
Or, if you prefer, you can just recompile Linux kernel with built-in drivers so that you don't have to be concerned with kernel modules.
Where to go from here
To install a desktop environment check out this page. Lunar_Linux:DesktopEnvironments
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).
Initial update for the 1.6.5 ISO by Duncan Gibson (engelsman AT lunar-linux DOT org).
Update for "Jump to 3.X kernel + Tips" by Robert Teminian(individual contributor).