How to Install Sun Ray Server SRSS on OpenIndiana Hipster 2025.10

How-To Guide·May 23, 2026·13 min read

Prerequisites & What You'll Need

Before you touch a single command, make sure you have everything assembled. Missing any one of these will cost you hours of debugging — trust me, the people who've emailed me for help have almost always skipped something in this list.

[ ] Proxmox VE 9.0 or later — earlier versions may lack the "Solaris Kernel" guest OS type
[ ] OpenIndiana Hipster 2025.10 Live DVD ISO — filename: OI-hipster-gui-20251026.iso, downloaded from the official OpenIndiana downloads page
[ ] SRSS 5.4.0.0 ZIP — filename: V37038-01.zip (Sun Ray Server Software for Solaris 11 i386). See Oracle eDelivery or archive.org
[ ] Oracle eDelivery account — free to create at edelivery.oracle.com; you must accept the license agreement before downloading
[ ] VM with minimum specs: 4 CPU cores (host model), 8 GB RAM, 60 GB disk, VirtIO network
[ ] Outbound internet access from the VM for pkg update and IPS publisher syncs

Required Hardware or VM Specs (Proxmox PVE 9.x Recommended)

Running this on bare metal is possible, but a Proxmox VM gives you snapshots — invaluable when you inevitably need to roll back after a botched pkg update. Here's the exact spec table:

| Component | Minimum | Recommended | Notes | |-----------|---------|-------------|-------| | CPU cores | 2 | 4 | Must expose host CPU model for AES-NI and other extensions | | RAM | 8 GB | 16 GB | SRSS Java services are memory-hungry | | Disk | 60 GB | 120 GB | VirtIO Block, write-back cache, discard on | | Network | 1 NIC | 2 NICs | VirtIO paravirtualized; second NIC for Sun Ray VLAN optional | | Machine type | q35 | q35 | Required for vIOMMU support | | Firmware | SeaBIOS | SeaBIOS | Do NOT use OVMF/UEFI — illumos loader behaves differently | | GPU | Standard VGA | Standard VGA | QXL causes installer hangs on OI |

Software Downloads: OI Hipster 2025.10 ISO and SRSS 5.4.0.0 ZIP

Get OI-hipster-gui-20251026.iso directly from openindiana.org. For V37038-01.zip, log into edelivery.oracle.com, search for "Sun Ray Server Software", and look under the Solaris 11 x86 family. If it's not listed in your account, several archive.org collections contain the file — search for V37038-01.zip directly.

Oracle eDelivery Account and Finding V37038-01.zip

Critical: SRSS 5.4.5.0 for i386 is not reliably available on Oracle eDelivery. The only confirmed 5.4.5.0 copy floating around is SPARC-only. Use V37038-01.zip (version 5.4.0.0) — this is what the OpenIndiana IPS packaging was tested against. If you somehow find a genuine 5.4.5.0 i386 build, it's worth trying, but don't spend more than 30 minutes hunting for it.

Estimated time: 3–4 hours (including downloads, VM setup, and first full pkg update)

Step 1 — Configure Your Proxmox VM Correctly

The VM configuration is where most people fail silently. Wrong machine type or missing vIOMMU won't throw a helpful error — the VM will just hang at boot or produce mysterious SMF failures later during SRSS startup.

Guest OS Type, Machine Type, and SeaBIOS Settings

In the Proxmox web UI, when creating the VM: set Guest OS to Solaris Kernel. Set Machine to q35 and Firmware to SeaBIOS. Do not use OVMF. The q35 chipset is required because it supports PCIe and the vIOMMU feature we'll enable next.

Adding VirtIO RNG Device and Enabling vIOMMU

After the VM is created but before you start it, go to the Hardware tab and:

Add a VirtIO RNG device — SRSS's cryptographic subsystem will starve /dev/random without it, causing utconfig to hang indefinitely.
Edit the Machine entry, check Advanced, and set IOMMU to vIOMMU. This is required for Sun Ray's USB redirection and certain device pass-through features to initialize correctly in the SMF service chain.

Disk, CPU, Network, and Graphics Settings That Actually Work

Here's what your resulting qm.conf should look like (replace <vmid> with your actual VM ID):

# /etc/pve/qemu-server/<vmid>.conf
agent: 1
bios: seabios
cores: 4
cpu: host
iommu: virtio
kvm: 1
machine: q35
memory: 8192
name: openindiana-sunray
net0: virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,firewall=0
numa: 0
ostype: solaris
rng0: source=/dev/urandom,max_bytes=1024,period=1000
scsihw: virtio-scsi-pci
sockets: 1
vga: std
virtio0: local-lvm:vm-<vmid>-disk-0,cache=writeback,discard=on,size=60G

Why each setting matters:

cpu: host — exposes actual CPU flags to the guest; without it, illumos may disable hardware acceleration and utconfig crypto checks fail
machine: q35 — PCIe topology required for iommu: virtio
bios: seabios — OVMF adds EFI variables illumos doesn't expect, causing boot menu loop
vga: std — Standard VGA; QXL triggers a known OI installer hang
rng0 — prevents /dev/random entropy starvation
cache=writeback on virtio0 — significantly improves IPS package extraction speed during pkg update
iommu: virtio — enables vIOMMU for Sun Ray device subsystem initialization

Step 2 — Install OpenIndiana Hipster 2025.10

The OI installer is straightforward, but it has a few quirks that will confuse you if you're not expecting them.

Booting the Live DVD and Running the GUI Installer

Boot the VM from the ISO. Once the live desktop loads, double-click the Install OpenIndiana shortcut on the desktop. The text installer also works, but the GUI installer handles ZFS pool configuration more transparently. Follow the prompts: select your VirtIO disk (c1d0 or similar), choose ZFS, accept the default swap sizing, and set your hostname and user account.

Handling Installer Error Dialogs and Screen Lock (live user password: jack)

Don't panic if one or two error dialog boxes pop up shortly after the installer starts copying files. This is a known cosmetic issue — click through them and the install continues normally. If you walk away and the screen locks, the live session password is jack. Write that down now.

Note: The installer takes 15–25 minutes depending on your storage speed. Don't interrupt it even if progress looks stalled — the ZFS pool creation step has a long quiet period.

First Boot: Fixing the Broken Terminal Color Profile

After the first reboot, log in as your unprivileged user (not root). Open a terminal — it will appear blank because the default profile renders black text on a black background.

Fix it immediately: Edit menu → Profile Preferences → Colors tab → uncheck "Use colors from system theme". Select a readable color scheme ("White on Black" works well). Do this before running any commands or you'll be flying blind.

Once you can see text, get a root shell:

sudo -i

Step 3 — Update OI and Enable the Encumbered Repository

Skipping this step is the single most common cause of SRSS installation failure. Don't skip it.

Why You Must Update Before Installing SRSS

The SRSS IPS packages have dependencies on specific versions of illumos libraries. If your base system is the version that shipped on the ISO (which is always slightly behind), you'll hit package conflicts, missing SMF manifests that utconfig expects, and in some cases a broken libdladm version that causes svc:/application/sun-ray/core to fail immediately on first enable. Update first, always.

Enabling hipster-encumbered Publisher

The hipster-encumbered repository contains media codecs and other packages with redistribution restrictions that Oracle/Sun software often depends on. Enable it before refreshing:

pkg set-publisher -g https://pkg.openindiana.org/hipster-encumbered/ hipster-encumbered
pkg refresh

Running pkg update and Rebooting if Needed

pkg update

This will pull a significant number of updates — budget 20–40 minutes depending on your connection. When it completes, check whether a reboot is required:

pkg list -u | grep 'reboot-needed'

If the update touched the kernel or boot archive, reboot before proceeding:

init 6

Note: If pkg update exits with Nothing to update, your ISO was already current — this is unusual but possible. You can proceed, but double-check that hipster-encumbered is showing as online with pkg publisher.

Step 4 — Install sunray-essential and Extract SRSS Packages

Now that the system is fully current, you can install the IPS framework packages and the SRSS software itself.

Installing the sunray-essential IPS Package

The sunray-essential metapackage pulls in runtime dependencies that SRSS needs: Java, specific X11 libraries, and SMF manifest scaffolding. Installing it first prevents a messy dependency resolution fight when you add the SRSS IPS publisher:

pkg install sunray-essential

This should complete without conflicts on a freshly updated system. If you see dependency errors here, go back and re-run pkg update — something wasn't fully applied.

Extracting V37038-01.zip with bsdtar

Copy V37038-01.zip to the VM (via scp, Proxmox file transfer, or however you prefer). Then extract it:

bsdtar -C /root -xf V37038-01.zip

Use bsdtar rather than unzip — the SRSS archive uses features that unzip handles poorly on illumos. The extraction will create the directory /root/srs_5.4.0.0-Solaris_11plus.i386/.

Registering the Local SRSS IPS Publisher and Installing SUNWut Packages

Point IPS at the extracted local repository, then install the core SRSS packages:

pkg set-publisher -g /root/srs_5.4.0.0-Solaris_11plus.i386/IPS.i386/ sunray
pkg install SUNWut-srss SUNWut-srwc

Note: The exact IPS repo path is /root/srs_5.4.0.0-Solaris_11plus.i386/IPS.i386/ — note the trailing slash and the IPS.i386 subdirectory. If you point IPS at the parent directory, it will return "no packages found" with no useful error message.

SUNWut-srss is the core Sun Ray Server Software. SUNWut-srwc is the Sun Ray Web Console component. Both are required for a functional server.

Step 5 — Resolve Manual Dependencies and Finish SRSS Configuration

The IPS solver won't automatically pull in every dependency SRSS needs on OpenIndiana. This is the step the OI Handbook glosses over, and where most email requests for help have come from.

Identifying Missing Dependencies Not Pulled in Automatically

After installing SUNWut-srss and SUNWut-srwc, check for any broken dependencies:

pkg verify SUNWut-srss SUNWut-srwc 2>&1 | grep -i 'missing\|error'

Also check for missing shared libraries that SRSS binaries reference:

ldd /opt/SUNWut/lib/utauthd | grep 'not found'
ldd /opt/SUNWut/sbin/utconfig | grep 'not found'

Manually Installing Required Packages or Libraries

The most commonly missing packages on a fresh OI 2025.10 install are library/libtecla and system/library/security/gss. Install them explicitly:

pkg install library/libtecla system/library/security/gss

If ldd reports a missing libdbus or libglib variant, install:

pkg install library/glib2 system/library/dbus

For any library that IPS can't provide (rare, but happens with very old SRSS-bundled .so files), you can place it manually and update the runtime linker cache:

# Example if a bundled library is missing from /opt/SUNWut/lib:
cp /path/to/missing.so.1 /opt/SUNWut/lib/
crle -l /opt/SUNWut/lib -u

Deviation from OI Handbook: The Handbook assumes these packages are already present. On a minimal OI install, they frequently are not. Always run the ldd checks above before invoking utconfig.

Running the SRSS Configuration Script (utconfig)

With dependencies satisfied, run the SRSS configuration script:

/opt/SUNWut/sbin/utconfig -x

The -x flag enables configuration of the Sun Ray Data Store (an LDAP directory instance SRSS uses internally). You'll be prompted for: the Sun Ray server group name (use your hostname if you're running standalone), admin password for the data store, and network interface selection. Choose the VirtIO interface (net0 or vioif0 depending on driver naming).

After utconfig completes, enable the services:

svcadm enable -r svc:/application/sun-ray/core
svcadm enable -r svc:/application/sun-ray/webserver

Common Issues & Fixes

Error: svc:/application/sun-ray/core enters maintenance state immediately after enable

Cause: A missing library or failed utconfig step left the SMF service with no valid method script path.

# Read the full failure reason:
svcs -xv svc:/application/sun-ray/core

# Tail the SMF log to see the actual error:
tail -100 $(svcs -L svc:/application/sun-ray/core)

# After fixing the underlying issue (see ldd checks in Step 5):
svcadm clear svc:/application/sun-ray/core
svcadm enable svc:/application/sun-ray/core

# Confirm it's online:
svcs svc:/application/sun-ray/core

Error: Sun Ray clients get no DHCP/multicast response and never connect

Cause: The Sun Ray server's firmware discovery service uses multicast, which is blocked by default on VirtIO interfaces in Proxmox when the bridge has bridge-vlan-aware yes set.

Fix: On the Proxmox host, either disable VLAN awareness on the bridge used by the Sun Ray VM, or add the Sun Ray multicast groups explicitly. Also verify svc:/network/sun-ray-dhcp-proxy is running inside OI:

svcs -a | grep sunray
# If dhcp-proxy is offline:
svcadm enable svc:/network/sun-ray-dhcp-proxy

Error: VM hangs at Grub or early boot after first OI install

Cause: Wrong machine type or firmware selected in Proxmox — most commonly OVMF (UEFI) instead of SeaBIOS, or i440fx machine type instead of q35.

Fix: Shut down the VM. In Proxmox, go to Hardware → Machine and verify q35 is set. Check that Firmware shows SeaBIOS. If you created the VM with OVMF, you'll need to recreate it — there's no clean in-place switch between OVMF and SeaBIOS for an already-installed guest.

Symptom → Root Cause → Fix Reference Table

| Symptom | Root Cause | Fix | |---------|-----------|-----| | pkg install SUNWut-srss fails with constraint errors | Base system not updated before adding sunray publisher | Run pkg update, reboot, retry | | utconfig hangs indefinitely at crypto init | Missing VirtIO RNG device; /dev/random entropy starved | Shut down VM, add RNG device, restart | | Terminal shows blank/black text | Default GNOME Terminal color profile bug in OI | Edit → Profile Preferences → Colors → uncheck system theme | | svcs -xv shows libdbus.so.1 not found | system/library/dbus not installed | pkg install system/library/dbus | | Sun Ray client loops at firmware download | Multicast blocked on Proxmox bridge | Disable bridge VLAN awareness or allow multicast groups |

FAQ

Q: Can I use SRSS 5.4.5.0 instead of 5.4.0.0 on OpenIndiana?

In theory, yes — SRSS 5.4.5.0 contains bug fixes over 5.4.0.0 and should be compatible with the same IPS packaging structure. The practical problem is that the i386 (x86) build of 5.4.5.0 is not reliably available anywhere: Oracle eDelivery listings that claim to have it don't always deliver it, and the only confirmed 5.4.5.0 archive on archive.org is the SPARC version. Use 5.4.0.0 (V37038-01.zip) — it works, and it's findable. If you locate a genuine 5.4.5.0 i386 build, the install procedure in this guide should work unchanged.

Q: Does this setup work on bare metal, or only in a Proxmox VM?

Bare metal works fine — the software requirements are the same, and illumos/OI runs excellently on physical x86 hardware. The VM-specific configuration steps (machine type, vIOMMU, VirtIO RNG) won't apply; instead you'll need to verify that your physical hardware exposes an IOMMU (VT-d on Intel, AMD-Vi on AMD) and that /dev/random has adequate entropy sources. The SRSS installation and configuration steps from Step 3 onward are identical for bare metal and VM.

Q: Where can I find V37038-01.zip if Oracle eDelivery doesn't have it?

Archive.org is your best fallback — search for V37038-01.zip or Sun Ray Server Software 5.4.0.0 Solaris 11. Several community-preserved collections exist there. Alternatively, search for sun-ray-server-software-5.4 on software archival communities. Oracle has not officially open-sourced SRSS, so sources outside eDelivery are gray-area at best — use your own judgment on licensing compliance for your use case.

Recommended Tools

DigitalOceanCloud hosting built for developers — $200 free credit for new users
DockerDevelop faster. Run anywhere.