Configuration Guide

S9S offers extensive configuration options to customize your experience. This guide covers all configuration methods and options.

📁 Configuration Files

S9S looks for configuration files in the following order:

```
~/.s9s/config.yaml
```
(user-specific)
```
~/.config/s9s/config.yaml
```
(XDG config)
```
/etc/s9s/config.yaml
```
(system-wide)
Environment variables (override files)
Command-line flags (highest priority)

🚀 Basic Configuration

Minimal Configuration

Create

~/.s9s/config.yaml


clusters:
  default:
    url: https://slurm.example.com
    auth:
      method: token
      token: ${SLURM_TOKEN}

Full Example Configuration


# ~/.s9s/config.yaml
version: 1

# Cluster configurations
clusters:
  production:
    url: https://prod-slurm.example.com
    auth:
      method: token
      token: ${SLURM_TOKEN}
    default: true
    timeout: 30s
    retries: 3
    
  development:
    url: https://dev-slurm.example.com
    auth:
      method: basic
      username: ${SLURM_USER}
      password: ${SLURM_PASS}
    insecureTLS: true
    
  research:
    url: https://research.example.edu:6820
    auth:
      method: oauth2
      clientId: ${OAUTH_CLIENT_ID}
      clientSecret: ${OAUTH_CLIENT_SECRET}
      tokenURL: https://auth.example.edu/token
      scopes: ["slurm.read", "slurm.write"]

# UI preferences
preferences:
  theme: dark
  defaultView: jobs
  refreshInterval: 5s
  confirmActions: true
  showRelativeTime: true
  dateFormat: "2006-01-02 15:04:05"
  timezone: "America/New_York"
  
# Column preferences per view
columns:
  jobs:
    - JobID
    - Name
    - User
    - State
    - Time
    - Nodes
    - Priority
  nodes:
    - NodeName
    - State
    - CPULoad
    - Memory
    - GPUs
    - Jobs
    
# Keyboard shortcuts
keybindings:
  global:
    "ctrl+j": "view jobs"
    "ctrl+n": "view nodes"
    "ctrl+q": "quit"
  jobs:
    "K": "cancel --force"
    "H": "hold --reason='Manual hold'"
    
# Filtering presets
filters:
  my-jobs:
    view: jobs
    filter: "user:${USER}"
  gpu-jobs:
    view: jobs
    filter: "partition:gpu state:RUNNING"
  failed-today:
    view: jobs
    filter: "state:FAILED time:>today"
    
# Notification settings
notifications:
  enabled: true
  desktop: true
  sound: true
  webhook:
    url: https://slack.example.com/webhook
    events:
      - job_complete
      - job_failed
      - node_down
      
# Export settings
export:
  defaultFormat: csv
  defaultPath: ~/Documents/s9s-exports
  includeHeaders: true
  dateFormat: RFC3339
  
# SSH settings
ssh:
  defaultUser: ${USER}
  keyFile: ~/.ssh/id_rsa
  knownHostsFile: ~/.ssh/known_hosts
  compression: true
  forwardAgent: true
  extraArgs: "-o StrictHostKeyChecking=ask"
  
# Performance settings
performance:
  maxConcurrentRequests: 10
  cacheEnabled: true
  cacheTTL: 60s
  logLevel: info
  debugFile: ~/.s9s/debug.log
  
# Plugin settings
plugins:
  enabled: true
  directory: ~/.s9s/plugins
  autoload:
    - efficiency-analyzer
    - job-templates
    - slack-notifier

🔧 Configuration Sections

Clusters

Configure multiple SLURM clusters:


clusters:
  <cluster-name>:
    url: <api-endpoint>          # Required: SLURM REST API URL
    auth:                        # Required: Authentication config
      method: <auth-type>        # token, basic, oauth2, cert
      # method-specific fields
    default: <boolean>           # Optional: Default cluster
    timeout: <duration>          # Optional: Request timeout (default: 30s)
    retries: <number>           # Optional: Retry attempts (default: 3)
    insecureTLS: <boolean>      # Optional: Skip TLS verification
    proxy: <url>                # Optional: HTTP proxy
    headers:                    # Optional: Custom headers
      X-Custom: value

Authentication Methods

Token Authentication


auth:
  method: token
  token: ${SLURM_TOKEN}  # Environment variable
  # or
  token: "your-token-here"
  # or
  tokenFile: ~/.s9s/token

Basic Authentication


auth:
  method: basic
  username: ${SLURM_USER}
  password: ${SLURM_PASS}

OAuth2


auth:
  method: oauth2
  clientId: ${OAUTH_CLIENT_ID}
  clientSecret: ${OAUTH_CLIENT_SECRET}
  tokenURL: https://auth.example.com/token
  scopes: ["slurm.read", "slurm.write"]
  redirectURL: http://localhost:8080/callback

Certificate Authentication


auth:
  method: cert
  certFile: ~/.s9s/client.crt
  keyFile: ~/.s9s/client.key
  caFile: ~/.s9s/ca.crt

UI Preferences

Customize the interface:


preferences:
  # Theme settings
  theme: dark|light|terminal|custom
  customTheme: ~/.s9s/themes/my-theme.yaml
  
  # View settings
  defaultView: jobs|nodes|dashboard
  refreshInterval: 5s|10s|30s|0 (disabled)
  
  # Display options
  showRelativeTime: true|false
  use24HourTime: true|false
  showSeconds: true|false
  dateFormat: "2006-01-02 15:04:05"
  timezone: "UTC"|"Local"|"America/New_York"
  
  # Behavior
  confirmActions: true|false
  autoRefresh: true|false
  showLineNumbers: true|false
  wrapLongLines: true|false
  
  # Performance
  pageSize: 50
  maxResults: 1000
  enableAnimations: true|false

Column Configuration

Customize visible columns per view:


columns:
  jobs:
    - JobID
    - Name
    - User
    - State
    - Time
    - Nodes
    - Partition
    - Priority
    - QoS
    - Account
    
  nodes:
    - NodeName
    - State
    - CPULoad
    - Memory
    - RealMemory
    - AllocMemory
    - FreeMem
    - GPUs
    - Jobs
    - Features
    
  users:
    - User
    - DefaultAccount
    - RunningJobs
    - PendingJobs
    - CPUTime
    - LastSeen

Custom Keybindings

Override default shortcuts:


keybindings:
  # Global shortcuts (work everywhere)
  global:
    "ctrl+q": "quit"
    "ctrl+s": "save"
    "ctrl+/": "search"
    "f1": "help"
    "ctrl+\\": "toggle-sidebar"
    
  # View-specific shortcuts
  jobs:
    "d": "delete"
    "D": "delete --force"
    "ctrl+c": "cancel"
    "ctrl+h": "hold"
    "ctrl+r": "release"
    
  nodes:
    "shift+d": "drain --reason='Maintenance'"
    "shift+r": "resume"

🌍 Environment Variables

S9S supports environment variable substitution:


# Use ${VAR_NAME} syntax
clusters:
  default:
    url: ${SLURM_API_URL}
    auth:
      token: ${SLURM_TOKEN}
      
# With defaults
preferences:
  theme: ${S9S_THEME:-dark}
  refreshInterval: ${S9S_REFRESH:-5s}

Supported Environment Variables

Variable	Description	Default
`S9S_CONFIG`	Config file path	`~/.s9s/config.yaml`
`S9S_CLUSTER`	Default cluster	First in config
`S9S_DEBUG`	Enable debug mode	`false`
`S9S_THEME`	UI theme	`dark`
`S9S_REFRESH`	Refresh interval	`5s`
`S9S_MOCK`	Enable mock mode	`false`
`S9S_LOG_LEVEL`	Log level	`info`
`SLURM_TOKEN`	Auth token	-
`SLURM_USER`	Username	-
`SLURM_PASS`	Password	-

🎨 Theme Configuration

Built-in Themes

```
dark
```
- Dark background, light text
```
light
```
- Light background, dark text
```
terminal
```
- Classic terminal green
```
high-contrast
```
- Accessibility optimized

Custom Theme

Create

~/.s9s/themes/custom.yaml


name: "My Theme"
colors:
  # Base colors
  background: "#1a1a1a"
  foreground: "#e0e0e0"
  selection: "#3a3a3a"
  cursor: "#ffffff"
  
  # UI elements
  border: "#404040"
  title: "#ffffff"
  subtitle: "#b0b0b0"
  
  # Status colors
  success: "#50fa7b"
  warning: "#f1fa8c"
  error: "#ff5555"
  info: "#8be9fd"
  
  # Job states
  running: "#50fa7b"
  pending: "#f1fa8c"
  failed: "#ff5555"
  completed: "#8be9fd"
  cancelled: "#ff79c6"
  
  # Syntax highlighting
  keyword: "#ff79c6"
  string: "#f1fa8c"
  number: "#bd93f9"
  comment: "#6272a4"

🔐 Security Configuration

Secure Token Storage


# Use system keyring (recommended)
clusters:
  secure:
    url: https://slurm.example.com
    auth:
      method: token
      tokenProvider: keyring
      tokenKey: s9s-prod-token

Certificate Validation


clusters:
  strict:
    url: https://slurm.example.com
    tls:
      insecure: false
      caFile: /etc/ssl/certs/ca-bundle.crt
      verifyHostname: true
      minVersion: "1.2"

📊 Advanced Configuration

Performance Tuning


performance:
  # Connection pooling
  maxIdleConns: 100
  maxConnsPerHost: 10
  idleConnTimeout: 90s
  
  # Caching
  cache:
    enabled: true
    size: 100MB
    ttl: 60s
    compression: true
    
  # Request handling
  requestTimeout: 30s
  responseTimeout: 60s
  keepAlive: 30s
  
  # UI performance
  virtualScrolling: true
  lazyLoading: true
  debounceDelay: 300ms

Logging Configuration


logging:
  level: debug|info|warn|error
  file: ~/.s9s/s9s.log
  maxSize: 100MB
  maxBackups: 3
  maxAge: 30d
  compress: true
  
  # Separate log levels
  levels:
    api: debug
    ui: info
    ssh: warn

Plugin Configuration


plugins:
  enabled: true
  directory: ~/.s9s/plugins
  
  # Plugin-specific config
  config:
    efficiency-analyzer:
      threshold: 0.8
      reportPath: ~/efficiency-reports
      
    job-templates:
      directory: ~/.s9s/templates
      validate: true
      
    notifications:
      slack:
        webhook: ${SLACK_WEBHOOK}
        channel: "#hpc-alerts"
        mentions:
          job_failed: "@channel"

🔄 Configuration Management

Validate Configuration


s9s config validate
s9s config test --cluster production

Export/Import Configuration


# Export current config
s9s config export > config-backup.yaml

# Import configuration
s9s config import config-backup.yaml

# Merge configurations
s9s config merge additional-config.yaml

Configuration Wizard


# Interactive setup
s9s setup

# Guided cluster addition
s9s config add-cluster

# Update specific settings
s9s config set preferences.theme dark
s9s config set clusters.default.url https://new-url.com

💡 Best Practices

Use environment variables for sensitive data
Version control your config (exclude secrets)
Test changes with
```
s9s config test
```
Backup before major changes
Use keyring for token storage
Separate dev/prod configurations
Document custom settings

🚀 Next Steps

Set up multiple clusters in Multi-Cluster Guide
Configure notifications in Notifications Guide
Create custom themes in Theming Guide
Learn about plugins in Plugin Development