{"id":13753473,"url":"https://github.com/oxidecomputer/helios","last_synced_at":"2025-07-22T23:38:47.086Z","repository":{"id":219790044,"uuid":"290132393","full_name":"oxidecomputer/helios","owner":"oxidecomputer","description":"Helios: Or, a Vision in a Dream. A Fragment.","archived":false,"fork":false,"pushed_at":"2025-07-10T17:43:07.000Z","size":431,"stargazers_count":388,"open_issues_count":55,"forks_count":11,"subscribers_count":29,"default_branch":"master","last_synced_at":"2025-07-10T23:50:32.535Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oxidecomputer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-08-25T06:26:48.000Z","updated_at":"2025-07-10T17:32:51.000Z","dependencies_parsed_at":"2024-08-06T20:09:00.204Z","dependency_job_id":"3f15cb74-4284-441b-be08-a24aa5a37069","html_url":"https://github.com/oxidecomputer/helios","commit_stats":null,"previous_names":["oxidecomputer/helios"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/oxidecomputer/helios","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxidecomputer","download_url":"https://codeload.github.com/oxidecomputer/helios/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266591233,"owners_count":23953082,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T09:01:22.965Z","updated_at":"2025-07-22T23:38:47.070Z","avatar_url":"https://github.com/oxidecomputer.png","language":"Rust","funding_links":[],"categories":["Rust","Active"],"sub_categories":["Illumos"],"readme":"# Oxide Helios\n\nHelios is a distribution of illumos powering the Oxide Rack.  The full\ndistribution is built from several consolidations of software, driven from\ntools and documentation in this top-level repository.\n\n| Consolidation                                                                                   | Public? | Description                                                                     |\n| ----------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------- |\n| [boot-image-tools](https://github.com/oxidecomputer/boot-image-tools)                           | ✅ Yes  | Tool for assembling boot images for Oxide hardware                              |\n| [garbage-compactor](https://github.com/oxidecomputer/garbage-compactor)                         | ✅ Yes  | Build scripts for packages beyond the core OS                                   |\n| [helios-omicron-brand](https://github.com/oxidecomputer/helios-omicron-brand)                   | ✅ Yes  | Zone brand for [Omicron](https://github.com/oxidecomputer/omicron) components   |\n| [helios-omnios-build](https://github.com/oxidecomputer/helios-omnios-build)                     | ✅ Yes  | Build scripts for packages beyond the core OS                                   |\n| [helios-omnios-extra](https://github.com/oxidecomputer/helios-omnios-extra)                     | ✅ Yes  | Build scripts for packages beyond the core OS                                   |\n| [illumos-gate (stlouis branch)](https://github.com/oxidecomputer/illumos-gate/tree/stlouis/)    | ✅ Yes  | Core operating system (kernel, libc, etc)                                       |\n| [phbl](https://github.com/oxidecomputer/phbl)                                                   | ✅ Yes  | Pico Host Boot Loader                                                           |\n| [pinprick](https://github.com/oxidecomputer/pinprick)                                           | ✅ Yes  | ROM image compression utility                                                   |\n| [illumos/image-builder](https://github.com/illumos/image-builder)                               | ✅ Yes  | Tool for building bootable illumos disk images                                  |\n| [amd-firmware](https://github.com/oxidecomputer/amd-firmware)                                   | ❌ No   | AMD CPU firmware binary blobs (will be available in future)                     |\n| [amd-host-image-builder](https://github.com/oxidecomputer/amd-host-image-builder)               | ✅ Yes  | ROM image construction tools for AMD CPUs                                       |\n| [chelsio-t6-roms](https://github.com/oxidecomputer/chelsio-t6-roms)                             | ❌ No   | Chelsio T6 network interface card firmware blobs (will be available in future)  |\n| [pilot](https://github.com/oxidecomputer/pilot)                                                 | ❌ No   | A utility for low-level control of Oxide systems (will be available in future)  |\n\n**NOTE:** Not all consolidations are presently available to the public.  We're\nworking on this, but for now you can set `OXIDE_STAFF=no` in your environment\nwhen you run `gmake setup` to skip cloning and building software that is not\nyet available.\n\n## Getting started\n\n**NOTE: These instructions are for building your own operating system packages\nand installing them.  If you're just trying to use Helios, you probably do not\nneed to do this.  See\n[helios-engvm](https://github.com/oxidecomputer/helios-engvm) for\ninformation about pre-built Helios software.**\n\nThe best way to get started is to be using a physical or virtual build machine\nrunning an up-to-date installation of Helios.  There are some details on\ngetting a virtual machine installed in the\n[helios-engvm](https://github.com/oxidecomputer/helios-engvm) repository.\nThere are also some details there about install media that you can use on a\nphysical x86 system.\n\n### Prerequisites\n\nIf you used the instructions from **helios-engvm** to create a virtual machine,\nyou should already have all of the packages needed.  If you used one of the ISO\ninstallers to set up a physical machine, or some other way of getting a Helios\nenvironment, you may need to install the **pkg:/developer/illumos-tools**\npackage.  You can check if you have this installed already with:\n\n```\n$ pkg list developer/illumos-tools\nNAME (PUBLISHER)                VERSION    IFO\ndeveloper/illumos-tools         11-2.0     im-i\n```\n\nIf missing from your system, it can be installed with `pkg install`.  It's also\na good idea to be running the latest Helios packages if you can.  You can\nupdate your system with:\n\n```\n# pkg update\n```\n\nPay careful attention to the instructions printed at the end of every update.\nYou may be told that a _boot environment_ was created and that you need to\nreboot to activate it.  You should do that with the `reboot` command before\nmoving on.\n\n### Install Rust and Cargo using Rustup\n\nOfficial Rust and Cargo binaries are available from the Rust project via the\nsame [rustup](https://rustup.rs/) tool that works on other systems.  Use the\nofficial instructions, but substitute `bash` anywhere you see `sh`; e.g., at\nthe time of writing, the (modified) official install instructions are:\n\n```\n$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | bash\n```\n\n### Clone the repository and build the tools\n\nOn your Helios machine, clone this repository and run the setup step:\n\n```\n$ git clone https://github.com/oxidecomputer/helios.git\nCloning into 'helios'...\n\n$ cd helios\n$ gmake setup\ncd tools/helios-build \u0026\u0026 cargo build --quiet\n...\nCloning into '/home/user/helios/projects/illumos'...\n...\n\nSetup complete!  ./helios-build is now available.\n```\n\n**NOTE:** If you do not have access to private repositories in the\n**oxidecomputer** GitHub organisation, you can request that the setup step only\nuse the public repositories; e.g.,\n\n```\n$ OXIDE_STAFF=no gmake setup\n```\n\nThe Rust-based `helios-build` tool will be built and several repositories will\nthen be cloned under `projects/`.  Note that, at least for now, the tool takes\na little while to build the first time.\n\nWhile the tool will initially clone the expected project repositories,\nsubsequent manipulation (e.g., pulling updates, switching branches) is only\nperformed for some repositories.  You can see which repositories the setup step\nwill update by looking at `auto_update` in the\n[`config/projects.toml`](./config/projects.toml) file.  You should otherwise\nexpect to manage local clones as you would any other git repository; switching\nbranches, pulling updates, etc.\n\n## Building illumos\n\nThe operating system components at the core of Helios come from the\n[**stlouis** branch of\nillumos-gate](https://github.com/oxidecomputer/illumos-gate/tree/stlouis).  The\npackages that ship on Helios systems are mostly [stock\nillumos](https://github.com/illumos/illumos-gate) with some additions for Oxide\nhardware and a few minor packaging transformations.\n\nTo make it easier to build illumos, `helios-build` provides several wrappers\nthat manage build configuration and invoke the illumos build tools.  The\nupstream illumos documentation has a guide, [Building\nillumos](https://illumos.org/docs/developers/build/), which covers most of what\nthe Helios tools are doing on your behalf if you are curious.\n\n### Building during development\n\nWhile making changes to illumos, you can perform a \"quick\" build.  This\ndisables the shadow compilers and some of the checks that we would otherwise\nrequire for a final integration.\n\n```\n$ ./helios-build build-illumos -q\nDec 04 22:04:49.214 INFO file /home/user/helios/projects/illumos/illumos-quick.sh does not exist\nDec 04 22:04:49.215 INFO writing /home/user/helios/projects/illumos/illumos-quick.sh ...\nDec 04 22:04:49.215 INFO ok!\nDec 04 22:04:49.216 INFO exec: [\"/sbin/sh\", \"-c\", \"cd /home/user/helios/projects/illumos \u0026\u0026 ./usr/src/tools/scripts/nightly /home/user/helios/projects/illumos/illumos-quick.sh\"]\n...\n```\n\nDepending on how many CPUs you have on your build machine, and the performance\nof your local storage, this can take some time.  The full build log is quite\nlarge, and can be seen via, e.g.,\n\n```\n$ tail -F projects/illumos/log/nightly.log\n```\n\nOnce your build has completed successfully, there will be a package repository\nat `projects/illumos/packages/i386`.  These packages can then be transformed\nand installed in various ways.\n\n#### Installing: locally on your build machine\n\nTo install your newly built packages on the build machine:\n\n```\n$ ./helios-build onu -t my-be-name\nJan 29 09:33:44.603 INFO creating temporary repository...\n...\nJan 29 09:35:53.050 INFO O| beadm activate my-be-name\nJan 29 09:35:53.911 INFO O| Activated successfully\nJan 29 09:35:53.921 INFO onu complete!  you must now reboot\n```\n\nThis will transform and install the illumos packages you just built and create\na new _Boot Environment_ with the name you pass with `-t` (e.g., `my-be-name`\nabove).  The new boot environment can be seen with `beadm list`, and has been\nactivated by `onu` so that you can reboot into it.  See\n[beadm(8)](https://illumos.org/man/8/beadm) for more information about boot\nenvironments.\n\nWhen rebooting, it is a good idea to be on the console so you can see any boot\nmessages and interact with the boot loader.\n\n```\nhelios console login: root\nPassword:\nLast login: Mon Jan 29 09:34:20 on console\nThe illumos Project     stlouis-0-g27e9202a98   January 2024\nroot@genesis:~# reboot\nupdating /platform/i86pc/amd64/boot_archive (CPIO)\nsyncing file systems... done\nrebooting...\n```\n\nYou can see that your updated packages are now running:\n\n```\n$ pkg list -Hv system/kernel\npkg://on-nightly/system/kernel@0.5.11-2.0.999999:20240129T090642Z            i--\n```\n\nCritically, the `system/kernel` package shown here comes from the `on-nightly`\npublisher (your local files) and has a quick build version (`2.0.999999`).\n\n#### Installing: on another machine, using a package repository server\n\nIf you have a build machine and a separate set of test machine(s), you may wish\nto use the package repository server (`pkg.depotd`) on your build machine.  You\ncan reconfigure the test system to prefer to install packages from your build\nmachine over the network without needing to copy files around.\n\nFirst, transform the packages from your most recent build and start the package\nserver:\n\n```\n$ ./helios-build onu -D\nJan 29 09:39:46.885 INFO creating temporary repository...\nJan 29 09:39:46.886 INFO repository /home/user/helios/tmp/onu/repo.redist exists, removing first\n...\nJan 29 09:41:00.428 INFO starting pkg.depotd on packages at: \"/home/user/helios/tmp/onu/repo.redist\"\nJan 29 09:41:00.428 INFO access log file is \"/home/user/helios/tmp/depot/log/access\"\nJan 29 09:41:00.428 INFO listening on port 7891\nJan 29 09:41:00.428 INFO ^C to quit\n[29/Jan/2024:09:41:01] INDEX Search Available\n[29/Jan/2024:09:41:01] ENGINE Listening for SIGTERM.\n[29/Jan/2024:09:41:01] ENGINE Listening for SIGHUP.\n[29/Jan/2024:09:41:01] ENGINE Listening for SIGUSR1.\n[29/Jan/2024:09:41:01] ENGINE Bus STARTING\n[29/Jan/2024:09:41:01] ENGINE Serving on http://0.0.0.0:7891\n[29/Jan/2024:09:41:01] ENGINE Bus STARTED\n```\n\nThe server is now running, and will remain running until you press Control-C or\nterminate it in some other way.  You will need to know a DNS name or IP address\n(e.g., via `ipadm show-addr`) on which your build machine can be contacted.\n\nNow, on the target machine, confirm that you can contact the build machine:\n\n```\n$ pkgrepo info -s http://genesis:7891\nPUBLISHER  PACKAGES STATUS           UPDATED\non-nightly 549      online           2024-01-29T09:40:50.716102Z\n```\n\nExamine your existing package publisher configuration.  On a stock Helios\nsystem, it should look like this:\n\n```\n# pkg publisher\nPUBLISHER               TYPE   STATUS P LOCATION\nhelios-dev              origin online F https://pkg.oxide.computer/helios/2/dev/\n```\n\nJust one publisher is configured, using the central repository.  We want to add\na second publisher and make it the preferred source for packages.  We also want\nto relax the \"sticky\" rule; i.e., that packages should only be updated from the\npublisher from which they were first installed.\n\n```\n# pkg set-publisher -r -O http://genesis:7891 --search-first on-nightly\n# pkg set-publisher -r --non-sticky helios-dev\n# pkg publisher\nPUBLISHER               TYPE   STATUS P LOCATION\non-nightly              origin online F http://genesis:7891/\nhelios-dev (non-sticky) origin online F https://pkg.oxide.computer/helios/2/dev/\n```\n\nFor now, depending on what you're doing on the test system, it may be necessary\nto uninstall the `entire` meta-package before proceeding.  This is especially\ntrue if you have zones based on the `lipkg` brand.  You can do this via `pkg\nuninstall entire`.  The stock `onu` tool from illumos does this automatically.\n\nPerform a dry-run update to confirm that we are going to get updated\npackages from the quick build on your build machine:\n\n```\n# pkg update -nv\n            Packages to update:       325\n     Estimated space available:  20.67 GB\nEstimated space to be consumed: 564.95 MB\n       Create boot environment:       Yes\n     Activate boot environment:       Yes\nCreate backup boot environment:        No\n          Rebuild boot archive:       Yes\n\nChanged packages:\nhelios-dev -\u003e on-nightly\n  SUNWcs\n    0.5.11-2.0.22430 -\u003e 0.5.11-2.0.999999\n  SUNWcsd\n    0.5.11-2.0.22430 -\u003e 0.5.11-2.0.999999\n...\n```\n\nNote that the version is changing from a stock Helios version (which is the\ncommit number on the master branch of illumos) to `2.0.999999`, the quick build\nversion.  A new boot environment will be created, and a reboot will be\nrequired.\n\nRun the operation again without the `-n` flag to update:\n\n```\n# pkg update -v\n...\nDOWNLOAD                                PKGS         FILES    XFER (MB)   SPEED\nCompleted                            325/325     5311/5311  107.1/107.1  4.9M/s\n\nPHASE                                          ITEMS\nRemoving old actions                       1213/1213\nInstalling new actions                       892/892\nUpdating modified actions                  5921/5921\nUpdating package state database                 Done\nUpdating package cache                       325/325\nUpdating image state                            Done\nCreating fast lookup database                   Done\nReading search index                            Done\nBuilding new search index                    582/582\nUpdating package cache                           2/2\n\nA clone of helios exists and has been updated and activated.\nOn the next boot the Boot Environment helios-1 will be\nmounted on '/'.  Reboot when ready to switch to this updated BE.\n\n*** Reboot required ***\nNew BE: helios-1\n\nUpdating package cache                           2/2\n```\n\nAssuming the update was successful, you should be able to reboot into your\nupdate software!\n\n```\n# reboot\nupdating /platform/i86pc/amd64/boot_archive (CPIO)\n```\n\nAfter reboot, note that the publisher configuration is persistent:\n\n```\nLoading unix...\nLoading /platform/i86pc/amd64/boot_archive...\nLoading /platform/i86pc/amd64/boot_archive.hash...\nBooting...\nOxide Helios Version stlouis-0-g27e9202a98 64-bit (onu)\nHostname: helios\n\nhelios console login: root\nPassword:\n\nThe illumos Project     stlouis-0-g27e9202a98   January 2024\n# uname -v\nstlouis-0-g27e9202a98\n\n# pkg publisher\nPUBLISHER               TYPE   STATUS P LOCATION\non-nightly              origin online F http://genesis:7891/\nhelios-dev (non-sticky) origin online F https://pkg.oxide.computer/helios/2/dev/\n```\n\nIn future, you should be able to do a new build, restart the package server,\nand then `pkg update -v` again on the test machine.\n\n#### Installing: producing packages without installing them\n\nIf you just want to transform the packages from a quick build without\ninstalling them, you can do so with the `-P` flag:\n\n```\n$ ./helios-build onu -P\nJan 29 09:45:36.040 INFO creating temporary repository...\nJan 29 09:45:36.040 INFO repository /home/user/helios/tmp/onu/repo.redist exists, removing first\n...\nJan 29 09:46:14.901 INFO O| Republish: pkg:/text/locale@0.5.11,5.11-2.0.999999:20240129T090648Z ...  Done\nJan 29 09:46:15.602 INFO exec: [\"/usr/bin/pkgrepo\", \"refresh\", \"-s\", \"/home/user/helios/tmp/onu/repo.redist\"], pwd: None\nJan 29 09:46:15.907 INFO O| Initiating repository refresh.\nJan 29 09:46:24.978 INFO transformed packages available for onu at: \"/home/user/helios/tmp/onu/repo.redist\"\n```\n\nThis may be useful if you just want to inspect the contents of the built\nrepository; e.g.,\n\n```\n$ pkgrepo info -s tmp/onu/repo.redist\nPUBLISHER  PACKAGES STATUS           UPDATED\non-nightly 549      online           2024-01-29T09:46:15.448096Z\n\n$ pkgrepo list -s tmp/onu/repo.redist\nPUBLISHER  NAME                          O VERSION\non-nightly SUNWcs                          0.5.11-2.0.999999:20240129T090617Z\non-nightly SUNWcsd                         0.5.11-2.0.999999:20240129T090618Z\non-nightly audio/audio-utilities           0.5.11-2.0.999999:20240129T090618Z\non-nightly benchmark/filebench           o 0.5.11-2.0.999999:20240129T090618Z\n...\n\n$ pkg contents -t file -s tmp/onu/repo.redist '*microcode*'\nPATH\nplatform/i86pc/ucode/AuthenticAMD/1020-00\nplatform/i86pc/ucode/AuthenticAMD/1022-00\nplatform/i86pc/ucode/AuthenticAMD/1041-00\nplatform/i86pc/ucode/AuthenticAMD/1043-00\nplatform/i86pc/ucode/AuthenticAMD/1062-00\nplatform/i86pc/ucode/AuthenticAMD/1080-00\nplatform/i86pc/ucode/AuthenticAMD/1081-00\nplatform/i86pc/ucode/AuthenticAMD/10A0-00\nplatform/i86pc/ucode/AuthenticAMD/2031-00\n...\n```\n\nYou can also preserve the package files for later analysis such as the\ncomparison of the output of multiple builds, or transport them to remote\nsystems for installation.\n\n### Making changes\n\nWhen making changes to the system it is generally best to start with a pristine\nbuilt workspace, as you would have left from the quick build in the previous\nsection.\n\nOnce your build has completed, you may wish to make a change to a particular\nsource file and rebuild a component.  There are many components in the illumos\nrepository, but we can choose a simple one as an example here.  To build a\nparticular component, we must first use `bldenv` to enter the build\nenvironment:\n\n```\n$ ./helios-build bldenv -q\nJan 29 09:50:22.895 INFO file /home/user/helios/projects/illumos/illumos-quick.sh exists, with correct contents\nJan 29 09:50:22.895 INFO ok!\nBuild type   is  non-DEBUG\nRELEASE      is\nVERSION      is stlouis-0-g27e9202a98\nRELEASE_DATE is January 2024\n\nThe top-level 'setup' target is available to build headers and tools.\n\nUsing /bin/bash as shell.\n$ pwd\n/home/user/helios/projects/illumos/usr/src\n```\n\nA new interactive shell has been started, with `PATH` and other variables set\ncorrectly, and you can now change to a component directory and build it:\n\n```\n$ cd cmd/id\n$ dmake -S -m serial install\n...\n```\n\nThis will build and install the updated `id` command into the proto area:\n\n```\n$ ls -l $ROOT/usr/bin/id\n-r-xr-xr-x   1 user     staff      17428 Jan 29 09:51 /home/user/helios/projects/illumos/proto/root_i386-nd/usr/bin/id\n```\n\nThis kind of targetted incremental edit-and-recompile is a good way to make\nchanges with a short cycle time and have some expectation that they will\ncompile.\n\nOnce you have changes you want to test, there are various things you can do\nnext.\n\n#### Option 1: Most correct and slowest\n\nYou can always do a new built of the entire OS.  This is the only process that\nis (as much as anything can be) guaranteed to produce correct results.  If,\nwhile doing something more incremental, you are experiencing an issue you\ncannot explain, a full build is always a good thing to try first.\n\n```\n$ ./helios-build build-illumos -q\n```\n\nThis will rebuild all of illumos and produce packages you can then install\nin the usual way, as described in previous sections.\n\n#### Option 2: No guarantees but faster\n\nIf you have updated some of the binaries in the proto area (e.g., by\nrunning `dmake install` in a kernel module or a command directory) you may\njust be able to regenerate the packages and install them without doing\na full build.\n\nWithin `bldenv`, regenerate the packages:\n\n```\n$ cd $SRC/pkg\n$ dmake install\n...\nPublishing system-zones-internal to redist repository\nPublishing system-test-zfstest to redist repository\nInitiating repository refresh.\n```\n\nOnce you have updated packages you can use them to start a package repository\nserver or install locally, as described in the previous sections.\n\n#### Option 3: It's your computer\n\nAt the end of the day, the operating system is just files in a file system.\nThe packaging tools and other abstractions often create a kind of mystique\nwhich separates the engineer from this concrete reality -- but you are an adult\nand it is your computer!  Other things you can do include:\n\n- Just running the modified binary on the build system, or using `scp` or\n  `rsync` to copy it to the test system and run it there.  Sometimes this\n  works!  If the binary requires changes to libraries or the kernel, it might\n  not work.\n\n- Creating a new boot environment and adjusting the files in it.  Boot\n  environments are separate ZFS file systems that can be modified, snapshotted,\n  cloned, and booted.  They can be created with `beadm create` and mounted for\n  modification with `beadm mount`.  The boot loader allows you to select a\n  different boot environment, and you can activate a specific boot environment\n  permanently or just for one boot using `beadm activate`.  See the `beadm(1M)`\n  manual page for more information.\n\n- Creating a wholly new disk image or ramdisk and booting that in a virtual\n  machine or via PXE.  There are some Helios-specific [tools for creating\n  images](https://github.com/oxidecomputer/helios-engvm/tree/main/image) that\n  can be made to include packages from a quick build, or even just arbitrary\n  additional files, by modifying image templates.  These tools are in turn\n  based on the upstream\n  [illumos/image-builder](https://github.com/illumos/image-builder).\n\nIf you want advice on how to do something not completely explained here, or\njust to streamline your workflow, please don't hesitate to reach out!\n\n## OS Image Archives\n\nAs part of building OS images for Oxide compute sleds, an image archive is\nproduced that includes the boot ROM and the root file system ramdisk image.  It\nalso includes some metadata in a JSON file, using the same format as [the\n**omicron1** brand](https://github.com/oxidecomputer/helios-omicron-brand/)\n(see **IMAGE ARCHIVES** in **omicron1(7)**).\n\nThe contents of the file represents a committed interface between Helios and\nthe parts of [Omicron](https://github.com/oxidecomputer/omicron) which need to\ndownload and install OS images on physical systems in the Oxide rack.  The\nrelevant contents for Omicron usage will always include at least:\n\n| Filename         | Description     |\n| ---------------- | --------------- |\n| `oxide.json`     | Metadata header file, with at least a `v=1` key and a `t=os` key to identify it as an OS image. |\n| `image/rom`      | The host boot ROM image. (32MiB) |\n| `image/zfs.img`  | The host root file system ramdisk image. (arbitrary size) |\n\nIn addition to the committed files listed above, some additional files may be\npresent for engineering or diagnostic purposes; e.g., a `unix.z` compressed\nkernel, and a `cpio.z` compressed boot archive, for use with **bldb** or\n**nanobl-rs**; or an array of extra ROM files with suffixes that represent\ndifferent diagnostic capabilities.  Additional files are not committed and may\nchange at any time in the future.  Software that interprets image archives\nshould ignore any unrecognised files.\n\n## Licence\n\nCopyright 2024 Oxide Computer Company\n\nUnless otherwise noted, all components are licenced under the [Mozilla Public\nLicense Version 2.0](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidecomputer%2Fhelios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxidecomputer%2Fhelios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidecomputer%2Fhelios/lists"}