0
# Security and Console Configuration
1

2
Configuration of Karaf security features and console access, including JMX RBAC security, remote shell configuration, and local console management. This capability provides fine-grained control over access mechanisms and security policies for test environments.
3

4
## Capabilities
5

6
### Console Configuration
7

8
Configure Karaf's local console and remote shell access for test containers.
9

10
```java { .api }
11
/**
12
 * Create a console configuration option with default settings
13
 * Both local console and remote shell are enabled by default
14
 * @return Console configuration option for fluent setup
15
 */
16
public static KarafDistributionConfigurationConsoleOption configureConsole();
17
```
18

19
**Usage Examples:**
20

21
```java
22
import static org.ops4j.pax.exam.karaf.options.KarafDistributionOption.*;
23

24
// Enable local console, disable remote shell
25
Option consoleOnly = configureConsole()
26
    .startLocalConsole()
27
    .ignoreRemoteShell();
28

29
// Disable local console, enable remote shell
30
Option remoteOnly = configureConsole()
31
    .ignoreLocalConsole()
32
    .startRemoteShell();
33

34
// Disable both console and remote shell
35
Option noConsole = configureConsole()
36
    .ignoreLocalConsole()
37
    .ignoreRemoteShell();
38

39
// Complete configuration
40
@Configuration
41
public Option[] config() {
42
    return new Option[] {
43
        karafDistributionConfiguration(),
44
        
45
        // Configure console access
46
        configureConsole()
47
            .startLocalConsole()
48
            .startRemoteShell(),
49
            
50
        // Enable SSH feature for remote access
51
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
52
                "ssh")
53
    };
54
}
55
```
56

57
### Security Configuration
58

59
Configure Karaf's JMX RBAC security features, particularly the KarafMBeanServerBuilder for secure JMX operation.
60

61
```java { .api }
62
/**
63
 * Create a security configuration option with default settings
64
 * KarafMBeanServerBuilder is disabled by default
65
 * @return Security configuration option for fluent setup
66
 */
67
public static KarafDistributionConfigurationSecurityOption configureSecurity();
68
```
69

70
**Usage Examples:**
71

72
```java
73
// Enable Karaf MBean Server Builder for RBAC
74
Option enableSecurity = configureSecurity()
75
    .enableKarafMBeanServerBuilder();
76

77
// Explicitly disable security (default behavior)
78
Option disableSecurity = configureSecurity()
79
    .disableKarafMBeanServerBuilder();
80

81
// Security configuration in test
82
@Configuration
83
public Option[] config() {
84
    return new Option[] {
85
        karafDistributionConfiguration(),
86
        
87
        // Enable JMX RBAC security
88
        configureSecurity()
89
            .enableKarafMBeanServerBuilder(),
90
            
91
        // Install management features
92
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
93
                "management")
94
    };
95
}
96
```
97

98
## Configuration Option Classes
99

100
### Console Configuration Option
101

102
Fluent configuration interface for Karaf console and remote shell settings.
103

104
```java { .api }
105
/**
106
 * Console configuration option with fluent interface
107
 */
108
class KarafDistributionConfigurationConsoleOption implements Option {
109
    
110
    public KarafDistributionConfigurationConsoleOption(Boolean startLocalConsole, Boolean startRemoteShell);
111
    
112
    // Fluent configuration methods (all return this)
113
    public KarafDistributionConfigurationConsoleOption startLocalConsole();
114
    public KarafDistributionConfigurationConsoleOption ignoreLocalConsole();
115
    public KarafDistributionConfigurationConsoleOption startRemoteShell();
116
    public KarafDistributionConfigurationConsoleOption ignoreRemoteShell();
117
    
118
    // Getter methods
119
    public Boolean getStartLocalConsole();
120
    public Boolean getStartRemoteShell();
121
}
122
```
123

124
**Usage Examples:**
125

126
```java
127
// Create and configure console option
128
KarafDistributionConfigurationConsoleOption consoleConfig = 
129
    configureConsole()
130
        .startLocalConsole()
131
        .ignoreRemoteShell();
132

133
// Inspect configuration
134
Boolean localConsole = consoleConfig.getStartLocalConsole();  // true
135
Boolean remoteShell = consoleConfig.getStartRemoteShell();    // false
136
```
137

138
### Security Configuration Option
139

140
Fluent configuration interface for JMX RBAC security settings.
141

142
```java { .api }
143
/**
144
 * Security configuration option for JMX RBAC
145
 */
146
class KarafDistributionConfigurationSecurityOption implements Option {
147
    
148
    public KarafDistributionConfigurationSecurityOption(Boolean enableKarafMBeanServerBuilder);
149
    
150
    // Fluent configuration methods (all return this)
151
    public KarafDistributionConfigurationSecurityOption enableKarafMBeanServerBuilder();
152
    public KarafDistributionConfigurationSecurityOption disableKarafMBeanServerBuilder();
153
    
154
    // Getter method
155
    public Boolean getEnableKarafMBeanServerBuilder();
156
}
157
```
158

159
**Usage Examples:**
160

161
```java
162
// Create and configure security option
163
KarafDistributionConfigurationSecurityOption securityConfig = 
164
    configureSecurity()
165
        .enableKarafMBeanServerBuilder();
166

167
// Inspect configuration
168
Boolean securityEnabled = securityConfig.getEnableKarafMBeanServerBuilder(); // true
169
```
170

171
## Configuration Patterns
172

173
### Development Environment
174

175
Configuration for development with full access and debugging capabilities:
176

177
```java
178
@Configuration
179
public Option[] developmentConfig() {
180
    return new Option[] {
181
        karafDistributionConfiguration(),
182
        
183
        // Full console access for development
184
        configureConsole()
185
            .startLocalConsole()
186
            .startRemoteShell(),
187
        
188
        // Disable security for easier debugging
189
        configureSecurity()
190
            .disableKarafMBeanServerBuilder(),
191
        
192
        // Install management and SSH features
193
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
194
                "ssh", "management", "webconsole"),
195
        
196
        // Debug configuration
197
        debugConfiguration("5005", true),
198
        keepRuntimeFolder()
199
    };
200
}
201
```
202

203
### Production-like Testing
204

205
Configuration that mimics production security settings:
206

207
```java
208
@Configuration
209
public Option[] productionTestConfig() {
210
    return new Option[] {
211
        karafDistributionConfiguration(),
212
        
213
        // Disable console access (production-like)
214
        configureConsole()
215
            .ignoreLocalConsole()
216
            .ignoreRemoteShell(),
217
        
218
        // Enable security features
219
        configureSecurity()
220
            .enableKarafMBeanServerBuilder(),
221
        
222
        // Minimal features for production testing
223
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
224
                "management"),
225
        
226
        // Configure security-related properties
227
        editConfigurationFilePut(
228
            "etc/users.properties",
229
            "admin",
230
            "admin,_g_:admingroup"
231
        )
232
    };
233
}
234
```
235

236
### Remote Management Testing
237

238
Configuration for testing remote management capabilities:
239

240
```java
241
@Configuration
242
public Option[] remoteManagementConfig() {
243
    return new Option[] {
244
        karafDistributionConfiguration(),
245
        
246
        // Enable remote shell only
247
        configureConsole()
248
            .ignoreLocalConsole()
249
            .startRemoteShell(),
250
        
251
        // Enable security for RBAC testing
252
        configureSecurity()
253
            .enableKarafMBeanServerBuilder(),
254
        
255
        // Management features
256
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
257
                "ssh", "management"),
258
        
259
        // Configure JMX ports
260
        editConfigurationFilePut(ManagementCfg.RMI_REGISTRY_PORT, "1099"),
261
        editConfigurationFilePut(ManagementCfg.RMI_SERVER_PORT, "44444"),
262
        
263
        // Configure SSH port
264
        editConfigurationFilePut(
265
            "etc/org.apache.karaf.shell.cfg",
266
            "sshPort",
267
            "8101"
268
        )
269
    };
270
}
271
```
272

273
### Headless Integration Testing
274

275
Configuration for automated testing without interactive console:
276

277
```java
278
@Configuration
279
public Option[] headlessConfig() {
280
    return new Option[] {
281
        karafDistributionConfiguration()
282
            .runEmbedded(true),
283
        
284
        // Disable all console access for headless operation
285
        configureConsole()
286
            .ignoreLocalConsole()
287
            .ignoreRemoteShell(),
288
        
289
        // Security can be enabled or disabled based on test needs
290
        configureSecurity()
291
            .disableKarafMBeanServerBuilder(),
292
        
293
        // Minimal features for headless operation
294
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
295
                "scr"),
296
        
297
        // Error-level logging for clean test output
298
        logLevel(LogLevel.ERROR)
299
    };
300
}
301
```
302

303
## Security Integration
304

305
### RBAC User Configuration
306

307
Combine security configuration with user management:
308

309
```java
310
@Configuration
311
public Option[] rbacConfig() {
312
    return new Option[] {
313
        karafDistributionConfiguration(),
314
        
315
        // Enable RBAC security
316
        configureSecurity()
317
            .enableKarafMBeanServerBuilder(),
318
        
319
        // Configure users and roles
320
        editConfigurationFilePut(UsersProperties.KARAF_USER, "admin,admin,manager,viewer,systembundles,ssh"),
321
        
322
        // Add custom users
323
        editConfigurationFileExtend(
324
            "etc/users.properties",
325
            "testuser",
326
            "testpass,viewer"
327
        ),
328
        
329
        // Management features for RBAC
330
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
331
                "management")
332
    };
333
}
334
```
335

336
### SSL/TLS Configuration
337

338
Configure secure connections for remote access:
339

340
```java
341
@Configuration
342
public Option[] sslConfig() {
343
    return new Option[] {
344
        karafDistributionConfiguration(),
345
        
346
        // Enable remote shell with security
347
        configureConsole()
348
            .ignoreLocalConsole()
349
            .startRemoteShell(),
350
        
351
        configureSecurity()
352
            .enableKarafMBeanServerBuilder(),
353
        
354
        // SSL keystore configuration
355
        editConfigurationFilePut(
356
            "etc/org.apache.karaf.management.cfg",
357
            "keyStore",
358
            "etc/keystore.jks"
359
        ),
360
        editConfigurationFilePut(
361
            "etc/org.apache.karaf.management.cfg",
362
            "keyStorePassword",
363
            "karaf"
364
        ),
365
        
366
        // SSH features with SSL
367
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
368
                "ssh", "management")
369
    };
370
}
371
```
372

373
## Console Access Patterns
374

375
### SSH Remote Access
376

377
Configure SSH access for remote container management:
378

379
```java
380
// Configure SSH with custom settings
381
@Configuration
382
public Option[] sshConfig() {
383
    return new Option[] {
384
        karafDistributionConfiguration(),
385
        
386
        configureConsole()
387
            .ignoreLocalConsole()  // No local console
388
            .startRemoteShell(),   // Enable SSH
389
        
390
        // SSH feature
391
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features", "ssh"),
392
        
393
        // SSH configuration
394
        editConfigurationFilePut("etc/org.apache.karaf.shell.cfg", "sshPort", "8101"),
395
        editConfigurationFilePut("etc/org.apache.karaf.shell.cfg", "sshHost", "0.0.0.0"),
396
        editConfigurationFilePut("etc/org.apache.karaf.shell.cfg", "hostKey", "etc/host.key")
397
    };
398
}
399
```
400

401
### Local Console Testing
402

403
Configure local console for interactive testing:
404

405
```java
406
@Configuration
407
public Option[] localConsoleConfig() {
408
    return new Option[] {
409
        karafDistributionConfiguration(),
410
        
411
        configureConsole()
412
            .startLocalConsole()   // Enable local console
413
            .ignoreRemoteShell(),  // Disable SSH
414
        
415
        // Keep runtime for manual testing
416
        keepRuntimeFolder(),
417
        debugConfiguration()
418
    };
419
}
420
```
421

422
## Error Handling
423

424
Security and console configuration handle errors for:
425
- Invalid security policy configurations
426
- JMX security conflicts with existing MBean servers
427
- SSH port conflicts or invalid port numbers
428
- Missing keystore files for SSL configuration
429
- Invalid user/role configurations
430
- Network binding issues for remote access
431
- Console startup failures
432

433
Configuration errors are typically detected during container startup and will cause test failures with specific error messages about security policy violations or network binding issues.