Install a Custom Distribution on a Linode
Updated by Linode Written by Nick Brewer
This guide will show you how to install and configure a custom distribution on your Linode.
For the sake of organization, it has been split into two main sections:
Install a Custom Distribution: shows you how to use the advantages of Direct Disk Boot to easily install the custom distribution.
Linode Manager Compatibility: builds upon the steps in the first section, and offers instructions to make your custom distribution work with features of the Linode Manager such as disk resizing, helpers, and the Linode Backup Service.
This guide will use Debian 8 (Jessie) as an example, but the steps provided are generic in nature and should work with most distributions.
NoteThis guide covers the process for installing a custom Linux distribution on a KVM Linode. If you’re currently running a Xen Linode, you can upgrade to KVM, or follow our older guide on Running a Custom Linux Distribution on a Xen Linode.
Advantages of KVM on Linode
Linodes running on our KVM hypervisor offer several advantages over Xen, particularly for those looking to install a custom operating system:
Direct Disk Boot: Direct disk booting allows you to boot from any disk with a Master Boot Record (MBR). This can be especially useful for operating systems that do not make use of the Grub bootloader, such as FreeBSD.
Full Virtualization: Our KVM hypervisor offers a full virtualization option that simulates the experience of running directly from hardware. This can be useful for non-standard configurations.
Glish: KVM introduces the Glish graphical console, which makes it easy to access your distribution’s installer directly from a disk.
Install a Custom Distribution
In this section you’ll install your custom distro onto a raw disk, with the direct disk boot option. The end result will be a working custom install; however, it will not support disk resizing from within the Linode Manager, nor will it be compatible with the Backup Service.
Prepare your Linode
Log into the Cloud Manager and create a Linode. You can use a 1GB Linode (Nanode) for this guide.
After the Linode is finished provisioning, power it down.
Click the Resize tab and uncheck the Auto Resize Disk option at the bottom of the screen.
Next, click the Disks/Configs tab and resize the main disk so you have some room for new disks; you’ll want to free 2100 MB for the Debian 9 disk we used in this example.
NoteDepending on the distribution you install first, you may need to resize your disk to a size slightly larger than 2100 MB. You can always check how much space your disk is actively using and would therefore require by entering the
df -hcommand when it’s mounted.
Create two raw, unformatted disk images from the Linode’s Dashboard:
- A disk labeled Installer. The size of this disk will depend upon the size of your distribution’s installer, but it’s recommended to make it slightly larger than the space taken up by the install media itself. For this example, the installer disk will be 100MB in size, giving us plenty of room for the Debian network installer.
- A disk labeled Boot. If you don’t plan to complete the next section on Linode Manager compatibility, this can take up the rest of the free space available on your Linode.
CautionIf you intend to continue to the next section on Linode Manager Compatibility, you should make your boot disk no larger than necessary - in this example we’ll install Debian to a 2000MB disk.
Create two configuration profiles and disable the options under Filesystem / Boot Helpers for each of them, as well as the Lassie shutdown watchdog under the Settings menu. Both profiles will use the Direct Disk option from the Kernel dropdown menu:
- Label: Installer
- Kernel: Direct Disk
- /dev/sda: Boot disk image.
- /dev/sdb: Installer disk image.
- root / boot device: Standard /dev/sdb
- Label: Boot
- Kernel: Direct Disk
- /dev/sda: Boot disk image.
- root / boot device: Standard /dev/sda
Download and Install Image
Once in Rescue Mode, download your installation media and copy it to your Installer disk. In this example we’re using the Debian network installer, but you can replace the URL in the following command with the location of the image you want to install:
NoteAs an additional security step, you can use the keys provided in the same directory as the
isoto verify the authenticity of the image.
wget http://ftp.debian.org/debian/dists/jessie/main/installer-amd64/current/images/netboot/mini.iso dd if=mini.iso of=/dev/sda
If you would prefer to write the installer directly to the disk as it downloads, use:
curl http://ftp.debian.org/debian/dists/jessie/main/installer-amd64/current/images/netboot/mini.iso | dd of=/dev/sda
Empty the cache so that you have enough space to unpack and install the image.
sync; echo 3 > /proc/sys/vm/drop_caches
Close the Lish window and go back to Cloud Manager. Reboot into your Installer configuration profile and open the Glish graphical console. You’ll see your distribution’s installer, and you can begin the install process.
During your installer’s partitioning/installation phase, be sure to instruct it to use the
/dev/sdavolume. Most installers will create separate root and swap partitions, but you can adjust this as needed.
NoteSome installers offer an option to place
/booton a separate partition. If you intend to make use of the steps in the second part of this guide for Linode Manager compatibility, it’s important that your
/bootdirectory is located on the same partition as your root filesystem.
Once the installation completes, close the Glish window and return to the Cloud Manager. Reboot into your Boot profile and open the Glish console. You will have access to a login prompt:
Configure Grub for Lish Access
At this point you can connect to your Linode via SSH or the Glish graphical console. However, you will not be able to connect to your Linode using the Lish serial console. To fix this, update the following settings in your
1 2 3
GRUB_TIMEOUT=10 GRUB_CMDLINE_LINUX_DEFAULT="" GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0"
Once you’ve finished editing
grub, issue the appropriate command to apply your changes to your Grub configuration:
Ubuntu and Debian:
CentOS and Fedora:
grub2-mkconfig -o /boot/grub2/grub.cfg
Arch Linux and Gentoo:
grub-mkconfig -o /boot/grub/grub.cfg
NoteIf you’re still not able to access your Linode via Lish after updating your GRUB configuration, a reboot may be required. If this is the case, make sure you’re rebooting into your Boot configuration profile.
Linode Manager Compatibility
If you’ve followed the steps so far, you should have a working custom distribution with raw disks, using the direct disk boot option. While this setup is functional, it’s not compatible with several features of the Linode Manager that require the ability to mount your filesystem, such as:
Disk Resizing: Since the Linode Cloud Manager cannot determine the amount of used storage space on a raw disk, it can only increase the size. The Linode Cloud Manager cannot be used to make a raw disk smaller, and it cannot resize the filesystem on the disk - this would need to be done manually. Also, some ext4 features like enabled metadata_csum are not supported for custom distribution images.
Backups: The Linode Backup Service needs to be able to mount your filesystem, and does not support partitioned disks.
This section covers how to move your custom installation over to an ext4 formatted disk so it can take advantage of these tools.
NoteThese features are not available even if you formatted the disk to ext4 during installation because direct disk was selected during disk creation.
Prepare your Linode
Create some room for two new disks. One will be formatted ext4 to move the file system to and one will be for swap. To make more room, consider deleting the initial distribution that was created during Linode creation.
Create a new ext4 disk. The new disk should be large enough to accommodate the root filesystem that was created on your raw disk (2000 MB). You can make this as large as you’d like, but you should leave enough space for a separate swap partition. For this example, we’ll name this disk Boot-New.
Create the second new disk and choose swap for the disk type. The size of this disk will depend upon your needs, but it’s recommended that you make it between 256-512MB to start. We’ll label this disk Swap.
Create a new configuration profile with a name of your choice. For this example, we’ll call the new profile Installer-New and it will use the following options:
- Label: Installer-New
- Kernel: GRUB 2
- /dev/sda: Boot-New disk image.
- /dev/sdb: Swap disk image.
- root / boot device: Standard /dev/sda
Update your fstab
You should still be booted into your Boot profile using direct disk boot; if not, boot into it now.
Before you update your
/etc/fstabfile, make sure you know the current root partition of your custom distro. You can use the
lsblkcommand to confirm which partition has
/as its mount point:
[email protected]:~# lsblk NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT fd0 2:0 1 4K 0 disk sda 8:0 0 7.8G 0 disk └─sda1 8:1 0 7.5G 0 part / sr0 11:0 1 1024M 0 rom
In this case, you can see that the
/dev/sda1partition is the location of your root filesystem.
Next, update your
/etc/fstabfile to match the following:
# <file system> <mount point> <type> <options> <dump> <pass> proc /proc proc defaults 0 0 /dev/sda / ext4 noatime,errors=remount-ro 0 1 /dev/sdb none swap sw
Depending upon your distribution, it may use different parameters for your root disk under the “options” section. These can be adjusted as needed. Note that you’re using
/dev/sdainstead of the
sda1root partition that was identified previously.
Confirm the location of your
grub.cfgfile. Some distributions (notably, CentOS and Fedora) place this file under the
/boot/grub2directory, while others have it under
/boot/grub. Your new setup will use our Grub 2 mode, which looks for a configuration file under
/boot/grub/grub.cfg. You can confirm if your
grub.cfgis located in the necessary spot with the
ls -la /boot/grub/grub.cfg
If your distro places its Grub configuration under this directory, you should receive output similar to the following:
[email protected]:~# ls -la /boot/grub/grub.cfg -r--r--r-- 1 root root 5235 Dec 28 08:05 /boot/grub/grub.cfg
If the Grub config is located under
/boot/grub2instead, create a symlink to provide the correct configuration to the bootloader:
mkdir /boot/grub ln -s /boot/grub2/grub.cfg /boot/grub/grub.cfg
grub.cfgfile, replacing all instances of
/dev/sda. Note that this command will need to be adjusted if your root filesystem is located on a partition other than
sed -i -e 's$/dev/sda1$/dev/sda$g' /boot/grub/grub.cfg
Keep in mind that if your
grub.cfgis located under
/boot/grub2, you should adjust this command to reflect that.
Transfer your Root Filesystem to your Ext4 Disk
Now that you’ve updated the necessary configuration files, you’re ready to move your root filesystem to the ext4 disk you created previously. To get started, boot your Linode into Rescue Mode with the following disk assignments:
- Boot disk mounted to
- Boot-New disk mounted to
In Rescue Mode, connect via Lish and transfer your root filesystem from the
/dev/sda1 partition to your new ext4 disk:
dd if=/dev/sda1 of=/dev/sdb bs=1M
Once the transfer completes, reboot into your Installer-New profile. You now have a custom distribution that works with the Linode Manager’s extra features. In order to make use of the Backup Service, you’ll need to remove the raw disks that were used during the installation process.
Linode offers an image feature. The feature allows users to quickly deploy custom or preconfigured distribution images to new Linodes. Read this guide to learn more.
Join our Community
This guide is published under a CC BY-ND 4.0 license.