Upon completing the Initial Rack Setup steps, the control plane services, including the web console, should be up and running.
In this final part of rack setup, you will configure the external IP addresses to be used by instances, create a new silo, and set up someone as the silo administrator with or without an identity provider (IdP).
Prerequisites
Before beginning rack configuration, confirm that the following are ready:
| Item | Status |
|---|---|
Initial Rack Setup completed — rack status shows "Initialized" | ☐ |
Recovery silo DNS resolves ( | ☐ |
External IP address range(s) allocated for VM instances | ☐ |
Silo name chosen (lowercase letters, numbers, dashes only) | ☐ |
TLS certificate ready for new silo (or wildcard cert covering | ☐ |
Identity provider configured (if using SAML SSO) — see Identity Providers guide | ☐ |
IdP admin group identified and your user account added to that group | ☐ |
Test VM image ready for acceptance testing (RAW or ISO format) | ☐ |
SSH key pair ready for VM access | ☐ |
Network team available if connectivity issues arise | ☐ |
If any of these items are not ready, complete the preparation before proceeding.
Log into Web Console
In your web browser, log into the Oxide Console with the username recovery at https://recovery.sys.$oxideDomainName and the password specified during the initial rack setup process.
The silo in use here is meant for first-time setup and recovery purposes. In the steps below, we’ll create another silo and grant its administrators fleet access so that these users can manage system-level configurations without logging in as the recovery user again.
Create Device Token (required for CLI only)
Follow the instructions in the CLI guide to create a device token. This token is linked to the recovery user and should only be used for managing rack setup.
Create Silo
First, navigate to the System menu using the dropdown at the top right-hand corner of the web console (next to user name). On the Silos menu, click New Silo.
The following information is required when creating a silo:
| attribute | value | ||||||||
|---|---|---|---|---|---|---|---|---|---|
name | Must start with a letter and contain only lower-case letters, numbers, and dashes. | ||||||||
description | A brief description of the silo. | ||||||||
discoverable | Whether the silo should be included in silo listing queries (non-discoverable silos are accessible only by direct name or id reference). | ||||||||
identity_mode | There are two options:
| ||||||||
admin_group_name | Required if using | ||||||||
mapped_fleet_roles | Optional mappings of fleet-level roles conferred by silo roles, applicable to the | ||||||||
quotas | Compute and storage resource limits.
| ||||||||
tls_certificates | Initial TLS certificates to be used for the new Silo’s console and API endpoints; should be valid for the Silo’s DNS name which follows the convention
|
Follow the create silo instructions in one of the integration examples in the Identity Providers guide that matches more closely with the SAML provider you have.
Create silo using the CLI
oxide silo create --json-body silo.json
Here are some examples of the silo.json request payload based on its identity_mode:
# identity_mode = saml_jit
# the mapped_fleet_roles enables silo admin group members to act as fleet admin
{
"name": "$siloName",
"description": "$siloDescription",
"discoverable": true,
"identity_mode": "saml_jit",
"admin_group_name": "$idpAdminGroup",
"mapped_fleet_roles": {
"admin": [
"admin"
]
},
"quotas": {
"cpus": 18,
"memory": 8589934592,
"storage": 107374182400
},
"tls_certificates": [{
"name": "initial-install-cert",
"description": "wildcard certificate",
"service": "external_api",
"cert": "$fullCertChainPemBlob",
"key": "$privateKeyPemBlob"
}]
}# identity_mode = local_user
{
"name": "$siloName",
"description": "$siloDescription",
"discoverable": true,
"identity_mode": "local_only",
"quotas": {
"cpus": 18,
"memory": 8589934592,
"storage": 107374182400
},
"tls_certificates": [{
"name": "initial-install-cert",
"description": "wildcard certificate",
"service": "external_api",
"cert": "$fullCertChainPemBlob",
"key": "$privateKeyPemBlob"
}]
}Identity Provider Preparation
Before configuring the identity provider in the Oxide Console, ensure you have gathered the following from your IdP (Okta, Google Workspace, Keycloak, Azure AD, etc.).
| What to Gather | Where to Find It | Oxide Field |
|---|---|---|
Application/client ID | IdP application settings |
|
SAML metadata XML or URL | IdP SAML configuration or metadata endpoint |
|
Entity ID / Issuer URL | IdP application settings |
|
Group attribute name | IdP SAML attribute mapping |
|
Admin group name | IdP group/role configuration | Silo |
Configure in your IdP before proceeding:
Create an application/service provider entry for Oxide
Set the ACS (Assertion Consumer Service) URL to:
https://$siloName.sys.$oxideDomainName/login/$siloName/saml/$idpNameConfigure the SAML response to include a group attribute listing the user’s groups
Ensure your admin user account is a member of the admin group
If providing metadata via URL, confirm the endpoint is accessible from the rack’s service network (not blocked by firewall)
Configure Silo Identity Provider
Perform this step if your silo uses SAML for authentication.
The following attributes are required when configuring an identity provider:
| attribute | value | ||||||
|---|---|---|---|---|---|---|---|
name | A short name of the silo’s IdP SAML configuration (the name will be used in the login URL path, see the example under ACS URL). For ease of tracking, this can be set to the same value as the application or service provider identifier in the IdP, but it is not required. | ||||||
description | A brief description of the SAML configuration in the identity provider. | ||||||
idp_metadata_source | Base64 encoded XML of identity provider SAML descriptor; the source can be specified as XML data or a URL for retrieving the metadata. If the URL is used, the rack service must have anonymous access to the endpoint.
| ||||||
idp_entity_id | IdP SAML issuer ID or client root URL. Examples: | ||||||
sp_client_id | The IdP ID that uniquely identifies the Oxide client; it may be labeled as service provider, application, audience, and so on. | ||||||
acs_url | The Oxide Console login endpoint registered with the identity provider for responses and assertions. It follows the naming convention https://$siloName.sys.$oxideDomainName/login/$siloName/saml/$providerName.
For example, if the silo name is
| ||||||
slo_url | Single logout endpoint, may be set to the same value as ACS URL (i.e., taking users back to the Oxide Console login page). | ||||||
technical_contact_email | Email address of identity provider support contact (Note: Oxide rack does not generate email notifications at this time). | ||||||
signing_keypair | (Optional) Used by the client for signing the login request, in the form of base64-encoded DER files.
| ||||||
group_attribute_name | The custom attribute in the SAML access token response that represents the user’s group memberships. The information will be used to create user groups and assign the user to them (required for JIT user provisioning). |
To set up an identity provider for the new silo, click New Provider on the Identity Providers tab.
Create identity provider using the CLI
Execute one of the following commands depending on how you want to specify the IdP metadata
oxide silo idp saml create --silo $siloName --json-body idp.json --metadata-value $base64EncodedMetadataXml
or
oxide silo idp saml create --silo $siloName --json-body idp.json --metadata-url $idpMetadataUrl
Here is a sample request payload of the idp.json file for a silo named "corp" on the delegated domain "oxide.acme.com" with a Google SAML provider.
{
"name": "google",
"description": "Corporate silo google SAML provider",
"idp_entity_id": "https://accounts.google.com/o/saml2?idpid=D12wdrk34",
"sp_client_id": "corp",
"idp_metadata_source": {
"type": "base64_encoded_xml",
"data": ""
},
"acs_url": "https://corp.sys.oxide.acme.com/login/corp/saml/google",
"slo_url": "https://corp.sys.oxide.acme.com/login/corp/saml/google",
"technical_contact_email": "infra@acme.com",
"signing_keypair": {
"public_cert": "$base64EncodedDer",
"private_key": "$base64EncodedDer"
},
"group_attribute_name": "admins"
}recovery silo to delete the silo and recreate it with the correct configuration.Test User Login
On a separate browser tab or window, log into the newly created silo at https://$siloName.sys.$oxideDomainName, either as yourself via the identity provider or as the local administrator using password authentication.
In the case of IdP integration, if the admin group attributes are configured correctly, your account should be imported into the rack with the silo "admin" role automatically granted. You can confirm your group assignments in the Profile page under Settings.
admin_group_name of the silo.If login fails:
| Issue | Solution |
|---|---|
Cannot reach the silo URL (timeout) | Verify DNS resolution works ( |
TLS certificate error | Verify that that the cert SAN covers |
"Invalid credentials" (local auth) | Reset password via recovery silo; verify user was created successfully |
SAML login redirects but fails with "unauthorized" | Check that your IdP account is in the admin group; verify |
SAML login fails with "invalid ACS URL" | Verify ACS URL format: |
Login succeeds but user has no groups/roles | Check IdP SAML response includes group attribute; verify |
When to contact Oxide Support:
Login fails with errors not listed above
SAML configuration appears correct but authentication consistently fails
User successfully authenticates but cannot access any resources despite correct group membership
Set silo resource quotas
Virtual compute and storage resources such as vCPUs are shared among users of different silos. For this first silo setup, you can configure the limits to what is required for initial usage and modify them later as needed.
Setting silo quotas using the CLI
oxide silo quotas update \ --silo $siloName \ --cpus $vcpuCount \ --memory $memoryBytes \ --storage $storageBytes
Create and configure IP Pool
IP pools are groups of addresses used for managing instance external IP address allocation. Each silo may have one or more IP pools associated with it, with one designated as the default pool. When an ephemeral or floating IP is provisioned, an address will be automatically assigned from the IP pool specified in the request, or the default pool if it is unspecified.
Follow these steps to create your first IP pool and link it to the new silo:
Locate the IP Pools menu under System, click New IP Pool.
Add one or more IP ranges to this new IP pool. The IP ranges can be discrete start/end IP addresses and do not need to be CIDR blocks.
Navigate back to Silos and click on the name of the silo created earlier.
On the IP Pools tab, click Link Pool and add the IP pool created above.
Click the three dots in the right-most column of the IP pool table and select Make default.
Create IP pool using the CLI
# create the IP pool oxide system networking ip-pool create --name $poolName --description $poolDescription # insert an address range into the new IP pool oxide system networking ip-pool range add --pool $poolName --first $firstIpInRange --last $lastIpInRange # link the pool to your new silo and make it the default oxide system networking ip-pool silo link --pool $poolName --silo $siloName --is-default true
Additional context and considerations about IP pools can be found in the Network Preparations and IP Pools guides.
Post-Configuration Validation
After completing silo and IP pool setup, walk through the following checks to confirm the rack is fully operational.
1. Verify Layer 3 Connectivity
Before testing higher-level services, confirm basic network connectivity to the rack.
From a workstation on the broader network:
# Verify you can reach the rack's uplink gateway
ping <rack_gateway_ip>
# Check if uplink ports are passing traffic (from a switch connected to the rack)
# Look for non-zero TX/RX counters on the uplink portsIf ping fails:
Verify upstream routing is configured to direct traffic to the rack’s gateway IP
Check that uplink fiber connections are active (LEDs lit on transceivers)
Confirm upstream switch ports have the correct VLAN and routing configuration
Review firewall rules between your workstation’s network and the rack uplinks
If you can ping the gateway but can’t reach rack services:
Check that BGP peering is established (if using BGP):
bgp summaryon upstream routersVerify static routes are configured correctly (if using static routing)
Confirm the rack’s external IP pools are routable from the broader network
2. Verify DNS Resolution
From a workstation on the broader network:
# Verify the recovery silo resolves
dig recovery.sys.<your_domain>
# Verify your new silo resolves
dig <silo_name>.sys.<your_domain>Both should return A records pointing to addresses in your services IP pool. If resolution fails, check:
NS delegation records in your upstream DNS
Firewall rules allowing UDP port 53 to/from the rack’s external DNS IPs
3. Verify Web Console Access
Open a browser and navigate to https://$siloName.sys.$domain. You should see the Oxide Console login page. If the page times out:
Verify the TLS certificate is valid for this hostname.
Confirm firewall allows HTTPS (TCP 443) from your workstation to the services IP pool.
Check that the DNS A record points to a reachable Oxide API address.
If you see a TLS certificate error, verify the certificate SAN covers *.sys.$domain and the full chain is uploaded.
4. Verify IdP Login
Log in via your identity provider. After successful authentication:
Confirm you land on the Oxide Console projects page
Navigate to Settings > Profile and verify your group memberships include the admin group
If login fails, check the ACS URL format, group attribute mapping, and that your account is in the admin group in the IdP
5. Deploy a Test VM
This validates end-to-end compute, storage, networking, and external connectivity.
Prepare: You will need a Linux VM image (RAW or ISO format) and an SSH key pair.
Upload an image: Navigate to a project, go to Images, and upload your Linux image.
If you have a qcow2 image, convert it first:
qemu-img convert -f qcow2 -O raw input.qcow2 output.rawAdd an SSH key: Go to Settings > SSH Keys and add your public key.
Create an instance: Go to Instances > New Instance.
Select your uploaded image as the boot disk.
Choose a small size (e.g., 2 vCPUs, 4 GiB RAM).
Confirm the default VPC and subnet are selected.
Ensure your SSH key is checked.
Click Create Instance.
Verify connectivity:
# Find the instance's external IP in the Console (Instances > your instance > Networking)
ssh <user>@<instance_external_ip>Once logged in, verify:
Outbound connectivity:
curl -I https://example.comDNS resolution:
dig oxide.computerPackage installation:
apt update(or equivalent)
Clean up: Stop and delete the test instance when satisfied.
5. Verify BGP (if applicable)
If using BGP, verify from your upstream router:
BGP sessions are established with both Oxide switches.
The rack is announcing the expected prefixes.
Routes to the rack’s service and instance IP pools are present in the routing table.
What’s Next
Congratulations! Your Oxide rack is now fully operational.
Operator next steps:
Document your specific configuration (IP ranges, DNS delegation, IdP settings) for future reference.
Save the recovery silo credentials in a credentials vault for emergency access.
Share silo access with your team members by adding them to the admin group in your IdP platform.
Review the Operator Guides for ongoing rack management (see Silo Management, Hardware Maintenance, and IP Pool Management)
Set up additional silos for different teams or environments.
Configure additional IP pools as needed.
Review monitoring and alerting setup.
For issues or questions, contact Oxide Support.
For developers and users:
Share the User Guides with application teams.
Point them to the API documentation for automation.
Install the Oxide CLI for command-line workflows.