urbackup/urbackup-api-actions.md

UrBackup API Actions (testati)

Server: http://localhost:55414 Credenziali: utente admin, password 12345678 API Version: 2

Riepilogo dei test (aggiornato 05/08/2026 — login 2-fasi VERIFICATO)

• Login (2-fasi salt/PBKDF2): ✅ FUNZIONANTE — POST username=admin a /x?a=salt → {"salt":"...","pbkdf2_rounds":10000,"rnd":"...","ses":"..."}; poi POST username=admin&password=<hash>&ses=<ses> a /x?a=login → {"success":true,...}. Hash = md5(md5_bin(salt+password) passato a PBKDF2-SHA256 con i rounds del salt, poi md5(rnd+risultato)). Con admin/12345678 il 05/08/2026: hash=4b640fe71c904e43c04ab17aa3fe3f5e → success:true.
• Login (stile v1 u=admin&p=12345678): ❌ fallisce ({"success":false}) — il server locale richiede il flusso 2-fasi.
• Salt: ✅ accessibile SENZA autenticazione (POST username=admin); l'eventuale {"error":1} era dovuto alla richiesta GET/v1.
• Status: ✅ testabile con sessione valida (POST /x?a=status&ses=...).
• Version: Non supportato; → "Error: Unknown action [version]"
• Server Identity: Non supportato; → "Error: Unknown action [server_identity]"
• Backups: Testabile con sessione valida.
• Livelog: Non testato (azione disponibile nel codice)
• Start Backup: Non testato (azione disponibile nel codice)
• Add Client: Non testato (azione disponibile nel codice)
• Remove Client: Non testato (azione disponibile nel codice)
• Clientsettings: Non testato (azione disponibile nel codice)
• Clientsettings_save: Non testato (azione disponibile nel codice)

API Actions disponibili nel codice (UrbackupApiClient.php)

Client Status

• getStatus(): Ottiene tutti i client → endpoint status
• getClientStatusByName(string $client_name): Ricerca client per nome
• getClientIdByName(string $client_name): Ottiene ID client per nome

Client Settings

• getClientSettings(string $client_name): Ottiene impostazioni client → endpoint settings con sa=clientsettings
• updateClientSettings(string $client_name, string $key, string $value): Aggiorna impostazioni client
• saveInternetMode(string $client_name, bool $enabled): Salva impostazione internet mode
• getClientAuthKey(string $client_name): Ottiene chiave di autenticazione internet client

Client Operations

• addClient(string $client_name): Aggiunge client → endpoint add_client
• removeClient(string $client_name): Rimuove client → endpoint remove_client

Backup Operations

• startIncrementalFileBackup(string $client_name): Avvia backup file incrementale
• startFullFileBackup(string $client_name): Avvia backup file completo
• startIncrementalImageBackup(string $client_name): Avvia backup immagine incrementale
• startFullImageBackup(string $client_name): Avvia backup immagine completo
• getRecentBackups(string $client_name, int $limit = 40): Ottiene backup recenti → endpoint backups

Log Operations

• getClientLogs(string $client_name, int $limit = 50): Ottiene log client → endpoint livelog

Server Operations

• getServerIdentity(): Ottiene identità server → endpoint server_identity

Dettaglio del payload delle API

Login (2-fasi, come implementato in UrbackupApiClient::login())

Fase 1 — GET/POST /x?a=salt
  Parametri: username=<utente>
  Risposta: {"salt":"...","pbkdf2_rounds":10000,"rnd":"...","ses":"..."}

Fase 2 — POST /x?a=login
  Parametri: username=<utente>, password=<hash>, ses=<ses da fase 1>
  hash = md5( pbkdf2_sha256( md5_bin(salt . password), salt, pbkdf2_rounds ) . rnd )
  (md5_bin = md5 binario, non esadecimale)

Risposta attesa: {"success": true, ...}

• Esempio verificato il 05/08/2026 con admin/12345678: hash=4b640fe71c904e43c04ab17aa3fe3f5e → "success":true.
• Lo stile v1 (u=/p=hash MD5) NON funziona sul server locale.

Salt

Endpoint: POST /x?a=salt?username=...
Risposta attesa: {"success": true, "salt": "...", "rnd": "...", "pbkdf2_rounds": ...}

Status

Endpoint: POST /x?a=status
Con sessione: ?ses=...
Risposta attesa: {"success": true, "status": [{"id":...,"name":...}]}

Settings (clientsettings)

Endpoint: POST /x?a=settings
Parametri:
sa=clientsettings
t_clientid=id_client
use=valore
value=valore
value_client=valore_client
value_group=valore_group

Settings Save (clientsettings_save)

Endpoint: POST /x?a=settings
Parametri:
sa=clientsettings_save
t_clientid=id_client
overwrite=true
key=valore

Backups

Endpoint: POST /x?a=backups
Con sessione: ?ses=...
Parametri:
sa=backups
clientid=id_client

Livelog

Endpoint: POST /x?a=livelog
Con sessione: ?ses=...
Parametri:
clientid=id_client
lastid=ultimo_id

Start Backup

Endpoint: POST /x?a=start_backup
Con sessione: ?ses=...
Parametri:
start_client=clientid
start_type=tipo (incr_file/full_file/incr_image/full_image)

Add Client

Endpoint: POST /x?a=add_client
Con sessione: ?ses=...
Parametri:
clientname=nome_client

Remove Client

Endpoint: POST /x?a=remove_client
Con sessione: ?ses=...
Parametri:
clientid=id_client (opzionale)
clientname=nome_client

Server Identity

Endpoint: POST /x?a=server_identity
Con sessione: ?ses=...
Risposta attesa: {"server_identity": "nome_server"}

Struct delle impostazioni (clientsettings)

{
    "use": "bool",
    "value": "mixed",
    "value_client": "string",
    "value_group": "string"
}

Struct dei backup (backups)

{
    "backup_id": backup id,
    "machine_name": server machine name,
    "starttime": "timestamp",
    "endtime": "timestamp",
    "status": "status",
    "size": "size"
}

Struttura del log (livelog)

{
    "time": "timestamp",
    "level": "level",
    "message": "message",
    "id": "log id"
}

Note sull'autenticazione

Il client implementa un flusso di autenticazione a due fasi:

1. Inizia il login con username → endpoint login
2. Se salta, chiama /x?a=salt con username per ottenere salt e RNG
3. Calcola hash password: hash_pbkdf2('sha256', md5(salt_str . password), salt_str, pbkdf2_rounds) + md5(rnd + passwordMd5)
4. Completa il login con username/password/hash/rnd/ses

Errori riscontrati

1. Autenticazione: u=admin&p=12345678 non valido; potrebbe non esistere nel server UrBackup
2. Salt: Fallisce senza autenticazione corretta
3. URL endpoint: Alcuni test con ?a=server_identity falliscono, suggerendo potrebbero usare un nome azione diverso

Passaggi successivi

1. Verificare esistenza utente admin nel server UrBackup (potrebbe non esistere)
2. Usare u=admin&p=12345678 non valido; ottenere credenziali corrette
3. Tentare di ottenere session token tramite il corretto flusso di autenticazione a due fasi
4. La maggior parte delle API funziona ma richiede autenticazione valida

Correzione del codice necessaria per future chiamate API

Il codice UrbackupApiClient.php usa una sessione con ses obbligatorio in tutte le chiamate API autenticate. La libreria del client non implementa yet gestione automatica del token di autenticazione a due fasi per tutte le azioni.