NetWorker : Guide de dépannage et de tri de l’API REST

Regarder sur YouTube

Mise en route

L’API (Representational State Transfer) fournit un accès par programmation au service de protection des données NetWorker. À l’aide de l’API REST, les utilisateurs NetWorker peuvent créer des applications clientes pour automatiser les opérations NetWorker. L’API REST NetWorker est installée dans le cadre de l’installation de NetWorker Server dans le même conteneur Apache tomcat que les services d’authentification NetWorker. L’authentification est effectuée à l’aide des mêmes informations d’identification que celles utilisées pour NetWorker Management Console.  

L’API REST permet l’interaction avec les ressources identifiées par des adresses URI (Uniform Resource Identifier). Il utilise des verbes HTTP (HEAD, GET, PUT, POST, DELETE) pour interagir avec l’URI (Uniform Resource Identifier) sans état. Le serveur ne contient aucun état client, chaque message étant autodescriptif.

Ce document traite de l’interaction avec les ressources NetWorker à l’aide d’appels d’API REST écrits par l’utilisateur. Ne doit pas être confondu avec les appels de l’API REST qui sont utilisés par les opérations NetWorker back-end.
 

Connexion à NetWorker :

Il existe plusieurs technologies clientes d’API REST différentes qui peuvent être utilisées pour exécuter les commandes de connexion à NetWorker. Y compris curl commandes (Linux), PowerShell curl.exe (Windows) et les extensions de navigateur client API REST. 

Trois en-têtes sont nécessaires pour la connexion :   

• Type de contenu : application/json
• Accepter: application/json
• Autorisation : Base avec nom d’utilisateur et mot de passe codés en Base 64

Dans les environnements où plusieurs zones de données NetWorker sont authentifiées via un seul serveur AUTHC NetWorker, un en-tête supplémentaire est requis :

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

L’API REST NetWorker est exposée dans l’URI de base suivant :

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

Il existe différentes versions d’API. Des améliorations ont été apportées depuis la mise en œuvre initiale de l’API REST. Les modifications apportées à ces points de terminaison sont détaillées dans : https://developer.dell.com/apis/2378/versions/v3/docs/GettingStarted.md

Le schéma JSON complet est disponible à l’adresse suivante :

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

Fonctions de l’API REST

Quelques exemples :

GET :

Répertoriez tous les clients.                                            

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

Un seul client, affichant uniquement trois champs (hostname, saveSets et protectionGroups)      

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

Répertorie les groupes de protection dans lesquels se trouve un client.     

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

Afficher les alertes actuelles.                                     

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

Afficher les tâches ayant récemment échoué.                               

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

Répertoriez les workflows d’une règle (nommée WinFS dans cet exemple).                   

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

Répertoriez les propriétés d’une seule instance de saveset (telles que définies par le nom d’hôte client et le saveset).      

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

PUBLIER:

Démarrez une action de workflow.                                 

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

Créez une instance de client (avec des valeurs par défaut pour toutes les propriétés, à l’exception des quatre répertoriées).           

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

Exemples de ligne de commande :

Linux :

Pour les systèmes qui ont python est installé :

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

Exemple :

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
}

Informations requises pour le support

Environnement :

• Nom du NetWorker Server
• Version et numéro de build de NetWorker
• Type et version du système d’exploitation hôte du serveur NetWorker

Linux :

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

Windows. :

nsrwatch

Détails du problème :

• Expliquez quelle opération d’API REST est en cours d’exécution (GET, POST, PUT, DELETE), l’URI utilisé, le contenu du corps JSON (le cas échéant). 
• Code de réponse de l’API REST et tout message d’erreur fourni.
• La connexion et l’autorisation initiales ont-elles été établies entre le client de l’API REST et NetWorker ?

Collecte de journaux :

• Fichier log rendu daemon.raw à partir du serveur NetWorker :
  • Linux : /nsr/logs/daemon.raw
  • Windows. : C:\Program Files\EMC NetWorker\nsr\logs\daemon.raw
  • NetWorker : utilisation de nsr_render_log
• Logs de l’API REST à partir du serveur NetWorker :  /nsr/logs/restapi (Linux) ou EMC NetWorker\nsr\logs\restapi (Windows)
• Pour les problèmes d’authentification, reportez-vous à la section Connexion à l’authentification NetWorker standard /nsr/authc/logs (Linux) ou ..\EMC NetWorker\nsr\authc-server\tomcat\logs (Windows)

Debug:

Performances :

Avant d’évaluer les problèmes liés aux performances de l’API REST, il est important de déterminer si le problème est observé sur toutes les fonctions de l’API REST ou sur des fonctions spécifiques. Par exemple, les requêtes GET sur des points de terminaison globaux tels que des clients, des tâches, des volumes, etc. peuvent extraire beaucoup de données. Ces types de demandes peuvent entraîner une utilisation élevée des ressources système et des délais d’expiration.
Voir: API REST NetWorker : Les demandes HTTP GET expirent par intermittence

Lorsque des problèmes de performances sont observés sur de grands points de terminaison globaux, il est recommandé d’utiliser le « filtre de liste de requêtes » (q) ou « filtre de liste de champs » (fl) afin de réduire les données renvoyées à des informations spécifiques requises. La base de connaissances ci-dessus détaille ces paramètres et des informations supplémentaires sont disponibles dans le Guide du développeur de l’API REST : Développeur 

Dell TechnologiesSi le problème est lié aux performances de l’API REST, vous pouvez utiliser les options suivantes pour suivre la consommation des ressources du processus nsrtomc+ utilisé par les appels d’API.

Linux:  

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

Cette sortie affiche la sortie supérieure standard, mais avec des horodatages lisibles par l’utilisateur. Cela peut être utilisé pour vérifier la consommation du processeur et de la mémoire par le processus, ainsi que la durée pendant laquelle elle est restée dans un certain état lors de l’exécution d’un appel REST. Les données peuvent être comparées aux journaux restapi.log et AUTHC pour voir quels appels ont été passés et à quelle fréquence.
 

Windows. : 

Pour les serveurs Windows, vous devez installer quelque chose comme « Performance Monitor :

1. Ouvrez l’Analyseur de performances en tant qu’administrateur.
2. Dans le volet de gauche, développez Outils de surveillance et sélectionnez Analyseur de performances.
3. Cliquez avec le bouton droit de la souris dans le volet de droite et sélectionnez Supprimer tous les compteurs.
4. Cliquez avec le bouton droit de la souris dans le volet de droite et sélectionnez Ajouter des compteurs.
5. Sous Compteurs disponibles, développez Mémoire, sélectionnez % Commit Bytes, puis cliquez sur Add.
6. Sous Mémoire, sélectionnez Octets disponibles,  puis cliquez sur Ajouter.
7. Sous Compteurs disponibles, développez Processus, puis sélectionnez % Temps processeur, puis sous Instances de l’objet sélectionné, sélectionnez la première entrée Java, puis cliquez sur Ajouter.
8. Sous Compteurs disponibles, développez Informations sur le processeur et sélectionnez % Utilitaire du processeur, puis cliquez sur Ajouter.
9. Les compteurs ajoutés dans le volet de droite doivent afficher :

10. Cliquez sur OK. Cliquez avec le bouton droit de la souris sur Analyseur de performances, puis cliquez sur New-Data> Collector Set.
11. Indiquez un nom, par exemple : RESTAPI_MON.
12. Sur l’écran Emplacement, cliquez sur Suivant,  sauf si vous choisissez de spécifier un autre emplacement de sortie.
13. Sélectionnez Enregistrer et fermer, puis cliquez sur Terminer.
14. Dans le volet de gauche , sous Data Collector Sets -> User Defined, ouvrez le RESTAPI_MON et sélectionnez Séparées par des virgules pour le format de journal, cliquez sur OK.

15. Dans le volet de gauche , sous Ensembles de contrôleurs de données -> Défini par l’utilisateur, sélectionnez l’ensemble de collecteurs de données RESTAPI_MON, puis cliquez sur Démarrer (bouton Lecture)
16. Si l’emplacement de sortie par défaut a été utilisé, le fichier .csv s’affiche sous C:\PerfLogs\Admin\RESTAPI_MON.
17. Une fois que le problème est observé et enregistré dans le fichier de sortie, vous pouvez arrêter la surveillance en cliquant sur Stop sous Data Collector Sets - User Defined.