Skip to main content

Custom Settings Configuration

Stirling PDF provides a /configs/custom_settings.yml file where users can configure additional settings beyond the standard configuration. This file follows standard YAML format and supports Spring Boot application properties, allowing you to customize the application without modifying core files.

Logging Configuration​

Control the verbosity of logs by adjusting log levels for different components:

logging:
  level:
    root: INFO
    org.springframework: WARN
    org.hibernate: WARN
    org.eclipse.jetty: WARN
    stirling.software.SPDF: INFO
    # Enable debug logging for specific components when troubleshooting
    # org.springframework.security.saml2: TRACE
    # org.springframework.security: DEBUG
    # org.opensaml: DEBUG

Server Configuration​

Configure server behavior including port, address binding, and session timeout:

server:
  port: 8080  # Default port
  address: 0.0.0.0  # Bind to all interfaces
  servlet:
    context-path: /  # Application context path
    session:
      timeout: 30m  # Session timeout
  jetty:
    threads:
      max: 200  # Maximum number of request processing threads
      min: 10   # Minimum number of threads always kept running
    connection-idle-timeout: 30000  # Connection idle timeout in milliseconds
    max-http-request-header-size: 65536  # Maximum size of request headers in bytes

HTTP 431 "Request Header Fields Too Large" during SSO/OAuth login​

Some SSO/OAuth providers send very large request headers (for example, large cookies or JWTs), which can trigger an HTTP 431 Request Header Fields Too Large error during login. Stirling PDF's default limit is 32768 (32 KB); raise it to resolve the error.

server:
  jetty:
    max-http-request-header-size: 65536  # bytes (Stirling default: 32768)

Raise the value further (for example 131072) if the error persists, then restart Stirling PDF.

SSL/TLS Configuration​

Configure HTTPS for secure connections:

server:
  port: 8443  # Standard HTTPS port
  ssl:
    enabled: true
    key-store: classpath:keystore.p12  # Path to keystore file
    key-store-password: your-keystore-password
    key-store-type: PKCS12  # Type of keystore
    key-alias: tomcat  # Alias of the certificate

Creating a Self-Signed Certificate​

To generate a self-signed certificate for development or testing:

keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore keystore.p12 -validity 365

⚠️ Note​

For production use, it's recommended to use a certificate from a trusted Certificate Authority.

Configuration Examples​

Basic Configuration​

A simple configuration that changes the port and adjusts logging levels:

# custom_settings.yml
server:
  port: 9000

logging:
  level:
    root: INFO
    org.springframework: WARN
    org.hibernate: WARN
    stirling.software.SPDF: INFO

HTTPS Configuration​

Enable HTTPS with a custom certificate:

# custom_settings.yml
server:
  port: 8443
  ssl:
    enabled: true
    key-store: classpath:keystore.p12
    key-store-password: your-keystore-password
    key-store-type: PKCS12
    key-alias: tomcat

logging:
  level:
    root: INFO
    org.springframework: WARN

Troubleshooting Common Issues​

Authentication Issues​

Increase security logging to diagnose authentication problems:

logging:
  level:
    org.springframework.security: DEBUG
    stirling.software.SPDF.config.security: DEBUG

SAML/OAuth Issues​

Increase SAML-related logging for SSO troubleshooting:

logging:
  level:
    org.springframework.security.saml2: TRACE
    org.springframework.security.oauth2: DEBUG
    org.opensaml: DEBUG

General Application Issues​

For general application issues:

logging:
  level:
    stirling.software.SPDF: DEBUG

⚠️ Note​

Debug-level logging can significantly increase log volume and may impact performance in production environments. Return logging to normal levels after troubleshooting.

x