InterLink Configuration Reference

This guide provides a comprehensive reference for configuring the interLink API server using the InterLinkConfig.yaml file and environment variables.

Configuration Overview

The interLink configuration is defined in pkg/interlink/config.go and consists of several main sections:

• Core Configuration: Basic interLink and plugin connection settings
• TLS Configuration: Security settings for encrypted communication
• Job Script Configuration: Settings for container runtime and job execution
• Logging Configuration: Control over log output levels
• Telemetry Configuration: OpenTelemetry tracing setup

Configuration File Structure

The main configuration file is typically located at /etc/interlink/InterLinkConfig.yaml and follows this structure:

# Core InterLink Settings
InterlinkAddress: "0.0.0.0"        # IP address for interLink API server
InterlinkPort: "3000"              # Port for interLink API server

SidecarURL: "http://localhost"     # URL of the InterLink plugin
SidecarPort: "4000"                # Port of the InterLink plugin


# Data and Storage
DataRootFolder: "/tmp/interlink"   # Root directory for temporary data

# Logging Configuration
VerboseLogging: false              # Enable debug level logging
ErrorsOnlyLogging: false          # Only log errors (overrides verbose)

# TLS Configuration (optional)
TLS:
  Enabled: true                    # Enable TLS/mTLS
  CertFile: "/path/to/cert.pem"   # Server certificate file
  KeyFile: "/path/to/key.pem"     # Server private key file
  CACertFile: "/path/to/ca.pem"   # CA certificate for client verification

# Job Script Build Configuration (optional)
JobScriptBuildConfig:
  singularity_hub:
    server: "https://singularityhub.org"
    master_token: "your-token"
    cache_validity_seconds: 3600

  apptainer_options:
    executable: "apptainer"
    fakeroot: true
    containall: true
    fuse_mode: "overlayfs"
    no_init: false
    no_home: false
    no_privs: false
    nvidia_support: true
    cleanenv: false
    unsquash: false

  volumes_options:
    scratch_area: "/tmp/interlink-scratch"
    apptainer_cachedir: "/tmp/apptainer-cache"
    image_dir: "/tmp/interlink-images"
    additional_directories_in_path: []
    fuse_sleep_seconds: 5

# Job Script Template (optional)
JobScriptTemplate: |
  #!/bin/bash
  # Custom job script template

Configuration Reference

Core Configuration

Field	Type	Default	Description
InterlinkAddress	string	"0.0.0.0"	IP address for the interLink API server to bind to
InterlinkPort	string	"3000"	Port for the interLink API server
SidecarURL	string	"http://localhost"	Base URL of the InterLink plugin
SidecarPort	string	"4000"	Port of the InterLink plugin
DataRootFolder	string	"/tmp/interlink"	Root directory for storing temporary data and job files

Logging Configuration

Field	Type	Default	Description
VerboseLogging	bool	false	Enable debug level logging for detailed output
ErrorsOnlyLogging	bool	false	Only log errors (takes precedence over verbose)

TLS Configuration

The TLS section enables secure communication between interLink components:

Field	Type	Required	Description
Enabled	bool	No	Enable TLS/mTLS for secure communication
CertFile	string	If TLS enabled	Path to the server certificate file
KeyFile	string	If TLS enabled	Path to the server private key file
CACertFile	string	For mTLS	Path to CA certificate for client verification

Job Script Build Configuration

The JobScriptBuildConfig section configures container runtime options and job script generation.

What is a Job?

A job in this context refers to the execution scripts generated by InterLink plugins to run containers on different backend systems (like SLURM, HTCondor, or Docker). The JobScriptBuildConfig allows plugins to customize how these execution scripts are generated and what runtime options are used.

For example:

• SLURM plugin: Generates SLURM batch scripts with sbatch commands
• HTCondor plugin: Creates HTCondor ClassAd files
• Docker plugin: Builds docker run commands
• Apptainer/Singularity plugin: Constructs apptainer run scripts with specific runtime flags

This configuration is optional and only used by plugins that need to generate custom job execution scripts:

Singularity Hub Configuration

Plugin-Specific Configuration

The Singularity Hub configuration is specific to Apptainer/Singularity-based plugins. This section may be removed in future versions as it's not used by all plugin types. Consider using plugin-specific configuration files instead.

Field	Type	Description
server	string	Singularity Hub server URL (e.g., https://singularityhub.org)
master_token	string	Authentication token for accessing private repositories
cache_validity_seconds	int	Duration in seconds to cache downloaded images

Apptainer Options

Field	Type	Default	Description
executable	string	"apptainer"	Path to Apptainer/Singularity executable
fakeroot	bool	false	Enable fakeroot mode for unprivileged execution
containall	bool	false	Contain all mount points
fuse_mode	string	""	FUSE mount mode (e.g., "overlayfs")
no_init	bool	false	Skip container initialization
no_home	bool	false	Don't mount home directory
no_privs	bool	false	Drop all privileges
nvidia_support	bool	false	Enable NVIDIA GPU support
cleanenv	bool	false	Clean environment variables
unsquash	bool	false	Unsquash container image

Volume Options

Field	Type	Description
scratch_area	string	Temporary scratch space directory
apptainer_cachedir	string	Apptainer cache directory
image_dir	string	Directory for storing container images
additional_directories_in_path	[]string	Additional directories to add to PATH
fuse_sleep_seconds	int	Delay in seconds for FUSE operations

Environment Variable Overrides

The following environment variables can override configuration file values:

Environment Variable	Config Field	Description
INTERLINKCONFIGPATH	-	Path to configuration file (default: /etc/interlink/InterLinkConfig.yaml)
INTERLINKURL	InterlinkAddress	Override interLink server address
INTERLINKPORT	InterlinkPort	Override interLink server port
SIDECARURL	SidecarURL	Override InterLink plugin URL
SIDECARPORT	SidecarPort	Override InterLink plugin port

Telemetry Configuration

OpenTelemetry tracing is configured through environment variables:

Environment Variable	Default	Description
TELEMETRY_ENDPOINT	"localhost:4317"	OTLP endpoint for trace export
TELEMETRY_UNIQUE_ID	Generated UUID	Unique identifier for service instances
TELEMETRY_CA_CRT_FILEPATH	-	CA certificate for mTLS to telemetry endpoint
TELEMETRY_CLIENT_CRT_FILEPATH	-	Client certificate for mTLS
TELEMETRY_CLIENT_KEY_FILEPATH	-	Client private key for mTLS
TELEMETRY_INSECURE_SKIP_VERIFY	"false"	Skip TLS certificate verification

Command Line Options

The interLink binary supports these command-line flags:

Flag	Type	Default	Description
-verbose	bool	false	Enable debug level logging
-errorsonly	bool	false	Only log errors
-interlinkconfigpath	string	-	Path to configuration file

Configuration Examples

Basic Configuration

InterlinkAddress: "0.0.0.0"
InterlinkPort: "3000"
SidecarURL: "http://localhost"
SidecarPort: "4000"
DataRootFolder: "/tmp/interlink"
VerboseLogging: false
ErrorsOnlyLogging: false

TLS-Enabled Configuration

InterlinkAddress: "0.0.0.0"
InterlinkPort: "3000"
SidecarURL: "https://remote-sidecar.example.com"
SidecarPort: "443"
DataRootFolder: "/tmp/interlink"

TLS:
  Enabled: true
  CertFile: "/etc/ssl/certs/interlink.crt"
  KeyFile: "/etc/ssl/private/interlink.key"
  CACertFile: "/etc/ssl/certs/ca.crt"

Apptainer/Singularity Configuration

InterlinkAddress: "0.0.0.0"
InterlinkPort: "3000"
SidecarURL: "http://localhost"
SidecarPort: "4000"
DataRootFolder: "/tmp/interlink"

JobScriptBuildConfig:
  apptainer_options:
    executable: "/usr/bin/apptainer"
    fakeroot: true
    containall: true
    nvidia_support: true
    cleanenv: true

  volumes_options:
    scratch_area: "/scratch/interlink"
    apptainer_cachedir: "/var/cache/apptainer"
    image_dir: "/var/lib/interlink/images"
    fuse_sleep_seconds: 10

Configuration Loading Order

The configuration is loaded in the following priority order:

1. Command-line flags (highest priority)
2. Environment variables
3. Configuration file (lowest priority)

Validation and Troubleshooting

Common Configuration Issues

1. Port conflicts: Ensure InterlinkPort and SidecarPort don't conflict with other services
2. File permissions: Verify that certificate files and data directories are readable
3. Network connectivity: Test connectivity between interLink and sidecar components
4. TLS certificate validation: Ensure certificate subject names match hostnames

Configuration Validation

The interLink binary validates configuration at startup and will log errors for:

• Missing required certificate files when TLS is enabled
• Invalid port numbers or addresses
• Inaccessible data directories
• Malformed YAML syntax

Debug Configuration

Enable verbose logging to troubleshoot configuration issues:

# Using command-line flag
./interlink -verbose

# Using environment variable in config
VerboseLogging: true

# Using environment variable
export VERBOSE_LOGGING=true

See Also

• Deploy InterLink Guide
• mTLS Deployment Guide
• Monitoring Guide
• API Reference