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.