0
# Configuration Management
1

2
The Selenium Grid server provides a flexible configuration system supporting multiple sources with well-defined precedence rules for enterprise deployment scenarios.
3

4
## Capabilities
5

6
### Configuration Interface
7

8
Core interface for accessing configuration values throughout the Grid server.
9

10
```java { .api }
11
package org.openqa.selenium.grid.config;
12

13
import java.util.Optional;
14

15
interface Config {
16
    /**
17
     * Get configuration value as Optional string
18
     * @param section Configuration section name
19
     * @param option Configuration option name
20
     * @return Optional containing value if present
21
     */
22
    Optional<String> get(String section, String option);
23
    
24
    /**
25
     * Get configuration value as Optional integer
26
     * @param section Configuration section name
27
     * @param option Configuration option name
28
     * @return Optional containing integer value if present and parseable
29
     */
30
    default Optional<Integer> getInt(String section, String option) {
31
        return get(section, option).map(Integer::parseInt);
32
    }
33
    
34
    /**
35
     * Get configuration value as Optional boolean
36
     * @param section Configuration section name
37
     * @param option Configuration option name
38
     * @return Optional containing boolean value if present and parseable
39
     */
40
    default Optional<Boolean> getBool(String section, String option) {
41
        return get(section, option).map(Boolean::parseBoolean);
42
    }
43
}
44
```
45

46
### Configuration Sources
47

48
Configuration sources are applied in order of precedence (highest to lowest):
49

50
```java { .api }
51
// Precedence order (1 = highest priority)
52
1. AnnotatedConfig     // From @ConfigValue annotations on flag classes
53
2. EnvConfig          // Environment variables (section.option format)
54
3. ConcatenatingConfig // System properties (selenium.section.option format)
55
4. CompoundConfig     // Combines multiple configuration sources
56
```
57

58
#### Environment Variables
59

60
Set configuration using environment variables with section.option format:
61

62
```bash { .api }
63
# Environment variable format
64
export section.option=value
65

66
# Examples
67
export server.port=4444
68
export server.hostname=grid-hub.example.com
69
export node.detect-drivers=true
70
export distributor.port=5553
71
```
72

73
#### System Properties
74

75
Set configuration using Java system properties with selenium prefix:
76

77
```bash { .api }
78
# System property format
79
-Dselenium.section.option=value
80

81
# Examples
82
java -Dselenium.server.port=4444 -jar selenium-server.jar standalone
83
java -Dselenium.node.detect-drivers=true -jar selenium-server.jar node
84
```
85

86
### Configuration Sections
87

88
#### Server Section
89

90
Basic server configuration options available for all components.
91

92
```java { .api }
93
// server section options
94
server.hostname         // Server hostname or IP address
95
server.port            // Port number to listen on
96
server.max-threads     // Maximum number of Jetty threads
97
```
98

99
**Examples:**
100
```bash
101
# Environment variables
102
export server.hostname=0.0.0.0
103
export server.port=4444
104
export server.max-threads=200
105

106
# System properties
107
-Dselenium.server.hostname=grid-hub.local
108
-Dselenium.server.port=4445
109
```
110

111
#### Distributor Section
112

113
Configuration specific to the distributor component.
114

115
```java { .api }
116
// distributor section options
117
distributor.host        // Distributor URI or hostname
118
distributor.port       // Distributor port number
119
distributor.hostname   // Distributor hostname
120
```
121

122
**Examples:**
123
```bash
124
# Environment variables
125
export distributor.host=http://distributor-service:5553
126
export distributor.port=5553
127
export distributor.hostname=distributor.grid.local
128

129
# System properties
130
-Dselenium.distributor.host=http://localhost:5553
131
-Dselenium.distributor.port=5553
132
```
133

134
#### Sessions Section
135

136
Configuration for the session map component.
137

138
```java { .api }
139
// sessions section options
140
sessions.host          // Session map URI or hostname
141
sessions.port         // Session map port number
142
sessions.hostname     // Session map hostname
143
```
144

145
**Examples:**
146
```bash
147
# Environment variables
148
export sessions.host=http://sessions-service:5556
149
export sessions.port=5556
150
export sessions.hostname=sessions.grid.local
151

152
# System properties
153
-Dselenium.sessions.host=http://localhost:5556
154
-Dselenium.sessions.port=5556
155
```
156

157
#### Node Section
158

159
Configuration specific to node components.
160

161
```java { .api }
162
// node section options
163
node.detect-drivers    // Boolean flag to auto-detect available drivers
164
```
165

166
**Examples:**
167
```bash
168
# Environment variables
169
export node.detect-drivers=true
170

171
# System properties
172
-Dselenium.node.detect-drivers=true
173
```
174

175
### Configuration Options Classes
176

177
The configuration system uses specific option classes for type-safe configuration access.
178

179
#### BaseServerOptions
180

181
Base server configuration options used by all server components.
182

183
```java { .api }
184
class BaseServerOptions {
185
    // Server hostname (defaults to auto-detected)
186
    String getHostname();
187
    
188
    // Server port number
189
    int getPort();
190
    
191
    // Maximum Jetty threads
192
    int getMaxThreads();
193
}
194
```
195

196
#### SessionMapOptions
197

198
Configuration options specific to session map components.
199

200
```java { .api }
201
class SessionMapOptions {
202
    // Session map service URI
203
    URI getSessionMap();
204
    
205
    // Session map hostname
206
    String getSessionMapHost();
207
    
208
    // Session map port
209
    int getSessionMapPort();
210
}
211
```
212

213
#### DistributorOptions
214

215
Configuration options for distributor components.
216

217
```java { .api }
218
class DistributorOptions {
219
    // Distributor service URI
220
    URI getDistributor();
221
    
222
    // Distributor hostname
223
    String getDistributorHost();
224
    
225
    // Distributor port
226
    int getDistributorPort();
227
}
228
```
229

230
### Configuration Examples
231

232
#### Standalone Server Configuration
233

234
```bash
235
# Using environment variables
236
export server.port=4440
237
export server.hostname=192.168.1.100
238
export node.detect-drivers=true
239

240
java -jar selenium-server.jar standalone
241
```
242

243
```bash
244
# Using system properties
245
java -Dselenium.server.port=4440 \
246
     -Dselenium.server.hostname=192.168.1.100 \
247
     -Dselenium.node.detect-drivers=true \
248
     -jar selenium-server.jar standalone
249
```
250

251
#### Distributed Setup Configuration
252

253
Hub configuration:
254
```bash
255
# Hub server
256
export server.port=4444
257
export server.hostname=hub.grid.local
258

259
java -jar selenium-server.jar hub
260
```
261

262
Node configuration:
263
```bash
264
# Node server
265
export server.port=5555
266
export distributor.host=http://hub.grid.local:4444
267
export sessions.host=http://hub.grid.local:4444
268
export node.detect-drivers=true
269

270
java -jar selenium-server.jar node
271
```
272

273
#### Microservices Configuration
274

275
Router service:
276
```bash
277
export server.port=4444
278
java -jar selenium-server.jar router
279
```
280

281
Distributor service:
282
```bash
283
export server.port=5553
284
java -jar selenium-server.jar distributor
285
```
286

287
Session map service:
288
```bash
289
export server.port=5556
290
java -jar selenium-server.jar sessions
291
```
292

293
Node service:
294
```bash
295
export server.port=5555
296
export distributor.host=http://distributor-host:5553
297
export sessions.host=http://sessions-host:5556
298
java -jar selenium-server.jar node
299
```
300

301
### Default Values
302

303
When no configuration is provided, the system uses these defaults:
304

305
```java { .api }
306
// Default configuration values
307
server.hostname = "0.0.0.0"      // Listen on all interfaces
308
server.port = 4444               // Standard Selenium port (hub/router/standalone)
309
server.port = 5555               // Standard node port
310
server.port = 5553               // Standard distributor port  
311
server.port = 5556               // Standard session map port
312
node.detect-drivers = false      // Manual driver configuration
313
```
314

315
### Configuration Validation
316

317
The configuration system validates values at startup and provides clear error messages for invalid configurations:
318

319
```java { .api }
320
// Common validation errors
321
"Invalid port number: must be between 1 and 65535"
322
"Invalid hostname format"
323
"Cannot connect to distributor at specified URI"
324
"Required configuration option not provided: distributor.host"
325
```