{"id":46911770,"url":"https://github.com/freshperf/pve4j","last_synced_at":"2026-04-02T22:08:07.722Z","repository":{"id":333460504,"uuid":"1127937393","full_name":"FreshPerf/PVE4J","owner":"FreshPerf","description":"A java library to interact with Proxmox the right way","archived":false,"fork":false,"pushed_at":"2026-01-19T15:27:10.000Z","size":417,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-19T17:49:31.355Z","etag":null,"topics":["api-client","french","java","oss","proxmox","proxmox-ve","pve","vm"],"latest_commit_sha":null,"homepage":"https://freshperf.fr","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FreshPerf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-04T22:01:59.000Z","updated_at":"2026-01-19T15:40:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/FreshPerf/PVE4J","commit_stats":null,"previous_names":["freshperf/pve4j"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/FreshPerf/PVE4J","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreshPerf%2FPVE4J","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreshPerf%2FPVE4J/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreshPerf%2FPVE4J/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreshPerf%2FPVE4J/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FreshPerf","download_url":"https://codeload.github.com/FreshPerf/PVE4J/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreshPerf%2FPVE4J/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30367798,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T21:41:54.280Z","status":"online","status_checked_at":"2026-03-11T02:00:07.027Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","french","java","oss","proxmox","proxmox-ve","pve","vm"],"created_at":"2026-03-11T02:00:19.780Z","updated_at":"2026-04-02T22:08:07.694Z","avatar_url":"https://github.com/FreshPerf.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"1000\" height=\"250\" alt=\"PVE4J logo\" src=\"https://github.com/user-attachments/assets/86626cd7-1284-4ef1-b5bb-fd192894ea12\"\n    /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.gnu.org/licenses/gpl-3.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-GPLv3-blue.svg\" alt=\"License: GPL v3\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://central.sonatype.com/artifact/fr.freshperf/PVE4J\"\u003e\u003cimg src=\"https://img.shields.io/badge/release-0.2.0-green\" alt=\"Maven Central\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/FreshPerf/PVE4J/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/FreshPerf/PVE4J\" alt=\"GitHub Issues\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/FreshPerf/PVE4J/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/FreshPerf/PVE4J\" alt=\"GitHub Stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://freshperf.fr\"\u003e\u003cimg src=\"https://img.shields.io/badge/FreshPerf-v1.5-blue\" alt=\"FreshPerf\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eProxmox® is a registered trademark of Proxmox Server Solutions GmbH. PVE4J is not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  A modern, fluent, and comprehensive Java library for interacting with the Proxmox VE API, created and maintained by \u003ca target=\"_blank\" href=\"https://freshperf.fr\"\u003eFreshPerf\u003c/a\u003e.\n\u003c/p\u003e\n\n---\n\n## Overview\n\nPVE4J 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.\n\n**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.\n\n\n## Features\n\n- **Comprehensive API Coverage** - Manage cluster resources, nodes, QEMU virtual machines, LXC containers, storage, and access controls (users, groups, roles, ACLs)\n- **Fluent API Design** - Clean, chainable request system for intuitive interaction with the Proxmox API\n- **Flexible Authentication** - Support for both API tokens and username/password authentication\n- **Asynchronous Task Handling** - Built-in support for long-running operations with `waitForCompletion()` and `onCompletion()` callback methods\n- **Automatic Retry Support** - Configurable retry logic with customizable delays for transient failures\n- **Robust Error Handling** - Clear and informative `ProxmoxAPIError` exceptions for easier debugging\n- **Type-Safe Entities** - Maps Proxmox API responses to strongly-typed Java objects\n- **Configurable Security** - Easily manage SSL/TLS certificate and hostname verification for different environments\n- **Detailed VM Management** - Create, clone, delete, resize disks, and update configurations for QEMU VMs with type-safe builder options\n- **Firewall Management** - Configure firewall options, rules, and IP Sets for QEMU VMs\n- **Storage Management** - Query storage status, list content, and retrieve statistics\n\n## Current Implementation Status\n\n### Fully Implemented\n\n- **Cluster Management**\n  - Cluster status and resources\n  - Next available VMID retrieval\n  - Resource filtering by type\n  - **HA (High Availability) management** - List/get/create/delete HA resources and change requested state\n\n- **Node Management**\n  - List all nodes\n  - Node status and version information\n  - Node-specific operations\n\n- **QEMU VM Management**\n  - **VM creation** with comprehensive options (CPU, memory, disks, networks, etc.)\n  - List, clone, and delete VMs\n  - VM lifecycle operations (start, stop, shutdown, reboot, reset, suspend, resume)\n  - VM configuration management (get/update) and pending changes\n  - Disk resizing\n  - VNC proxy access\n  - **Backup operations** (vzdump with options)\n  - **Migration** to other nodes (online/offline)\n  - **Convert to template**\n  - **Cloud-init helpers**\n  - **Guest agent operations**\n  - Firewall options and IP Set management\n  - **Firewall rules management** (list, create, update, delete rules)\n  - **Snapshot management** (list, create, delete, rollback, update description)\n\n- **LXC Container Management**\n  - **Container creation** with comprehensive options (templates, networks, mount points, etc.)\n  - List and query containers\n  - Container lifecycle operations (start, stop, shutdown, reboot, suspend, resume)\n  - Container configuration retrieval and updates\n  - Pending changes, interfaces, and feature checks\n  - Clone, migrate, and convert to template\n  - Snapshot management\n  - Container deletion\n\n- **Storage Management**\n  - List storage pools\n  - Storage status and content\n  - RRD statistics\n\n- **Access Control**\n  - User management\n  - Group management\n  - Role management\n  - ACL (Access Control List) queries\n  - Authentication domains/realms\n  - Ticket-based authentication\n\n- **Pool Management**\n  - List all resource pools\n  - Create and delete pools\n  - Get pool details and members\n  - Add/remove VMs and storage to/from pools\n  - Update pool configuration\n\n### Scope Note\n\nPVE4J 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.\n\n## Installation\n\n### Maven Central\n\n#### Gradle\n\nAdd the dependency to your `build.gradle`:\n\n```groovy\ndependencies {\n    implementation 'fr.freshperf:PVE4J:0.2.0'\n}\n```\n\n#### Maven\n\nAdd the dependency:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003efr.freshperf\u003c/groupId\u003e\n    \u003cartifactId\u003ePVE4J\u003c/artifactId\u003e\n    \u003cversion\u003e0.2.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Quick Start\n\n### Creating a Client\n\nFirst, create a `Proxmox` client instance. You can use either an API token (recommended) or username/password authentication.\n\n#### Using API Token (Recommended)\n\n```java\nimport fr.freshperf.pve4j.Proxmox;\nimport fr.freshperf.pve4j.SecurityConfig;\n\n// For production environments with valid SSL certificates\nProxmox proxmox = Proxmox.create(\"pve.example.com\", 8006, \"your-api-token\");\n\n// For development/testing with self-signed certificates\nProxmox proxmoxDev = Proxmox.create(\"192.168.1.10\", 8006, \"your-api-token\", SecurityConfig.insecure());\n```\n\n#### Using Username/Password\n\n```java\nimport fr.freshperf.pve4j.Proxmox;\nimport fr.freshperf.pve4j.SecurityConfig;\nimport fr.freshperf.pve4j.throwable.ProxmoxAPIError;\n\ntry {\n    // With default PAM realm\n    Proxmox proxmox = Proxmox.createWithPassword(\"pve.example.com\", 8006, \"root\", \"password\");\n    \n    // With custom realm and security config\n    Proxmox proxmox = Proxmox.createWithPassword(\"192.168.1.10\", 8006, \"admin\", \"password\", \"pve\", SecurityConfig.insecure());\n} catch (ProxmoxAPIError | InterruptedException e) {\n    e.printStackTrace();\n}\n```\n\n### Basic Operations\n\n**Get Proxmox Version**\n\n```java\nimport fr.freshperf.pve4j.entities.PveVersion;\nimport fr.freshperf.pve4j.throwable.ProxmoxAPIError;\n\ntry {\n    PveVersion version = proxmox.getVersion().execute();\n    System.out.println(\"Proxmox Version: \" + version.getVersion());\n} catch (ProxmoxAPIError | InterruptedException e) {\n    e.printStackTrace();\n}\n```\n\n**List All QEMU VMs on a Specific Node**\n\n```java\nimport fr.freshperf.pve4j.entities.nodes.node.qemu.PveQemuIndex;\nimport java.util.List;\n\ntry {\n    List\u003cPveQemuIndex\u003e vms = proxmox.getNodes()\n            .get(\"pve-node-01\")\n            .getQemu()\n            .getIndex()\n            .execute();\n            \n    for (PveQemuIndex vm : vms) {\n        System.out.printf(\"VMID: %d, Name: %s, Status: %s%n\",\n                vm.getVmid(), vm.getName(), vm.getStatus());\n    }\n} catch (ProxmoxAPIError | InterruptedException e) {\n    e.printStackTrace();\n}\n```\n\n### Managing VMs and Tasks\n\nPVE4J simplifies handling long-running tasks like starting or cloning a VM.\n\n**Start a VM and Wait for Completion**\n\n```java\nimport fr.freshperf.pve4j.entities.PveTask;\n\ntry {\n    PveTask startTask = proxmox.getNodes()\n            .get(\"pve-node-01\")\n            .getQemu()\n            .get(101)\n            .start()\n            .waitForCompletion(proxmox)\n            .execute();\n            \n    System.out.println(\"VM 101 started successfully. Task: \" + startTask.getUpid());\n    \n} catch (ProxmoxAPIError | InterruptedException e) {\n    System.err.println(\"Failed to start VM 101: \" + e.getMessage());\n}\n```\n\n**Clone a VM with an Asynchronous Callback**\n\n```java\nimport fr.freshperf.pve4j.entities.nodes.node.qemu.PveQemuCloneOptions;\n\ntry {\n    PveQemuCloneOptions cloneOptions = PveQemuCloneOptions.builder()\n            .name(\"clone-of-template\")\n            .description(\"A new VM cloned via PVE4J\");\n            \n    proxmox.getNodes()\n            .get(\"pve-node-01\")\n            .getQemu()\n            .get(9000)\n            .cloneVm(201, cloneOptions)\n            .onCompletion(status -\u003e {\n                if (status.isSuccessful()) {\n                    System.out.println(\"VM 201 cloned successfully!\");\n                } else {\n                    System.err.println(\"Cloning failed: \" + status.getExitstatus());\n                }\n            }, proxmox)\n            .execute();\n            \n    System.out.println(\"Clone task submitted.\");\n} catch (ProxmoxAPIError | InterruptedException e) {\n    e.printStackTrace();\n}\n```\n\n## API Overview\n\nThe library's functionality is structured hierarchically, starting from the main `Proxmox` object:\n\n- `proxmox.getVersion()` - Get the API version information\n- `proxmox.getTaskStatus(task)` - Check the status of a running task\n- `proxmox.getCluster()` - Access cluster-wide information and resources\n  - `.getStatus()` - Get the status of all cluster members\n  - `.getResources()` - List all resources in the cluster (VMs, containers, storage, etc.)\n  - `.getNextId()` - Get the next available VMID\n  - `.getHa()` - Manage High Availability\n    - `.listResources()`, `.getResource()`, `.createResource()`, `.deleteResource()`\n    - `.setResourceState()` - Change HA resource state\n- `proxmox.getNodes()` - List all nodes in the cluster\n  - `.get(\"node-name\")` - Access a specific node by its name\n    - `.getQemu()` - Manage QEMU VMs on the node\n      - `.create(vmid, options)` - Create a new VM\n      - `.get(vmid)` - Access a specific VM\n        - `.start()`, `.stop()`, `.shutdown()`, `.reboot()`, `.reset()`\n        - `.suspend()`, `.resume()`\n        - `.cloneVm()`, `.resize()`, `.delete()`\n        - `.updateConfig()`, `.getConfig()`, `.getStatus()`\n        - `.backup(options)` - Create a backup\n        - `.migrate(targetNode, online, targetStorage)` - Migrate to another node\n        - `.template()` - Convert to template\n        - `.getCloudInit()`, `.getAgent()`, `.getVnc()`, `.getRrdData()`\n        - `.getFirewall()` - Manage VM firewall settings\n          - `.getRules()` - Manage firewall rules\n        - `.getSnapshots()` - Manage VM snapshots\n    - `.getLxc()` - Manage LXC containers on the node\n      - `.create(vmid, options)` - Create a new container\n      - `.get(vmid)` - Access a specific container\n        - `.updateConfig()`, `.getConfig()`, `.getStatus()`, `.getPending()`\n        - `.getInterfaces()`, `.getFeature()`\n        - `.cloneContainer()`, `.migrate()`, `.template()`, `.delete()`\n        - `.getSnapshots()` - Manage container snapshots\n    - `.getStorage()` - Manage storage pools on the node\n- `proxmox.getPools()` - Manage resource pools\n  - `.list()` - List all resource pools\n  - `.create()` - Create a new pool\n  - `.get(poolid)` - Access a specific pool\n    - `.getDetails()` - Get pool information and members\n    - `.addVms()`, `.removeVms()` - Manage VM membership\n    - `.addStorage()`, `.removeStorage()` - Manage storage membership\n    - `.delete()` - Delete the pool\n- `proxmox.getAccess()` - Manage access control\n  - `.getUsers()` - List and manage users\n  - `.getGroups()` - List and manage groups\n  - `.getRoles()` - List and manage roles\n  - `.getAcl()` - Query access control lists\n  - `.getDomains()` - List authentication domains\n\n## Security Configuration\n\nThe `SecurityConfig` class allows you to control SSL/TLS verification:\n\n- **`SecurityConfig.secure()` (Default)** - Enforces both SSL certificate validation and hostname verification. Use this for production environments with properly configured certificates.\n\n```java\nProxmox proxmox = Proxmox.create(\"pve.example.com\", 8006, \"token\");\n```\n\n- **`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.\n\n```java\nProxmox proxmox = Proxmox.create(\"192.168.1.10\", 8006, \"token\", SecurityConfig.insecure());\n```\n\n- **Custom Configuration** - Use the builder for fine-grained control.\n\n```java\nSecurityConfig customConfig = SecurityConfig.builder()\n        .disableSslVerification()\n        .enableHostnameVerification()\n        .build();\n\n// Or disable all security checks at once\nSecurityConfig allDisabled = SecurityConfig.builder()\n        .disableAll()\n        .build();\n```\n\n## Documentation\n\nFor detailed documentation, please refer to the [Wiki](https://github.com/FreshPerf/PVE4J/wiki/Home):\n\n- [Getting Started](https://github.com/FreshPerf/PVE4J/wiki/Getting-Started)\n- [Authentication](https://github.com/FreshPerf/PVE4J/wiki/Authentication)\n- [Client Configuration](https://github.com/FreshPerf/PVE4J/wiki/Client-Configuration)\n- [Request API](https://github.com/FreshPerf/PVE4J/wiki/Request-API)\n- [VM Management](https://github.com/FreshPerf/PVE4J/wiki/VM-Management)\n- [Firewall Management](https://github.com/FreshPerf/PVE4J/wiki/Firewall-Management)\n- [Snapshot Management](https://github.com/FreshPerf/PVE4J/wiki/Snapshot-Management)\n- [Container Management](https://github.com/FreshPerf/PVE4J/wiki/Container-Management)\n- [Cluster Operations](https://github.com/FreshPerf/PVE4J/wiki/Cluster-Operations)\n- [Storage Management](https://github.com/FreshPerf/PVE4J/wiki/Storage-Management)\n- [Pool Management](https://github.com/FreshPerf/PVE4J/wiki/Pool-Management)\n- [Access Control](https://github.com/FreshPerf/PVE4J/wiki/Access-Control)\n- [Task Handling](https://github.com/FreshPerf/PVE4J/wiki/Task-Handling)\n- [Error Handling](https://github.com/FreshPerf/PVE4J/wiki/Error-Handling)\n\n## Contributing\n\nContributions are welcome and appreciated! Here's how you can help:\n\n### Reporting Issues\n\nIf you encounter a bug or have a feature request:\n\n1. Check the [issue tracker](https://github.com/FreshPerf/PVE4J/issues) to see if it's already reported\n2. If not, create a new issue with a clear description\n3. Include code samples, error messages, and your environment details\n\n### Contributing Code\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes following the existing code style\n4. Write tests for your changes\n5. Commit your changes (`git commit -m 'Add some amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n### Development Guidelines\n\n- Follow Java best practices and naming conventions\n- Maintain the fluent API design pattern\n- Add JavaDoc comments for public APIs\n- Write unit tests for new functionality\n- Ensure all tests pass before submitting a PR\n\n### Areas for Contribution\n\nWe particularly welcome contributions in these areas:\n\n- Missing API endpoint implementations\n- Additional builder options for existing operations\n- Documentation improvements\n- Example code and tutorials\n- Bug fixes and performance improvements\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0. See the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- The Proxmox VE team for their excellent virtualization platform and API documentation\n- All contributors who help improve this library\n\n## Support\n\n- **Documentation:** [Wiki](https://github.com/FreshPerf/PVE4J/wiki)\n- **Issues:** [GitHub Issues](https://github.com/FreshPerf/PVE4J/issues)\n- **AI Assistant:** [Ask DeepWiki](https://deepwiki.com/FreshPerf/PVE4J)\n\n---\n\n\u003cp align=\"center\"\u003eMaintainted with 🩵 by the \u003ca href=\"https://freshperf.fr\" target=\"_blank\"\u003eFreshPerf.fr\u003c/a\u003e Team.\u003c/p\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreshperf%2Fpve4j","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreshperf%2Fpve4j","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreshperf%2Fpve4j/lists"}