CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-ops4j-pax-exam--pax-exam-container-karaf

Integration testing framework for OSGi applications running in Apache Karaf containers

—

Pending
Overview
Eval results
Files

security-console.mddocs/

Security and Console Configuration

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.

Capabilities

Console Configuration

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

/**
 * Create a console configuration option with default settings
 * Both local console and remote shell are enabled by default
 * @return Console configuration option for fluent setup
 */
public static KarafDistributionConfigurationConsoleOption configureConsole();

Usage Examples:

import static org.ops4j.pax.exam.karaf.options.KarafDistributionOption.*;

// Enable local console, disable remote shell
Option consoleOnly = configureConsole()
    .startLocalConsole()
    .ignoreRemoteShell();

// Disable local console, enable remote shell
Option remoteOnly = configureConsole()
    .ignoreLocalConsole()
    .startRemoteShell();

// Disable both console and remote shell
Option noConsole = configureConsole()
    .ignoreLocalConsole()
    .ignoreRemoteShell();

// Complete configuration
@Configuration
public Option[] config() {
    return new Option[] {
        karafDistributionConfiguration(),
        
        // Configure console access
        configureConsole()
            .startLocalConsole()
            .startRemoteShell(),
            
        // Enable SSH feature for remote access
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
                "ssh")
    };
}

Security Configuration

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

/**
 * Create a security configuration option with default settings
 * KarafMBeanServerBuilder is disabled by default
 * @return Security configuration option for fluent setup
 */
public static KarafDistributionConfigurationSecurityOption configureSecurity();

Usage Examples:

// Enable Karaf MBean Server Builder for RBAC
Option enableSecurity = configureSecurity()
    .enableKarafMBeanServerBuilder();

// Explicitly disable security (default behavior)
Option disableSecurity = configureSecurity()
    .disableKarafMBeanServerBuilder();

// Security configuration in test
@Configuration
public Option[] config() {
    return new Option[] {
        karafDistributionConfiguration(),
        
        // Enable JMX RBAC security
        configureSecurity()
            .enableKarafMBeanServerBuilder(),
            
        // Install management features
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
                "management")
    };
}

Configuration Option Classes

Console Configuration Option

Fluent configuration interface for Karaf console and remote shell settings.

/**
 * Console configuration option with fluent interface
 */
class KarafDistributionConfigurationConsoleOption implements Option {
    
    public KarafDistributionConfigurationConsoleOption(Boolean startLocalConsole, Boolean startRemoteShell);
    
    // Fluent configuration methods (all return this)
    public KarafDistributionConfigurationConsoleOption startLocalConsole();
    public KarafDistributionConfigurationConsoleOption ignoreLocalConsole();
    public KarafDistributionConfigurationConsoleOption startRemoteShell();
    public KarafDistributionConfigurationConsoleOption ignoreRemoteShell();
    
    // Getter methods
    public Boolean getStartLocalConsole();
    public Boolean getStartRemoteShell();
}

Usage Examples:

// Create and configure console option
KarafDistributionConfigurationConsoleOption consoleConfig = 
    configureConsole()
        .startLocalConsole()
        .ignoreRemoteShell();

// Inspect configuration
Boolean localConsole = consoleConfig.getStartLocalConsole();  // true
Boolean remoteShell = consoleConfig.getStartRemoteShell();    // false

Security Configuration Option

Fluent configuration interface for JMX RBAC security settings.

/**
 * Security configuration option for JMX RBAC
 */
class KarafDistributionConfigurationSecurityOption implements Option {
    
    public KarafDistributionConfigurationSecurityOption(Boolean enableKarafMBeanServerBuilder);
    
    // Fluent configuration methods (all return this)
    public KarafDistributionConfigurationSecurityOption enableKarafMBeanServerBuilder();
    public KarafDistributionConfigurationSecurityOption disableKarafMBeanServerBuilder();
    
    // Getter method
    public Boolean getEnableKarafMBeanServerBuilder();
}

Usage Examples:

// Create and configure security option
KarafDistributionConfigurationSecurityOption securityConfig = 
    configureSecurity()
        .enableKarafMBeanServerBuilder();

// Inspect configuration
Boolean securityEnabled = securityConfig.getEnableKarafMBeanServerBuilder(); // true

Configuration Patterns

Development Environment

Configuration for development with full access and debugging capabilities:

@Configuration
public Option[] developmentConfig() {
    return new Option[] {
        karafDistributionConfiguration(),
        
        // Full console access for development
        configureConsole()
            .startLocalConsole()
            .startRemoteShell(),
        
        // Disable security for easier debugging
        configureSecurity()
            .disableKarafMBeanServerBuilder(),
        
        // Install management and SSH features
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
                "ssh", "management", "webconsole"),
        
        // Debug configuration
        debugConfiguration("5005", true),
        keepRuntimeFolder()
    };
}

Production-like Testing

Configuration that mimics production security settings:

@Configuration
public Option[] productionTestConfig() {
    return new Option[] {
        karafDistributionConfiguration(),
        
        // Disable console access (production-like)
        configureConsole()
            .ignoreLocalConsole()
            .ignoreRemoteShell(),
        
        // Enable security features
        configureSecurity()
            .enableKarafMBeanServerBuilder(),
        
        // Minimal features for production testing
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
                "management"),
        
        // Configure security-related properties
        editConfigurationFilePut(
            "etc/users.properties",
            "admin",
            "admin,_g_:admingroup"
        )
    };
}

Remote Management Testing

Configuration for testing remote management capabilities:

@Configuration
public Option[] remoteManagementConfig() {
    return new Option[] {
        karafDistributionConfiguration(),
        
        // Enable remote shell only
        configureConsole()
            .ignoreLocalConsole()
            .startRemoteShell(),
        
        // Enable security for RBAC testing
        configureSecurity()
            .enableKarafMBeanServerBuilder(),
        
        // Management features
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
                "ssh", "management"),
        
        // Configure JMX ports
        editConfigurationFilePut(ManagementCfg.RMI_REGISTRY_PORT, "1099"),
        editConfigurationFilePut(ManagementCfg.RMI_SERVER_PORT, "44444"),
        
        // Configure SSH port
        editConfigurationFilePut(
            "etc/org.apache.karaf.shell.cfg",
            "sshPort",
            "8101"
        )
    };
}

Headless Integration Testing

Configuration for automated testing without interactive console:

@Configuration
public Option[] headlessConfig() {
    return new Option[] {
        karafDistributionConfiguration()
            .runEmbedded(true),
        
        // Disable all console access for headless operation
        configureConsole()
            .ignoreLocalConsole()
            .ignoreRemoteShell(),
        
        // Security can be enabled or disabled based on test needs
        configureSecurity()
            .disableKarafMBeanServerBuilder(),
        
        // Minimal features for headless operation
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
                "scr"),
        
        // Error-level logging for clean test output
        logLevel(LogLevel.ERROR)
    };
}

Security Integration

RBAC User Configuration

Combine security configuration with user management:

@Configuration
public Option[] rbacConfig() {
    return new Option[] {
        karafDistributionConfiguration(),
        
        // Enable RBAC security
        configureSecurity()
            .enableKarafMBeanServerBuilder(),
        
        // Configure users and roles
        editConfigurationFilePut(UsersProperties.KARAF_USER, "admin,admin,manager,viewer,systembundles,ssh"),
        
        // Add custom users
        editConfigurationFileExtend(
            "etc/users.properties",
            "testuser",
            "testpass,viewer"
        ),
        
        // Management features for RBAC
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
                "management")
    };
}

SSL/TLS Configuration

Configure secure connections for remote access:

@Configuration
public Option[] sslConfig() {
    return new Option[] {
        karafDistributionConfiguration(),
        
        // Enable remote shell with security
        configureConsole()
            .ignoreLocalConsole()
            .startRemoteShell(),
        
        configureSecurity()
            .enableKarafMBeanServerBuilder(),
        
        // SSL keystore configuration
        editConfigurationFilePut(
            "etc/org.apache.karaf.management.cfg",
            "keyStore",
            "etc/keystore.jks"
        ),
        editConfigurationFilePut(
            "etc/org.apache.karaf.management.cfg",
            "keyStorePassword",
            "karaf"
        ),
        
        // SSH features with SSL
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features",
                "ssh", "management")
    };
}

Console Access Patterns

SSH Remote Access

Configure SSH access for remote container management:

// Configure SSH with custom settings
@Configuration
public Option[] sshConfig() {
    return new Option[] {
        karafDistributionConfiguration(),
        
        configureConsole()
            .ignoreLocalConsole()  // No local console
            .startRemoteShell(),   // Enable SSH
        
        // SSH feature
        features("mvn:org.apache.karaf.features/standard/4.2.0/xml/features", "ssh"),
        
        // SSH configuration
        editConfigurationFilePut("etc/org.apache.karaf.shell.cfg", "sshPort", "8101"),
        editConfigurationFilePut("etc/org.apache.karaf.shell.cfg", "sshHost", "0.0.0.0"),
        editConfigurationFilePut("etc/org.apache.karaf.shell.cfg", "hostKey", "etc/host.key")
    };
}

Local Console Testing

Configure local console for interactive testing:

@Configuration
public Option[] localConsoleConfig() {
    return new Option[] {
        karafDistributionConfiguration(),
        
        configureConsole()
            .startLocalConsole()   // Enable local console
            .ignoreRemoteShell(),  // Disable SSH
        
        // Keep runtime for manual testing
        keepRuntimeFolder(),
        debugConfiguration()
    };
}

Error Handling

Security and console configuration handle errors for:

  • Invalid security policy configurations
  • JMX security conflicts with existing MBean servers
  • SSH port conflicts or invalid port numbers
  • Missing keystore files for SSL configuration
  • Invalid user/role configurations
  • Network binding issues for remote access
  • Console startup failures

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.

Install with Tessl CLI

npx tessl i tessl/maven-org-ops4j-pax-exam--pax-exam-container-karaf

docs

configuration-management.md

distribution-configuration.md

feature-management.md

index.md

runtime-configuration.md

security-console.md

tile.json