Client Configuration

Client Configuration

This guide covers how to configure the PVE4J client for different environments and security requirements.

Basic Client Creation

Using API Token

The simplest way to create a client with an API token:

import fr.freshperf.pve4j.Proxmox;

Proxmox proxmox = Proxmox.create(
    "pve.example.com",  // Proxmox host
    8006,               // API port
    "root@pam!mytoken=secret"  // API token
);

This uses the default secure configuration with full SSL/TLS verification.

Using Username/Password

For username/password authentication:

import fr.freshperf.pve4j.Proxmox;
import fr.freshperf.pve4j.throwable.ProxmoxAPIError;

try {
    // With default PAM realm
    Proxmox proxmox = Proxmox.createWithPassword(
        "pve.example.com",
        8006,
        "root",
        "your-password"
    );
    
    // With custom realm
    Proxmox proxmox = Proxmox.createWithPassword(
        "pve.example.com",
        8006,
        "admin",
        "password",
        "ldap",  // realm
        SecurityConfig.secure()
    );
} catch (ProxmoxAPIError | InterruptedException e) {
    System.err.println("Authentication failed: " + e.getMessage());
}

The createWithPassword() method authenticates with Proxmox and stores the session ticket for subsequent requests.

Security Configuration

PVE4J provides flexible security configuration through the SecurityConfig class.

Default Secure Configuration

The default configuration is secure and suitable for production:

Proxmox proxmox = Proxmox.create("pve.example.com", 8006, "token");
// Equivalent to:
Proxmox proxmox = Proxmox.create("pve.example.com", 8006, "token", SecurityConfig.secure());

This configuration:

• Validates SSL certificates
• Verifies hostname matches certificate
• Rejects self-signed certificates

Insecure Configuration (Development)

For development environments with self-signed certificates:

import fr.freshperf.pve4j.SecurityConfig;

Proxmox proxmox = Proxmox.create(
    "192.168.1.100",
    8006,
    "root@pam!mytoken=secret",
    SecurityConfig.insecure()
);

This configuration:

• Accepts any SSL certificate (including self-signed)
• Skips hostname verification
• Should NOT be used in production

Custom Security Configuration

For fine-grained control, use the builder pattern:

SecurityConfig customConfig = SecurityConfig.builder()
    .disableSslVerification()      // Accept any certificate
    .enableHostnameVerification()  // But still verify hostname
    .build();

Proxmox proxmox = Proxmox.create("pve.example.com", 8006, "token", customConfig);

Or inversely:

SecurityConfig customConfig = SecurityConfig.builder()
    .enableSslVerification()       // Verify certificates
    .disableHostnameVerification() // But skip hostname check
    .build();

API Token Format

Proxmox API tokens follow this format:

USER@REALM!TOKENID=SECRET

Where:

• USER - Username (e.g., root)
• REALM - Authentication realm (e.g., pam, pve)
• TOKENID - Token identifier
• SECRET - Token secret (UUID)

Example Tokens

// Root user with PAM authentication
String token = "root@pam!myapp=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

// Custom user with PVE authentication
String token = "admin@pve!automation=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy";

Connection Parameters

Host

The Proxmox host can be:

• Fully qualified domain name: pve.example.com
• Hostname: proxmox01
• IP address: 192.168.1.100

Port

Common ports:

• 8006 - Default Proxmox web interface port (HTTPS)
• 443 - Alternative HTTPS port if configured

Protocol

PVE4J always uses HTTPS. The protocol is automatically added to the host.

Environment-Specific Configurations

Production Configuration

public class ProxmoxConfig {
    public static Proxmox createProductionClient() {
        return Proxmox.create(
            System.getenv("PROXMOX_HOST"),
            Integer.parseInt(System.getenv("PROXMOX_PORT")),
            System.getenv("PROXMOX_TOKEN"),
            SecurityConfig.secure()
        );
    }
}

Use environment variables for sensitive configuration:

export PROXMOX_HOST=pve.example.com
export PROXMOX_PORT=8006
export PROXMOX_TOKEN=root@pam!mytoken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Development Configuration

public class ProxmoxConfig {
    public static Proxmox createDevClient() {
        return Proxmox.create(
            "localhost",
            8006,
            "root@pam!dev=dev-token",
            SecurityConfig.insecure()
        );
    }
}

Testing Configuration

For integration tests:

import org.junit.jupiter.api.BeforeAll;

public class ProxmoxIntegrationTest {
    private static Proxmox proxmox;
    
    @BeforeAll
    public static void setup() {
        String host = System.getProperty("test.proxmox.host", "localhost");
        int port = Integer.parseInt(System.getProperty("test.proxmox.port", "8006"));
        String token = System.getProperty("test.proxmox.token");
        
        proxmox = Proxmox.create(host, port, token, SecurityConfig.insecure());
    }
}

Run tests with:

./gradlew test -Dtest.proxmox.host=192.168.1.100 \
               -Dtest.proxmox.port=8006 \
               -Dtest.proxmox.token="root@pam!test=secret"

HTTP Client Configuration

PVE4J uses Java's built-in HttpClient under the hood. The client is automatically configured with:

• Connection timeout: Default system timeout
• Request timeout: No timeout (long-running tasks are supported)
• SSL context: Based on SecurityConfig

Connection Pooling

The Proxmox client can be reused across multiple requests. Create one instance and share it:

public class ProxmoxManager {
    private static final Proxmox INSTANCE = Proxmox.create(
        System.getenv("PROXMOX_HOST"),
        Integer.parseInt(System.getenv("PROXMOX_PORT")),
        System.getenv("PROXMOX_TOKEN")
    );
    
    public static Proxmox getInstance() {
        return INSTANCE;
    }
}

Shutdown

When you're done using PVE4J, shut down global resources (thread pools for async task management):

Proxmox.shutdownGlobalResources();

Troubleshooting

SSL Certificate Validation Failures

Symptom: SSLHandshakeException or certificate validation errors

Solutions:

1. Ensure you're using a valid SSL certificate in production
2. For self-signed certificates, use SecurityConfig.insecure() (development only)
3. Import the self-signed certificate into Java's trust store

Hostname Verification Failures

Symptom: Hostname verification errors

Solutions:

1. Ensure your certificate includes the correct hostname/IP
2. Use the hostname that matches the certificate
3. Temporarily disable hostname verification for testing (not recommended for production)

Connection Timeout

Symptom: Connection takes too long or times out

Solutions:

1. Verify network connectivity to Proxmox host
2. Check firewall rules
3. Ensure Proxmox API is running (port 8006 accessible)

Next Steps

• Authentication - Detailed authentication guide
• Request API - Understanding the request API
• Getting Started - Basic usage examples