[PATCH proxmox-backup v2 3/9] api: add /nodes/localhost/identity

Lukas Wagner
2026-04-24T08:31:16Z

This one returns a unique ID that can be used to uniquely identify a PBS
node. This will be used by PDM to match PBS storages in a PVE cluster to
PBS remotes in PDM, mainly for associating backup jobs with the
appropriate PBS remote. Later we can also use this to match PBS sync
jobs to their matching PBS remotes in PDM.

The instance ID is derived from /etc/machine-id as recommended by
systemd [1] by using proxmox_systemd::sd_id128::get_app_specific_id.

[1] https://www.freedesktop.org/software/systemd/man/latest/sd_id128_get_machine_app_specific.html

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
---
src/api2/node/mod.rs | 40 +++++++++++++++++++++++++++++++++++++---
1 file changed, 37 insertions(+), 3 deletions(-)

diff --git a/src/api2/node/mod.rs b/src/api2/node/mod.rs
index 42e1dbaa2..3d48629e1 100644
--- a/src/api2/node/mod.rs
+++ b/src/api2/node/mod.rs
@@ -25,7 +25,7 @@ use proxmox_schema::*;
use proxmox_sortable_macro::sortable;
use proxmox_sys::fd::fd_change_cloexec;

-use pbs_api_types::{NodeShellTicket, NODE_SCHEMA, PRIV_SYS_CONSOLE};
+use pbs_api_types::{NodeShellTicket, ServerIdentity, NODE_SCHEMA, PRIV_SYS_CONSOLE};
use tracing::{info, warn};

use crate::auth::{private_auth_keyring, public_auth_keyring};
@@ -291,12 +291,46 @@ fn list_nodes() -> Result<Value, Error> {
Ok(json!([ { "node": proxmox_sys::nodename().to_string() } ]))
}

-pub const SUBDIRS: SubdirMap = &[
+/// Static key used for deriving a unique instance id from `/etc/machine-id` using
+/// [`proxmox_systemd::sd_id128::get_app_specific_id`].
+///
+/// This key was generated by `systemd-id128 new`.
+///
+const INSTANCE_ID_KEY: [u8; 16] = 0xe5415d9999c146399b8bdae1260e19d2_u128.to_le_bytes();
+
+#[api(
+ input: {
+ properties: {
+ node: {
+ schema: NODE_SCHEMA,
+ optional: true,
+ },
+ }
+ },
+ returns: {
+ type: ServerIdentity,
+ },
+ access: {
+ permission: &Permission::Anybody,
+ }
+)]
+/// Returns a unique server identity. The ID is derived from `/etc/machine-id`.
+pub fn get_identity() -> Result<ServerIdentity, Error> {
+ let machine_id_derived_app_id =
+ proxmox_systemd::sd_id128::get_app_specific_id(INSTANCE_ID_KEY)?;
+ let pbs_instance_id = hex::encode(machine_id_derived_app_id);
+
+ Ok(ServerIdentity { pbs_instance_id })
+}
+
+#[sortable]
+pub const SUBDIRS: SubdirMap = &sorted!([
("apt", &apt::ROUTER),
("certificates", &certificates::ROUTER),
("config", &config::ROUTER),
("disks", &disks::ROUTER),
("dns", &dns::ROUTER),
+ ("identity", &Router::new().get(&API_METHOD_GET_IDENTITY)),
("journal", &journal::ROUTER),
("network", &network::ROUTER),
("report", &report::ROUTER),
@@ -312,7 +346,7 @@ pub const SUBDIRS: SubdirMap = &[
"vncwebsocket",
&Router::new().upgrade(&API_METHOD_WEBSOCKET),
),
-];
+]);

pub const ITEM_ROUTER: Router = Router::new()
.get(&list_subdirs_api_method!(SUBDIRS))
--
2.47.3