About News Download Docs Forum Bugs Contact





Chroot Install Guide

Here's a complete guide to install Source Mage GNU/Linux using chroot tarballs.


Chroot image is a compressed archive of a live system. It contains everything you need to extract on your disk and start using Source Mage.

Here we have a few official images to start with, which contain all the essential programs and libraries to boot from any modern hardware and specific networking setup (PPPoE, Wi-Fi, etc.).

It is usually based on the specific grimoire release, and in our project is used for testing purposes and grimoire release process.


Chroot image is just an archive, so to make your system up and running, you need to boot from some LiveCD/LiveUSB/LiveLAN Linux-based media to partition your drive, extract the image, install a bootloader and configure some basic stuff like network interface, hostname, etc.

These steps will help you to do so in a proper order:

1. Get some bootable media

It can be our installation ISO or any compact Linux distribution image.

Possible recommendations include:

Those mentioned above support all modern hardware, and it's easy to find the nearest mirror to you and get them pretty quickly. Additionally, Archboot is perfect for booting via network (PXE).

But as already mentioned above, it can likely be any Linux distribution you would like to use or feel comfortable with.

Note: if you're planning to boot Source Mage via UEFI, make sure you get the UEFI-friendly install media.

2. Burn it & Boot it

Potential methods for preparing a bootable media might include:

If in doubt, check for documentation provided by the distribution you would like to use (e.g., Devuan) for information on how to create the appropriate bootable media.

Once the bootable media has been created boot into the minimal environment provided and move on to the next step.

3. Get the chroot image

Almost all modern Linux distributions support network configuration and have download tools available when boot process is complete.

So it's usually not a problem. Though if you don't have (or you know that you won't have Internet-connection inplace for some reason) such ability, you can put the desired chroot image on your USB-key or CD/DVD disc.

You can download the appropriate chroot image from our downloads page; and we will use the one based on 0.63-test grimoire in the example below. While others are listed, I have found that they are too old and either do not provide a stable system to start with, or break during the update process noted towards the end of this guide. Also note, while the 0.63-test version is specifically mentioned, the datetime stamp may be different on the official download page as updates to the 0.63-test chroot image are made.

Let's imagine there's no trouble with our Ethernet adapter, and we know how networking works in Linux on a very basic level:

# ifconfig eth0 netmask
# route add default gw
# echo "nameserver" > /etc/resolv.conf
# wget "http://download.sourcemage.org/image/official/test/smgl-test-0.63-20190513_0600-basesystem-x86_64.tar.xz"

4. Partition your drive

This is done mostly with fdisk and/or parted. Disk drives (SATA) are usually /dev/sda, /dev/sdb, etc., but that completely depends on hardware (for example it could be /dev/cciss/c0d0 if you know what SMART RAID Controller is).

More complex disk setup (RAID/LVM) is also fine, but out of the topic.

Here we start, using parted in our example below:

# parted /dev/sda
> mklabel gpt
> unit mb
> mkpart primary 0g 128
> mkpart primary 128 2048
> mkpart primary 2048 4096
> mkpart primary 4096 6000
> mkpart primary 6000 8000
> mkpart primary 8000 20000
> mkpart primary 20000 -1
> name 1 boot
> toggle 1 boot
> name 2 swap
> name 3 root
> name 4 home
> name 5 temp
> name 6 usr
> name 7 var

Note: on UEFI systems /dev/sda1 is usually a FAT32-formatted EFI system partition, so the ordering would be different starting with /dev/sda2 as you should keep EFI system partition untouched.

To review the partitions you just created:

> p free

Quit when you are satisfied with your setup:

> quit

Next, we create filesystems on these partitions (in the example below we use XFS for /):

# mkfs.xfs /dev/sda3

The swap space is then created with mkswap command:

# mkswap /dev/sda2

5. Mount partitions

Now you're almost ready to extract Source Mage from the chroot image. However, before we start the extraction process we must mount the partitions created in the previous step:

# mkdir /mnt/drive
# mount /dev/sda3 /mnt/drive
# mkdir /mnt/drive/{boot,home,tmp,usr,var}
# mount /dev/sda1 /mnt/drive/boot
# swapon /dev/sda2
# mount /dev/sda4 /mnt/drive/home
# mount /dev/sda5 /mnt/drive/tmp
# mount /dev/sda6 /mnt/drive/usr
# mount /dev/sda7 /mnt/drive/var

6. Extract from chroot

Finally, using the chroot image we fetched in step #3 and assuming we wrote it to the /root directory, we extract the image to our forthcoming main space:

# cd /mnt/drive
# tar xvJf /root/smgl-test-0.63-20231208_1200-basesystem-x86_64.tar.xz --xattrs-include='*.*' --numeric-owner


7. Finalize installation

Here are a few final steps which were mentioned at the beginning of this guide.

7.1 Prepare chroot environment

# mount --bind /dev /mnt/drive/dev
# mount --bind /sys /mnt/drive/sys
# mount -t proc none /mnt/drive/proc
# mount -t devpts none /mnt/drive/dev/pts

7.2 Chroot into it

# chroot /mnt/drive

Note: in case your host system doesn't follow FHS directory structure, make sure to update the $PATH environment variable before proceeding:

# export PATH="/bin:/usr/bin:/sbin:/usr/sbin:/usr/local/bin:/usr/local/sbin"

7.3 Set root password

# passwd root

Warning: don't skip this substep. Root password in the chroot images isn't installed. No, it doesn't mean you can login with an empty password, it means you won't be able to login at all.

7.4 Configure network and set hostname

This is usually done with editing /etc/network/interfaces file. For more info see interfaces(5). For simple setups there's already a template where you only need to replace X-values with real IPs of the machine's primary address, netmask and default route. Do not forget to uncomment (remove preceding # symbols) the actual interface configuration lines.

To set your hostname type this:

# echo "yourhostname.yourdomain.tld" > /etc/hostname
# echo "yourdomain.tld" > /etc/defaultdomain

DNS servers are located in /etc/resolv.conf file.

Recent chroot images use Neustar's DNS Advantage (until 0.61-stable it was Comodo's Secure DNS) as primary and Google's as secondary DNS server. Feel free to use your own ones.

7.5 Set up static information about the filesystems

Edit /etc/fstab file according to your disk setup in step #4:

# nano /etc/fstab

7.6 Update Sorcery and Codex

7.7 Update Essential spells for compiling

# cast -c binutils gcc gettext glibc

7.8 Compile a kernel

Because we are installing from chroot, we will need to compile our own kernel. While there are a number of ways that we might be able to do this, below we simply provide the following:

# cast -c elfutils
# cast -r linux

and following instructions in the menus.

7.9 Install a bootloader

Now that we have our Linux kernel created, we need to install a bootloader. Spells are available for LILO and GRUB(2). For the purpose of this guide, we will be using LILO for a BIOS/non-UEFI setup and GRUB2 – for both non-UEFI and UEFI setups.

7.9.1 BIOS/non-UEFI using LILO

While we will need to install the bootloader, an example has already been provided at /etc/lilo.conf.

# cast -c lilo
# nano /etc/lilo.conf
# lilo
7.9.2 BIOS/non-UEFI using GRUB2
# cast -c grub2
# grub-mkconfig -o /boot/grub/grub.cfg
# parted /dev/sda
> toggle 1 bios_grub
> quit
# grub-install /dev/sda
7.9.3 UEFI using GRUB2
# cast -r grub2 efibootmgr

Note: when casting grub2 choose either i386-efi or x86_64-efi platform (depending on your CPU arch).

Make sure efivarfs is mounted:

# mount -t efivarfs efivarfs /sys/firmware/efi/efivars

Mount EFI system partition (assuming it's /dev/sda1):

# mkdir /boot/efi
# mount /dev/sda1 /boot/efi

Install GRUB2:

# grub-mkconfig -o /boot/grub/grub.cfg
# grub-install --bootloader-id=SMGL --recheck

7.10 Configure your localization settings

Chroot images come with only one locale – en_US, and use UTF-8 version of it by default. If you need to change it, type:

# cast -r locale

Select those you want, and then change the LANG variable in /etc/sysconfig/locale file to the one you'd like to use.

By default timezone is set to UTC. To change it, you need to choose timezone file and symlink it with /etc/localtime. For example to set GMT-4 timezone:

# ln -sf /usr/share/zoneinfo/Etc/GMT-4 /etc/localtime

All timezone files are located in /usr/share/zoneinfo directory.

Alternatively, you may also re-cast or reconfigure the time zone database using the following command:

# cast -r tzdata

7.11 Get back to real environment

This is usually done with Ctrl+D or by typing:

# exit

8. Reboot

Now you're ready to boot into Source Mage GNU/Linux system, so type:

# reboot

Note: don't forget to set HDD as a primary media in the boot priority list of BIOS.

9. Continue on

As an option, you may wish to install and view the "smgl-setup" man page:

# cast smgl-setup
# man smgl-setup

Now is the perfect time to do a rebuild of your system. You have already taken care of many of the preliminary steps above as you performed the chroot install. Once you have booted your new system, it's recommended to:

Doing all of this will recompile your installed spells and optimize them for your processor. We highly recommend that you do this now, as it can speed up your system.
The longer you hold off, the more spells will be recompiled later on.

Once again, to rebuild your system anytime, type:

# sorcery rebuild

Welcome to Source Mage!

10. Report

Feel free to report back, comment and yell on this guide by dropping me a mail to stealth@sourcemage.org or notifying me on IRC.