NetWorker: Guida alla risoluzione dei problemi e alla valutazione delle API REST

Guarda su YouTube

Guida introduttiva

L'API (Application Programming Interface) REST (Representational State Transfer) fornisce l'accesso programmatico al servizio di protezione dei dati NetWorker. Utilizzando l'API REST, gli utenti di NetWorker possono creare applicazioni client per automatizzare le operazioni di NetWorker. L'API REST NetWorker viene installata come parte dell'installazione del server NetWorker nello stesso container Apache Tomcat dei servizi di autenticazione NetWorker. L'autenticazione viene eseguita con le stesse credenziali usate per NetWorker Management Console.  

L'API REST consente l'interazione con le risorse identificate da indirizzi URI (Uniform Resource Identifier). Utilizza verbi HTTP (HEAD, GET, PUT, POST, DELETE) per interagire con l'URI (Uniform Resource Identifier) in modo senza stato. Il server non contiene alcuno stato del client, ogni messaggio è autodescrittivo.

Questo documento illustra l'interazione con le risorse di NetWorker tramite chiamate API REST scritte dall'utente. Da non confondere con le chiamate API REST utilizzate dalle operazioni back-end di NetWorker.
 

Connessione a NetWorker:

Esistono diverse tecnologie client API REST che possono essere utilizzate per eseguire i comandi per la connessione a NetWorker. Compreso curl (Linux), PowerShell curl.exe (Windows) e le estensioni del browser client API REST. 

Per la connessione sono necessarie tre intestazioni:   

• Tipo di contenuto: application/json
• Accettare: application/json
• Authorization: Base con nome utente e password codificati Base 64

Negli ambienti in cui sono presenti più datazone NetWorker autenticate tramite un singolo server NetWorker AUTHC, è necessaria un'intestazione aggiuntiva:

• X-NW-AUTHC-BASE-URL:AUTHC_HOSTNAME_OR_IP:AUTHC_PORT

L'API REST NetWorker è esposta nel seguente URI di base:

https://[nw-server-hostname]:9090/nwrestapi/v3

Esistono diverse versioni di API. Da quando è stata inizialmente implementata l'API REST, sono stati implementati miglioramenti. Le modifiche apportate a questi endpoint sono descritte in dettaglio in: https://developer.dell.com/apis/2378/versions/v3/docs/GettingStarted.md

Lo schema json completo è disponibile all'indirizzo:

https://[nw-server-hostname]:9090/nwrestapi/v3/schemas/swagger.json

Funzioni API REST

Alcuni esempi:

GET:

Elencare tutti i client.                                            

https://[nw-server-hostname]:9090/nwrestapi/v3/global/clients

Un solo client, con visualizzazione di soli tre campi (hostname, saveSet e protectionGroups)      

https://[nw-server-hostname]:9090/nwrestapi/v3/global/clients?fl=hostname,saveSets,protectionGroups&q=hostname:nwserver121

Elencare i gruppi di protezione in cui si trova un client.     

https://[nw-server-hostname]:9090/nwrestapi/v3/global/clients?fl=protectionGroups&q=hostname:nwserver121

Mostrare gli avvisi correnti.                                     

https://[nw-server-hostname]:9090/nwrestapi/v3/global/alerts

Mostra i processi recenti non riusciti.                               

https://[nw-server-hostname]:9090/nwrestapi/v3/global/jobs?q=completionStatus:"Failed"&fl=clientHostname,startTime,name,message

Elencare i flussi di lavoro in una policy (denominata WinFS in questo esempio).                   

https://[nw-server-hostname]:9090/nwrestapi/v3/global/protectionpolicies/WinFS/workflows

Elencare le proprietà di una sola istanza del saveset (come definito dal nome host del client e dal saveset).      

https://[nw-server-hostname]:9090/nwrestapi/v3/global/clients?q=hostname:vm-lego-231 and saveSets:"/etc"

INSERISCI:

Avvia un'azione del flusso di lavoro.                                 

https://[nw-server-hostname]:9090/nwrestapi/v3/global/protectionpolicies/Angela/workflows/WinFS/op/backup
                                                      JSON Body: 
                                                      {
                                                       }

Creare una nuova istanza client (con valori predefiniti per tutte le proprietà tranne le quattro elencate).           

https://[nw-server-hostname]:9090/nwrestapi/v3/global/clients  
                                                     JSON Body 
                                                     {    
            "hostname": "vm-lego-231",
            "backupType": "Filesystem",
            "saveSets": [ "/etc" ],
            "protectionGroups" : [ "LinuxFS" ]
                                                          

Esempi di riga di comando:

Linux:

Per i sistemi che dispongono di python installata:

curl -k -u Administrator:'ADMINISTRATOR_PASSWORD' https://NETWORKER_SERVER_ADDRESS:9090/nwrestapi/v3/global/ENDPOINT | python -m json.tool

curl -k -u Administrator:'ADMINISTRATOR_PASSWORD' https://NETWORKER_SERVER_ADDRESS:9090/nwrestapi/v3/global/ENDPOINT | jq

[root@nsr ~]# curl -k -u Administrator https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01 | jq
Enter host password for user 'Administrator':
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  2820    0  2820    0     0  72307      0 --:--:-- --:--:-- --:--:-- 72307
{
  "accessWeight": 1,
  "accesses": "66",
  "activeSessions": [],
  "autoMediaManagement": false,
  "autoRecoverDtf": "None",
  "cdi": "NotUsed",
  "cleaningRequired": false,
  "consecutiveErrors": "0",
  "currentNSRMMDCount": "1",
  "dataDomainFibreChannel": false,
  "dataDomainRetentionLockMode": "None",
  "deviceAccessInfo": "ddve01.amer.lan:/nsr/VMBackupDevice01",
  "deviceBlockSize": "HandlerDefault",
  "dltWormCapable": false,
  "idleDeviceTimeout": 0,
  "jukeboxDevice": "No",
  "links": [
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01/opstatus",
      "title": "Volume operation status"
    },
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01/op/label",
      "title": "Label volume"
    },
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01/op/mount",
      "title": "Mount volume"
    },
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01/op/unmount",
      "title": "Unmount volume"
    },
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01/op/verifylabel",
      "title": "Verify volume label"
    },
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/devices/ddve01.amer.lan_VMBackupDevice01/op/erase",
      "title": "Erase the device"
    },
    {
      "href": "https://nsr.amer.lan:9090/nwrestapi/v3/global/volumes/4267924096",
      "title": "Volume"
    }
  ],
  "longVolumeId": "703cdc60-00000005-fe635a80-66635a80-00045000-592bbe56",
  "maxConsecutiveErrors": 20,
  "maxNsrmmdCount": 4,
  "maxSession": 60,
  "mediaFamily": "Disk",
  "mediaType": "Data Domain",
  "message": "mounted Data Domain disk VMBackupPool.001",
  "mountedVolume": "VMBackupPool.001",
  "name": "ddve01.amer.lan_VMBackupDevice01",
  "ndmp": false,
  "operationParameters": [],
  "password": "*******",
  "pathId": "53f9269d-00000010-e2f994bd-66635a7e-00035000-592bbe56",
  "readOnly": false,
  "remoteUser": "ddboost",
  "reserveRelease": "None",
  "resourceId": {
    "id": "178.0.90.20.0.0.0.0.196.80.99.102.192.168.9.150",
    "sequence": 256
  },
  "saveLockout": 0,
  "saveMountTimeout": 30,
  "secureMultiTenancy": false,
  "sharedDevices": "Done",
  "statistics": [
    "elapsed = 17310",
    "errors = 0",
    "last rate = 0",
    "max clients = 0",
    "file marks = 0",
    "rewinds = 0",
    "files skipped = 0",
    "records skipped = 0",
    "current file = 0",
    "current record = 0",
    "seek files = 0",
    "seek records = 0",
    "estimated kb = 0",
    "amount kb = 0",
    "file amount kb = 0",
    "sessions = 0"
  ],
  "status": "Enabled",
  "suspectedDevice": false,
  "tapeAlertsCritical": [],
  "tapeAlertsInformation": [],
  "tapeAlertsWarning": [],
  "targetSession": 20,
  "unlabeledVolumeLoaded": false,
  "verifyLabelOnEject": false,
  "volumeBlockSize": "256 KB",
  "volumeCurrentCapacity": "0 KB",
  "volumeErrorNumber": "0",
  "volumeExpiration": "Sun Jun  7 15:07:44 2026",
  "volumeId": "4267924096",
  "volumeLabel": "VMBackupPool.001",
  "volumePool": "VMBackupPool",
  "warnOnSuspectVolumesInPercent": 80,
  "wormCapable": false,
  "wormCartridgePresent": false,
  "writeEnabled": true
}
[root@nsr ~]#

Windows (PowerShell):

curl.exe -k -u Administrator:'ADMISTRATOR_PASSWORD' "https://NETWORKER_SERVER_ADDRESS:9090/nwrestapi/v3/global/ENDPOINT" | ConvertFrom-Json | ConvertTo-Json -Depth 50

Esempio:

PS C:\Users\Administrator.NETWORKER> curl.exe -k -u Administrator:'!Password1' "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup" | ConvertFrom-Json | ConvertTo-Json -Depth 50
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  2824    0  2824    0     0  20311      0 --:--:-- --:--:-- --:--:-- 21074
{
    "accessWeight":  1,
    "accesses":  "45",
    "activeSessions":  [

                       ],
    "autoMediaManagement":  false,
    "autoRecoverDtf":  "None",
    "cdi":  "NotUsed",
    "cleaningRequired":  false,
    "consecutiveErrors":  "0",
    "currentNSRMMDCount":  "1",
    "dataDomainFibreChannel":  false,
    "dataDomainRetentionLockMode":  "None",
    "deviceAccessInfo":  "dd3300-ff28:/win-srvr02/Backup",
    "deviceBlockSize":  "HandlerDefault",
    "dltWormCapable":  false,
    "idleDeviceTimeout":  0,
    "jukeboxDevice":  "No",
    "links":  [
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup/opstatus",
                      "title":  "Volume operation status"
                  },
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup/op/label",
                      "title":  "Label volume"
                  },
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup/op/mount",
                      "title":  "Mount volume"
                  },
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup/op/unmount",
                      "title":  "Unmount volume"
                  },
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup/op/verifylabel",
                      "title":  "Verify volume label"
                  },
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/devices/dd3300-ff28_Backup/op/erase",
                      "title":  "Erase the device"
                  },
                  {
                      "href":  "https://win-srvr02.networker.lan:9090/nwrestapi/v3/global/volumes/3963713",
                      "title":  "Volume"
                  }
              ],
    "longVolumeId":  "0aea479c-00000005-003c7b41-693c7b41-00025000-e6b5bb56",
    "maxConsecutiveErrors":  20,
    "maxNsrmmdCount":  4,
    "maxSession":  60,
    "mediaFamily":  "Disk",
    "mediaType":  "Data Domain",
    "message":  "writing, done",
    "mountedVolume":  "win_srvr02.networker.lan.dddefault.001",
    "name":  "dd3300-ff28_Backup",
    "ndmp":  false,
    "operationParameters":  [

                            ],
    "password":  "*******",
    "pathId":  "a30a7858-00000010-5ded760e-693c7b41-00015000-e6b5bb56",
    "readOnly":  false,
    "remoteUser":  "loudekboost",
    "reserveRelease":  "None",
    "resourceId":  {
                       "id":  "176.0.164.7.0.0.0.0.69.121.60.105.192.168.0.22",
                       "sequence":  100
                   },
    "saveLockout":  0,
    "saveMountTimeout":  30,
    "secureMultiTenancy":  false,
    "sharedDevices":  "Done",
    "statistics":  [
                       "elapsed = 228514",
                       "errors = 0",
                       "last rate = 0",
                       "max clients = 0",
                       "file marks = 0",
                       "rewinds = 0",
                       "files skipped = 0",
                       "records skipped = 0",
                       "current file = 0",
                       "current record = 0",
                       "seek files = 0",
                       "seek records = 0",
                       "estimated kb = 0",
                       "amount kb = 0",
                       "file amount kb = 52206",
                       "sessions = 0"
                   ],
    "status":  "Enabled",
    "suspectedDevice":  false,
    "tapeAlertsCritical":  [

                           ],
    "tapeAlertsInformation":  [

                              ],
    "tapeAlertsWarning":  [

                          ],
    "targetSession":  20,
    "unlabeledVolumeLoaded":  false,
    "verifyLabelOnEject":  false,
    "volumeBlockSize":  "256 KB",
    "volumeCurrentCapacity":  "0 KB",
    "volumeErrorNumber":  "0",
    "volumeExpiration":  "Sun Dec 12 15:29:53 2027",
    "volumeId":  "3963713",
    "volumeLabel":  "win_srvr02.networker.lan.dddefault.001",
    "volumePool":  "Data Domain Default",
    "warnOnSuspectVolumesInPercent":  80,
    "wormCapable":  false,
    "wormCartridgePresent":  false,
    "writeEnabled":  true
}

Informazioni richieste per il supporto

Ambiente:

• Nome server NetWorker
• Versione e numero di build di NetWorker
• Tipo e versione del sistema operativo host del server NetWorker

Linux:

hostname
strings /usr/sbin/nsrd | grep -i "(#)"
cat /etc/*release
uname -a

Windows:

nsrwatch

Dettagli del problema:

• Spiegare quale operazione API REST viene eseguita (GET, POST, PUT, DELETE), l'URI utilizzato e il contenuto del corpo JSON (se applicabile). 
• Codice di risposta dell'API REST ed eventuale messaggio di errore fornito.
• La connessione e l'autorizzazione iniziali tra il client API REST e NetWorker sono riuscite?

Raccolta dei registri:

• Rendering daemon.raw file di log dal server NetWorker:
  • Linux: /nsr/logs/daemon.raw
  • Windows: C:\Program Files\EMC NetWorker\nsr\logs\daemon.raw
  • NetWorker: Come utilizzare nsr_render_log (in inglese)
• Log API REST dal server NetWorker:  /nsr/logs/restapi (Linux) o EMC NetWorker\nsr\logs\restapi (Windows)
• Per i problemi di autenticazione, consultare la procedura di accesso standard per l'autenticazione di NetWorker /nsr/authc/logs (Linux) o ..\EMC NetWorker\nsr\authc-server\tomcat\logs (Windows)

Debug:

Prestazione:

Prima di valutare i problemi relativi alle prestazioni dell'API REST, è importante determinare se il problema viene osservato su tutte le funzioni dell'API REST o su funzioni specifiche. Ad esempio, le richieste GET su endpoint globali, come client, job, volumi e così via, possono estrarre una grande quantità di dati. Questi tipi di richieste possono comportare un utilizzo elevato delle risorse di sistema e timeout.
Vedere: API REST NetWorker: Le richieste HTTP GET sono in timeout intermittente

Quando si riscontrano problemi di prestazioni sugli endpoint globali di grandi dimensioni, è consigliabile utilizzare il "filtro dell'elenco di query" (q) o "filtro elenco campi" (fl) per ridurre i dati restituiti alle informazioni specifiche necessarie. L'articolo della KB precedente descrive in dettaglio queste impostazioni e ulteriori informazioni sono disponibili nella Guida per gli sviluppatori di API REST: Sviluppatore Dell Technologies 

Se il problema è correlato alle prestazioni dell'API REST, è possibile utilizzare le seguenti opzioni per tenere traccia dell'utilizzo delle risorse del processo nsrtomc+ utilizzato dalle chiamate API.

Linux:  

top -b | awk '/nsrtomc+/ {print strftime("%Y-%m-%d-%H:%M:%S", systime()), $0}'

Questo output mostra l'output superiore standard, ma con timestamp leggibili. Può essere utilizzato per esaminare il consumo di CPU e memoria da parte del processo e per quanto tempo è rimasto in un determinato stato quando è stata effettuata una chiamata REST. È possibile confrontarlo con i registri restapi.log e AUTHC per vedere quali chiamate sono state effettuate e con quale frequenza.
 

Windows: 

Per i server Windows, è necessario installare qualcosa come "Performance Monitor:

1. Aprire Performance Monitor come amministratore.
2. Nel riquadro di sinistra, espandere Monitoring Tools e selezionare Performance Monitor.
3. Cliccare con il pulsante destro del mouse all'interno del riquadro di destra e selezionare Remove all Counters.
4. Cliccare con il pulsante destro del mouse all'interno del riquadro di destra e selezionare Add Counters.
5. In Available Counters, espandere Memory, selezionare % Commit Bytes e cliccare su Add.
6. In Memory selezionare Available Bytes e cliccare su Add.
7. In Available Counters espandere Process e selezionare % Processor Time e in Instances of Selected object selezionare la prima voce Java, quindi cliccare su Add.
8. In Available Counters espandere Processor Information e selezionare % Processor Utility, quindi cliccare su Add.
9. I contatori aggiunti nel riquadro destro dovrebbero mostrare:

10. Cliccare su OK. Cliccare con il pulsante destro del mouse su Monitoraggio prestazioni, quindi cliccare su Nuovo> set agenti di raccolta dati.
11. Fornire un nome, ad esempio: RESTAPI_MON.
12. Nella schermata del percorso, cliccare su Avanti,  a meno che non si scelga di specificare un percorso di output alternativo.
13. Selezionare Save and Close , quindi cliccare su Finish.
14. Nel riquadro a sinistra, in Set agenti raccolta dati-Definito dall'utente,> aprire la finestra RESTAPI_MON e selezionare Comma Separated per il formato di registro, quindi cliccare su OK.

15. Nel riquadro sinistro, in Set agenti raccolta dati-Definito dall'utente,>selezionare il set di agenti raccoglitori dati RESTAPI_MON e cliccare su Avvia (pulsante Play)
16. Se è stato utilizzato il percorso di output predefinito, il file .csv viene visualizzato in C:\PerfLogs\Admin\RESTAPI_MON.
17. Una volta che il problema è stato osservato e registrato nel file di output, è possibile interrompere il monitoraggio cliccando su Stop in Set agenti di raccolta dati - Definito dall'utente.