Welcome! This page contains a complete guide to install Cucumber Linux start to finish. This guide aims to be concise and brief, yet complete. For special case installations and other information not mentioned here, please see the Special Installations and the Installation Hints pages.

Before you can install Cucumber Linux, you need a medium to install from. There are two easy ways to obtain an installation medium, detailed below.

Currently the easiest way to obtain an installation medium is to download the an ISO image from the download page.

If you already know which ISO image you would like to download, you can skip this section.

Select an i686 ISO for the 32 bit Intel version of Cucumber Linux or x86_64 for the 64 bit Intel/AMD version of the distribution.

The difference between the basic edition and the full edition is explained in detail here. In short, you probably want the full edition for most cases. The basic edition is really only useful if you *need* the installer to fit on a single CD or if you have limited bandwidth. If you do opt to use the basic edition, you will not end up with a complete Cucumber Linux installation; there will be packages missing (which can be installed post installation).

Now you have to create a physical installation medium from the ISO image you just downloaded. You really have two options here: burn it to a CD/DVD or write it to a flash drive/memory card. Both these options are detailed below.

In order to burn the ISO image to a CD/DVD, you will need a CD/DVD writable drive in your computer, as well as CD/DVD burning software. We recommend the following software:

• Xfburn (for Linux/BSD). This should already be installed if you are using Cucumber Linux. If not, it can be installed by running pickle xfburn. For most other distributions, this should be available from your distribution's repositories.
• Brasero (for Linux). This is not supported on Cucumber Linux (we don't use Gnome here); however, it is supported and included by default on many other distributions.
• InfraRecorder (for Windows).

Once you have the necessary software installed, follow that software's instructions for burning the ISO image to a disk.

To create a bootable installation flash drive/memory card on Linux/BSD/Mac, use a modified version of the following dd command:

dd if=cucumber-linux-1.0.beta.1-x86_64.iso of=/dev/sdx

Replace cucumber-linux-1.0.beta.1-x86_64.iso with the path of the ISO image you downloaded. Replace /dev/sdx with the path of the *block device* of the flash drive/memory card you want to write the ISO to (i.e. use /dev/sdb, not /dev/sdb1). Make sure you use the right device here, otherwise you could accidentally corrupt another device on your system or delete your operating system all together.

If you would rather not download an ISO image yourself, Cucumber Linux also sells official installation media. Details about purchasing the official installation CD and/or DVD can be found here.

The way you do this is system dependent. Consult your hardware's documentation to figure this step out.

The Cucumber Linux installer supports both UEFI boot and legacy boot. If you want the installer to set up UEFI boot for your installed system, you must boot using UEFI here, not legacy boot.

Once the installer has booted, select the 'Install' option from the main menu.

The installer will now drop you to a root prompt to partition and format your drives. This is the most difficult part of the installation, but don't be discouraged. To help people who are unfamiliar with partitioning and formatting drives from the Linux command line, we have created a couple of examples below. Select the section that matches your skill level.

The following example creates two partitions on /dev/sda: a 512 MB partition for /boot (/dev/sda1) and a 31.5 GB partition for / (/dev/sda2).

bash-4.3# fdisk /dev/sda
Welcome to fdisk (util-linux 2.27.1).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.


Command (m for help): o
Created a new DOS disklabel with disk identifier 0xdb87f542.

Command (m for help): n
Partition type
   p   primary (0 primary, 0 extended, 4 free)
   e   extended (container for logical partitions)
Select (default p): p
Partition number (1-4, default 1): 1
First sector (2048-67108863, default 2048): <press enter>
Last sector, +sectors or +size{K,M,G,T,P} (2048-67108863, default 67108863): +512M

Created a new partition 1 of type 'Linux' and of size 512 MiB.

Command (m for help): n
Partition type
   p   primary (1 primary, 0 extended, 3 free)
   e   extended (container for logical partitions)
Select (default p): p
Partition number (2-4, default 2): 2
First sector (1050624-67108863, default 1050624): <press enter>
Last sector, +sectors or +size{K,M,G,T,P} (1050624-67108863, default 67108863): <press enter> 

Created a new partition 2 of type 'Linux' and of size 31.5 GiB.

Command (m for help): w
The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks.

bash-4.3# 

To start, you need to partition your drives. This can be done using the fdisk or cfdisk programs. We'll use fdisk in this example. To start partitioning a drive, run the command fdisk /dev/sdx, where sdx is the block device you want to format (i.e. sda for your first hard drive). Once in fdisk, you can type m followed by enter at any time for help.

Note that fdisk doesn't actually write any changes to your drives until you enter the w command. If you would like to abort or start over at any time, you can enter q to exit fdisk without making any changes to your drive.

If the drive already has a partition table you can skip this step. This will be the case if you have partitioned this drive before or if there is already another operating system installed on the drive.

If you have not previously partitioned this drive, create a new partition table. This is done by entering o to create a MS DOS partition table or g to create a GPT partition table. If you are planning to use this drive in a version of Microsoft Windows prior to Windows 8, you will need to use a MS DOS partition table. If the drive is larger than 2 TB, you will need to use a GPT partition table in order to utilize all of the drive's capacity. If you don't fall into either of these categories, then it doesn't make a huge difference which you choose. If in doubt, MS DOS is the safer option.

Now, type p to create a new partition. You may be asked if you would like to use a primary or extended/logical partition. If you are, you can elect to use either; Cucumber Linux doesn't really care. Keep in mind though that you can have only four primary partitions, and some versions of Windows will work *only* if they are installed on a primary partition. For details about using extended/logical partitions and other advanced partitioning techniques, see this article at TLDP.

Next, select a partition number. It doesn't really matter what number you choose, however the convention is to use the next lowest number available. Press enter to continue.

If you would like to use a non-default offset for the partition, you can change the first sector now. If you would like to accept the default, just press enter. If you are not sure what to do here, just press enter.

Now enter the desired size of the partition in the format +nG, where n is the desired size in gigabytes. For example, to create a partition that is 20 GB in size, enter +20G. You can also use K, M or T in place of G to specify the size in kilobytes, megabytes or terabytes respectively. Press enter to confirm the size. Alternatively, you can opt to use all of the remaining space on the drive for this partition by just pressing enter without typing anything.

Cucumber Linux can be installed using a single partition, however it is often desirable to create additional partitions (for swap space, for /home and so on). If you would like to use additional partitions, repeat the 'Creating a Single Partition' section as needed to create the additional partitions.

If you get an error message that says To create more partitions, first replace a primary partition with an extended partition or something similar, it will be necessary to shrink or delete one of your existing partitions first. This can be done by typing d to delete a partition.

Once you have set up all of your partitions, type w followed by enter to confirm the changes and exit fdisk.

Now it is time to format the new partitions. This is done by using a mkfs command. The Cucumber Linux Installer currently supports the following formats: bfs, btrfs, cramfs, ext2, ext3, ext4, minix, ntfs, reiser and vfat (fat32). To format a partition, run mkfs.<format> /dev/sdx1, substituting '<format>' with one of the aforementioned formats and 'sdx1' with the partition you would like to format. For example, to format the first partition of the first hard drive as ext4, run mkfs.ext4 /dev/sda1.

If the partition you are formatting is on a solid state drive, it is recommended that you use a non-journaling or SSD aware filesystem (such as ext2 or btrfs respectively). This will help extend the life of your solid state drive significantly. If you have a traditional disk drive, it doesn't make a huge difference which filesystem you use. Note that if you use a filesystem other than ext 2, 3 or 4 for your root partition, it will be necessary to create a separate boot partition. This partition can be about 200 MB in size and must be formatted as ext 2, 3 or 4.

To format a partition as swap space, run mkswap /dev/sdx1 substituting the partition in for 'sdx1' as before.

Partition your drives from the command line. The installer has the fdisk and cfdisk programs installed for this.

Format your partitions as you please (using mkfs.ext4 or the equivalent).

Exit the shell to continue with the installation.

After you finish partitioning, the installer will let you choose the mount points for your partitions. Here are a few things to be mindful of when choosing your mount points:

You must set the mount point for one partition to /. This will be the root partition for your system. The root partition should be formatted using some Linux filesystem (i.e. ext2, ext3, ext4, btrfs, etc), not a DOS/Windows (i.e. fat or ntfs) filesystem.

If you opted to use a non-ext filesystem for your root partition and you want to use legacy boot, you must set the mount point for your ext2, 3 or 4 formatted boot partition to /boot.

If you are planning to use UEFI to boot your system, you must set the mount point for your fat formatted EFI system partition to /boot/efi.

If you have a swap partition, set the mount point for it to swap. While not strictly required, having a swap partition is recommended for systems with non solid state drives.

If you would like to mount any additional partitions, the standard place to do this is in /media/<partition name>. Data on any partitions mounted under /media will not be modified during the installation.

In the event that you forgot to format one of your partitions or need to get back to a root shell, there is a 'Root Shell' button on this menu for these purposes.

When you are finished, select 'Done' to continue with the installation.

Now it is time to select the package groups you want to install. Each package group contains a series of packages that are all related in some way. For example, the dev-base group provides basic development packages, such as the GCC and binutils. For more information on how package groups work and what packages are in each group, see the packages wiki page.

There are a few things that are worth noting here:

The base package group is the only package group that is required in order to get a bootable system, and as such is the only package group selected by default.

Despite this however, the recommended way to install Cucumber Linux is to install all of the available package groups. This is also the only way that is officially supported. This will require 5.5 GB of disk space for the 32 bit version and 6.1 GB of disk space for the 64 bit version (as of Cucumber Linux 1.0). Keep in mind that Cucumber Linux doesn't have any automated dependency tracking, so installing every package is the only way to ensure that there are are no unresolved dependencies.

Once you have selected the package groups you want, select 'Ok' to continue. Next you will be asked how you would like to install the packages. You have two options here. If you opt for 'full', every package will be installed automatically. This is the safest way to do the installation. If you select the other option, 'prompt', the installer will prompt you before it installs every single package, asking if you want to install or skip this package. This option takes while, and you may quickly find yourself doing something like this. Once you have made your decision, select 'Ok' to begin actually installing the system.

Now you can either sit back and watch the installation or exercise your fingers on your keyboard, depending on how you decided to install the packages.

Once the base system installation has finished, you will be asked if you would like to configure your system. This section is entirely optional; however, if you skip it all of your system’s configuration (hostname, root password, timezone, etc.) will be set to the default values. It is typically recommended not to skip this section.

If you opt to configure your system, you will be asked to enter a hostname for your new system. The hostname is a human readable name that is used to identify your system on the network. You should select a hostname that describes the system’s purpose but is not too long. A hostname may contain letters, numbers and the dash (-) character.

Once you are satisfied with your hostname, select ‘Ok’ to continue. You can change your hostname later by editing the /etc/hostname file.

Next, you will be asked if you would like to set a root password. If you select no, the root user will be able to login without entering a password, which creates a very severe security hazard. Therefore, it is strongly recommended that you set a root password here.

You will be required to make your root password at least five characters long; however, it is recommended that you it make longer than this. Having a reasonably long and complex root password is one of the single most important things you can do to keep your system secure.

Selecting the Timezone

Next, you will be asked to select your timezone. Simply follow the menu based system. If you make a mistake, continue on and select any timezone. Then at the end, it will ask you if the information you entered is correct. Select no and the selection process will start over.

Finally, you will be asked if you would like to enter a shell to perform any additional configuration. It is up to you whether you would like to further configure your system now or perform the rest of you configuration after the installation process is complete.

Some typical tasks that may be done here are adding an unprivileged user, configuring networking and setting up a graphical interface. These tasks can also all be done after the installation process is complete.

If you select ‘Yes’, you will be sent to a root shell chrooted to the newly installed system (this effectively means you will be logged in as root on the new installation). Perform any additional configuration you would like, and then exit the shell to finish up the installation process. Do not reboot yet, or you will end up with an unbootable system.

The installation is almost done now. There remains only one more task: making the system bootable. There are two ways to do this: using the legacy BIOS bootloader or using UEFI. Generally, it is recommended to use the legacy BIOS bootloader; UEFI currently has a lot of issues and works properly only on select motherboards.

You will now be asked if you would like to install the GRUB bootloader to the MBR (Master Boot Record). It is recommended you choose yes here. If you choose no, you will be required to do additional work to get your system to boot; this option is intended for experienced users who probably don’t need this guide to install Cucumber Linux in the first place and consequentially either won’t be reading it or will know to ignore this recommendation. Therefore, we can safely recommend that anyone reading this guide select yes.

Next, you will be asked to enter the path of the drive to install GRUB on. It is important to enter the path of the drive here, not the path of the partition. For example, enter /dev/sda, not /dev/sda1. Usually, you will want to install GRUB to the drive you partitioned back in step three.

Finally, you will be asked if you want to install a new GRUB configuration file. If you choose no, additional configuration will be necessary to boot your system. If you choose yes, any other existing operating systems you may have installed will temporarily be rendered unbootable. Unless you are an experienced user (who as previously discussed, probably won’t be reading this anyway) it is recommended you choose yes here.

As previously mentioned, UEFI is known to have many problems, so we recommend that users stick with using the legacy BIOS. Nonetheless, if you booted the installer using UEFI, you will be given the option to set up UEFI boot now. If not, then good: you can skip this section.

If you opt to use UEFI and experience trouble booting after the installation, go into your BIOS and switch back to legacy boot. If you chose to install the legacy BIOS bootloader, your computer will fall back to that and still be able to boot your system.

After you finish making the system bootable, Cucumber Linux will be installed and ready to use. You will be brought back to the main menu of the installer, and all you have to do now is reboot, which can be done by selecting the ‘Restart’ option from the menu.

When you reboot, make sure to remove the installation medium. Otherwise, you could accidentally start the installation over instead of booting into your new installation.

This is a list of some things that it is often desirable to do after the installation is done. It is in no way meant to be a complete list.

• Add an unprivileged user.
• If this is a desktop system, set up a graphical login screen.
• Set up networking.
• Set up firewall rules.
• Update the system.