# Omniverse Client Library — Configuration Reference

## Table of Contents

1. [omniverse.toml Configuration File](#omniversetoml-configuration-file)
2. [Environment Variables](#environment-variables)
3. [Provider Routing](#provider-routing)
4. [URL Format Rules](#url-format-rules)
5. [Authentication Flows](#authentication-flows)
6. [Hub Configuration](#hub-configuration)

---

## omniverse.toml Configuration File

Located at `OMNI_CONFIG_PATH` or platform-default locations.

### URL Aliases
```toml
[aliases]
"nvidia:" = "http://www.nvidia.com/"
"myserver:" = "omniverse://my-nucleus.company.com/"
```
Also settable at runtime: `omniClientSetAlias("nvidia:", "http://www.nvidia.com/")` or `omni.client.set_alias("nvidia:", "http://www.nvidia.com/")`.

### S3 Configuration
```toml
[s3."{hostname}"]
bucket = "{bucket}"
region = "{region}"
accessKeyId = "{access-key-id}"
secretAccessKey = "{secret-access-key}"
sessionToken = "{optional-token}"
cloudfront = "https://{distribution-id}.cloudfront.net"  # optional
cloudfrontList = false  # optional: route list/stat through CloudFront
canonicalHost = "bucket.s3.region.amazonaws.com"  # optional: for custom DNS
```

Hostname must be the full host (e.g., `bucket.s3.us-west-2.amazonaws.com`). Path-style URLs (`s3.region.amazonaws.com/bucket`) are NOT supported.

### Azure Configuration
```toml
[azure."{account}.blob.core.windows.net/{container}"]
sasToken = "{sas-token}"
```

### CloudFront Server-Side Config
Place `.cloudfront.toml` in the S3 bucket root:
```toml
cloudfront = "http://dcb18d6mfegct.cloudfront.net"
cloudfrontList = false
```
Client-side `omniverse.toml` overrides this.

If `cloudfrontList = true` or using CloudFront URLs directly, CloudFront must forward these query params to S3: `list-type`, `delimiter`, `prefix`, `continuation-token`.

### Cache Configuration
```toml
[paths]
cache_root = "/path/to/cache"
```

---

## Environment Variables

### General Library
| Variable | Description | Default |
|---|---|---|
| `OMNICLIENT_PROVIDERS` | Comma-separated providers to register: `file`, `http`, `nucleus`, `storage` | All registered |
| `OMNICLIENT_NO_BROWSER` | `1` = prefer device-flow auth over browser | Not set |
| `OMNICLIENT_ALLOW_VERBOSE_LIVE` | `1` = verbose live update logging | Not set |
| `OMNI_CONFIG_PATH` | Path to configuration directory | Platform default |

### Nucleus
| Variable | Description | Default |
|---|---|---|
| `OMNI_MULTIPART_CHUNK_SIZE_MB` | Chunk size for multipart uploads (MB) | Provider default |
| `OMNI_DEPLOYMENT` | Deployment type for connections | `"external"` |
| `OMNI_USER` / `OMNI_USERNAME` | Force specific username | Not set |
| `OMNI_PASS` / `OMNI_PASSWORD` | Force specific password | Not set |

### OmniStorage
| Variable | Description | Default |
|---|---|---|
| `OMNI_STORAGE_DISCOVERY` | Discovery URL for OpenID Connect | Not set |
| `OMNI_STORAGE_CLIENT_NAME` | Client name for OIDC config | `"client_library"` |
| `OMNI_STORAGE_HOST` | Storage server hostname (required if no discovery) | None |
| `OMNI_STORAGE_PORT` | Storage server port | `"50051"` |
| `OMNI_STORAGE_SECURE` | `1` = enable TLS | `true` when port=443 |
| `OMNI_STORAGE_AUTHORIZATION` | Authorization header (e.g., `"Bearer {token}"`) | Not set |
| `OMNI_STORAGE_FUNCTION_ID` | NVCF Function-ID header | Not set |
| `OMNI_STORAGE_FUNCTION_VERSION_ID` | NVCF Function-Version-ID header | Not set |
| `OMNI_STORAGE_DEADLINE` | Operation deadline (seconds, 0=none) | `0` |
| `OMNI_STORAGE_RETRY_MAX` | Max retry attempts | `10` |
| `OMNI_STORAGE_RETRY_MAX_DELAY_MS` | Max delay between retries (ms) | `5000` |
| `OMNI_STORAGE_RETRY_BASE_MS` | Base delay between retries (ms) | `10` |
| `OMNI_STORAGE_RETRY_FORMULA` | 0=constant, 1=linear, 2=exponential | `2` |
| `OMNI_STORAGE_RETRY_JITTER` | 0=none, 1=full, 2=equal | `2` |

### HTTP (applies to HTTP, S3, Azure, CloudFront)
| Variable | Description | Default |
|---|---|---|
| `OMNICLIENT_HTTP_VERBOSE` | `1` = verbose HTTP logging | Not set |
| `OMNICLIENT_HTTP_TIMEOUT` | Seconds before slow-transfer abort | `60` |
| `OMNICLIENT_HTTP_RETRIES` | Failed operation retry count | `8` |
| `OMNICLIENT_HTTP_PROXY_SSL_VERIFYHOST` | SSL host verification for proxy | `1` |
| `OMNICLIENT_HTTP_PROXY_SSL_VERIFYPEER` | SSL peer verification for proxy | `1` |
| `OMNICLIENT_HTTP_CONCURRENT_OPS` | Max concurrent HTTP operations | `20` |

### Hub
| Variable | Description | Default |
|---|---|---|
| `OMNICLIENT_HUB_MODE` | `"disabled"`, `"exclusive"`, or `"shared"` | Auto-detect |
| `OMNICLIENT_HUB_EXE` | Path to Hub executable | Auto-detect |
| `OMNICLIENT_HUB_CACHE_DIR` | Hub cache directory (required for exclusive) | From omniverse.toml |

### NVCF
| Variable | Description | Default |
|---|---|---|
| `NVCF_JWT_ENABLED` | Non-zero = add JWT to storage requests | Not set |
| `NVCF_JWT_FILE_PATH` | JWT file path | `/var/run/nvcf/info/self` |
| `NVCF_JWT_HEADER` | JWT header name | `"Omni-Tenant-Token"` |

JWT rotates every 2.5-3 hours; bridge has 3-hour expiry.

### Testing Only
| Variable | Description |
|---|---|
| `OMNI_TEST_NO_BROWSER` | `1` = disable browser auth in tests |
| `OMNI_TEST_BYPASS_LISTCACHE` | `1` = bypass list cache |
| `OMNI_TEST_USER` | Test username |
| `OMNI_TEST_PASS` | Test password |
| `OMNI_TEST_HOST` | Test hostname |

---

## Provider Routing

When a URL is resolved to a provider, the routing order is:

1. **StorageProviderFactory** (scheme `*`) — gets first chance. Intercepts URLs if the host is registered via `OMNI_STORAGE_DISCOVERY`, `register_storage_from_discovery()`, or `register_storage_direct()`.
2. **Scheme-specific factories**:
   - `omniverse://` / `omniverses://` → NucleusProviderFactory
   - `http://` / `https://` → HttpProviderFactory (then dispatches to S3, Azure, or generic HTTP based on hostname patterns)
   - `file://` → FileProviderFactory
3. **Fallback** — bare paths with no scheme (e.g., `C:\folder`) → FileProvider

### HTTP Sub-Provider Selection
HttpProviderFactory picks the sub-provider by hostname pattern:
- `*.amazonaws.com` → S3Provider
- `*.cloudfront.net` → S3Provider (via CloudFront)
- `*.blob.core.windows.net` → AzureProvider
- Hostname configured in `[s3."hostname"]` in omniverse.toml → S3Provider
- Everything else → generic HttpProvider

---

## URL Format Rules

| Format | Example | Notes |
|---|---|---|
| Omniverse | `omniverse://server:port/path` | Port optional |
| Short Omniverse | `omni://server/path` | Same as above |
| Embedded | `http://web/?omniverse://server/path` | Everything before `omniverse:` ignored |
| File URL | `file:///c:/local%20path` | Must percent-encode special chars |
| Raw Windows path | `C:\local path` | Works but not recommended |
| Raw Linux path | `/local/path` | Unreliable — could be server path |
| HTTP/HTTPS | `https://www.example.com/file` | Read-only for generic HTTP |
| S3 | `https://bucket.s3.region.amazonaws.com/key` | Virtual-hosted style only |
| Azure | `https://account.blob.core.windows.net/container/blob` | SAS token in toml |

**Important gotchas**:
- File URIs: 1 or 3 slashes, never 2 (`file:///path` or `file:/path`, not `file://path`)
- Raw Linux paths are unreliable — always prefer `file://` URLs
- S3 path-style URLs are NOT supported
- Special characters in file URLs must be percent-encoded

---

## Authentication Flows

### Nucleus Authentication (Priority Order)

1. **Application callbacks** — `register_authentication_callback()` / `omniClientRegisterAuthCallback()`
   - Return token, username+password, abort, or None to try next
   - Multiple callbacks supported, called newest-first

2. **Environment variables** — `OMNI_USER`/`OMNI_USERNAME` + `OMNI_PASS`/`OMNI_PASSWORD`
   - Overrides cached tokens when set

3. **Cached tokens** — from previous successful logins
   - Stored on disk, used automatically

4. **Device flow** (RFC 8628) — when `OMNICLIENT_NO_BROWSER=1` or device flow callback registered
   - User visits URL and enters code on another device
   - If no callback registered, URL and code logged at info level

5. **Browser authentication** — interactive sign-in via local browser
   - Default interactive method when device flow not requested

### OmniStorage Authentication

**With discovery** (`OMNI_STORAGE_DISCOVERY` set):
- Default: OAuth2 authorization-code flow (browser redirect)
- Device flow when `OMNICLIENT_NO_BROWSER=1` or device flow callback registered
- Discovery URL's OpenID config must include `device_authorization_endpoint` for device flow

**Manual** (no discovery):
- Bearer token via `OMNI_STORAGE_AUTHORIZATION` env var
- Application callback via `register_storage_auth_callback()`

### Storage Auth Callback Pattern
```python
def storage_auth(auth_handle, server):
    # Get token from your auth system
    token = get_my_token(server)
    omni.client.set_storage_access_token(auth_handle, token)
    return True  # I'm handling it

reg = omni.client.register_storage_auth_callback(storage_auth)
# IMPORTANT: auth_handle (int) ≠ reg (Registration object)
# auth_handle → use with set_storage_access_token
# reg → keep alive to maintain callback; set to None to unregister
```

---

## Hub Configuration

Hub is a local process that provides caching and connection management for Nucleus.

### Modes
| Mode | Behavior |
|---|---|
| `disabled` | Don't use Hub at all |
| `exclusive` | Launch Hub at init, shut down at shutdown/exit |
| `shared` | Use Hub if running, launch if not, never shut down |

### Compatibility
- Newer Hub versions are backward-compatible with older client-library versions
- Older Hub versions are NOT compatible with newer client-library versions
- Use a Hub build that matches your client-library version expectations (see release notes for your stack)

### Obtaining Hub
Install Hub using one of these:

- **Cache Status Indicator** Kit extension — installs Hub as part of that workflow
- **[Hub Workstation Cache on NGC](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/omniverse/collections/hub-workstation-cache)** — collection and images for Hub / workstation cache use cases

Set **`OMNICLIENT_HUB_EXE`** to the Hub binary path (see the **Hub** row in [Environment Variables](#environment-variables)). Set **`OMNICLIENT_HUB_CACHE_DIR`** when using `exclusive` mode if required.
