{"id":29675841,"url":"https://github.com/oxidecomputer/helios-omicron-brand","last_synced_at":"2025-07-22T23:38:53.263Z","repository":{"id":169555201,"uuid":"447501857","full_name":"oxidecomputer/helios-omicron-brand","owner":"oxidecomputer","description":"A zone brand for Omicron components running under Helios","archived":false,"fork":false,"pushed_at":"2024-03-15T23:10:21.000Z","size":144,"stargazers_count":5,"open_issues_count":5,"forks_count":0,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-02-10T00:58:05.081Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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}},"created_at":"2022-01-13T07:19:12.000Z","updated_at":"2025-01-24T10:55:15.000Z","dependencies_parsed_at":"2024-02-22T00:25:24.740Z","dependency_job_id":"e36def96-2145-4ab3-98f9-4a1d34ee5831","html_url":"https://github.com/oxidecomputer/helios-omicron-brand","commit_stats":null,"previous_names":["oxidecomputer/helios-omicron-brand"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/oxidecomputer/helios-omicron-brand","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios-omicron-brand","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios-omicron-brand/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios-omicron-brand/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios-omicron-brand/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxidecomputer","download_url":"https://codeload.github.com/oxidecomputer/helios-omicron-brand/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios-omicron-brand/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":"2025-07-22T23:38:52.509Z","updated_at":"2025-07-22T23:38:53.237Z","avatar_url":"https://github.com/oxidecomputer.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# helios-omicron-brand\n\nThis repository contains the `omicron1` zone brand for deployment of\n[Omicron](https://github.com/oxidecomputer/omicron) components running under\n[Helios](https://github.com/oxidecomputer/helios).\n\n\u003c!-- MANUAL START --\u003e\n```\nOMICRON1(7)        Standards, Environments, and Macros       OMICRON1(7)\n\nNAME\n     omicron1 – zone brand for running Omicron components\n\nDESCRIPTION\n     The omicron1 brand uses the brands(7) framework to provide an\n     environment in which to run Omicron components within the Oxide\n     Helios ramdisk image.  Each zone is created from the combination of\n     the libraries and executables on the running system, a baseline\n     archive of pristine configuration files, and an optional set of\n     image archives provided at install time.\n\n     This brand is intended for use in a ramdisk system where zones are\n     not persistent; they are recreated from images as needed each time\n     the system boots.  If persistent data is required, such as for a\n     database server, the zone should be provided with a delegated ZFS\n     dataset and the application should be configured to store its data\n     within that dataset.  See DELEGATING A DATASET.\n\nBASELINE ARCHIVES\n   Production Systems\n     In production systems the baseline archive will be generated\n     against the ramdisk contents at build time and shipped as a file in\n     the ramdisk itself.  This work is not yet complete.\n\n   Development Systems\n     For development purposes, a baseline archive can be generated\n     against the running system.  An SMF service,\n     svc:/system/omicron/baseline:default, is provided in the\n     pkg:/system/zones/brand/omicron1/tools package, and will generate a\n     baseline archive at boot and store it in /var/run/brand/omicron\n     where the brand will look for it when installing a zone with\n     zoneadm(8).\n\n     The baseline generator makes use of pkg(7) to assemble the contents\n     of the zone root file system into an archive that can be unpacked\n     for each install.  Once the archive is generated, whether on the\n     development system or in the ramdisk, zones can be installed\n     without further interaction with the packaging system.  Any time\n     pkg(1) is used to update a development system, the contents of any\n     previously installed zones is likely invalid and they will need to\n     be uninstalled and reinstalled.  See LIMITATIONS.\n\nIMAGE ARCHIVES\n     An image archive is a gzip-compressed tar file with a specific\n     layout.  The first file in the archive should be a file with the\n     name oxide.json and the following contents:\n\n       {\"v\":\"1\",\"t\":\"layer\"}\n\n     This metadata is used by the brand to identify the type of image so\n     that it may be unpacked correctly.\n\n     Files to be unpacked into the zone root must be stored within the\n     archive under a directory called root.  A minimal image might\n     contain very few files; e.g.,\n\n       $ tar tfz /tmp/someimage.tar.gz\n       oxide.json\n       root/\n       root/var/svc/manifest/site/program1.xml\n       root/var/svc/manifest/site/program2.xml\n       root/var/svc/profile/site.xml\n       root/usr/lib/program1\n       root/usr/lib/program2\n\nCONFIGURATION\n     Zones using the omicron1 brand must have an exclusive IP stack.  If\n     networking in the zone is required, create a VNIC with dladm(8)\n     (e.g., testzone0 below) and pass it in the zone configuration.\n     There is presently no mechanism for automated IP configuration from\n     zone properties, though enabling the svc:/network/physical:nwam\n     service within the zone will make a best effort attempt at IPv4 and\n     IPv6 automated configuration.\n\n       create\n       set brand=omicron1\n       set zonepath=/zones/testzone\n       set autoboot=false\n       set ip-type=exclusive\n       add net\n           set physical=testzone0\n       end\n\nINSTALLATION\n     At zone install time, the omicron1 brand unpacks the baseline\n     archive into the zone root to establish a basic Helios environment\n     inside the zone.  Additional files may optionally be layered on top\n     of the base system by providing them as arguments to zoneadm(8)\n     when installing the zone:\n\n       # zoneadm -z testzone0 install /tmp/someimage.tar.gz\n       A ZFS file system has been created for this zone.\n       INFO: omicron: installing zone testzone @ \"/zones/testzone\"...\n       INFO: omicron: replicating /usr tree...\n       INFO: omicron: replicating /lib tree...\n       INFO: omicron: replicating /sbin tree...\n       INFO: omicron: pruning SMF manifests...\n       INFO: omicron: pruning global-only files...\n       INFO: omicron: unpacking baseline archive...\n       INFO: omicron: unpacking image \"/tmp/someimage.tar.gz\"...\n       INFO: omicron: install complete, probably!\n\n     Note that, as per LIMITATIONS, for correct operation each omicron1\n     zone must be uninstalled and reinstalled any time a development\n     system is updated, such as with pkg(1).  In a production ramdisk\n     system, this will effectively happen automatically as all zone\n     state is discarded each time the system reboots.\n\nDELEGATING A DATASET\n     One can create a delegated dataset that will automatically mount at\n     /data within the zone as follows:\n\n       # zfs create -o canmount=noauto rpool/delegated/testzone\n       # zfs set mountpoint=/data rpool/delegated/testzone\n       # zfs set zoned=on rpool/delegated/testzone\n       # zfs set canmount=on rpool/delegated/testzone\n\n     Once this dataset has been created, it can be delegated to the zone\n     via zonecfg(8):\n\n       # zonecfg -z testzone\n       zonecfg:testzone\u003e add dataset\n       zonecfg:testzone:dataset\u003e set name=rpool/delegated/testzone\n       zonecfg:testzone:dataset\u003e end\n       zonecfg:testzone\u003e commit\n\n     The dataset will then be mounted at /data next time the zone boots.\n     Note that the delegated dataset can also be added during initial\n     zone configuration, and does not need to be added as a second step.\n\nLIMITATIONS\n     Various components in the operating system share Private interfaces\n     with one another; e.g., the system call interface used by libc.so.1\n     and the kernel are subject to change without notice.  To ensure\n     correct operation such components must always be built together,\n     and installed or updated in lock step.\n\n     During zone installation, the omicron1 brand draws baseline files,\n     which include such components with Private interfaces, from two\n     sources:\n\n     -   Executable and library files in /usr, /lib, and /sbin, which\n         are copied or symlinked from their source locations on the\n         running system.\n\n     -   Seed configuration and data files, such as those in /etc and\n         /var, which are unpacked from the baseline archive.\n\n     The copying and symlinking of contents from trees like /usr\n     represents a compromise:\n\n     -   It allows us to modify those trees by layering on additional\n         files from images, which a read-only lofs(4FS) mount would not.\n         A more complete solution for the future, which would require\n         more engineering effort, would be to develop a union or layered\n         file system.\n\n     -   It requires us to reinstall the zone any time the contents of\n         /usr, /lib, or /sbin, change; i.e., any time the operating\n         system is updated.  This is only a problem on development\n         machines, as production ramdisks are sealed at build time and\n         zones will be recreated each time the machine boots.\n\n     In short: use zoneadm(8) to uninstall and reinstall your omicron1\n     brand zones after updating with pkg(1) and rebooting.\n\nINTERFACE STABILITY\n     During early development the brand will continue to evolve, and is\n     thus Uncommitted.\n\nSEE ALSO\n     pkg(1), dladm(8), zfs(8), zoneadm(8), zonecfg(8), brands(7),\n     pkg(7), zones(7), lofs(4FS)\n\nillumos                     December 12, 2021                    illumos\n```\n\u003c!-- MANUAL END --\u003e\n\n## Licence\n\nCopyright 2023 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-omicron-brand","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxidecomputer%2Fhelios-omicron-brand","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidecomputer%2Fhelios-omicron-brand/lists"}