Silos

Silos are the top-level containers for users, projects, and resources, ensuring strict tenancy separation. Users can only see resources in their own silo. Each silo has its own resource limits and access policies as well as its own subdomain for the web console and API. You can choose to set up one or multiple silos depending on your organization’s resource and access management policies.

Rack administrators and users are typically onboarded into silos via identity provider (IdP) integration. Silos can also be configured to have rack-local accounts, which authenticate with username and password and must be created manually by silo administrators.

Recovery silo

A special silo called recovery is created during rack setup. The silo hosts a system account which is also named recovery. This built-in account has the fleet admin role that allows the operator to create user-defined silos and grant the fleet admin privilege to other users. After the rack setup process, the recovery silo will only be used for rescue purposes such as remediating identity provider integration configuration problems.

Silos vs. Projects as Tenants

Both silos and projects can be used as the abstraction for tenants. While projects provide some separation between different application workloads, when the tenant is in an entirely different security domain (e.g., a subsidiary or a third-party company), it may be more appropriate to give them their own silo so they are fully isolated.

Preparations for Silo Setup

Generate a TLS Certificate

A TLS certificate is required during silo setup and will be used for TLS termination on the silo-specific UI/API DNS name. The certificate’s DNS SAN can either be the silo’s fully-qualified domain name (FQDN):

$SILO_NAME.sys.$OXIDE_DOMAIN_NAME

or a wildcard domain name:

*.sys.$OXIDE_DOMAIN_NAME

For production deployments, use a certificate from a trusted Certificate Authority (CA). For testing or development, a self-signed certificate may be sufficient.

Option 1: Using OpenSSL

For a quick, self-signed setup:

Create a directory for your certificate files:
```
mkdir ~/silo-certs
cd ~/silo-certs
```

Create an OpenSSL configuration file (san.cnf) with the required Subject Alternative Names (SANs). Replace silo1.sys.example.com with your silo’s actual FQDN:

san.cnf

[req]
default_bits  = 2048
distinguished_name = req_distinguished_name
req_extensions = req_ext
x509_extensions = v3_req
prompt = no
[req_distinguished_name]
countryName = US
stateOrProvinceName = N/A
localityName = N/A
organizationName = Self-signed certificate
commonName = silo1.sys.example.com
[req_ext]
subjectAltName = @alt_names
[v3_req]
subjectAltName = @alt_names
[alt_names]
DNS.1 = silo1.sys.example.com

Generate the self-signed certificate:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout key.pem -out cert.pem -config san.cnf

Verify the generated certificate:
```
openssl x509 -in cert.pem -text -noout
```

Option 2: Using Let’s Encrypt and Certbot

For deployments with a public domain and IP, Let’s Encrypt provides free TLS certificates. This requires that the domain is publicly accessible and that you can use either HTTP or DNS challenges, so this will not work for internal-only deployments.

Note

Certificates issued by Let’s Encrypt in this manner are intentionally short-lived, with a maximum lifetime of 90 days as of 2025, and an intended lifetime of 45 days by 2028. Plan for an automated renewal mechanism.

Certbot is a tool published by the EFF for obtaining and renewing TLS certificates using the ACME protocol. It is available for most major operating systems and can be installed via package manager, with detailed instructions available at Certbot Instructions.

It is possible to generate a certificate on a local machine using Certbot and then transfer it to the Oxide silo. This includes wildcard certificates, which can be useful for multiple silos under the same domain.

Install certbot:

sudo apt install certbot #Linux
brew install certbot # macOS

Obtain the certificate using the HTTP-01 challenge:

sudo certbot certonly --standalone -d silo1.sys.example.com

Note

Port 80 must be open and accessible in order for the HTTP challenge to succeed. If you have a web server running, you may need to stop it temporarily in order to obtain the certificate.

Alternatively, use the DNS-01 challenge if you control DNS:

sudo certbot certonly --manual --preferred-challenges dns -d silo1.sys.example.com

The certificates will be stored in /etc/letsencrypt/live/silo1.sys.example.com/. When using the certificate, reference the fullchain.pem and privkey.pem files in your Oxide silo configuration.

Preparing Client-Provided Signing Certificates

For some IdP integrations, operators may need to provide a client signing certificate for Oxide’s API or console authentication flows. This process involves different formatting requirements depending on the integration method:

For API or CLI IdP setup:

openssl x509 -in idp-cert.pem -outform der | base64 > idp-cert.base64
openssl rsa -in idp-key.pem -outform der -traditional | base64 > idp-key.base64

For Console IdP setup:

openssl x509 -in idp-cert.pem -outform der -out idp-cert.der
openssl rsa -in idp-key.pem -outform der -traditional -out idp-key.der

Configure Identity Provider

Oxide supports the use of SAML SSO authentication with third-party identity provider systems. User and group provisioning can be configured to be just-in-time (JIT) or synchronized real-time using SCIM 2.0 API. More information about the different types of authentication and authorization setup can be found in the Identity Providers guide.

Before setting up the IdP integration for a silo, you will need to identify the IdP group, role, or attribute to be used for governing memberships of the new silo and users who are designated as administrators.

Determine which IP pools to use

You may configure the new silo to have its own IP pools or use existing pools for external IP and multicast address assignment. If you choose to provide the silo with new IP pools, you will create the pools and allocate IP ranges to them prior to setting up the silo. If the new silo will be using existing pools, you may need to review the size of those IP pools and add capacity as needed.

You can find out more about IP pools in the IP Pools and Subnet Pools guide.

Setting up a Silo

The procedures for setting up new silos and identity provider integration are similar to those during rack initialization. Operators who have the fleet-admin role can use the Oxide Console, API, or CLI to create a new silo and configure its resource and integration settings.

Note

It is also possible to use IaC tooling such as Terraform to create silos and configure auth. Please refer to the Terraform Integration guide for additional information.

1. Create Silo and Upload TLS Certificate

The first step of silo setup is creating the silo record and importing a matching TLS certificate. Virtual resource quotas are required during silo creation, and can be modified afterwards.

See the Resource Management guide for additional information regarding capacity planning and managing quotas.

The following information is required when creating a silo:

attribute value

attribute	value
`name`	Must start with a letter and contain only lower-case letters, numbers, and dashes.
`description`	A brief description of the silo context and purpose.
`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 three identity modes, `saml_jit`, `saml_scim`, and `local_only`. See Authentication Configuration below for details on each.
`admin_group_name`	Required if using `saml_jit` or `saml_scim` identity modes; specifies which IdP group will be granted the Silo Admin role. The group is created in Oxide upon the first successful SAML login that includes this group attribute value.
`mapped_fleet_roles`	Optional mappings of fleet-level roles conferred by silo roles, applicable to the `saml_jit` and `saml_scim` modes only.
`quotas`	Compute and storage resource limits: `cpu`: Total number of virtual CPUs of all running instances. `memory`: Total number of bytes of all running instances' memory. `storage`: Total number of bytes of all disks provisioned, including snapshots.
`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 `$SILO_NAME.sys.$OXIDE_DOMAIN_NAME` or `*.sys.$OXIDE_DOMAIN_NAME` for a wildcard certificate: `name`: A short name of the certificate `description`: Certificate description (e.g., issuer, expiration date) `cert`: PEM-formatted string containing public certificate chain `key`: PEM-formatted string containing private key

name

Must start with a letter and contain only lower-case letters, numbers, and dashes.

description

A brief description of the silo context and purpose.

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 three identity modes, saml_jit, saml_scim, and local_only. See Authentication Configuration below for details on each.

admin_group_name

Required if using saml_jit or saml_scim identity modes; specifies which IdP group will be granted the Silo Admin role. The group is created in Oxide upon the first successful SAML login that includes this group attribute value.

mapped_fleet_roles

Optional mappings of fleet-level roles conferred by silo roles, applicable to the saml_jit and saml_scim modes only.

quotas

Compute and storage resource limits:

cpu: Total number of virtual CPUs of all running instances.
memory: Total number of bytes of all running instances' memory.
storage: Total number of bytes of all disks provisioned, including snapshots.

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 $SILO_NAME.sys.$OXIDE_DOMAIN_NAME or *.sys.$OXIDE_DOMAIN_NAME for a wildcard certificate:

name: A short name of the certificate
description: Certificate description (e.g., issuer, expiration date)
cert: PEM-formatted string containing public certificate chain
key: PEM-formatted string containing private key

Using the Oxide Console

From the Oxide Console, navigate to the System menu using the dropdown at the top right-hand corner of the interface (next to your user name). On the Silos menu, click New Silo.

Using the CLI or API

The silo creation JSON payload must be provided in a file, for example silo.json. This is then passed to the oxide silo create command:

oxide silo create --json-body silo.json

You can also refer directly to the documentation for the silo_create endpoint.

Two examples of the silo.json request payload are provided below. Replace the placeholders with your actual values.

The cert and key placeholders are PEM-formatted strings, with the contents of certificate and private-key files including their headers, passed as a single-line JSON string with \n escape sequences in place of newlines. For example:

"cert": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"

Example 1: saml_jit JSON payload

{
  "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"
  }]
}

Example 2: local_only JSON payload

{
  "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"
  }]
}

Authentication Configuration

Local Authentication: Set identity_mode to local_only. User accounts are managed directly within the Oxide system without an external IdP. Follow the Local Only guide to configure your silo for local user authentication and create the first local user.

Identity Provider (IdP) Authentication: Set identity_mode to saml_jit or saml_scim. Users are authenticated using SAML assertions from the IdP. Follow the Identity Providers guide to configure your silo for IdP authentication.

2. Create identity provider (optional)

Perform this step only if your silo integrates with an external identity provider (IdP).

In this step, you’ll create the IdP configuration to integrate Oxide rack user authentication and authorization with the provider. See the Identity Providers guide for detailed specifications and integration examples.

You can verify the IdP setup by logging into the Oxide console as any of the users in the silo admin group specified in the IdP configuration. The new silo URL will be at: https://$SILO_NAME.sys.$OXIDE_DOMAIN_NAME/.

3. Create silo administrator account (optional)

Perform this step only if your silo uses the local authentication mode. An example of the API requests for creating the user account and granting administrator access can be found at Create Local Users.

4. Configure access control policies (optional)

If the silo is set up for IdP integration, the admin role is automatically granted to members of the Admin group name specified during silo creation.

You may grant other access levels via the collaborator and viewer roles to other users via the Console, API, or CLI.

5. Link silo to IP pools

Each silo can be linked to one or more IP pools and one of them should be marked as the default. Only linked IP pools can be used for automatic address assignment when ephemeral or floating IPs are created for VM instances.

6. Configure access token expiration (optional)

Tokens generated for API and Console sessions are set to never expire by default. You can override the setting with the /v1/auth-settings API (the setting will be available on the Console in a future release). Token expiration is specified in the form of token lifetime or time-to-live (TTL), not a certain system time. As an example, if you make it 3600 seconds, new tokens will be set to expire one hour from their respective creation times.

Changes in TTL only take effect on tokens created after the fact. Existing tokens will still be revoked based on the original expiration dates set during creation. More enhancements will come in future releases to allow administrators to configure the TTL of Console session tokens and to expire tokens on behalf of other users.

Related API Reference

The following APIs are accessible to fleet administrators only:

Note

Silo administrators can also use the scim_token_* endpoints to manage SCIM tokens for their own silo, while fleet administrators can manage tokens across all silos.

Silo Administrator Capabilities

Silo Resource Access

Silo administrators can access and act on all the child resources within the silo, including projects, instances, images, disks, snapshots, and VPCs. They can also modify the access policies of the projects to grant or revoke access permissions.

Silo administrators can view the capacity allocated to the silo as well as the current resources utilization on the console

They can also see the available resources via the API:

utilization_view

When users attempt to provision more disks or start up more instances than permitted by the resource quotas or IP pools, they will receive an InsufficientCapacity error from the API. Silo administrators can either ask the fleet administrator to increase the resources allocated to the silo, or advise users in the silo to remove unused disks or running instances to free up compute, storage, and network resources.

Silo TLS Certificate Replacement

Silo administrators have the permission to manage TLS certificates for their silos.

To replace the existing TLS certificate for a silo:

If the administrator has access to more than one silo, first configure the OXIDE_HOST and OXIDE_TOKEN environment variables that correspond to the target silo.
Import the new certificate using certificate_create. Pass the --insecure or -k argument if the existing certificate already expired.
Remove the old certificate using certificate_delete.

Note

If a wildcard certificate is used, ensure that the wildcard glob is under the sys subdomain in the DNS SAN (e.g., *.sys.$OXIDE_DOMAIN_NAME). This is necessary because silos are created as $SILO_NAME.sys.$OXIDE_DOMAIN_NAME.

Important

There should be at least one valid TLS certificate associated with each silo for the silo API/Console to be accessible. Always create a new certificate before removing the old one.

Here are the API endpoints for managing TLS certificates:

Rotating Silo SCIM Tokens

Silo administrators have the permission to create new SCIM tokens and delete any unused ones through the Console or API.

The new token needs to be set in the SCIM app integration configurations of the identity provider before removing the existing one to avoid disrupting live user and group import.

Here are the API endpoints for managing SCIM tokens:

Silos

Table of Contents