https://github.com/freshperf/pve4j
A java library to interact with Proxmox the right way
https://github.com/freshperf/pve4j
api-client french java oss proxmox proxmox-ve pve vm
Last synced: 3 months ago
JSON representation
A java library to interact with Proxmox the right way
- Host: GitHub
- URL: https://github.com/freshperf/pve4j
- Owner: FreshPerf
- License: gpl-3.0
- Created: 2026-01-04T22:01:59.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-19T15:27:10.000Z (6 months ago)
- Last Synced: 2026-01-19T17:49:31.355Z (6 months ago)
- Topics: api-client, french, java, oss, proxmox, proxmox-ve, pve, vm
- Language: Java
- Homepage: https://freshperf.fr
- Size: 407 KB
- Stars: 7
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Proxmox® is a registered trademark of Proxmox Server Solutions GmbH. PVE4J is not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH.
A modern, fluent, and comprehensive Java library for interacting with the Proxmox VE API, created and maintained by FreshPerf.
---
## Overview
PVE4J is a Java library that provides an object-oriented wrapper around the Proxmox Virtual Environment REST API. It enables programmatic management of Proxmox infrastructure with a clean, intuitive, and type-safe interface.
**Note:** This library is currently in active development. While core functionality is implemented and stable, some API endpoints may be missing. Contributions and feedback are welcome.
## Features
- **Comprehensive API Coverage** - Manage cluster resources, nodes, QEMU virtual machines, LXC containers, storage, and access controls (users, groups, roles, ACLs)
- **Fluent API Design** - Clean, chainable request system for intuitive interaction with the Proxmox API
- **Flexible Authentication** - Support for both API tokens and username/password authentication
- **Asynchronous Task Handling** - Built-in support for long-running operations with `waitForCompletion()` and `onCompletion()` callback methods
- **Automatic Retry Support** - Configurable retry logic with customizable delays for transient failures
- **Robust Error Handling** - Clear and informative `ProxmoxAPIError` exceptions for easier debugging
- **Type-Safe Entities** - Maps Proxmox API responses to strongly-typed Java objects
- **Configurable Security** - Easily manage SSL/TLS certificate and hostname verification for different environments
- **Detailed VM Management** - Create, clone, delete, resize disks, and update configurations for QEMU VMs with type-safe builder options
- **Firewall Management** - Configure firewall options, rules, and IP Sets for QEMU VMs
- **Storage Management** - Query storage status, list content, and retrieve statistics
## Current Implementation Status
### Fully Implemented
- **Cluster Management**
- Cluster status and resources
- Next available VMID retrieval
- Resource filtering by type
- **HA (High Availability) management** - List/get/create/delete HA resources and change requested state
- **Node Management**
- List all nodes
- Node status and version information
- Node-specific operations
- **QEMU VM Management**
- **VM creation** with comprehensive options (CPU, memory, disks, networks, etc.)
- List, clone, and delete VMs
- VM lifecycle operations (start, stop, shutdown, reboot, reset, suspend, resume)
- VM configuration management (get/update) and pending changes
- Disk resizing
- VNC proxy access
- **Backup operations** (vzdump with options)
- **Migration** to other nodes (online/offline)
- **Convert to template**
- **Cloud-init helpers**
- **Guest agent operations**
- Firewall options and IP Set management
- **Firewall rules management** (list, create, update, delete rules)
- **Snapshot management** (list, create, delete, rollback, update description)
- **LXC Container Management**
- **Container creation** with comprehensive options (templates, networks, mount points, etc.)
- List and query containers
- Container lifecycle operations (start, stop, shutdown, reboot, suspend, resume)
- Container configuration retrieval and updates
- Pending changes, interfaces, and feature checks
- Clone, migrate, and convert to template
- Snapshot management
- Container deletion
- **Storage Management**
- List storage pools
- Storage status and content
- RRD statistics
- **Access Control**
- User management
- Group management
- Role management
- ACL (Access Control List) queries
- Authentication domains/realms
- Ticket-based authentication
- **Pool Management**
- List all resource pools
- Create and delete pools
- Get pool details and members
- Add/remove VMs and storage to/from pools
- Update pool configuration
### Scope Note
PVE4J is already very usable for common compute automation workflows, but it does not aim to cover every Proxmox VE endpoint yet. For a more detailed map of the current scope, see the wiki pages linked below.
## Installation
### Maven Central
#### Gradle
Add the dependency to your `build.gradle`:
```groovy
dependencies {
implementation 'fr.freshperf:PVE4J:0.2.0'
}
```
#### Maven
Add the dependency:
```xml
fr.freshperf
PVE4J
0.2.0
```
## Quick Start
### Creating a Client
First, create a `Proxmox` client instance. You can use either an API token (recommended) or username/password authentication.
#### Using API Token (Recommended)
```java
import fr.freshperf.pve4j.Proxmox;
import fr.freshperf.pve4j.SecurityConfig;
// For production environments with valid SSL certificates
Proxmox proxmox = Proxmox.create("pve.example.com", 8006, "your-api-token");
// For development/testing with self-signed certificates
Proxmox proxmoxDev = Proxmox.create("192.168.1.10", 8006, "your-api-token", SecurityConfig.insecure());
```
#### Using Username/Password
```java
import fr.freshperf.pve4j.Proxmox;
import fr.freshperf.pve4j.SecurityConfig;
import fr.freshperf.pve4j.throwable.ProxmoxAPIError;
try {
// With default PAM realm
Proxmox proxmox = Proxmox.createWithPassword("pve.example.com", 8006, "root", "password");
// With custom realm and security config
Proxmox proxmox = Proxmox.createWithPassword("192.168.1.10", 8006, "admin", "password", "pve", SecurityConfig.insecure());
} catch (ProxmoxAPIError | InterruptedException e) {
e.printStackTrace();
}
```
### Basic Operations
**Get Proxmox Version**
```java
import fr.freshperf.pve4j.entities.PveVersion;
import fr.freshperf.pve4j.throwable.ProxmoxAPIError;
try {
PveVersion version = proxmox.getVersion().execute();
System.out.println("Proxmox Version: " + version.getVersion());
} catch (ProxmoxAPIError | InterruptedException e) {
e.printStackTrace();
}
```
**List All QEMU VMs on a Specific Node**
```java
import fr.freshperf.pve4j.entities.nodes.node.qemu.PveQemuIndex;
import java.util.List;
try {
List vms = proxmox.getNodes()
.get("pve-node-01")
.getQemu()
.getIndex()
.execute();
for (PveQemuIndex vm : vms) {
System.out.printf("VMID: %d, Name: %s, Status: %s%n",
vm.getVmid(), vm.getName(), vm.getStatus());
}
} catch (ProxmoxAPIError | InterruptedException e) {
e.printStackTrace();
}
```
### Managing VMs and Tasks
PVE4J simplifies handling long-running tasks like starting or cloning a VM.
**Start a VM and Wait for Completion**
```java
import fr.freshperf.pve4j.entities.PveTask;
try {
PveTask startTask = proxmox.getNodes()
.get("pve-node-01")
.getQemu()
.get(101)
.start()
.waitForCompletion(proxmox)
.execute();
System.out.println("VM 101 started successfully. Task: " + startTask.getUpid());
} catch (ProxmoxAPIError | InterruptedException e) {
System.err.println("Failed to start VM 101: " + e.getMessage());
}
```
**Clone a VM with an Asynchronous Callback**
```java
import fr.freshperf.pve4j.entities.nodes.node.qemu.PveQemuCloneOptions;
try {
PveQemuCloneOptions cloneOptions = PveQemuCloneOptions.builder()
.name("clone-of-template")
.description("A new VM cloned via PVE4J");
proxmox.getNodes()
.get("pve-node-01")
.getQemu()
.get(9000)
.cloneVm(201, cloneOptions)
.onCompletion(status -> {
if (status.isSuccessful()) {
System.out.println("VM 201 cloned successfully!");
} else {
System.err.println("Cloning failed: " + status.getExitstatus());
}
}, proxmox)
.execute();
System.out.println("Clone task submitted.");
} catch (ProxmoxAPIError | InterruptedException e) {
e.printStackTrace();
}
```
## API Overview
The library's functionality is structured hierarchically, starting from the main `Proxmox` object:
- `proxmox.getVersion()` - Get the API version information
- `proxmox.getTaskStatus(task)` - Check the status of a running task
- `proxmox.getCluster()` - Access cluster-wide information and resources
- `.getStatus()` - Get the status of all cluster members
- `.getResources()` - List all resources in the cluster (VMs, containers, storage, etc.)
- `.getNextId()` - Get the next available VMID
- `.getHa()` - Manage High Availability
- `.listResources()`, `.getResource()`, `.createResource()`, `.deleteResource()`
- `.setResourceState()` - Change HA resource state
- `proxmox.getNodes()` - List all nodes in the cluster
- `.get("node-name")` - Access a specific node by its name
- `.getQemu()` - Manage QEMU VMs on the node
- `.create(vmid, options)` - Create a new VM
- `.get(vmid)` - Access a specific VM
- `.start()`, `.stop()`, `.shutdown()`, `.reboot()`, `.reset()`
- `.suspend()`, `.resume()`
- `.cloneVm()`, `.resize()`, `.delete()`
- `.updateConfig()`, `.getConfig()`, `.getStatus()`
- `.backup(options)` - Create a backup
- `.migrate(targetNode, online, targetStorage)` - Migrate to another node
- `.template()` - Convert to template
- `.getCloudInit()`, `.getAgent()`, `.getVnc()`, `.getRrdData()`
- `.getFirewall()` - Manage VM firewall settings
- `.getRules()` - Manage firewall rules
- `.getSnapshots()` - Manage VM snapshots
- `.getLxc()` - Manage LXC containers on the node
- `.create(vmid, options)` - Create a new container
- `.get(vmid)` - Access a specific container
- `.updateConfig()`, `.getConfig()`, `.getStatus()`, `.getPending()`
- `.getInterfaces()`, `.getFeature()`
- `.cloneContainer()`, `.migrate()`, `.template()`, `.delete()`
- `.getSnapshots()` - Manage container snapshots
- `.getStorage()` - Manage storage pools on the node
- `proxmox.getPools()` - Manage resource pools
- `.list()` - List all resource pools
- `.create()` - Create a new pool
- `.get(poolid)` - Access a specific pool
- `.getDetails()` - Get pool information and members
- `.addVms()`, `.removeVms()` - Manage VM membership
- `.addStorage()`, `.removeStorage()` - Manage storage membership
- `.delete()` - Delete the pool
- `proxmox.getAccess()` - Manage access control
- `.getUsers()` - List and manage users
- `.getGroups()` - List and manage groups
- `.getRoles()` - List and manage roles
- `.getAcl()` - Query access control lists
- `.getDomains()` - List authentication domains
## Security Configuration
The `SecurityConfig` class allows you to control SSL/TLS verification:
- **`SecurityConfig.secure()` (Default)** - Enforces both SSL certificate validation and hostname verification. Use this for production environments with properly configured certificates.
```java
Proxmox proxmox = Proxmox.create("pve.example.com", 8006, "token");
```
- **`SecurityConfig.insecure()`** - Disables both SSL certificate and hostname verification. This is useful for development or testing environments where Proxmox is using a self-signed certificate.
```java
Proxmox proxmox = Proxmox.create("192.168.1.10", 8006, "token", SecurityConfig.insecure());
```
- **Custom Configuration** - Use the builder for fine-grained control.
```java
SecurityConfig customConfig = SecurityConfig.builder()
.disableSslVerification()
.enableHostnameVerification()
.build();
// Or disable all security checks at once
SecurityConfig allDisabled = SecurityConfig.builder()
.disableAll()
.build();
```
## Documentation
For detailed documentation, please refer to the [Wiki](https://github.com/FreshPerf/PVE4J/wiki/Home):
- [Getting Started](https://github.com/FreshPerf/PVE4J/wiki/Getting-Started)
- [Authentication](https://github.com/FreshPerf/PVE4J/wiki/Authentication)
- [Client Configuration](https://github.com/FreshPerf/PVE4J/wiki/Client-Configuration)
- [Request API](https://github.com/FreshPerf/PVE4J/wiki/Request-API)
- [VM Management](https://github.com/FreshPerf/PVE4J/wiki/VM-Management)
- [Firewall Management](https://github.com/FreshPerf/PVE4J/wiki/Firewall-Management)
- [Snapshot Management](https://github.com/FreshPerf/PVE4J/wiki/Snapshot-Management)
- [Container Management](https://github.com/FreshPerf/PVE4J/wiki/Container-Management)
- [Cluster Operations](https://github.com/FreshPerf/PVE4J/wiki/Cluster-Operations)
- [Storage Management](https://github.com/FreshPerf/PVE4J/wiki/Storage-Management)
- [Pool Management](https://github.com/FreshPerf/PVE4J/wiki/Pool-Management)
- [Access Control](https://github.com/FreshPerf/PVE4J/wiki/Access-Control)
- [Task Handling](https://github.com/FreshPerf/PVE4J/wiki/Task-Handling)
- [Error Handling](https://github.com/FreshPerf/PVE4J/wiki/Error-Handling)
## Contributing
Contributions are welcome and appreciated! Here's how you can help:
### Reporting Issues
If you encounter a bug or have a feature request:
1. Check the [issue tracker](https://github.com/FreshPerf/PVE4J/issues) to see if it's already reported
2. If not, create a new issue with a clear description
3. Include code samples, error messages, and your environment details
### Contributing Code
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes following the existing code style
4. Write tests for your changes
5. Commit your changes (`git commit -m 'Add some amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
### Development Guidelines
- Follow Java best practices and naming conventions
- Maintain the fluent API design pattern
- Add JavaDoc comments for public APIs
- Write unit tests for new functionality
- Ensure all tests pass before submitting a PR
### Areas for Contribution
We particularly welcome contributions in these areas:
- Missing API endpoint implementations
- Additional builder options for existing operations
- Documentation improvements
- Example code and tutorials
- Bug fixes and performance improvements
## License
This project is licensed under the GNU General Public License v3.0. See the [LICENSE](LICENSE) file for details.
## Acknowledgments
- The Proxmox VE team for their excellent virtualization platform and API documentation
- All contributors who help improve this library
## Support
- **Documentation:** [Wiki](https://github.com/FreshPerf/PVE4J/wiki)
- **Issues:** [GitHub Issues](https://github.com/FreshPerf/PVE4J/issues)
- **AI Assistant:** [Ask DeepWiki](https://deepwiki.com/FreshPerf/PVE4J)
---
Maintainted with 🩵 by the FreshPerf.fr Team.