XCOMPUTE-SERVER Administration Guide

XCOMPUTE-SERVER Administration Guide#

1. Configuration#

XCOMPUTE-SERVER ingests several configuration files at launch. Edit these files to customize behavior, access control, and compute defaults.

Administration (`server.cfg`)#

Define one or two administrators. The first must match the email/fingerprint used for the server license. The optional second should be a trusted deputy.

admin=tech.boss@company.com          # Required: Registered server email
fingerprint=YOUR_XCSERVER_FINGERPRINT # Required: Server license fingerprint
admin2=tech.deputy@company.com       # Optional: Trusted client email (must be in users.cfg)
input=/mnt/FAST_SSD/                 # Project load directory
output=/mnt/FAST_SSD/                # Project save directory
cache=/mnt/FAST_SSD/_cache/          # Temporary runtime files (underscore prefix recommended)

Tip: For enhanced isolation and performance, consider mounting cache on a separate high-speed drive.

Server administration is typically performed headless via SSH. Administrators act on behalf of their organization and have full access to project data. Exercise caution; mismanagement can corrupt or destroy projects. Contact Xplicit Computing for administrative support.

User Access (`users.cfg`)#

Manage team access by adding fingerprints and emails:

allow_guests=false
SOMEONES_XCCLIENT_FINGERPRINT=someone@somewhere.com
ANOTHERS_XCCLIENT_FINGERPRINT=helper@subcontractor.com

Set allow_guests=true to permit read-only public access. Default is false.

Host Collaboration (`hosts.cfg`)#

Configure LAN auto-discovery and remote server connections:

# localnet=192.168.1   # Optional: Class-C subnet scan range
CLUSTER_XCSERVER_FINGERPRINT=192.168.1.2
ANOTHER_XCSERVER_FINGERPRINT=anothercompany.com

Server-to-server protocols and load distribution are under active development.

Compute Defaults (`compute.cfg`)#

Set preferred default solver and meshing parameters:

ReservedThreads=1       # CPU threads reserved for server responsiveness
DefaultDevice=0         # 0: Auto-select best OpenCL device
Iterations=500          # Default steps for iterative solvers
Resolution=16000000     # Shape resolution (typically 1e6–1e8)
ElementCount=40000      # Default node/cell count for new meshes

2. Execution Modes#

System-Managed Service (Recommended)#

XCOMPUTE-SERVER can run as a persistent systemd service, starting automatically on boot.

Installation: Use the Debian (.deb) package. Requires root privileges. Creates a dedicated xcompute system user.

Service Management: # Check status systemctl status xcompute

# Start / Stop / Restart
sudo systemctl start xcompute
sudo systemctl stop xcompute
sudo systemctl restart xcompute

Expected Output:

● xcompute.service - XCOMPUTE Service
     Loaded: loaded (/etc/systemd/system/xcompute.service; linked; vendor preset: enabled)
     Active: active (running) since Sat 2025-03-29 18:32:35 PDT; 18min ago
   Main PID: 233561 (xcompute-server)
      Tasks: 13 (limit: 18988)
     Memory: 21.4M
     CGroup: /system.slice/xcompute.service
             └─233561 /opt/xcompute/xcserver/bin/xcompute-server

Logs are written to /var/opt/xcompute/xcserver/log/:

xcserver.log: Standard output (version, license, CPU/OpenCL detection)
xcserver.err: Errors and warnings

Example Startup Log:

Model name:                           Intel(R) Core(TM) i9-9900 CPU @ 3.10GHz
CPU(s):                               16
NUMA node0 CPU(s):                    0-15
...
compute platform: NVIDIA CUDA
OpenCL 3.0 CUDA 12.4.131 (FULL_PROFILE)
...

User-Managed Execution#

Run manually without root privileges. Suitable for individual use or environments where system services are restricted.

./xcompute-server

Ensure the listening socket binds successfully and at least one OpenCL device is detected. Only one instance can run at a time.

3. File I/O & Storage#

Operation	Server Side	Client Side
Input	Load from host filesystem	Import from local machine
Output	Save to host filesystem	Export to local machine

Save & Load#

Save: Writes project state to the output directory.
Load: Reads from the input directory.
Each system maps to a folder containing:
- *.xcs / *.json: System setup (JSON tried first, then XCS)
- *.xcg: Native geometry
- *.xco: Data properties (view with xc2csv or XC-Messages bindings)
Previous states are backed up with a . prefix for triple-redundancy.

Import & Export#

Files are staged in the cache directory during transfer to prevent corruption. Supported formats:

Import: stl, obj, msh, sdf
Export: csv, vtu, stl, obj, msh, sdf

Default export types can be set in compute.cfg: SystemExportType=vtu GeometryExportType=msh

4. Troubleshooting#

Common Errors#

Authentication Failed:

Cannot authenticate without a fingerprint. Aborting.
Authentication Failed.
A valid certificate is required to launch xcompute-server...

Fix: Verify fingerprint in server.cfg matches your license. Check certificate validity in your account profile.

Log Inspection#

Review logs for OpenCL device detection, license loading, and network binding status.

# View standard logs
vi /var/opt/xcompute/xcserver/log/xcserver.log

# View errors
vi /var/opt/xcompute/xcserver/log/xcserver.err