Configuration Reference

Rusty Beam uses an HTML-based configuration format with microdata attributes. This reference covers all configuration options and their usage.

Configuration Overview
Server Configuration
Virtual Hosts
Plugin Configuration
Path Configuration
Hot Reload
Complete Examples
Configuration Validation
Best Practices

Configuration Overview

Rusty Beam's configuration is stored in an HTML file using microdata attributes. This approach provides:

Human-readable format: Easy to view and edit
Self-documenting: Can include comments and documentation
Structured data: Uses standard HTML with microdata
Extensible: Plugins can define their own configuration schemas

Basic Structure

<!DOCTYPE html>
<html>
<head>
    <title>Rusty Beam Configuration</title>
</head>
<body>
    <!-- Server Configuration -->
    <table itemscope itemtype="https://rustybeam.net/schema/ServerConfig">
        <!-- Server settings -->
    </table>
    
    <!-- Virtual Hosts -->
    <ul>
        <li itemscope itemtype="https://rustybeam.net/schema/HostConfig">
            <!-- Host configuration -->
        </li>
    </ul>
</body>
</html>

Note: The configuration file must be valid HTML. Comments and additional documentation can be included without affecting functionality.

Server Configuration

The server configuration is defined using the https://rustybeam.net/schema/ServerConfig schema.

Schema Reference: ServerConfig Schema

Server Configuration Properties

Property	Type	Required	Default	Description
`bind`	String	No	"127.0.0.1"	IP address to bind to. Use "0.0.0.0" for all interfaces.
`port`	Integer	No	3000	Port number to listen on (1-65535).
`root`	String	Yes	-	Default document root directory.
`workers`	Integer	No	CPU cores	Number of worker threads.
`max-connections`	Integer	No	1000	Maximum concurrent connections.
`request-timeout`	Integer	No	30	Request timeout in seconds.

Example Server Configuration

<table itemscope itemtype="https://rustybeam.net/schema/ServerConfig">
    <tr>
        <td>Bind Address</td>
        <td itemprop="bind">0.0.0.0</td>
    </tr>
    <tr>
        <td>Port</td>
        <td itemprop="port">8080</td>
    </tr>
    <tr>
        <td>Document Root</td>
        <td itemprop="root">/var/www/html</td>
    </tr>
    <tr>
        <td>Worker Threads</td>
        <td itemprop="workers">4</td>
    </tr>
    <tr>
        <td>Max Connections</td>
        <td itemprop="max-connections">5000</td>
    </tr>
</table>

Virtual Hosts

Virtual hosts allow different configurations for different domains or paths.

Schema Reference: HostConfig Schema

Virtual Host Properties

Property	Type	Required	Description
`host`	String	Yes	Hostname pattern (e.g., "example.com", ".example.com", "")
`root`	String	No	Document root for this host (overrides server root)
`plugin`	Plugin[]	No	List of plugins for this host
`ssl-cert`	String	No	Path to SSL certificate file
`ssl-key`	String	No	Path to SSL private key file

Virtual Host Examples

Simple Virtual Host

<li itemscope itemtype="https://rustybeam.net/schema/HostConfig">
    <span itemprop="host">example.com</span>
    <span itemprop="root">/var/www/example</span>
</li>

Virtual Host with Plugins

<li itemscope itemtype="https://rustybeam.net/schema/HostConfig">
    <h3>Host: <span itemprop="host">api.example.com</span></h3>
    <p>Root: <span itemprop="root">/var/www/api</span></p>
    
    <h4>Plugins</h4>
    <ul>
        <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
            <span itemprop="library">file://./plugins/lib/cors.so</span>
            <meta itemprop="allowed-origins" content="https://example.com">
        </li>
        <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
            <span itemprop="library">file://./plugins/lib/rate-limit.so</span>
            <meta itemprop="requests-per-minute" content="60">
        </li>
    </ul>
</li>

Wildcard Host

<!-- Catch-all host -->
<li itemscope itemtype="https://rustybeam.net/schema/HostConfig">
    <span itemprop="host">*</span>
    <span itemprop="root">/var/www/default</span>
</li>

Host Matching Order: Virtual hosts are matched in the order they appear in the configuration. More specific hosts should be listed before wildcards.

Plugin Configuration

Plugins extend Rusty Beam's functionality and are configured within virtual hosts.

Schema Reference: Plugin Schema

Plugin Properties

Property	Type	Required	Description
`library`	String (URL)	Yes	Path to plugin library (e.g., "file://./plugins/lib/plugin.so")
`enabled`	Boolean	No	Whether the plugin is enabled (default: true)
`priority`	Integer	No	Plugin execution priority (lower = earlier)
Additional properties depend on the specific plugin

Plugin Configuration Examples

Basic Plugin

<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/lib/file-handler.so</span>
</li>

Plugin with Configuration

<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/lib/basic-auth.so</span>
    <meta itemprop="authfile" content="file://./config/users.html">
    <meta itemprop="realm" content="Protected Area">
    <meta itemprop="enabled" content="true">
</li>

Complex Plugin Configuration

<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/lib/cors.so</span>
    
    <!-- Multiple values using repeated meta tags -->
    <meta itemprop="allowed-origins" content="https://example.com">
    <meta itemprop="allowed-origins" content="https://api.example.com">
    
    <meta itemprop="allowed-methods" content="GET,POST,PUT,DELETE,OPTIONS">
    <meta itemprop="allowed-headers" content="Content-Type,Authorization,X-Custom">
    <meta itemprop="expose-headers" content="X-Total-Count,X-Page">
    <meta itemprop="max-age" content="3600">
    <meta itemprop="credentials" content="true">
</li>

Plugin Pipeline Order

Plugins are executed in the order they appear in the configuration. Common ordering:

Security plugins (rate limiting, IP filtering)
Authentication plugins (basic-auth, oauth)
Authorization plugins (role-based access)
Request modification (headers, redirects)
Content handling (selector-handler, compression)
File serving (file-handler)
Response modification (headers, caching)
Logging (access-log, error-log)

Path Configuration

Paths in configuration files can be specified in several ways:

Path Types

Type	Example	Description
Absolute	`/var/www/html`	Full system path
Relative	`./files`	Relative to config file directory
File URL	`file:///var/www/html`	Explicit file URL
HTTP URL	`http://example.com/config`	Remote configuration (some plugins)

Path Resolution

Relative paths are resolved from the configuration file's directory
Paths are canonicalized to prevent directory traversal
Symbolic links are followed
Non-existent paths cause startup errors

Security Note: All file paths are validated and canonicalized to prevent directory traversal attacks.

Hot Reload

Rusty Beam supports hot configuration reload without restarting the server.

Triggering Reload

# Send SIGHUP signal to the server process
kill -HUP <PID>

# The server will log:
# "Received SIGHUP signal, reloading configuration..."
# "Configuration reloaded successfully"

What Gets Reloaded

✅ Virtual host configurations
✅ Plugin configurations
✅ Plugin-specific settings (authfiles, etc.)
❌ Server bind address and port
❌ Worker thread count

Note: Some settings require a full server restart. The server will log warnings for settings that cannot be hot-reloaded.

Complete Examples

Minimal Configuration

<!DOCTYPE html>
<html>
<body>
    <table itemscope itemtype="https://rustybeam.net/schema/ServerConfig">
        <tr><td itemprop="root">./public</td></tr>
    </table>
    
    <ul>
        <li itemscope itemtype="https://rustybeam.net/schema/HostConfig">
            <span itemprop="host">*</span>
            <ul>
                <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
                    <span itemprop="library">file://./plugins/lib/file-handler.so</span>
                </li>
            </ul>
        </li>
    </ul>
</body>
</html>

Production Configuration

<!DOCTYPE html>
<html>
<head>
    <title>Production Rusty Beam Configuration</title>
</head>
<body>
    <h1>Server Configuration</h1>
    <table itemscope itemtype="https://rustybeam.net/schema/ServerConfig">
        <tr>
            <td>Bind Address</td>
            <td itemprop="bind">0.0.0.0</td>
            <td>Listen on all interfaces</td>
        </tr>
        <tr>
            <td>Port</td>
            <td itemprop="port">80</td>
            <td>Standard HTTP port</td>
        </tr>
        <tr>
            <td>Document Root</td>
            <td itemprop="root">/var/www/default</td>
            <td>Default document root</td>
        </tr>
        <tr>
            <td>Workers</td>
            <td itemprop="workers">8</td>
            <td>Worker threads</td>
        </tr>
    </table>
    
    <h2>Virtual Hosts</h2>
    <ul>
        <!-- Main website -->
        <li itemscope itemtype="https://rustybeam.net/schema/HostConfig">
            <h3>Main Site: <span itemprop="host">www.example.com</span></h3>
            <p>Document Root: <span itemprop="root">/var/www/example</span></p>
            
            <h4>Plugin Pipeline</h4>
            <ul>
                <!-- Rate limiting -->
                <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
                    <span itemprop="library">file:///usr/lib/rusty-beam/plugins/rate-limit.so</span>
                    <meta itemprop="requests-per-minute" content="100">
                    <meta itemprop="burst-size" content="20">
                </li>
                
                <!-- Security headers -->
                <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
                    <span itemprop="library">file:///usr/lib/rusty-beam/plugins/security-headers.so</span>
                    <meta itemprop="hsts-max-age" content="31536000">
                    <meta itemprop="x-frame-options" content="SAMEORIGIN">
                </li>
                
                <!-- Compression -->
                <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
                    <span itemprop="library">file:///usr/lib/rusty-beam/plugins/compression.so</span>
                    <meta itemprop="min-size" content="1024">
                    <meta itemprop="compression-level" content="6">
                </li>
                
                <!-- File serving -->
                <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
                    <span itemprop="library">file:///usr/lib/rusty-beam/plugins/file-handler.so</span>
                    <meta itemprop="index-files" content="index.html,index.htm">
                    <meta itemprop="show-hidden" content="false">
                </li>
                
                <!-- Access logging -->
                <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
                    <span itemprop="library">file:///usr/lib/rusty-beam/plugins/access-log.so</span>
                    <meta itemprop="format" content="combined">
                    <meta itemprop="log-file" content="/var/log/rusty-beam/access.log">
                </li>
            </ul>
        </li>
        
        <!-- API endpoint with authentication -->
        <li itemscope itemtype="https://rustybeam.net/schema/HostConfig">
            <h3>API: <span itemprop="host">api.example.com</span></h3>
            <p>Document Root: <span itemprop="root">/var/www/api</span></p>
            
            <h4>Plugin Pipeline</h4>
            <ul>
                <!-- CORS -->
                <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
                    <span itemprop="library">file:///usr/lib/rusty-beam/plugins/cors.so</span>
                    <meta itemprop="allowed-origins" content="https://www.example.com">
                    <meta itemprop="allowed-methods" content="GET,POST,PUT,DELETE,OPTIONS">
                    <meta itemprop="credentials" content="true">
                </li>
                
                <!-- Authentication -->
                <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
                    <span itemprop="library">file:///usr/lib/rusty-beam/plugins/basic-auth.so</span>
                    <meta itemprop="authfile" content="file:///etc/rusty-beam/api-users.html">
                    <meta itemprop="realm" content="API Access">
                </li>
                
                <!-- Authorization -->
                <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
                    <span itemprop="library">file:///usr/lib/rusty-beam/plugins/authorization.so</span>
                    <meta itemprop="policy-file" content="file:///etc/rusty-beam/api-policies.html">
                </li>
                
                <!-- Selector handler for API -->
                <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
                    <span itemprop="library">file:///usr/lib/rusty-beam/plugins/selector-handler.so</span>
                </li>
                
                <!-- File handler -->
                <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
                    <span itemprop="library">file:///usr/lib/rusty-beam/plugins/file-handler.so</span>
                </li>
            </ul>
        </li>
        
        <!-- Default/fallback host -->
        <li itemscope itemtype="https://rustybeam.net/schema/HostConfig">
            <h3>Default Host: <span itemprop="host">*</span></h3>
            <p>Handles all other requests</p>
            
            <ul>
                <!-- Redirect to main site -->
                <li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
                    <span itemprop="library">file:///usr/lib/rusty-beam/plugins/redirect.so</span>
                    <meta itemprop="redirect-to" content="https://www.example.com">
                    <meta itemprop="status-code" content="301">
                </li>
            </ul>
        </li>
    </ul>
</body>
</html>

Configuration Validation

Rusty Beam validates configuration on startup and during hot reload.

Validation Checks

HTML validity: File must be valid HTML
Schema compliance: Microdata must match schemas
Required fields: All required properties must be present
Type validation: Properties must have correct types
Path validation: File paths must exist and be accessible
Plugin validation: Plugin libraries must be loadable
Port availability: Configured port must be available

Validation Errors

Configuration errors prevent server startup:

# Example error messages
Error: Failed to load configuration from config.html
  - Missing required property 'root' in ServerConfig
  - Plugin file not found: ./plugins/lib/missing.so
  - Invalid port number: 70000 (must be 1-65535)
  - Cannot bind to 0.0.0.0:80: Permission denied

Testing Configuration

# Test configuration without starting server (dry run)
rusty-beam --test-config config.html

# Verbose output for debugging
rusty-beam -v config.html

Best Practices

Organization

Use comments: Document your configuration with HTML comments
Group related settings: Organize virtual hosts logically
Consistent formatting: Use consistent indentation and structure
Descriptive names: Use clear virtual host names

Security

Restrict bind address: Use specific IPs instead of 0.0.0.0 when possible
Secure file paths: Use absolute paths for sensitive files
Limit permissions: Ensure config files are readable only by the server user
Validate plugins: Only load trusted plugin libraries

Performance

Optimize plugin order: Place lightweight plugins first
Limit workers: Set workers based on CPU cores and load
Use specific hosts: Avoid wildcards when possible
Cache configuration: Minimize config file size and complexity

Maintenance

Version control: Keep configurations in git
Backup configs: Maintain configuration backups
Test changes: Test configuration changes before production
Document changes: Keep a changelog for configuration updates