Client Update Service
The Client Update Service (CUS) is a component of the Web API Service that distributes JARs, configuration files, and resources to remote clients. It is enabled by default and starts automatically when the Web API Service starts.
Clients use the Deephaven Updater to sync files from the CUS.
How it works
The CUS collates JARs, configuration files, and resources from standard server directories and makes them available for clients to download. A reload re-runs the collation and updates the files clients see. For a full description of the Launcher-centric file sync mechanism, see Launcher and client configuration.
Files distributed to clients
The CUS distributes content from several standard server directories. The CUS automatically excludes some known files — including temporary files, server-only configuration, and sensitive data — from the sync.
Configuration
These properties configure the CUS. Set them in iris-common.prop or a service-specific property file and restart the Web API Service to apply changes.
| Property | Default | Description |
|---|---|---|
client_update_service.host | (none — required) | Hostname the CUS advertises to clients in the appbase URL. Must be set or the Web API Service will not start. |
client_update_service.port | 8443 (HTTPS) or 8480 (HTTP) | Overrides the port the CUS web server listens on. When not set, defaults to 8443 if a TLS keystore is configured, or 8480 otherwise. |
Webapi.server.cus.enabled | true | Set to false to disable the CUS entirely. |
Webapi.server.cus.home | /etc/sysconfig/illumon.d/client_update_service/iris/ | CUS staging home directory. |
Webapi.server.cus.getdown.port | -1 (use listener port) | Overrides the port written into the appbase URL in getdown.txt. When not set, the listener port is used. When Envoy is configured, the Envoy port is used automatically. Set this when the CUS is behind a reverse proxy that exposes a different external port. |
Webapi.server.cus.getdown.threadPoolSize | CPU cores / 2 | Number of threads used for parallel digest computation. |
Webapi.server.cus.reload.timeout | 120000 (2 minutes) | Milliseconds to wait for a reload operation before returning a timeout response. |
Webapi.server.cus.resource.exclusions | (built-in list) | Comma-separated Java regex patterns of filenames to exclude from resources/. Setting this property replaces the built-in exclusion list entirely; omit it to retain the defaults. |
client_update_service.install.error.file | error.html | Filename of the error page shown to clients if installation fails. |
Webapi.server.cus.cache.maxCacheSize | A quarter of the direct memory limit, or 512 MB when no limit is set | Total bytes of client update content held in memory. See Memory used for caching. |
Webapi.server.cus.cache.maxCachedFileSize | A quarter of maxCacheSize, clamped to between 1 MB and 64 MB | Largest file to hold in the cache. Files above this size are served from a memory mapping instead. |
Webapi.server.cus.cache.fileMappingMinSize | Same as maxCachedFileSize | Smallest file to serve from a memory mapping. Defaults to the cache cutoff so that each file is either cached or mapped, never both. |
The number of files the cache holds is also configurable, with Webapi.server.cus.cache.maxCachedFiles, but the default limit is sufficient to hold all Deephaven system resource files that are served by the CUS.
Memory used for caching
The Web API Service keeps recently requested client update files in memory so that many clients logging in at once are served without re-reading the files. This cache lives in direct memory, outside the Java heap, so it does not appear in heap usage or in garbage collection logs.
The cache shares that direct memory with the rest of the service's work — chiefly the service's own authentication and configuration calls. The cache defaults to a quarter of the JVM's direct memory limit for that reason, leaving the remainder for everything else the service does.
The service reports the sizes it chose when it starts:
To keep a larger share of the client files warm, raise the direct memory limit and the cache will follow. Raising Webapi.server.cus.cache.maxCacheSize on its own is capped by the direct memory available, and on Kubernetes the container memory limit has to accommodate the heap and the direct memory limit together. See process memory.
Warning
Without -XX:MaxDirectMemorySize, the JVM allows direct allocation up to the size of the maximum heap, so the service can grow to roughly twice the memory you planned for it. Running out that way produces no Java error and no stack trace — the operating system terminates the process. The Kubernetes chart sets this limit for you; the service logs a warning at startup if it is missing.
Adding customer JARs
To distribute additional JARs to all clients, add their paths to /etc/sysconfig/illumon.d/resources/customer_jars.txt — one path per line. The CUS supports both individual JAR files and directories. Reload the CUS after editing this file.
Reloading the CUS
A reload re-runs the full file collation and re-digest without restarting the Web API Service. Trigger a reload by sending any request to the /reload/ endpoint:
The reload runs synchronously up to the timeout (Webapi.server.cus.reload.timeout). After a reload, connected clients pick up the new files on their next sync.
Note
A CUS reload does not re-read client_update_service.host, client_update_service.port, or other JVM properties. Changes to those properties require a full Web API Service restart.