{"id":29675846,"url":"https://github.com/oxidecomputer/helios-engvm","last_synced_at":"2025-07-22T23:38:53.792Z","repository":{"id":219729358,"uuid":"318423625","full_name":"oxidecomputer/helios-engvm","owner":"oxidecomputer","description":"Tools for creating and using Helios images on i86pc (classic PC) physical and virtual machines ","archived":false,"fork":false,"pushed_at":"2025-06-05T18:56:16.000Z","size":248,"stargazers_count":39,"open_issues_count":14,"forks_count":4,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-06-05T19:45:05.241Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","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-12-04T06:21:36.000Z","updated_at":"2025-06-04T04:24:05.000Z","dependencies_parsed_at":"2024-02-28T19:43:52.641Z","dependency_job_id":"4f76366d-1c4f-4ccb-a5c3-335dc0cf4a6b","html_url":"https://github.com/oxidecomputer/helios-engvm","commit_stats":null,"previous_names":["oxidecomputer/helios-engvm"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/oxidecomputer/helios-engvm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios-engvm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios-engvm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios-engvm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios-engvm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxidecomputer","download_url":"https://codeload.github.com/oxidecomputer/helios-engvm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fhelios-engvm/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:53.234Z","updated_at":"2025-07-22T23:38:53.781Z","avatar_url":"https://github.com/oxidecomputer.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Helios Engineering System Tools\n\nThis repository contains tools for setting up a Helios virtual or physical host\nfor development purposes.  It provides support for at least the following\nenvironments:\n\n* Linux workstation, Ubuntu 20.04.01 LTS, KVM/QEMU as managed by libvirt\n* Macintosh workstation (with an Intel CPU), VMware Fusion 12\n\n## Creating a Helios Virtual Machine\n\n### Installing Dependencies\n\n#### Linux\n\nThese instructions assume you are using an Ubuntu 20.04.01 LTS system and that\nyou have the libvirt suite installed.  The easiest way to get these tools is to\ninstall the `virt-manager` package, which also gets you a limited GUI interface\nfor managing virtual machines; e.g.,\n\n```\nhost ~ $ sudo apt install virt-manager\n```\n\nSo that you can interact with virtual machines directly, make sure your regular\nuser account is a member of the `libvirt` group.\n\nNOTE: New group memberships generally don't take effect until you log out and\nlog in again; to avoid needing to do that you can temporarily switch your\nprimary group to libvirt with `newgrp`.  You only need to do this until the\nnext time you log out and log in.\n\n```\nhost ~ $ sudo usermod -a -G libvirt $(whoami)\nhost ~ $ newgrp libvirt\n```\n\n#### Macintosh\n\n**NOTE: Helios is only built for x86 CPUs, so these instructions will only work\non a Macintosh with an Intel CPU.  Newer systems with ARM CPUs are not suitable\nand will not work.**\n\nInstall VMware Fusion.  These instructions have been tested with VMware Fusion\n12.1.  It should be installed in the usual place; i.e.,\n`/Applications/VMware Fusion.app`.\n\nRun the setup script that will download the `vmware-sercons` tool and build it\nfrom source:\n\n```\nhost ~ $ ./macos/setup.sh\n```\n\nYou will need to have some package installed that provides `make` and `gcc`,\nsuch as XCode or the SDK command-line utilities.\n\n### Downloading Seed Image\n\nTo create the virtual machine, you must first obtain the seed image:\n\n```\nhost ~/helios-engvm $ ./download.sh\nchecking hash on existing gz file /home/user/helios-engvm/tmp/helios-qemu-ttya-full.raw.gz...\nextracting /home/user/helios-engvm/tmp/helios-qemu-ttya-full.raw.gz\nmoving /home/user/helios-engvm/tmp/helios-qemu-ttya-full.raw.gz.extracted -\u003e /home/user/helios-engvm/input/helios-qemu-ttya-full.raw\nchecking hash on existing file /home/user/helios-engvm/input/helios-qemu-ttya-full.raw...\nseed image downloaded ok\n```\n\nIf you already have an instance of Helios running, you can *alternatively*\nchoose to create this image [manually](image/README.md).\n\n### VM Creation\n\n#### Choose a VM configuration\n\nThe default virtual machine settings (e.g., CPU count, disk size, memory size)\nare stored in `config/defaults.sh`:\n\n```\nhost ~/helios-engvm $ cat config/defaults.sh\nVM=helios\nPOOL=default\nINPUT_IMAGE=helios-qemu-ttya-full.raw\nSIZE=30G\nVCPU=2\nMEM=$(( 2 * 1024 * 1024 ))\n```\n\nYou can override them by making a new file under `config`; e.g.,\n\n```\nhost ~/helios-engvm $ echo 'VCPU=8' \u003econfig/big.sh\nhost ~/helios-engvm $ echo 'MEM=$(( 8 * 1024 * 1024 ))' \u003e\u003econfig/big.sh\n```\n\n#### Ensure the libvrt `default` network is activated\n\nYou can check the state of existing networks as such:\n\n```\n$ sudo virsh net-list --all\n```\n\nThe output should include the `default` network as \"active\":\n\n```\n Name      State    Autostart   Persistent\n--------------------------------------------\n default   active   no          yes\n```\n\nIf it is not active, activate it:\n\n```\n$ sudo virsh net-start default\n```\n\n#### Create the VM\n\nYou can now create a virtual machine. If you chose to use a non-default config,\nprovide its name as the argument, which will override the default. E.g., for a\nconfig called `big.sh`:\n\n```\nhost ~/helios-engvm $ ./create.sh big\n```\n\nIf everything goes well, you will be attached to the serial console of the\nvirtual machine which will boot into the Helios development image.  An account\nwill be created with the same username and uid as your account on the host\nsystem, and your `authorized_keys` file will be copied into the guest.\nOnce boot and setup are complete, you should see a prompt that tells you\nthe IP address the guest was given; e.g.,\n\n```\nYou should be able to SSH to your VM:\n\n    ssh user@192.168.122.235\n```\n\nIf you need to get into the root account on the console to debug something, the\ndevelopment image ships with an empty root password to make it easy to do so.\n\nYou can halt the VM and destroy the created resources (disks, etc) with the\nmatching `destroy.sh`:\n\n```\nhost ~/helios-engvm $ ./destroy.sh big\n```\n\nIf you need to get back on the console later, you can use the `console.sh`\nscript; e.g.,\n\n```\nhost ~/helios-engvm $ ./console.sh big\n```\n\n## Building Helios and illumos software\n\nOnce you have a virtual machine running Helios and you are able to use SSH to\naccess it, you can build and test Helios and illumos software inside, like you\nwould with any other machine.  There are detailed instructions in the\n[Helios](https://github.com/oxidecomputer/helios.git) repository that cover\nbuilding OS packages and updating the build machine (in this case, your virtual\nmachine!) to use those packages.\n\n**NOTE**: As mentioned in the Helios documentation, when installing and\nrebooting it is a good idea to be on the console of the virtual machine so you\ncan see any boot messages and interact with the boot loader.  If you are not\nstill attached from when you created the virtual machine, you can re-attach\nwith:\n\n```\nhost$ virsh console --force helios\nConnected to domain helios\nEscape character is ^]\n\nhelios console login: root\nPassword:\nDec  4 22:58:11 helios login: ROOT LOGIN /dev/console\nThe illumos Project     master-0-g7b4214534c    December 2020\nroot@helios:~# reboot\nDec  4 22:58:49 helios reboot: initiated by root on /dev/console\nupdating /platform/i86pc/amd64/boot_archive (CPIO)\nsyncing file systems... done\nrebooting...\n```\n## Installing on a physical machine using the ISO\n\nIf you want to install the OS on a physical machine, there is a crude\ninstallation image available that can be booted as either an ISO or a USB disk.\n\nFirst, grab the images from the download area at:\nhttps://pkg.oxide.computer/install/latest/\n\nThis directory contains three ISO images, each of which is configured to use a\ndifferent device for the operating system console; `ttya` (aka COM1), `ttyb`\n(aka COM2), or `vga` (the framebuffer and keyboard).  If you have a system with\nan IPMI Serial-over-LAN (SOL) facility, you probably want `ttyb`.  If you have\na desktop with a keyboard and monitor, you probably want `vga`.  Prefer serial\nif you can!\n\n### Prepare installation media\n\nIf you have a physical USB mass storage device (e.g., a flash drive) you can\nuse `dd` to write the image to the disk.  It should replace the partition\ntable, so use the whole-disk device for your OS (e.g., something like\n`/dev/sda` on Linux, or `/dev/dsk/c0t0d0p0` on illumos).\n\nIf you want to try booting the ISO via IPMI remote media redirection that may\nalso work.\n\n### Initial install\n\nBoot from your media.  The install media will log in automatically as **root**\nand display an informational banner:\n\n```\n -- Welcome to Oxide Helios! -------------------------------------------------\n\n    This bootable ISO allows you to install Helios on a traditional\n    install-to-disk system; e.g., a desktop PC or a BIOS/EFI-boot\n    server.\n\n    To install, use \"diskinfo\" to locate the disk you wish to install\n    to, and then use \"install-helios\" to format it and install the\n    operating system.\n\n    More information is available in the \"Installing on a physical\n    machine using the ISO\" section of the README at:\n\n        https://github.com/oxidecomputer/helios-engvm\n\n -----------------------------------------------------------------------------\n```\n\nFrom this shell:\n\n* Run `diskinfo` to find your disk; you may need to run it a few times if the\n  disk devices have not yet finished attaching and you don't see the disks you\n  expect.  For example:\n  ```\n  # diskinfo\n  TYPE  DISK                    VID      PID              SIZE          RMV SSD\n  NVME  c1t0025385C9150D623d0   Samsung  SSD 970 EVO 1TB   931.51 GiB   no  yes\n  NVME  c2t0014EE83021EAE80d0   NVMe     WUS4BB019D4M9E4  1788.50 GiB   no  yes\n  ```\n* Choose a hostname.\n* Run the installer, providing the hostname you've chosen and the disk onto\n  which you wish to install; e.g.,\n  ```\n  # install-helios myhostname c1t0025385C9150D623d0\n  ...\n  ok to reboot now\n  ```\n* Once you get the **\"ok to reboot now\"** prompt, you should be able to remove\n  the media and boot from your installed disk.\n* After reboot, log in with `root` and no password.\n\n### Configure networking\n\nFind your NIC:\n\n```\n# dladm show-ether\nLINK            PTYPE    STATE    AUTO  SPEED-DUPLEX                    PAUSE\nbge0            current  up       yes   1G-f                            none\nbge1            current  unknown  no    0G                              none\n\n# dladm show-phys -m\nLINK         SLOT     ADDRESS            INUSE CLIENT\nbge0         primary  a0:42:3f:42:91:50  yes  bge0\nbge1         primary  a0:42:3f:42:91:51  no   --\n```\n\nLet's say we pick `bge0`.  Set up IP:\n\n```\n# ipadm create-if bge0\n# ipadm create-addr -T dhcp bge0/dhcp\n# svcadm restart network/service\n# ipadm show-addr\nADDROBJ           TYPE     STATE        ADDR\nlo0/v4            static   ok           127.0.0.1/8\nbge0/dhcp         dhcp     ok           172.20.3.63/24\nlo0/v6            static   ok           ::1/128\n```\n\n### Create your user account\n\nClone `helios-engvm.git` on your workstation, and try generating a setup\nscript:\n\n```\n$ ./aws/gen_userdata.sh\n#!/bin/bash\nset -o errexit\nset -o pipefail\nset -o xtrace\necho 'Just a moment...' \u003e/dev/msglog\n/sbin/zfs create 'rpool/home/jclulow'\n/usr/sbin/useradd -u '1000' -g staff -c 'Joshua M. Clulow' -d '/home/jclulow' \\\n    -P 'Primary Administrator' -s /bin/bash 'jclulow'\n/bin/passwd -N 'jclulow'\n/bin/mkdir '/home/jclulow/.ssh'\n/bin/uudecode \u003c\u003c'EOSSH'\nbegin-base64 600 /home/jclulow/.ssh/authorized_keys\nZWNkc2Etc2hhMi1uaXN0cDM4NCBBQUFBRTJWalpITmhMWE5vWVRJdGJtbHpk\nSEF6T0RRQUFBQUlibWx6ZEhBek9EUUFBQUJoQlBKNXU0d1pqdmUrUDFTQTEx\nQ1U1WDVIcytGY29RQnFLZFpjMVA3MjhLS1dtbTBTK3YwVHMyR0Z1SldVcnV6\nNnpDVm1JM3JWc2J4TGZ4cXFLbHZ6d0xrWXRhOU41aFZBakZhOTltQzRkYk1i\nUlFWVFJrdW42ZXZPK3RvaTlCcXU2dz09IGpjbHVsb3ctc3lzbWdyLTAyCg==\n====\nEOSSH\n/bin/chown -R 'jclulow:staff' '/home/jclulow'\n/bin/chmod 0700 '/home/jclulow'\n/bin/sed -i \\\n    -e '/^PATH=/s#$#:/opt/ooce/bin:/opt/ooce/sbin#' \\\n    /etc/default/login\n/bin/ntpdig -S 0.pool.ntp.org || true\necho 'ok go' \u003e/dev/msglog\n```\n\nIf this works, you can go to the Helios machine and listen with netcat for a\nscript:\n\n```\n$ nc -l 1701 \u003c/dev/null | bash -x\n```\n\nThen, on your workstation:\n\n```\n$ ./aws/gen_userdata.sh | nc 172.20.3.63 1701\n```\n\nThis should send the script to the Helios machine and create your account.\nAssuming it completed successfully you should be able to SSH to the machine now\nwith your key:\n\n```\n$ ssh 172.20.3.63\nThe illumos Project     helios-1.0.20642        August 2021\njclulow@myhostname ~ $\n```\n\n### Configure multicast DNS\n\nIf you're using DHCP, your IP address may change from time to time.  On your\nHelios machine you can enable Multicast DNS:\n\n```\n# svcadm enable network/dns/multicast\n```\n\nYou should then be able to find the machine from your workstation as\n`myhostname.local`, rather than needing to use the IP address.\n\n### Configure swap\n\nYou should probably create a swap device if you don't already have one.\nDetermining the size is not an exact science, but somewhere between 1GB and\nhalf the size of RAM is probably a good guess.\n\n```\n# zfs create -V 8G rpool/swap\n# echo '/dev/zvol/dsk/rpool/swap - - swap - no -' \u003e\u003e /etc/vfstab\n# /sbin/swapadd\n```\n\n### Configure a dump device\n\nAlso useful is to configure a dump device for capturing system crash dumps:\n\n```\n# zfs create -V 8G rpool/dump\n# dumpadm -d /dev/zvol/dsk/rpool/dump\n```\n\nThe dump device needs to be large enough to hold a compressed copy of all of\nthe allocated kernel memory in a system.  The most correct answer for sizing is\n\"the same size as physical RAM\", but you can often get away with less.  You can\nestimate how large a dump would be if the system panicked right now with\n`dumpadm -e`, but note that this estimate does not reflect how large a dump\nmight be after you begin seriously using the system.\n\n### Updating your system\n\nNeither the ISO nor the virtual machine images always include the latest\npackages.  You can update your system via:\n\n```\n# pkg update -v\n```\n\nPay careful attention to the instructions printed at the end of the 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\nYou can do this again whenever you need to update your system.\n\n### Installing packages for building software\n\nUnlike the `create.sh` script for producing a virtual machine, the ISO images\nwill install a minimal base system that does not include developer tools.  If\nyou are setting up a machine for developing (or just building) Helios and other\nsoftware, install at least these extra packages:\n\n```\n# pkg install -v \\\n    /developer/build-essential \\\n    /developer/illumos-tools\n```\n\nThis will make available a variety of tools like Git, GNU Make, and GCC.\n\n### Installing 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## 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-engvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxidecomputer%2Fhelios-engvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidecomputer%2Fhelios-engvm/lists"}