### PVE4J QEMU VM Start Method

Source: https://github.com/freshperf/pve4j/wiki/Contributing

Example of a method to start a QEMU virtual machine using the Proxmox API client.

```java
public class PveQemuVm {
    private final ProxmoxHttpClient client;
    private final String nodeName;
    private final int vmid;
    
    public ProxmoxRequest<PveTask> start() {
        return new ProxmoxRequest<>(() ->
            client.post("nodes/" + nodeName + "/qemu/" + vmid + "/status/start")
                .transformer(new TaskResponseTransformer())
                .execute(PveTask.class)
        );
    }
}
```

--------------------------------

### start()

Source: https://github.com/freshperf/pve4j/wiki/Container-Management

Starts a specific LXC container.

```APIDOC
## Method: start()

### Description
Initiates the startup sequence for a specified LXC container.

### Signature
`proxmox.getNodes().get(nodeId).getLxc().get(ctid).start().waitForCompletion(proxmox).execute()`

### Returns
- Executes the start command and waits for the operation to complete.
```

--------------------------------

### Start a Virtual Machine

Source: https://github.com/freshperf/pve4j/wiki/Getting-Started

Initiates a start command for a specific VM and waits for the task to complete.

```java
import fr.freshperf.pve4j.entities.PveTask;

try {
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .start()
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("VM started successfully!");
    System.out.println("Task UPID: " + task.getUpid());
} catch (ProxmoxAPIError | InterruptedException e) {
    System.err.println("Failed to start VM: " + e.getMessage());
}
```

--------------------------------

### JavaDoc for Start Method

Source: https://github.com/freshperf/pve4j/wiki/Contributing

Example of JavaDoc comments for a public API method, explaining its purpose and return value.

```java
/**
 * Starts the virtual machine. 
 * 
 * @return ProxmoxRequest that executes the start operation and returns a PveTask
 */
public ProxmoxRequest<PveTask> start() {
    // implementation
}
```

--------------------------------

### Conditional Request Chains

Source: https://github.com/freshperf/pve4j/wiki/Request-API

Demonstrates a multi-step workflow for cloning, updating, and starting a VM.

```java
public class VMWorkflow {
    
    public void deployVM(Proxmox proxmox, int templateId, int newVmid) 
            throws ProxmoxAPIError, InterruptedException {
        
        // Clone from template
        proxmox.getNodes()
                .get("pve-node-01")
                .getQemu()
                .get(templateId)
                .cloneVm(newVmid)
                .waitForCompletion(proxmox)
                .execute();
        
        // Update configuration
        PveQemuConfigUpdateOptions config = PveQemuConfigUpdateOptions.builder()
                .memory(4096)
                .cores(2)
                .build();
        
        proxmox.getNodes()
                .get("pve-node-01")
                .getQemu()
                .get(newVmid)
                .updateConfig(config)
                .waitForCompletion(proxmox)
                .execute();
        
        // Start the VM
        proxmox.getNodes()
                .get("pve-node-01")
                .getQemu()
                .get(newVmid)
                .start()
                .waitForCompletion(proxmox)
                .execute();
        
        System.out.println("VM " + newVmid + " deployed successfully");
    }
}
```

--------------------------------

### Example API Tokens

Source: https://github.com/freshperf/pve4j/wiki/Client-Configuration

Examples of valid API token strings for different authentication realms.

```java
// 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";
```

--------------------------------

### Start a Container

Source: https://github.com/freshperf/pve4j/wiki/Container-Management

Initiates the start sequence for a specific container ID.

```java
try {
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .start()
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Container started!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Start a VM

Source: https://github.com/freshperf/pve4j/wiki/VM-Management

Powers on a specific VM identified by its ID.

```java
try {
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .start()
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("VM started successfully!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Setup Integration Test Client

Source: https://github.com/freshperf/pve4j/wiki/Client-Configuration

Configures a client for integration tests using system properties.

```java
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());
    }
}
```

--------------------------------

### Start Multiple Containers in Java

Source: https://github.com/freshperf/pve4j/wiki/Container-Management

Iterates through a list of container IDs to start them sequentially, waiting for each operation to complete.

```java
import java.util.Arrays;
import java.util.List;

List<Integer> containerIds = Arrays.asList(200, 201, 202, 203);

for (int ctid : containerIds) {
    try {
        proxmox.getNodes()
                .get("pve-node-01")
                .getLxc()
                .get(ctid)
                .start()
                .waitForCompletion(proxmox)
                .execute();
        
        System.out.println("Container " + ctid + " started");
        
    } catch (ProxmoxAPIError | InterruptedException e) {
        System.err.println("Failed to start container " + ctid + ": " + e.getMessage());
    }
}
```

--------------------------------

### Run Specific Tests with Gradle

Source: https://github.com/freshperf/pve4j/wiki/Contributing

Examples of how to run specific tests or test classes using Gradle.

```bash
# Run all tests
./gradlew test

# Run specific test class
./gradlew test --tests "fr.freshperf.pve4j.ProxmoxTest"

# Run tests matching pattern
./gradlew test --tests "*VM*"
```

--------------------------------

### Commit Changes with Description

Source: https://github.com/freshperf/pve4j/wiki/Contributing

Example of staging all changes and committing them with a detailed multi-line message.

```bash
git add .
git commit -m "Add snapshot support for QEMU VMs

- Implement snapshot creation
- Add snapshot deletion
- Add snapshot listing
- Include unit tests
- Update documentation"
```

--------------------------------

### Integration Test for Starting a VM

Source: https://github.com/freshperf/pve4j/wiki/Contributing

An integration test that starts a VM via the Proxmox API. Requires 'test.proxmox.host' system property to be set.

```java
@Test
void testStartVM() throws ProxmoxAPIError, InterruptedException {
    // Only runs if test.proxmox.host is set
    String host = System.getProperty("test.proxmox.host");
    if (host == null) {
        return;
    }
    
    Proxmox proxmox = createTestClient();
    PveTask task = proxmox.getNodes()
            .get("test-node")
            .getQemu()
            .get(100)
            .start()
            .execute();
    
    assertNotNull(task.getUpid());
}
```

--------------------------------

### Install PVE4J Dependency

Source: https://github.com/freshperf/pve4j/wiki/Getting-Started

Add the PVE4J library to your project build configuration.

```groovy
implementation 'fr.freshperf:pve4j:0.2.2'
```

```xml
<dependency>
    <groupId>fr.freshperf</groupId>
    <artifactId>pve4j</artifactId>
    <version>0.2.2</version>
</dependency>
```

--------------------------------

### Access Proxmox Node Resources

Source: https://github.com/freshperf/pve4j/wiki/Node-Management

Provides examples for accessing QEMU VMs, LXC containers, and storage resources on a specified Proxmox node.

```java
// Access QEMU VMs on a node
var qemu = proxmox.getNodes().get("pve-node-01").getQemu();

// Access LXC containers on a node
var lxc = proxmox.getNodes().get("pve-node-01").getLxc();

// Access storage on a node
var storage = proxmox.getNodes().get("pve-node-01").getStorage();
```

--------------------------------

### Retrieve Guest System Information

Source: https://github.com/freshperf/pve4j/wiki/VM-Management

Fetches various system details from a VM via the QEMU guest agent. The guest must have the qemu-guest-agent package installed and enabled.

```java
var agent = proxmox.getNodes()
        .get("pve-node-01")
        .getQemu()
        .get(100)
        .getAgent();

try {
    // Hostname
    var hostname = agent.getHostName().execute();
    System.out.println("Hostname: " + hostname);
    
    // OS info
    var osInfo = agent.getOsInfo().execute();
    System.out.println("OS: " + osInfo);
    
    // Time and timezone
    var time = agent.getTime().execute();
    var timezone = agent.getTimezone().execute();
    
    // Users
    var users = agent.getUsers().execute();
    
    // vCPUs
    var vcpus = agent.getVcpus().execute();
    
    // Network interfaces
    var interfaces = agent.getNetworkInterfaces().execute();
    
    // Agent info
    var info = agent.getInfo().execute();
    
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### API Token Formats

Source: https://github.com/freshperf/pve4j/wiki/Authentication

Examples of Proxmox API token formats for different users and realms.

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

```java
// Custom user with PVE realm
String token = "admin@pve!readonly=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy";
```

```java
// Service account
String token = "backup@pam!backup-service=zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz";
```

--------------------------------

### Get QEMU VM Snapshot Information

Source: https://github.com/freshperf/pve4j/wiki/Snapshot-Management

Retrieves detailed configuration information for a specific QEMU VM snapshot, including its description, memory usage, and core count at the time of creation.

```java
import fr.freshperf.pve4j.entities.nodes.node.qemu.snapshot.PveQemuSnapshotConfig;

try {
    PveQemuSnapshotConfig config = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getSnapshots()
            .get("pre-upgrade")
            .getConfig()
            .execute();
    
    System.out.println("Description: " + config.getDescription());
    System.out.println("Memory at snapshot: " + config.getMemory() + " MB");
    System.out.println("Cores at snapshot: " + config.getCores());
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Unit Test Example

Source: https://github.com/freshperf/pve4j/wiki/Contributing

A basic unit test using JUnit 5, Mockito, and AssertJ to verify functionality.

```java
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class PveQemuVmTest {
    
    @Test
    void testVmCreation() {
        // Test implementation
        assertNotNull(vm);
        assertEquals(100, vm.vmid());
    }
}
```

--------------------------------

### Basic Password Authentication with PVE4J

Source: https://github.com/freshperf/pve4j/wiki/Authentication

Example of authenticating with Proxmox using username and password via the `createWithPassword` method. This is suitable for default PAM realms and secure settings.

```java
import fr.freshperf.pve4j.Proxmox;
import fr.freshperf.pve4j.SecurityConfig;

try {
    // With default PAM realm and secure settings
    Proxmox proxmox = Proxmox.createWithPassword(
        "pve.example.com",
        8006,
        "root",
        "your-password"
    );
    
    // Now you can use the client as normal
    System.out.println("Version: " + proxmox.getVersion().execute().getVersion());
    
} catch (ProxmoxAPIError | InterruptedException e) {
    System.err.println("Authentication failed: " + e.getMessage());
}
```

--------------------------------

### Create a VM with Options

Source: https://github.com/freshperf/pve4j/wiki/VM-Management

Configures a new VM with specific hardware and OS settings using PveQemuCreateOptions.

```java
import fr.freshperf.pve4j.entities.nodes.node.qemu.PveQemuCreateOptions;

try {
    PveQemuCreateOptions options = PveQemuCreateOptions.builder()
            .name("web-server")
            .memory(4096)
            .cores(4)
            .sockets(1)
            .ostype("l26")
            .scsihw("virtio-scsi-pci")
            .boot("order=scsi0;ide2;net0")
            .agent(true)
            .onboot(true)
            .build();
    
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .create(100, options)
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("VM created!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Create Simple QEMU VM Snapshot

Source: https://github.com/freshperf/pve4j/wiki/Snapshot-Management

Creates a basic snapshot for a QEMU VM with a specified name. Waits for the snapshot creation task to complete.

```java
try {
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getSnapshots()
            .create("pre-upgrade")
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Snapshot created!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Manage QEMU VM Snapshots in Java

Source: https://github.com/freshperf/pve4j/wiki/VM-Management

Demonstrates creating, listing, and rolling back snapshots for a specific QEMU VM using the pve4j fluent API.

```java
// Create a snapshot
proxmox.getNodes()
        .get("pve-node-01")
        .getQemu()
        .get(100)
        .getSnapshots()
        .create("pre-upgrade", PveQemuSnapshotCreateOptions.builder()
                .description("Before system upgrade")
                .build())
        .waitForCompletion(proxmox)
        .execute();

// List snapshots
List<PveQemuSnapshot> snapshots = proxmox.getNodes()
        .get("pve-node-01")
        .getQemu()
        .get(100)
        .getSnapshots()
        .list()
        .execute();

// Rollback
proxmox.getNodes()
        .get("pve-node-01")
        .getQemu()
        .get(100)
        .getSnapshots()
        .get("pre-upgrade")
        .rollback()
        .waitForCompletion(proxmox)
        .execute();
```

--------------------------------

### Create a QEMU Firewall IP Set

Source: https://github.com/freshperf/pve4j/wiki/Firewall-Management

Initializes a new IP set for a QEMU VM using builder options.

```java
import fr.freshperf.pve4j.entities.nodes.node.qemu.firewall.ipset.PveQemuFirewallIpSetCreateOptions;

try {
    PveQemuFirewallIpSetCreateOptions options = PveQemuFirewallIpSetCreateOptions.builder()
            .build();
    
    proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getIpSet()
            .create("trusted-ips", options)
            .execute();
    
    System.out.println("IP Set 'trusted-ips' created!");
    
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Create Production Client

Source: https://github.com/freshperf/pve4j/wiki/Client-Configuration

Initializes a production client using environment variables for secure configuration.

```java
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()
        );
    }
}
```

--------------------------------

### Create a VM backup with custom options

Source: https://github.com/freshperf/pve4j/wiki/Backup-Management

Configures backup parameters such as storage, compression, and retention policies using PveQemuBackupOptions.

```java
import fr.freshperf.pve4j.entities.nodes.node.qemu.PveQemuBackupOptions;

try {
    PveQemuBackupOptions options = PveQemuBackupOptions.builder()
            .storage("DATA")                       // target storage for the archive
            .mode("snapshot")                      // "snapshot" (default), "suspend", "stop"
            .compress("zstd")                      // "0", "1", "gzip", "lzo", "zstd"
            .notesTemplate("{{guestname}} - {{node}}")
            .protected_(true)                      // protect the archive from pruning/deletion
            .pruneBackups("keep-last=3,keep-daily=7")
            .bwlimit(102400)                       // I/O limit in KiB/s (0 = unlimited)
            .build();

    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .backup(options)
            .waitForCompletion(proxmox)
            .execute();

    System.out.println("Backup completed with options!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Create QEMU VM Snapshot with Options

Source: https://github.com/freshperf/pve4j/wiki/Snapshot-Management

Creates a snapshot with additional options, such as including the VM's memory state for a more complete restore. VM state snapshots are larger and take longer to create.

```java
import fr.freshperf.pve4j.entities.nodes.node.qemu.snapshot.PveQemuSnapshotCreateOptions;

try {
    PveQemuSnapshotCreateOptions options = PveQemuSnapshotCreateOptions.builder()
            .description("Snapshot before system upgrade")
            .vmstate(true)  // Include memory state
            .build();
    
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getSnapshots()
            .create("pre-upgrade", options)
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Snapshot created with VM state!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Get Access Index

Source: https://github.com/freshperf/pve4j/wiki/Access-Control

Retrieves an index of available API endpoints.

```APIDOC
## Access Index

### Get Access Index

#### Description
Retrieves an index of available API subdirectories or endpoints.

#### Method
GET

#### Endpoint
/access/index

#### Parameters
None

#### Request Example
```java
// Java code example provided in the source text demonstrates usage.
// No direct HTTP request example available.
```

#### Response Example
```json
[
  {
    "subdir": "vms"
  },
  {
    "subdir": "storage"
  }
]
```
```

--------------------------------

### Build the Project with Gradle

Source: https://github.com/freshperf/pve4j/wiki/Contributing

Use Gradle to build the entire project, including compiling code and running tests.

```bash
./gradlew build
```

--------------------------------

### Get Cluster Index in Java

Source: https://github.com/freshperf/pve4j/wiki/Cluster-Operations

Retrieves the list of available cluster endpoints.

```java
import fr.freshperf.pve4j.entities.cluster.PveClusterIndex;
import java.util.List;

try {
    List<PveClusterIndex> index = proxmox.getCluster()
            .getIndex()
            .execute();
    
    for (PveClusterIndex item : index) {
        System.out.println("Available endpoint: " + item);
    }
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Create a Minimal VM

Source: https://github.com/freshperf/pve4j/wiki/VM-Management

Creates a new VM using default configuration settings.

```java
try {
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .create(101)
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("VM 101 created with defaults!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Get VM Configuration

Source: https://github.com/freshperf/pve4j/wiki/VM-Management

Retrieves the static configuration settings for a specific virtual machine.

```APIDOC
## Method: getConfig()

### Description
Retrieves the configuration details of a QEMU virtual machine.

### Signature
`proxmox.getNodes().get(nodeId).getQemu().get(vmid).getConfig().execute()`

### Returns
- **PveQemuConfig**: Object containing name, memory, cores, sockets, and boot order settings.
```

--------------------------------

### Create a Rule

Source: https://github.com/freshperf/pve4j/wiki/Firewall-Management

Creates a new firewall rule for a QEMU virtual machine using provided configuration options.

```APIDOC
## Create a Rule

### Description
Creates a new firewall rule using `PveFirewallRuleCreateOptions`.

### Method
SDK Method: `proxmox.getNodes().get(node).getQemu().get(vmid).getFirewall().getRules().create(options).execute()`

### Parameters
- **options** (PveFirewallRuleCreateOptions) - Required - Configuration object for the new rule.
```

--------------------------------

### list()

Source: https://github.com/freshperf/pve4j/wiki/Firewall-Management

Retrieves a list of all IP sets configured for a specific QEMU virtual machine.

```APIDOC
## list()

### Description
Retrieves a list of all IP sets configured for a specific QEMU virtual machine.

### Method
SDK Method: proxmox.getNodes().get(node).getQemu().get(vmid).getFirewall().getIpSet().list()

### Parameters
- **node** (String) - Required - The ID of the Proxmox node.
- **vmid** (Integer) - Required - The ID of the QEMU virtual machine.
```

--------------------------------

### Get VM Firewall Options

Source: https://github.com/freshperf/pve4j/wiki/Firewall-Management

Retrieves the current firewall configuration for a specific VM.

```java
import fr.freshperf.pve4j.entities.nodes.node.qemu.firewall.PveQemuFirewallOptions;

try {
    PveQemuFirewallOptions options = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getOptions()
            .execute();
    
    System.out.println("DHCP: " + options.getDhcp());
    System.out.println("Enabled: " + options.getEnable());
    System.out.println("IP Filter: " + options.getIpfilter());
    System.out.println("Log Level In: " + options.getLogLevelIn());
    System.out.println("Log Level Out: " + options.getLogLevelOut());
    System.out.println("MAC Filter: " + options.getMacfilter());
    System.out.println("NDP: " + options.getNdp());
    System.out.println("Policy In: " + options.getPolicyIn());
    System.out.println("Policy Out: " + options.getPolicyOut());
    System.out.println("RADV: " + options.getRadv());
    
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Get Node Status

Source: https://github.com/freshperf/pve4j/wiki/Node-Management

Retrieves detailed status information for a specific Proxmox VE node.

```APIDOC
## GET /nodes/{node}/status

### Description
Fetches comprehensive status details for a specified node, including PVE version, CPU usage, memory, swap, filesystem, CPU information, boot details, and kernel information.

### Method
GET

### Endpoint
/nodes/{node}/status

### Parameters
#### Path Parameters
- **node** (String) - Required - The name of the node to retrieve status for.

### Request Example
```java
import fr.freshperf.pve4j.entities.nodes.node.PveNodeStatus;

try {
    PveNodeStatus status = proxmox.getNodes()
            .get("pve-node-01")
            .getStatus()
            .execute();
    
    System.out.println("PVE Version: " + status.getPveversion());
    System.out.println("CPU Usage: " + status.getCpu());
    System.out.println("Uptime: " + status.getUptime());
    System.out.println("Load Average: " + String.join(", ", status.getLoadavg()));
    
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

### Response
#### Success Response (200)
- **PveNodeStatus** (Object) - Contains detailed status information for the node.
  - **pveversion** (String) - The Proxmox VE version.
  - **cpu** (double) - Current CPU utilization percentage.
  - **uptime** (long) - Uptime in seconds.
  - **loadavg** (List<String>) - Load average values.
  - **memory** (PveNodeMemory) - Memory usage details.
    - **total** (long) - Total memory in bytes.
    - **used** (long) - Used memory in bytes.
    - **free** (long) - Free memory in bytes.
    - **available** (long) - Available memory in bytes.
  - **swap** (PveNodeSwap) - Swap usage details.
    - **total** (long) - Total swap in bytes.
    - **used** (long) - Used swap in bytes.
    - **free** (long) - Free swap in bytes.
  - **rootfs** (PveNodeRootfs) - Root filesystem usage details.
    - **total** (long) - Total root filesystem size in bytes.
    - **used** (long) - Used bytes on root filesystem.
    - **free** (long) - Free bytes on root filesystem.
    - **avail** (long) - Available bytes on root filesystem.
  - **cpuinfo** (PveNodeCpuInfo) - CPU hardware information.
    - **model** (String) - CPU model name.
    - **cores** (int) - Number of physical cores.
    - **cpus** (int) - Number of logical threads.
    - **sockets** (int) - Number of CPU sockets.
  - **bootInfo** (PveNodeBootInfo) - Boot firmware information.
    - **mode** (String) - Boot firmware mode (`"efi"` or `"legacy-bios"`).
    - **secureboot** (Boolean) - Whether secure boot is enabled.
  - **currentKernel** (PveNodeCurrentKernel) - Current kernel information.
    - **sysname** (String) - OS kernel name.
    - **release** (String) - OS kernel release.
    - **version** (String) - OS kernel version with build info.
    - **machine** (String) - Hardware architecture type.

#### Response Example
```json
{
  "pveversion": "8.1.0",
  "cpu": 0.05,
  "uptime": 172800,
  "loadavg": ["0.10", "0.15", "0.20"],
  "memory": {
    "total": 8589934592,
    "used": 1073741824,
    "free": 7516192768,
    "available": 7340032000
  },
  "swap": {
    "total": 2147483648,
    "used": 0,
    "free": 2147483648
  },
  "rootfs": {
    "total": 100000000000,
    "used": 50000000000,
    "free": 50000000000,
    "avail": 48000000000
  },
  "cpuinfo": {
    "model": "Intel(R) Core(TM) i7-8700K CPU @ 3.70GHz",
    "cores": 6,
    "cpus": 12,
    "sockets": 1
  },
  "bootInfo": {
    "mode": "efi",
    "secureboot": true
  },
  "currentKernel": {
    "sysname": "Linux",
    "release": "6.8.0-2-pve",
    "version": "#1 SMP PREEMPT_DYNAMIC Debian 6.8.7-1 (2024-05-15)",
    "machine": "x86_64"
  }
}
```
```

--------------------------------

### create(String name, PveQemuFirewallIpSetCreateOptions options)

Source: https://github.com/freshperf/pve4j/wiki/Firewall-Management

Creates a new IP set for a specific QEMU virtual machine.

```APIDOC
## create(String name, PveQemuFirewallIpSetCreateOptions options)

### Description
Creates a new IP set for a specific QEMU virtual machine.

### Method
SDK Method: proxmox.getNodes().get(node).getQemu().get(vmid).getFirewall().getIpSet().create(name, options)

### Parameters
- **name** (String) - Required - The name of the new IP set.
- **options** (PveQemuFirewallIpSetCreateOptions) - Required - Configuration options for the IP set.
```

--------------------------------

### Get a Specific Rule

Source: https://github.com/freshperf/pve4j/wiki/Firewall-Management

Retrieves the details of a specific firewall rule based on its position index.

```APIDOC
## Get a Specific Rule

### Description
Retrieves a single firewall rule at a specified position index.

### Method
SDK Method: `proxmox.getNodes().get(node).getQemu().get(vmid).getFirewall().getRules().get(position).execute()`

### Parameters
- **position** (Integer) - Required - The index position of the rule.
```

--------------------------------

### Get Specific Firewall Rule

Source: https://github.com/freshperf/pve4j/wiki/Firewall-Management

Fetches a single firewall rule based on its position index.

```java
try {
    PveFirewallRule rule = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getRules()
            .get(0)  // position
            .execute();
    
    System.out.println("Rule at position 0: " + rule);
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Create Development Client

Source: https://github.com/freshperf/pve4j/wiki/Client-Configuration

Initializes a development client using hardcoded local settings and insecure security configuration.

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

--------------------------------

### Get Firewall Options

Source: https://github.com/freshperf/pve4j/wiki/Firewall-Management

Retrieves the current firewall configuration options for a specific virtual machine.

```APIDOC
## PveQemuFirewall.getOptions()

### Description
Retrieves the current firewall settings for a specific VM, including policies, logging levels, and filter settings.

### Method
SDK Method Call

### Signature
`proxmox.getNodes().get(nodeId).getQemu().get(vmid).getFirewall().getOptions().execute()`

### Returns
- **PveQemuFirewallOptions**: An object containing firewall settings such as dhcp, enable, ipfilter, logLevelIn, logLevelOut, macfilter, ndp, policyIn, policyOut, and radv.
```

--------------------------------

### Create a basic LXC container

Source: https://github.com/freshperf/pve4j/wiki/Container-Management

Initializes a new container with specified resource limits and OS template. Requires a valid Proxmox node connection and appropriate storage configuration.

```java
import fr.freshperf.pve4j.entities.nodes.node.lxc.PveLxcCreateOptions;

try {
    PveLxcCreateOptions options = PveLxcCreateOptions.builder()
            .ostemplate("local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst")
            .hostname("my-container")
            .memory(1024)
            .swap(512)
            .cores(2)
            .rootfs("local-lvm:8")
            .password("secure-password")
            .unprivileged(true)
            .onboot(true)
            .start(true)
            .build();
    
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .create(200, options)
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Container created!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Get Pending Configuration Changes

Source: https://github.com/freshperf/pve4j/wiki/VM-Management

Retrieves a list of pending configuration changes for a specific virtual machine.

```APIDOC
## Method: getPending()

### Description
Retrieves pending configuration changes for a QEMU virtual machine.

### Signature
`proxmox.getNodes().get(nodeId).getQemu().get(vmid).getPending().execute()`

### Returns
- **List<PveQemuPendingChange>**: A list of objects containing key and value pairs for pending changes.
```

--------------------------------

### List Firewall Rules

Source: https://github.com/freshperf/pve4j/wiki/Firewall-Management

Retrieves a list of all firewall rules for a specific QEMU virtual machine.

```java
import fr.freshperf.pve4j.entities.nodes.node.qemu.firewall.rules.PveFirewallRule;

try {
    List<PveFirewallRule> rules = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getRules()
            .list()
            .execute();
    
    for (PveFirewallRule rule : rules) {
        System.out.println("Rule: " + rule);
    }
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Get Container Network Interfaces in Java

Source: https://github.com/freshperf/pve4j/wiki/Container-Management

Retrieves a list of network interfaces for a specific container on a node.

```java
try {
    List<PveLxcInterface> interfaces = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .getInterfaces()
            .execute();
    
    for (PveLxcInterface iface : interfaces) {
        System.out.println("Interface: " + iface);
    }
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Manage Backup Jobs with PVE4J

Source: https://github.com/freshperf/pve4j/wiki/Cluster-Operations

Demonstrates listing existing backup jobs and creating a new scheduled job for specific VMs.

```java
import fr.freshperf.pve4j.entities.cluster.backup.PveBackupJob;
import fr.freshperf.pve4j.entities.cluster.backup.PveBackupJobCreateOptions;
import java.util.List;

try {
    // List existing jobs
    List<PveBackupJob> jobs = proxmox.getCluster().getBackup().getJobs().execute();
    for (PveBackupJob job : jobs) {
        System.out.printf("%s | enabled=%s | schedule=%s%n",
                job.getId(), job.isEnabled(), job.getSchedule());
    }

    // Create a nightly job for two VMs
    proxmox.getCluster().getBackup().createJob(PveBackupJobCreateOptions.builder()
            .schedule("mon..fri 02:00")
            .storage("DATA")
            .vmid("100,101")
            .mode("snapshot")
            .compress("zstd")
            .build())
        .execute();
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Get Pending Configuration Changes

Source: https://github.com/freshperf/pve4j/wiki/Container-Management

Retrieves a list of pending configuration changes for a specific LXC container.

```APIDOC
## Method: getPending()

### Description
Retrieves pending configuration changes for an LXC container.

### Signature
`proxmox.getNodes().get(nodeId).getLxc().get(containerId).getPending().execute()`

### Returns
`List<PveLxcPendingChange>` containing the pending configuration updates.
```

--------------------------------

### Get Pending LXC Configuration Changes

Source: https://github.com/freshperf/pve4j/wiki/Container-Management

Fetches a list of configuration changes that are pending for the specified container.

```java
try {
    List<PveLxcPendingChange> pending = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .getPending()
            .execute();
    
    for (PveLxcPendingChange change : pending) {
        System.out.println("Pending: " + change);
    }
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Manage QEMU Firewall with FirewallManager

Source: https://github.com/freshperf/pve4j/wiki/Firewall-Management

A helper class to toggle firewall status and manage IP sets for a specific VM. Requires an initialized Proxmox client instance.

```java
public class FirewallManager {
    private final Proxmox proxmox;
    private final String node;
    private final int vmid;
    
    public FirewallManager(Proxmox proxmox, String node, int vmid) {
        this.proxmox = proxmox;
        this.node = node;
        this.vmid = vmid;
    }
    
    public void enableFirewall() throws ProxmoxAPIError, InterruptedException {
        PveQemuFirewallOptionsUpdate options = PveQemuFirewallOptionsUpdate.builder()
                .enable(true)
                .build();
        
        proxmox.getNodes().get(node).getQemu().get(vmid)
                .getFirewall()
                .updateOptions(options)
                .waitForCompletion(proxmox)
                .execute();
    }
    
    public void disableFirewall() throws ProxmoxAPIError, InterruptedException {
        PveQemuFirewallOptionsUpdate options = PveQemuFirewallOptionsUpdate.builder()
                .enable(false)
                .build();
        
        proxmox.getNodes().get(node).getQemu().get(vmid)
                .getFirewall()
                .updateOptions(options)
                .waitForCompletion(proxmox)
                .execute();
    }
    
    public void createIPSet(String name) throws ProxmoxAPIError, InterruptedException {
        proxmox.getNodes().get(node).getQemu().get(vmid)
                .getFirewall()
                .getIpSet()
                .create(name, PveQemuFirewallIpSetCreateOptions.builder().build())
                .execute();
    }
    
    public void addIPToSet(String setName, String cidr) 
            throws ProxmoxAPIError, InterruptedException {
        
        proxmox.getNodes().get(node).getQemu().get(vmid)
                .getFirewall()
                .getIpSet()
                .addMember(setName, cidr, PveQemuFirewallIpSetMemberCreateOptions.builder().build())
                .execute();
    }
    
    public void removeIPFromSet(String setName, String cidr) 
            throws ProxmoxAPIError, InterruptedException {
        
        proxmox.getNodes().get(node).getQemu().get(vmid)
                .getFirewall()
                .getIpSet()
                .deleteMember(setName, cidr, null)
                .execute();
    }
}
```

--------------------------------

### Get Specific HA Resource

Source: https://github.com/freshperf/pve4j/wiki/Cluster-Operations

Fetches details for a specific HA resource identified by its type and ID.

```java
try {
    PveHaResource resource = proxmox.getCluster()
            .getHa()
            .getResource("vm:100")
            .execute();
    
    System.out.println("HA Resource: " + resource);
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### List Rules

Source: https://github.com/freshperf/pve4j/wiki/Firewall-Management

Retrieves a list of all firewall rules configured for a specific QEMU virtual machine.

```APIDOC
## List Rules

### Description
Retrieves a list of all firewall rules for a specific node and QEMU virtual machine.

### Method
SDK Method: `proxmox.getNodes().get(node).getQemu().get(vmid).getFirewall().getRules().list().execute()`

### Parameters
- **node** (String) - Required - The node identifier.
- **vmid** (Integer) - Required - The QEMU virtual machine identifier.
```

--------------------------------

### Get Cluster Status in Java

Source: https://github.com/freshperf/pve4j/wiki/Cluster-Operations

Retrieves the status of cluster members, including their online state and type.

```java
import fr.freshperf.pve4j.entities.cluster.PveClusterStatus;
import java.util.List;

try {
    List<PveClusterStatus> status = proxmox.getCluster()
            .getStatus()
            .execute();
    
    for (PveClusterStatus member : status) {
        System.out.println("Name: " + member.getName());
        System.out.println("Type: " + member.getType());
        System.out.println("Online: " + member.getOnline());
        System.out.println("---");
    }
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Migrate a Container with Options

Source: https://github.com/freshperf/pve4j/wiki/Container-Management

Configures migration parameters such as online status, target storage, and timeouts using PveLxcMigrateOptions.

```java
import fr.freshperf.pve4j.entities.nodes.node.lxc.PveLxcMigrateOptions;

try {
    PveLxcMigrateOptions options = PveLxcMigrateOptions.builder()
            .online(true)
            .targetStorage("local-lvm")
            .restart(true)
            .timeout(120)
            .build();
    
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .migrate("pve-node-02", options)
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Container migrated with options!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Get Authentication Ticket

Source: https://github.com/freshperf/pve4j/wiki/Access-Control

Obtains an authentication ticket and CSRF prevention token using username and password.

```APIDOC
## Authentication Ticket

### Get Authentication Ticket

#### Description
Authenticates a user with username and password to obtain an API ticket and a CSRF prevention token. This is an alternative to API token authentication.

#### Method
POST

#### Endpoint
/access/ticket

#### Parameters
##### Query Parameters
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.
- **realm** (string) - Required - The authentication realm (e.g., "pam").

#### Request Example
```java
// Java code example provided in the source text demonstrates usage.
// No direct HTTP request example available.
```

#### Response
##### Success Response (200)
- **ticket** (string) - The authentication ticket.
- **CSRFPreventionToken** (string) - A token for CSRF prevention.
- **username** (string) - The authenticated username.

#### Response Example
```json
{
  "ticket": "TICKET_STRING",
  "CSRFPreventionToken": "CSRF_TOKEN_STRING",
  "username": "root@pam"
}
```
```

--------------------------------

### Create VM with Next Available VMID

Source: https://github.com/freshperf/pve4j/wiki/Cluster-Operations

Uses the retrieved VMID to provision a new QEMU virtual machine on a specific node.

```java
try {
    Integer vmid = proxmox.getCluster().getNextId().execute();
    
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .create(vmid, PveQemuCreateOptions.builder()
                    .name("new-vm")
                    .memory(2048)
                    .cores(2)
                    .build())
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Created VM with VMID: " + vmid);
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Get IP Set Member in Java

Source: https://github.com/freshperf/pve4j/wiki/Firewall-Management

Retrieves details for a specific IP set member identified by its CIDR.

```java
try {
    PveQemuFirewallIpSetMember member = proxmox.getNodes()
            .get("pve-node-01")
            .getQemu()
            .get(100)
            .getFirewall()
            .getIpSet()
            .getMember("trusted-ips", "192.168.1.0/24")
            .execute();
    
    System.out.println("Member: " + member);
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### qemu.restore(vmid, options)

Source: https://github.com/freshperf/pve4j/wiki/Backup-Management

Restores a virtual machine from a specified backup archive.

```APIDOC
## qemu.restore(vmid, options)

### Description
Restores a VM from a backup archive. The archive must be a valid Proxmox volume identifier.

### Parameters
- **vmid** (int) - Required - The ID of the VM to restore.
- **options** (PveQemuRestoreOptions) - Required - Configuration object including the archive volid, force flag, target storage, and other restore settings.

### Returns
- **PveTask** - A task object representing the asynchronous restore operation.
```

--------------------------------

### Get Storage Content in Java

Source: https://github.com/freshperf/pve4j/wiki/Storage-Management

Lists all content volumes stored within a specific storage location on a node.

```java
import fr.freshperf.pve4j.entities.nodes.node.storage.PveStorageContent;
import java.util.List;

try {
    List<PveStorageContent> content = proxmox.getNodes()
            .get("pve-node-01")
            .getStorage()
            .get("local-lvm")
            .getContent()
            .execute();
    
    System.out.println("Storage Content:");
    
    for (PveStorageContent item : content) {
        System.out.println("Volume ID: " + item.getVolid());
        System.out.println("Content Type: " + item.getContent());
        System.out.println("Format: " + item.getFormat());
        System.out.println("Size: " + item.getSize() + " bytes");
        
        if (item.getVmid() != null) {
            System.out.println("VMID: " + item.getVmid());
        }
        
        System.out.println("---");
    }
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}
```

--------------------------------

### Assign Token Permissions

Source: https://github.com/freshperf/pve4j/wiki/Authentication

Examples of assigning roles and permissions to API tokens using the pveum acl modify command.

```bash
# Grant VM.Admin role to token for all VMs
pveum acl modify /vms -token 'root@pam!automation' -role PVEVMAdmin
```

```bash
# Grant read-only access to cluster
pveum acl modify / -token 'root@pam!readonly' -role PVEAuditor
```