This document covers the dynamic generation of config.toml files for Selenium Grid components, specifically focusing on browser node configuration. The generate_config script reads environment variables and browser metadata files to construct a comprehensive configuration file that defines node capabilities, stereotypes, and connection settings.
For information about environment variables that control this generation process, see Environment Variables Reference. For details on how these configuration files are used during component startup, see Component Startup and Lifecycle.
The configuration file generation system enables flexible, multi-browser node deployment through a template-based approach. Instead of requiring static configuration files, the system:
/opt/selenium/browsers/config.toml file at container startupThis approach allows a single node image to support multiple browsers with different configurations, controlled entirely through environment variables and mounted metadata files.
Sources: NodeBase/generate_config1-195
The primary configuration generator is located at NodeBase/generate_config, a bash script that executes during node initialization. The script determines the output file location:
| Variable | Default | Purpose |
|---|---|---|
CONFIG_FILE | /opt/selenium/config.toml | Destination path for generated configuration |
The script initializes by clearing any existing configuration file and then proceeds to write sections in a specific order.
Sources: NodeBase/generate_config79-85
Sources: NodeBase/generate_config79-194
The script defines a set of environment variable prefixes that support browser-specific suffixes. This array drives the backup/restore/assignment mechanism:
ENV_PREFIXES=( "SE_NODE_STEREOTYPE" "SE_NODE_BROWSER_NAME" "SE_NODE_BROWSER_VERSION" "SE_NODE_PLATFORM_NAME" "SE_BROWSER_BINARY_LOCATION" "SE_NODE_STEREOTYPE_EXTRA" "SE_NODE_MAX_SESSIONS" ) Each prefix can have three variants:
SE_NODE_BROWSER_NAME - applies to all browsers if no specific overrideSE_NODE_BROWSER_NAME_CHROME - applies only to ChromeSE_NODE_BROWSER_NAME_ORIGINAL - stores the original common valueSources: NodeBase/generate_config11-20
Sources: NodeBase/generate_config22-77
The backup_original_env_vars() function preserves the original values of common environment variables before browser-specific processing begins:
This ensures that subsequent browser iterations can inherit the original common value if no browser-specific override exists.
Sources: NodeBase/generate_config22-36
The assign_browser_specific_env_vars() function applies browser-specific overrides:
| Priority | Variable Pattern | Example | Behavior |
|---|---|---|---|
| 1 (highest) | {PREFIX}_{BROWSER} | SE_NODE_MAX_SESSIONS_FIREFOX | Overrides common value for this browser |
| 2 (fallback) | {PREFIX}_ORIGINAL | SE_NODE_MAX_SESSIONS_ORIGINAL | Inherits backed-up common value |
| 3 (default) | Variable cleared | - | If neither exists, variable is empty |
The browser name is uppercased (e.g., chrome → CHROME) to match environment variable naming conventions.
Sources: NodeBase/generate_config57-77
After each browser's configuration is written, restore_original_env_vars() resets all common variables to their original values, ensuring clean state for the next browser iteration:
Sources: NodeBase/generate_config38-55
The script discovers installed browsers by scanning /opt/selenium/browsers/:
/opt/selenium/browsers/ ├── chrome/ │ ├── name # Contains "chrome" │ ├── version # Contains "141.0.6785.5" │ └── binary_location # Contains {"se:browserBinary": "/usr/bin/google-chrome"} ├── firefox/ │ ├── name │ ├── version │ └── binary_location └── edge/ ├── name ├── version └── binary_location Each browser directory is named with the lowercase browser identifier (e.g., chrome, firefox, edge). The script uppercases this name to match environment variable suffixes.
Sources: NodeBase/generate_config134-145
For each browser directory found, the script reads up to three metadata files:
| File | Purpose | Processing | Example |
|---|---|---|---|
name | Browser identifier | Assigns to SE_NODE_BROWSER_NAME | chrome |
version | Full browser version | Converted to short version if SE_NODE_BROWSER_VERSION="stable" | 141.0.6785.5 → 141.0 |
binary_location | JSON fragment with binary path | Merged into stereotype, supports envsubst | {"se:browserBinary": "${SE_BROWSER_BINARY_LOCATION}"} |
The short_version() function truncates version strings to major.minor format by extracting the first digit of the minor version:
Sources: NodeBase/generate_config3-9 NodeBase/generate_config146-155
The config.toml file is written in sections, with conditional inclusion based on environment variables:
Sources: NodeBase/generate_config85-194
Written only if SE_EVENT_BUS_HOST is set (for distributed Grid deployments):
This section connects the node to the Grid's event bus for coordination with the Distributor and other components.
Sources: NodeBase/generate_config87-92
Defines the node's listening address:
This section is omitted entirely if both SE_NODE_HOST and SE_NODE_PORT are unset.
Sources: NodeBase/generate_config94-110
Optional configuration for network behavior:
Written only if SE_RELAX_CHECKS is set. This allows relaxed IP address validation, useful in complex networking environments.
Sources: NodeBase/generate_config112-115
Core node configuration parameters:
| Parameter | Environment Variable | Validation | Purpose |
|---|---|---|---|
grid-url | SE_NODE_GRID_URL | None | URL where the Grid Hub can be reached |
session-timeout | SE_NODE_SESSION_TIMEOUT | None | Session inactivity timeout |
override-max-sessions | SE_NODE_OVERRIDE_MAX_SESSIONS | Boolean | Whether to override max-sessions per stereotype |
max-sessions | SE_NODE_MAX_SESSIONS | Must be positive integer | Global session limit for the node |
detect-drivers | - | Always false | Disable automatic driver detection |
drain-after-session-count | DRAIN_AFTER_SESSION_COUNT or SE_DRAIN_AFTER_SESSION_COUNT | None | Sessions before node draining begins |
Sources: NodeBase/generate_config117-132
A stereotype declares the capabilities that a node offers. The Selenium Grid Distributor uses stereotypes to match incoming session requests to appropriate nodes. The stereotype is a JSON object containing standard and custom capabilities.
If SE_NODE_STEREOTYPE is not explicitly set, and the node is not relay-only, the script constructs a default stereotype:
Sources: NodeBase/generate_config159-161
If the browser's binary_location metadata file exists, its contents are merged into the stereotype using json_merge.py:
The binary_location file content is processed through envsubst, allowing environment variable substitution within the JSON.
Sources: NodeBase/generate_config152-163
The SE_NODE_STEREOTYPE_EXTRA environment variable (including browser-specific variants like SE_NODE_STEREOTYPE_EXTRA_CHROME) can inject additional capabilities:
If the merge fails (invalid JSON), the script logs a warning and continues with the unmerged stereotype.
Sources: NodeBase/generate_config167-175
For each browser with a valid stereotype, the script writes a [[node.driver-configuration]] section:
The max-sessions parameter at this level overrides the global node max-sessions for this specific browser type (only if SE_NODE_MAX_SESSIONS is a positive integer).
Sources: NodeBase/generate_config178-187
Sources: NodeBase/generate_config1-195
Consider a node with Chrome and Firefox installed:
Environment Variables:
Browser Metadata:
/opt/selenium/browsers/chrome/name: "chrome" /opt/selenium/browsers/chrome/version: "141.0.6785.5" /opt/selenium/browsers/firefox/name: "firefox" /opt/selenium/browsers/firefox/version: "143.0.0" Generated config.toml:
Note how Chrome gets max-sessions = 3 from the browser-specific override, while Firefox inherits the global max-sessions = 2.
Sources: NodeBase/generate_config126-187
The generate_config script is typically invoked by the startup scripts (e.g., start-selenium-node.sh) before launching the Selenium server. The generated config.toml is then passed to the Java process:
This ensures that the configuration reflects the current environment state at container startup, supporting dynamic reconfiguration through environment variable changes without requiring image rebuilds.
Sources: NodeBase/generate_config79-83
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.