How to install SmartOS on a datacenter machine (2025)

# How to install SmartOS on a datacenter machine Source: [https://blog.jcea.es/posts/20250209-install_SmartOS.html](https://blog.jcea.es/posts/20250209-install_SmartOS.html) This blogpost documents how to install[SmartOS](https://en.wikipedia.org/wiki/SmartOS)in a datacenter machine, with no remote[KVM](https://en.wikipedia.org/wiki/KVM_switch)neither physical access\. [SmartOS](https://en.wikipedia.org/wiki/SmartOS)used to need a[CD](https://en.wikipedia.org/wiki/Compact_disc),[DVD](https://en.wikipedia.org/wiki/DVD)or[USB](https://en.wikipedia.org/wiki/USB)[pendrive](https://en.wikipedia.org/wiki/USB_flash_drive)to boot the[Hypervisor](https://en.wikipedia.org/wiki/Hypervisor)\(saving hacks like[Installing/booting SmartOS in/from a harddisk without physical access](https://blog.jcea.es/posts/20161021-smartos_image.html)\), but since late 2020 you can install it in the[ZFS](https://en.wikipedia.org/wiki/ZFS)[ZPOOL](https://en.wikipedia.org/wiki/ZFS)and directly boot from there, using the new utilitypiadm\. ## [1 Create a template ZPOOL image](https://blog.jcea.es/posts/20250209-install_SmartOS.html#id1) First step is to create a[zpool](https://en.wikipedia.org/wiki/ZFS)[image](https://en.wikipedia.org/wiki/Optical_disc_image)to deploy on the server: 1. Download the[mostly current version](https://us-central.manta.mnx.io/Joyent_Dev/public/SmartOS/smartos.html)\(I usually prefer to avoid last version and use the previous version, if not marked as*toxic*\) of[SmartOS](https://en.wikipedia.org/wiki/SmartOS)\. 2. Launch[Virtualbox](https://en.wikipedia.org/wiki/VirtualBox), create a new machine with 4 GB of[RAM](https://en.wikipedia.org/wiki/Random-access_memory)and a[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive)of 10 GB\. The[virtual machine](https://en.wikipedia.org/wiki/Virtual_machine)[CPU](https://en.wikipedia.org/wiki/Central_processing_unit)**must be**configured as 64 bits\. Provide a virtual[NIC](https://en.wikipedia.org/wiki/Network_interface_controller)card\. That is, a network card\. Use the[SmartOS](https://en.wikipedia.org/wiki/SmartOS)[image](https://en.wikipedia.org/wiki/Optical_disc_image)as the virtual[CD](https://en.wikipedia.org/wiki/Compact_disc)drive\. 3. Boot the[virtual machine](https://en.wikipedia.org/wiki/Virtual_machine)\.[SmartOS](https://en.wikipedia.org/wiki/SmartOS)should enter a configuration script\. Provide dummy data for most of it, we will override later\. At the end, enable booting from the**zones**[zpool](https://en.wikipedia.org/wiki/ZFS)in order to do a[SmartOS](https://en.wikipedia.org/wiki/SmartOS)install on the virtual[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive)\. Advertencia When creating the**zones**[zpool](https://en.wikipedia.org/wiki/ZFS),**BE SURE**it is created withashift=12\. Boot must be compatible with[BIOS](https://en.wikipedia.org/wiki/BIOS)and[UEFI](https://en.wikipedia.org/wiki/UEFI)machines\. The easiest way to be sure is: 1. When asked about the[zpool](https://en.wikipedia.org/wiki/ZFS), entermanual\. 2. Create the[zpool](https://en.wikipedia.org/wiki/ZFS)manually: ``` [root@ /]# zpool create -B -o ashift=12 zones c1t0d0 ``` 3. Exit the*shell*and continue the configuration process\. 4. Eject the[SmartOS](https://en.wikipedia.org/wiki/SmartOS)virtual[CD](https://en.wikipedia.org/wiki/Compact_disc)and reboot the[virtual machine](https://en.wikipedia.org/wiki/Virtual_machine)\. Be sure it boots from the virtual[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive)\. 5. We must destroy[dataset](https://en.wikipedia.org/wiki/ZFS)zones/dumpand recreate it with the right size\. What is the right size? It is difficult to say\. It depends of the[RAM](https://en.wikipedia.org/wiki/Random-access_memory)size, but it is not linear\. The[SmartOS](https://en.wikipedia.org/wiki/SmartOS)configuration script usesdumpadm \-ejust after reset and multiply it by two\. In this[SmartOS](https://en.wikipedia.org/wiki/SmartOS)[image](https://en.wikipedia.org/wiki/Optical_disc_image)I will use 4 GB\. For a 64 GB machine, SmartOS seems to require around 1\.5 GB, so we are quite safe for now\. ``` [root@ /]# dumpadm -d none [root@ /]# zfs destroy zones/dump [root@ /]~# zfs create -V 4G zones/dump ``` 1. Be sure the machine can boot under[BIOS](https://en.wikipedia.org/wiki/BIOS)and[UEFI](https://en.wikipedia.org/wiki/UEFI): ``` [root@ /]# piadm bootable zones ==> BIOS and UEFI ``` 2. Shutdown the[virtual Machine](https://en.wikipedia.org/wiki/Virtual_machine)and boot with a Linux, for instance, a[Debian](https://en.wikipedia.org/wiki/Debian)[Live CD](https://en.wikipedia.org/wiki/Live_CD)\. 3. Upload an[image](https://en.wikipedia.org/wiki/Optical_disc_image)of the 10 GB virtual[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive)with[SmartOS](https://en.wikipedia.org/wiki/SmartOS)installed to your[cloud](https://en.wikipedia.org/wiki/Cloud_storage)or[file hosting service](https://en.wikipedia.org/wiki/File-hosting_service)\. Since most of the virtual[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive)is empty, compressing it will be highly effective\. 4. You can now destroy the[virtual machine](https://en.wikipedia.org/wiki/Virtual_machine)\. You don't need it anymore\. The[image](https://en.wikipedia.org/wiki/Optical_disc_image)just created will be a template to deploy any number of remote datacenter machines\. > I already did this for you\. You can use the[SmartOS](https://en.wikipedia.org/wiki/SmartOS)[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive)[image](https://en.wikipedia.org/wiki/Optical_disc_image)I host at[https://download\.jcea\.es/tamiza/dump\_SmartOS\_10GB\_20250124T134639Z\_pass\_jcea2025\.xz](https://download.jcea.es/tamiza/dump_SmartOS_10GB_20250124T134639Z_pass_jcea2025.xz)\. Compressed, it is only 180 MB\. The**root**password is**jcea2025**\. Its[SHA256](https://en.wikipedia.org/wiki/SHA-2)[hash](https://en.wikipedia.org/wiki/Cryptographic_hash_function)isf7ae2a59d58737a01850c9cb8696bbfe68b0a4b37d21b322005d076d054da562\. Advertencia DO NOT FORGET to change that default password\!\. ## [2 Overwrite and configure the remote machine in a datacenter](https://blog.jcea.es/posts/20250209-install_SmartOS.html#id2) 1. Rent a machine in a remote datacenter\.[SmartOS](https://en.wikipedia.org/wiki/SmartOS)kernel is[Illumos](https://en.wikipedia.org/wiki/Illumos), a[Solaris](https://en.wikipedia.org/wiki/Oracle_Solaris)derivative\. It is quite compatible with most server hardware\. I advice you to use an Intel[NIC](https://en.wikipedia.org/wiki/Network_interface_controller), performant and well supported, but many other popular brands are supported\. 2. Boot the machine in**rescue**mode\. This will be, typically, a[Linux](https://en.wikipedia.org/wiki/Linux)environment\. 3. Access to the remote machine in the**rescue**mode\. This will tipically run on a[ramdisk](https://en.wikipedia.org/wiki/RAM_drive), leaving the[HardDisks](https://en.wikipedia.org/wiki/Hard_disk_drive)alone\. 4. Download the[SmartOS](https://en.wikipedia.org/wiki/SmartOS)you prepared\. This will typically be a[ramdisk](https://en.wikipedia.org/wiki/RAM_drive)but you will probably have plenty of[RAM](https://en.wikipedia.org/wiki/Random-access_memory)available and the[SmartOS](https://en.wikipedia.org/wiki/SmartOS)compressed[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive)is tiny\. You can download my[SmartOS](https://en.wikipedia.org/wiki/SmartOS)[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive)[image](https://en.wikipedia.org/wiki/Optical_disc_image):[https://download\.jcea\.es/tamiza/dump\_SmartOS\_10GB\_20250124T134639Z\_pass\_jcea2025\.xz](https://download.jcea.es/tamiza/dump_SmartOS_10GB_20250124T134639Z_pass_jcea2025.xz)\. Its[SHA256](https://en.wikipedia.org/wiki/SHA-2)[hash](https://en.wikipedia.org/wiki/Cryptographic_hash_function)isf7ae2a59d58737a01850c9cb8696bbfe68b0a4b37d21b322005d076d054da562\. Feel free to use it\. For instance, you can do something like: ``` root@RESCUE:~# wget https://download.jcea.es/tamiza/dump_SmartOS_10GB_20250124T134639Z_pass_jcea2025.xz root@RESCUE:~# sha256sum dump_SmartOS_10GB_20250124T134639Z_pass_jcea2025.xz f7ae2a59d58737a01850c9cb8696bbfe68b0a4b37d21b322005d076d054da562 dump_SmartOS_10GB_20250124T134639Z_pass_jcea2025.xz ``` 5. Destroy any[GPT](https://en.wikipedia.org/wiki/GUID_Partition_Table)label in the[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive)\. You can usegdisk /dev/sda\. Pressxfor*expert*mode andzto delete any trace of[GPT](https://en.wikipedia.org/wiki/GUID_Partition_Table)in the disk\. Do this for all the server[HardDisks](https://en.wikipedia.org/wiki/Hard_disk_drive)\. Advertencia **BEWARE:**This step will**DESTROY**the content of your remote[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive)\. Be sure that is what you want\. 6. Overwrite the[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive)with the[image](https://en.wikipedia.org/wiki/Optical_disc_image)\. For instance, do something like this: ``` root@RESCUE:~# xzcat dump_SmartOS_10GB_20250124T134639Z_pass_jcea2025.xz | \ dd of=/dev/sda bs=65536 status=progress root@RESCUE:~# partprobe ``` Notice that this command expand the[image](https://en.wikipedia.org/wiki/Optical_disc_image)directly over the[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive), you don't need to decompress first\. that is nice because it is faster and you could run out of[RAM](https://en.wikipedia.org/wiki/Random-access_memory)in you**rescue**[ramdisk](https://en.wikipedia.org/wiki/RAM_drive)\. Advertencia **BEWARE:**This step will**DESTROY**the content of your remote[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive)\. Be sure that is what you want\. 7. My reference datacencer[Linux](https://en.wikipedia.org/wiki/Linux)**rescue**system doesn't have[ZFS](https://en.wikipedia.org/wiki/ZFS)preinstalled, but it installs it at first use: ``` root@RESCUE:~# zpool The Hetzner Rescue System does not come with preinstalled ZFS support, however, we will attempt to compile and install the latest release for you. Please read the information below thoroughly before entering any response. ATTENTION This script will attempt to install the current OpenZFS release which is available in the OpenZFS git repository to the Rescue System. If this script fails, do not contact Hetzner Support, as it is provided AS-IS and Hetzner will not support the installation or usage of OpenZFS due to License incompatiblity (see below). Due to github.com limitations, this script only works via IPv4. Licenses of OpenZFS and Linux are incompatible OpenZFS is licensed under the Common Development and Distribution License (CDDL), and the Linux kernel is licensed under the GNU General Public License Version 2 (GPL-2). While both are free open source licenses they are restrictive licenses. The combination of them causes problems because it prevents using pieces of code exclusively available under one license with pieces of code exclusively available under the other in the same binary. Please be aware that distributing of the binaries may lead to infringing. Press y to accept this. ``` Pressyand wait a few minutes\. 8. If you already have[ZFS](https://en.wikipedia.org/wiki/ZFS)available, import the[zpool](https://en.wikipedia.org/wiki/ZFS)you just wrote on your[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive): ``` root@RESCUE:~# zpool import zones -f -R /mnt ``` Nota Remember to use the**root**option:\-Rwhen you import the[zpool](https://en.wikipedia.org/wiki/ZFS)\. 1. Be sure theashiftof the[zpool](https://en.wikipedia.org/wiki/ZFS)is 12 \(4096 bytes\): ``` root@RESCUE:~# zpool get ashift zones NAME PROPERTY VALUE SOURCE zones ashift 12 local ``` 2. Check the zpool: ``` root@RESCUE:~# zpool list NAME SIZE ALLOC FREE CKPOINT EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT zones 9.50G 1.57G 7.93G - 3.63T 0% 16% 1.00x ONLINE /mnt root@RESCUE:~# zpool status pool: zones state: ONLINE status: Some supported and requested features are not enabled on the pool. The pool can still be used, but some features are unavailable. action: Enable all features using 'zpool upgrade'. Once this is done, the pool may no longer be accessible by software that does not support the features. See zpool-features(7) for details. config: NAME STATE READ WRITE CKSUM zones ONLINE 0 0 0 sda ONLINE 0 0 0 errors: No known data errors ``` 3. All the[SmartOS](https://en.wikipedia.org/wiki/SmartOS)[hypervisor](https://en.wikipedia.org/wiki/Hypervisor)configuration resides inzones/usbkey[dataset](https://en.wikipedia.org/wiki/ZFS)\. This[dataset](https://en.wikipedia.org/wiki/ZFS)is tagged aslegacyin the[zpool](https://en.wikipedia.org/wiki/ZFS)by[SmartOS](https://en.wikipedia.org/wiki/SmartOS), so was not automatically mounted\. You must do it by hand: ``` root@RESCUE:~# mkdir /tmp/x root@RESCUE:~# mount -t zfs zones/usbkey /tmp/x root@RESCUE:~# cd /tmp/x root@RESCUE:/tmp/x# ``` 4. Configure there the fileconfigwith the necessary details, IPs,[NIC](https://en.wikipedia.org/wiki/Network_interface_controller)[MAC address](https://en.wikipedia.org/wiki/MAC_address), netmasks, hostname, default gateway, dns domain, and so on\. You can get those details from the**rescue**[Linux](https://en.wikipedia.org/wiki/Linux)\. You need to know how to configure[SmartOS](https://en.wikipedia.org/wiki/SmartOS)hypervisor\. Check, for instance: - [Persistent Configuration for the Global Zone](https://docs.smartos.org/persistent-configuration-for-the-global-zone/)\. - [Extra Configuration Options](https://docs.smartos.org/extra-configuration-options/)\. You can add a[SSH](https://en.wikipedia.org/wiki/Secure_Shell)public key in that directory, and you can provide a newshadowfile with a new password for**root**\. Pay attention to the edits you do\. If you make a mistake,[SmartOS](https://en.wikipedia.org/wiki/SmartOS)will not boot\. 5. When done, reboot\! ## [3 First SmartOS boot\!](https://blog.jcea.es/posts/20250209-install_SmartOS.html#id3) 1. First thing you**MUST**do when first booting is to change the**root**password and do that change persistent\. This is not trivial because[SmartOS](https://en.wikipedia.org/wiki/SmartOS)[hypervisor](https://en.wikipedia.org/wiki/Hypervisor)is inmutable\. You can see the necessary steps \(and why they are needed\) in[Changing the Root Password in the Global Zone](https://docs.smartos.org/changing-the-root-password-in-the-global-zone/)\. Log into your new[SmartOS](https://en.wikipedia.org/wiki/SmartOS)machine and do: ``` [root@xXx ~]# umount /etc/shadow [root@xXx ~]# cp /usbkey/shadow /etc/shadow [root@xXx ~]# passwd root New Password: Re-enter new Password: passwd: password successfully changed for root [root@xXx ~]# cp /etc/shadow /usbkey/shadow ``` 2. Expand the[zpool](https://en.wikipedia.org/wiki/ZFS), currently 10 GB in size, to the entire[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive): ``` [root@xXx ~]# zpool online -e zones c1t0d0 [root@xXx ~]# zpool list NAME SIZE ALLOC FREE CKPOINT EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT zones 3,64T 4,58G 3,63T - - 0% 0% 1.00x ONLINE - ``` 3. Add the[mirror](https://en.wikipedia.org/wiki/Disk_mirroring)[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive): ``` [root@xXx ~]# zpool attach zones c1t0d0 c1t1d0 Make sure to wait until resilver is done before rebooting. ``` There is almost no data yet, so the[ZFS](https://en.wikipedia.org/wiki/ZFS)resilvering is fast: ``` [root@xXx ~]# zpool status pool: zones state: ONLINE scan: resilvered 4,58G in 0 days 00:00:29 with 0 errors on Mon Feb 10 08:38:07 2025 config: NAME STATE READ WRITE CKSUM zones ONLINE 0 0 0 mirror-0 ONLINE 0 0 0 c1t0d0 ONLINE 0 0 0 c1t1d0 ONLINE 0 0 0 errors: No known data errors ``` 4. Be sure we can boot from the[mirror](https://en.wikipedia.org/wiki/Disk_mirroring)[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive), just in case: ``` [root@xXx ~]# piadm bootable -r zones ``` 5. If the[SmartOS](https://en.wikipedia.org/wiki/SmartOS)[image](https://en.wikipedia.org/wiki/Optical_disc_image)you are using is old, consider updating the installed[SmartOS](https://en.wikipedia.org/wiki/SmartOS)[hypervisor](https://en.wikipedia.org/wiki/Hypervisor)usingpiadm\. 6. When you are done messing with the configuration, reboot just to be sure you are golden and enjoy your new[SmartOS](https://en.wikipedia.org/wiki/SmartOS)machine\! ## [4 Things to consider](https://blog.jcea.es/posts/20250209-install_SmartOS.html#id4) 1. You can retrieve the configuration details of your remote machine and edit the[SmartOS](https://en.wikipedia.org/wiki/SmartOS)[virtual machine](https://en.wikipedia.org/wiki/Virtual_machine)in[VirtualBox](https://en.wikipedia.org/wiki/VirtualBox)\. The new configuration will not correctly boot in thevirtual machinebut, if you did everything correct, I should boot when copied over the target remote machine[HardDisk](https://en.wikipedia.org/wiki/Hard_disk_drive)\. In this case: you must size the[ZFS](https://en.wikipedia.org/wiki/ZFS)[zpool](https://en.wikipedia.org/wiki/ZFS)bigger, at least 10GB plus[RAM](https://en.wikipedia.org/wiki/Random-access_memory)size of the real machine\. dump 2. You will most probably want to expand the[swap](https://en.wikipedia.org/wiki/Memory_paging)space\. You can follow instructions in Spanish at[Cómo cambiar el tamaño del espacio de intercambio \(SWAP\) en SmartOS](https://blog.jcea.es/posts/20230112-resize_swap_SmartOS.html)\. 3. Remember to change the[SmartOS](https://en.wikipedia.org/wiki/SmartOS)default**"root"**password I provided in the[image](https://en.wikipedia.org/wiki/Optical_disc_image)\!\.