Configuration

Configuration

ohProxy uses a layered configuration system:

• config.defaults.js - Built-in defaults (don't modify)
• config.local.js - Your local overrides (deep-merged with defaults)
• Environment variables - Override sensitive values

Config Reload: Live config reload + auto-restart on config.local.js changes.

Server Configuration

module.exports = {
  server: {
    http: {
      enabled: true,
      host: '0.0.0.0',
      port: 9080,
    },
    https: {
      enabled: true,
      http2: false,
      host: '0.0.0.0',
      port: 9443,
      certFile: '/path/to/fullchain.pem',
      keyFile: '/path/to/privkey.pem',
    },
    openhab: {
      target: 'http://localhost:8080',
      // For openHAB 1.x/2.x: use Basic Auth
      user: '',  // or use OH_USER env var
      pass: '',  // or use OH_PASS env var
      // For openHAB 3.x/4.x: use API token (takes precedence over user/pass)
      apiToken: '',  // or use OH_API_TOKEN env var
    },
    allowSubnets: ['192.168.1.0/24', '10.0.0.0/8'],
    proxyAllowlist: ['camera.local:8080', 'example.com'],
  },
};

Note: For openHAB 3.x/4.x, generate an API token via the openHAB UI: Settings > API Security > Create new API token.

Authentication Configuration

module.exports = {
  server: {
    auth: {
      mode: 'basic',                     // 'basic' or 'html' (form login)
      realm: 'openHAB Proxy',            // Basic auth realm (basic mode only)
      cookieName: 'AuthStore',
      cookieDays: 365,                   // >0 required when cookieKey is set
      cookieKey: 'your-secret-key-here', // HMAC signing key
      authFailNotifyCmd: '/path/to/notify.sh {IP}',  // Optional
      authFailNotifyIntervalMins: 15,    // Optional rate limit
    },
    sessionMaxAgeDays: 14,               // Session cleanup threshold
  },
};

Note: Users are managed via the users-cli.js utility (see CLI Tools), not via config files.

Security Headers Configuration

module.exports = {
  server: {
    securityHeaders: {
      enabled: true,
      hsts: {
        enabled: true,
        maxAge: 31536000,
        includeSubDomains: true,
        preload: false,
      },
      csp: {
        enabled: true,
        reportOnly: false,
        policy: "default-src 'self'; img-src 'self' data: https: blob:; ...",
      },
      referrerPolicy: 'same-origin',
    },
  },
};

WebSocket Configuration

module.exports = {
  server: {
    websocket: {
      // Mode options:
      // - 'polling': Works with ANY openHAB version (universal fallback)
      // - 'atmosphere': openHAB 1.x/2.x real-time via Atmosphere long-polling
      // - 'sse': openHAB 3.x/4.x real-time via Server-Sent Events
      mode: 'polling',
      pollingIntervalMs: 500,    // Active polling interval
      pollingIntervalBgMs: 2000, // Background polling interval
    },
  },
};

Recommended modes by openHAB version:

• openHAB 1.x/2.x: Use 'atmosphere' for real-time updates, or 'polling' as fallback
• openHAB 3.x/4.x: Use 'sse' for real-time updates, or 'polling' as fallback

MySQL Configuration

ohProxy can optionally connect to a MySQL database to power additional features like the GPS presence map.

module.exports = {
  server: {
    mysql: {
      socket: '/run/mysqld/mysqld.sock',  // Unix socket (if set, host/port ignored)
      host: '',                            // MySQL host (alternative to socket)
      port: '',                            // MySQL port (default: 3306)
      database: 'openhab',                 // Database name
      username: 'openhab',                 // MySQL username
      password: 'openhab',                 // MySQL password
    },
  },
};

Connection options:

• Use socket for local MySQL connections via Unix socket (recommended for performance)
• Use host and port for TCP connections (remote or local)
• If socket is set, host and port are ignored

Logging:

• [MySQL] Connecting to {target}... - Connection attempt
• [MySQL] Connection to {target} established - Successful connection
• [MySQL] Connection to {target} failed: {error} - Connection failure
• [MySQL] Reconnecting to {target} in 5s... - Auto-reconnect scheduled

If no socket or host is configured, the MySQL worker remains dormant.

Client Configuration

module.exports = {
  client: {
    // Sections that display glow effects based on valueColor
    glowSections: ['Cameras', 'Device Information'],

    // State-based glow colors for specific sections
    stateGlowSections: [
      {
        section: 'Door Sensors',
        states: { Closed: 'green', Open: 'red' }
      },
    ],

    // Polling intervals (ms)
    pollIntervalsMs: {
      default: { active: 2000, idle: 10000 },
      slim: { active: 10000, idle: 20000 },
    },

    // UI timing (ms)
    pageFadeOutMs: 250,
    pageFadeInMs: 250,
    loadingDelayMs: 1000,
    idleAfterMs: 60000,

    // Image settings
    minImageRefreshMs: 5000,
    imageLoadTimeoutMs: 15000,

    // Hide titles for specific items
    hideTitleItems: ['Clock', 'Weather_Icon'],
  },
};

Asset Versioning

Update these versions to bust browser caches after changes:

module.exports = {
  server: {
    assets: {
      jsVersion: 'v274',
      cssVersion: 'v229',
      appleTouchIconVersion: 'v200',
      iconVersion: 'v3',
    },
  },
};

Environment Variables

Variable	Description
OH_TARGET	openHAB target URL
OH_USER	openHAB basic auth username (OH 1.x/2.x)
OH_PASS	openHAB basic auth password (OH 1.x/2.x)
OH_API_TOKEN	openHAB API token (OH 3.x/4.x, takes precedence)
ICON_VERSION	override icon cache version
USER_AGENT	override proxy User-Agent
PROXY_LOG_LEVEL	override proxy middleware log level
LOG_FILE	override server log file path
ACCESS_LOG	override access log file path
ACCESS_LOG_LEVEL	override access log verbosity (all or 400+)
SITEMAP_REFRESH_MS	override sitemap refresh interval (ms)