smartos-live

Quickstart

git clone https://github.com/TritonDataCenter/smartos-live.git
cd smartos-live
./configure
gmake world
gmake live
ls output/

Overview

This repository is smartos-live, which builds a SmartOS platform image containing the illumos core OS components; a set of "extra" mostly third-party software required by illumos, by other SmartOS software, or for system management; and a collection of utilities comprising SmartOS-specific functionality found in projects/local/.

Contents

• Community
• Bug Reports
• Components of SmartOS
• Building SmartOS
  • Setting up a Build Environment
  • Common Tasks
  • Incremental Development
  • Proto Area
  • Packaging and Manifests
• Contributing
  • Review
  • Upstreaming
  • Integration
  • Testing changes

Community

You can interact with the SmartOS community in a number of ways. This includes:

• The smartos-discuss mailing list. If you wish to send mail to the list you'll need to join, but you can view and search the archives online without being a member.

• In the #smartos IRC channel on the Libera Chat IRC network.

Bug Reports

If you encounter a problem, please reach out for assistance. You can file a GitHub issue for any problem you encounter. When filing a bug, please include the platform version that you're running and a description of the problem.

If there was an operating system crash dump or a program generated a core dump, it would be greatly appreciated if you could make that available.

While there are multiple repositories that make up the smartos-live image, if you're in doubt about where to file a bug or just are uncertain, please file it on the SmartOS live issue tracker and we'll help from there. It's more important that the bug is recorded and we can work on solving it than it end up in the right location.

Components of SmartOS

SmartOS is made up of several different components. These components are:

smartos-live

The smartos-live repository is the root of SmartOS. It has logic for how to build all of the different components that make up SmartOS and has components that are specific to the SmartOS live image environment. For example, it has tools like vmadm and imgadm.

illumos-joyent

The illumos-joyent repository is the core of the operating system. It represents SmartOS's child of illumos-gate. This has the core kernel, libraries, and user commands.

The illumos-joyent code can be found in the smartos-live tree under projects/illumos. The SmartOS build only supports using illumos-joyent and not stock illumos-gate.

illumos-extra

The illumos-extra repository contains a few different sets of software:

1. Software which is held at a specific version that is required for the platform to build. For example, GNU binutils fall into this category.
2. Software which is required for illumos-gate to build and is required at run time. This category includes things like OpenSSL and libz.
3. Extra software that we want to exist in the platform image at run time. This category includes software like bash, curl, and Node.js.

illumos-extra serves to make sure that we have the specific versions of software that we require at build time. The theory is that given a basic working build machine of any illumos vintage, we can build the rest of the platform and get the specific patched versions of software we need from illumos-extra.

The illumos-extra code can be found in the smartos-live tree under projects/illumos-extra.

illumos-extra design

illumos-extra operates in a different fashion from the rest of the tree. Because it consists solely of third-party software, it operates in a different way. This software is often built using the GNU autotools.

Rather than modifying the software directly like we do in the rest of the platform, we instead maintain a series of patches that we apply to a stock release of the software, conventionally in a directory named Patches.

illumos-extra will build the software at least once, but possibly more times. For example, most software doesn't support building both a 32-bit and 64-bit version of itself. We also build software that's required to build the platform image against the host-system during a bootstrap phase. For each version, we'll create a directory that uses the name and version of the software appended with the bitness of the version and whether or not it's the bootstrap phase. For example, if we were building zlib-1.2.3.tar.gz, we'd see the following directories:

$ ls -1 libz/
...
zlib-1.2.3-32
zlib-1.2.3-32strap
zlib-1.2.3-64
zlib-1.2.3-64strap
zlib-1.2.3.tar.gz
...

Finally, while many tarballs are part of the repository, to keep down the ever increasing size of the repository, we are transitioning to having the contents stored externally and downloaded initially as part of the set up process.

Local Projects

There are a collection of extra projects that live in separate repositories. Each of these projects lives in the projects/local directory of the smartos-live root. The local projects system defines a series of Makefile targets that a local project is required to implement.

The current set of local projects include:

• illumos-kvm
• illumos-kvm-cmd aka QEMU
• mdata-client
• ur-agent

Building SmartOS

Setting up a Build Environment

The first step when building is to set up a build environment. The SmartOS build requires building on SmartOS. As of the base-64-lts 24.4.1 build image, the SmartOS Platform Image must be 20220728 or newer. This can be done in VMware, on an existing SmartOS machine, or other virtualization. You must build inside of a non-global zone.

Minimum Platform Image

Because of changes in our build system regarding python3, you'll need to use a platform that includes OS-8397. Release builds as of 20220728T031731Z will satisfy this requirement.

Importing the Zone Image

The SmartOS build currently uses the base-64-lts 24.4.1 image which has a UUID of 2f1dc911-6401-4fa4-8e9d-67ea2e39c271. To import the image, you should run the imgadm command from the global zone:

# imgadm import 2f1dc911-6401-4fa4-8e9d-67ea2e39c271
Importing 2f1dc911-6401-4fa4-8e9d-67ea2e39c271 ([email protected]) from "https://images.smartos.org"
Gather image 2f1dc911-6401-4fa4-8e9d-67ea2e39c271 ancestry
Must download and install 1 image (237.1 MiB)
Download 1 image     [=======================>] 100% 237.16MB  18.90MB/s    12s
Downloaded image 2f1dc911-6401-4fa4-8e9d-67ea2e39c271 (237.1 MiB)
...8e9d-67ea2e39c271 [=======================>] 100% 237.16MB  31.69MB/s     7s
Imported image 2f1dc911-6401-4fa4-8e9d-67ea2e39c271 ([email protected])
#

Creating the Zone

To create a zone, you need to create a joyent branded zone with vmadm. We recommend that the zone have the following attributes:

• The brand set to "joyent"
• The image_uuid set to "2f1dc911-6401-4fa4-8e9d-67ea2e39c271"
• At least 25 GiB of disk space specified in the quota property
• At least 2-4 GiB of DRAM specified in the max-physical-memory property
• 1.5-2x the amount of DRAM in the max_swap property
• At least 1 network interface that can reach the Internet
• The fs_allowed property set to "ufs,pcfs,tmpfs"

For more information, please see the vmadm manual page and its EXAMPLES section. Once written, you can validate your JSON file by running vmadm validate. For example, if your JSON file was in /var/tmp/build.json you would run:

# vmadm validate create -f /var/tmp/build.json

If there are problems, then it will tell you which portions of the JSON are incorrect and need to be fixed. You can always check if a file is valid JSON by using the json command as json --validate -f /var/tmp/build.json

Once that's done, then you can create the VM using vmadm as:

# vmadm create -f /var/tmp/build.json

Setting Up the Zone

While you can build as the root user, we recommend that you create a user to do your day to day work as. If you do create that user there are two things that you should do:

1. Make sure that the user has the 'Primary Administrator' privilege. There are occasional parts of the build that require administrator privileges and these will use pfexec to do so. To add a user to the primary administrator role, as the root user in the zone, you should run:

# usermod -P 'Primary Administrator' <user>

1. Make sure that the user's shell is set to /bin/bash. There have occasionally been build issues when using different shells. Ultimately, those are bugs. If you do use another shell and encounter issues, please tell us.

The final prerequisite is to make sure that git is installed. To do that, you should run as your user:

$ pfexec pkgin -y in git
...
$

With this, you should be all set in your new environment. The normal build process will make sure that any required packages are installed.

If you're running any of the release-engineering targets, the build will also require Manta tools and updates-imgadm to be available on $PATH, but most users are unlikely to need to build these targets.

Basic Build Pattern

Once the build zone has been configured, you can kick off a build in a few easy steps:

$ git clone https://github.com/TritonDataCenter/smartos-live
$ cd smartos-live
$ ./configure
$ gmake live

This will produce a tarball that contains the platform. The platform will be placed in the output directory and a symlink to the latest tarball will be there.

The configure script takes a few options that allow you to do a DEBUG build, configure shadow compilers, etc. See ./configure -h.

Build Outputs

By default, running gmake live produces a directory and a tarball in the output directory. This can be used in Triton with the sdcadm commands and can be used to boot through ipxe or other network boot loaders.

It is also possible to create ISO and USB images. These images default to the VGA console. To make an ISO or USB image you can run from the root of the smartos-live repository:

$ ./tools/build_boot_image -r $ROOT
$ ./tools/build_boot_image -I -r $ROOT
$ ./tools/build_boot_image -I -r $ROOT -c ttyb # sets the default console to ttyb

These will create images in the output-usb and output-iso directories based on the latest platform image.

Build Order and Common Targets

When you kick off a smartos-live build (running gmake live), it will build components in the following order:

1. illumos-extra bootstrap phase against the build system
2. illumos-joyent
3. illumos-extra main phase against the proto area
4. smartos-live src against the proto area
5. local projects against the proto area
6. assemble packaging manifests
7. assemble the platform tgz

If you run gmake world instead of gmake live, then the build will stop after all of the components have been built.

The following summarizes the primary targets used on a day to day basis:

• world: Builds all the components
• live: Assembles the live image from the built components
• check: Runs v