Getting started with Chisel¶

This tutorial will walk you through the creation of your first chiseled Ubuntu root filesystem, from installation to the slicing of Ubuntu packages.

The goal is to give you a basic understanding of what Chisel is and how to use it to install package slices. By the end of it, you will have a minimal slice of Ubuntu comprising only the necessary files to run our application.

Prerequisites¶

A Linux machine.

Download and install Chisel¶

Let’s install the Chisel from its GitHub releases page. If you prefer a different installation method, see How to install Chisel.

To install the latest Chisel binary:

Visit the latest release page to determine the latest version, for example, v1.0.0 (update the following steps according to your desired version and architecture).

Run the following command to download the file.

wget https://github.com/canonical/chisel/releases/download/v1.0.0/chisel_v1.0.0_linux_amd64.tar.gz

We publish checksum files for the release tarballs. Download the appropriate checksum file with the following command.
```
wget https://github.com/canonical/chisel/releases/download/v1.0.0/chisel_v1.0.0_linux_amd64.tar.gz.sha384
```

Verify the checksum with the following command:

sha384sum -c chisel_v1.0.0_linux_amd64.tar.gz.sha384

Extract the contents of the downloaded tarball by running:
```
tar zxvf chisel_v1.0.0_linux_amd64.tar.gz
```
Install the Chisel binary. Make sure the installation directory is included in your system’s PATH environment variable. For example:
```
sudo mv chisel /usr/local/bin/
```

Verify the Chisel installation¶

Once the installation is complete, verify that Chisel has been installed correctly by running:

chisel

This should produce output similar to the following:

user@host:~$ chisel

Chisel can slice a Linux distribution using a release databaseand construct a new filesystem using the finely defined parts. Usage: chisel <command> [<options>...] ...

Slice the “hello” package¶

The hello package has already been sliced and its slice definitions are available in the chisel-releases repository.

Before running Chisel, create an empty directory where the root file system should be located:

mkdir rootfs

Finally, use the cut command to install the hello_bins slice from the ubuntu-24.04 chisel-release:

user@host:~$ chisel cut --release ubuntu-24.04 --root rootfs/ hello_bins

2024/11/26 12:21:35 Consulting release repository...2024/11/26 12:21:37 Cached ubuntu-24.04 release is still up-to-date.2024/11/26 12:21:37 Processing ubuntu-24.04 release...2024/11/26 12:22:12 Selecting slices...2024/11/26 12:22:12 Fetching ubuntu 24.04 noble suite details...2024/11/26 12:22:15 Release date: Thu, 25 Apr 2024 15:10:33 UTC2024/11/26 12:22:15 Fetching index for ubuntu 24.04 noble main component...2024/11/26 12:22:15 Fetching index for ubuntu 24.04 noble universe component...2024/11/26 12:22:16 Fetching ubuntu 24.04 noble-security suite details...2024/11/26 12:22:16 Release date: Tue, 26 Nov 2024 3:33:31 UTC2024/11/26 12:22:16 Fetching index for ubuntu 24.04 noble-security main component...2024/11/26 12:22:16 Fetching index for ubuntu 24.04 noble-security universe component...2024/11/26 12:22:16 Fetching ubuntu 24.04 noble-updates suite details...2024/11/26 12:22:17 Release date: Tue, 26 Nov 2024 5:53:50 UTC2024/11/26 12:22:17 Fetching index for ubuntu 24.04 noble-updates main component...2024/11/26 12:22:18 Fetching index for ubuntu 24.04 noble-updates universe component...2024/11/26 12:22:19 Fetching pool/main/b/base-files/base-files_13ubuntu10.1_amd64.deb...2024/11/26 12:22:19 Fetching pool/main/h/hello/hello_2.10-3build1_amd64.deb...2024/11/26 12:22:19 Fetching pool/main/g/glibc/libc6_2.39-0ubuntu8.3_amd64.deb...2024/11/26 12:22:19 Extracting files from package "base-files"...2024/11/26 12:22:19 Extracting files from package "hello"...2024/11/26 12:22:19 Extracting files from package "libc6"...

Inspect the chiseled root file system¶

A quick look at the rootfs/ directory will show that the hello binary has been installed at rootfs/usr/bin/hello.

user@host:~$ find rootfs

rootfsrootfs/lib64rootfs/usrrootfs/usr/lib64rootfs/usr/lib64/ld-linux-x86-64.so.2rootfs/usr/sharerootfs/usr/share/docrootfs/usr/share/doc/base-filesrootfs/usr/share/doc/base-files/copyrightrootfs/usr/share/doc/hellorootfs/usr/share/doc/hello/copyrightrootfs/usr/share/doc/libc6rootfs/usr/share/doc/libc6/copyrightrootfs/usr/binrootfs/usr/bin/hellorootfs/usr/librootfs/usr/lib/x86_64-linux-gnurootfs/usr/lib/x86_64-linux-gnu/libpthread.so.0rootfs/usr/lib/x86_64-linux-gnu/libthread_db.so.1rootfs/usr/lib/x86_64-linux-gnu/libm.so.6rootfs/usr/lib/x86_64-linux-gnu/libc.so.6rootfs/usr/lib/x86_64-linux-gnu/libmemusage.sorootfs/usr/lib/x86_64-linux-gnu/libdl.so.2rootfs/usr/lib/x86_64-linux-gnu/librt.so.1rootfs/usr/lib/x86_64-linux-gnu/libnss_files.so.2rootfs/usr/lib/x86_64-linux-gnu/libanl.so.1rootfs/usr/lib/x86_64-linux-gnu/libnss_hesiod.so.2rootfs/usr/lib/x86_64-linux-gnu/libc_malloc_debug.so.0rootfs/usr/lib/x86_64-linux-gnu/libmvec.so.1rootfs/usr/lib/x86_64-linux-gnu/libutil.so.1rootfs/usr/lib/x86_64-linux-gnu/libresolv.so.2rootfs/usr/lib/x86_64-linux-gnu/ld-linux-x86-64.so.2rootfs/usr/lib/x86_64-linux-gnu/libBrokenLocale.so.1rootfs/usr/lib/x86_64-linux-gnu/libpcprofile.sorootfs/usr/lib/x86_64-linux-gnu/libnss_dns.so.2rootfs/usr/lib/x86_64-linux-gnu/libnsl.so.1rootfs/usr/lib/x86_64-linux-gnu/libnss_compat.so.2rootfs/lib

Note

Notice that there are other files besides the hello binary. This is because the hello_bins slice depends on other slices, such as libc6_libs, which provides necessary runtime libraries:

user@host:~$ chisel info --release ubuntu-24.04 hello_bins 2>/dev/null

package: helloarchive: ubuntuslices: bins: essential: - hello_copyright - libc6_libs contents: /usr/bin/hello: {}

When installing a slice, Chisel installs its dependencies as well.

Test the application¶

Run hello from the chiseled root file system to verify that it works:

user@host:~$ sudo chroot rootfs/ hello

Hello, world!

Next steps¶

See what other CLI Commands are there, and have a look at the How-to guides for learning about other typical Chisel operations.