Update NetBackup Documentation

README.md

@@ -1,23 +1,25 @@
 ### NetBackup API Code Samples
 
-Contains code samples to invoke NetBackup REST API using different programming languages.
+Contains code samples of using NetBackup REST APIs in different scripting/programming languages.
 
-#### Disclaimer
-These scripts are only meant to be used as a reference. Please do not use these in production.
+##### Disclaimer
+These samples are only meant to be used as a reference. Please do not use these in production.
 
-#### Executing the snippets for different programming languages
+##### Executing the 'snippets'
 
-The `snippets` folder contains code samples to invoke NetBackup REST API using different programming languages. 
+The `snippets` folder contains code samples to invoke NetBackup APIs using different scripting/programming languages. 
+These are usually simple examples that demonstrate specific API. 
 
 Pre-requisites:
 
 - NetBackup 8.1.1 or higher
 - See the script's README for the corresponding requirements and usage
 
 
-#### Executing the recipes for different programming languages
+##### Executing the 'recipes'
 
-The `recipes` folder contains code samples to invoke NetBackup REST API using different programming languages. 
+The `recipes` folder contains code samples to invoke NetBackup APIs using different scripting/programming languages. 
+These are usually examples of usage of multiple APIs covering specific use-cases.
 
 Pre-requisites:
 
@@ -26,8 +28,29 @@ Pre-requisites:
 
 
 
-#### Tools
-The `tools` folder contains utilities that have proven useful in the development of projects using
-NetBackup REST APIs, but do not provide any API usage examples.  Again, these tools are not for
-production use, but they may be of some use in your work.
+##### Tools
+The `tools` folder contains utilities that have proven useful in the development of projects using NetBackup APIs, but do not provide any API usage examples.  Again, these tools are not for production use, but they may be of some use in your work.
 
+#### NetBackup 8.3 RBAC Design Shift
+NetBackup 8.3 introduced a major change in its RBAC configuration and enforcement design.  
+
+RBAC was introduced to NetBackup in the 8.1.2 release, offering access control for a limited number of security settings and workloads.  That access control configuration was based on a dynamic object-level enforcement model using “Access Rules”.
+
+With the NetBackup 8.3 release, RBAC has moved away from the dynamic access rule design.  
+The new RBAC allows more granular permissions, improved flexibility and greater control. The RBAC design is now based on Access Control Lists (ACLs) and closely follows the ANSI INCITS 359-2004.  While the earlier design of RBAC enforcement was dynamic in nature, the new RBAC is static in its configuration.
+
+The system-defined roles shipped with NetBackup also changed from 8.1.2 to the 8.3 release.  In 8.1.2, there were three system-defined roles available for RBAC configuration.  In the 8.3 release, this was simplified to offer a single “Administrator” role which has all privileges for RBAC.
+
+Due to the significant design shift, automatic upgrade conversion of 8.1.2 RBAC roles to the new 8.3 roles is not feasible.  However, tools are available to migrate the Backup administrator role and create a new Security administrator role for the users that had the old RBAC Security administrator role. 
+Other roles must be reconfigured manually. 
+There is also a script in this repository available to generate templated NetBackup roles.
+See **/recipes/perl/access-control/rbac_role_templates.pl**
+
+
+Any API keys in use prior to upgrade will still be valid, however, the underlying access granted those API keys must
+ be reconfigured using the new RBAC configuration, after which any active user sessions must be removed.
+A utility script exists in this repository to help convert active API keys after upgrade to NetBackup 8.3.  
+See **/recipes/perl/access-control/access_control_api_requests.pl**
+
+Most of the API examples in this repository assume a valid JWT (Json Web Token) or API Key issued by NetBackup and do
+ not incorporate role configuration as part of the script. However, there may be some examples which do configure RBAC as part of the script and have not yet been updated to use the RBAC design.

recipes/go/admin/README.md

@@ -0,0 +1,18 @@
+### NetBackup API Code Samples for go (often referred to as golang)
+
+This directory contains code samples to invoke NetBackup administration REST APIs using go.
+
+#### Disclaimer
+
+These scripts are only meant to be used as a reference. If you intend to use them in production, use it at your own risk.
+
+#### Pre-requisites:
+
+- NetBackup 8.2 or higher
+- go1.10.2 or higher
+
+#### Executing the recipes using go
+
+Use the following commands to run the go samples.
+- `go run ./get_processes.go -nbmaster <masterServer> -username <username> -password <password> [-domainName <domainName>] [-domainType <domainType>] -client <client>`
+- `go run ./get_services.go -nbmaster <masterServer> -username <username> -password <password> [-domainName <domainName>] [-domainType <domainType>] -client <client>`

recipes/go/admin/get_processes.go

@@ -0,0 +1,56 @@
+//This script can be run using NetBackup 8.2 and higher.
+//It gets all NetBackup processes running on the given host.
+
+package main
+
+import (
+    "flag"
+    "fmt"
+    "log"
+    "os"
+    "apihelper"
+)
+
+//###################
+// Global Variables
+//###################
+var (
+    nbmaster            = flag.String("nbmaster", "", "NetBackup Master Server")
+    username            = flag.String("username", "", "User name to log into the NetBackup webservices")
+    password            = flag.String("password", "", "Password for the given user")
+    domainName          = flag.String("domainName", "", "Domain name of the given user")
+    domainType          = flag.String("domainType", "", "Domain type of the given user")
+    client              = flag.String("client", "", "NetBackup host name")
+)
+
+const usage = "\n\nUsage: go run ./get_processes.go -nbmaster <masterServer> -username <username> -password <password> [-domainName <domainName>] [-domainType <domainType>] -client <client>\n\n"
+
+func main() {
+    // Print usage
+    flag.Usage = func() {
+        fmt.Fprintf(os.Stderr, usage)
+        os.Exit(1)
+    }
+
+    // Read command line arguments
+    flag.Parse()
+
+    if len(*nbmaster) == 0 {
+        log.Fatalf("Please specify the name of the NetBackup Master Server using the -nbmaster parameter.\n")
+    }
+    if len(*username) == 0 {
+        log.Fatalf("Please specify the username using the -username parameter.\n")
+    }
+    if len(*password) == 0 {
+        log.Fatalf("Please specify the password using the -password parameter.\n")
+    }
+    if len(*client) == 0 {
+        log.Fatalf("Please specify the name of a NetBackup host using the -client parameter.\n")
+    }
+
+    httpClient := apihelper.GetHTTPClient()
+    jwt := apihelper.Login(*nbmaster, httpClient, *username, *password, *domainName, *domainType)
+    hostUuid := apihelper.GetHostUUID(*nbmaster, httpClient, jwt, *client);
+    filter := "";
+    apihelper.GetProcesses(*nbmaster, httpClient, jwt, *client, hostUuid, filter);
+}

recipes/go/admin/get_services.go

@@ -0,0 +1,55 @@
+//This script can be run using NetBackup 8.2 and higher.
+//It gets all NetBackup services available on the given host.
+
+package main
+
+import (
+    "flag"
+    "fmt"
+    "log"
+    "os"
+    "apihelper"
+)
+
+//###################
+// Global Variables
+//###################
+var (
+    nbmaster            = flag.String("nbmaster", "", "NetBackup Master Server")
+    username            = flag.String("username", "", "User name to log into the NetBackup webservices")
+    password            = flag.String("password", "", "Password for the given user")
+    domainName          = flag.String("domainName", "", "Domain name of the given user")
+    domainType          = flag.String("domainType", "", "Domain type of the given user")
+    client              = flag.String("client", "", "NetBackup host name")
+)
+
+const usage = "\n\nUsage: go run ./get_services.go -nbmaster <masterServer> -username <username> -password <password> [-domainName <domainName>] [-domainType <domainType>] -client <client>\n\n"
+
+func main() {
+    // Print usage
+    flag.Usage = func() {
+        fmt.Fprintf(os.Stderr, usage)
+        os.Exit(1)
+    }
+
+    // Read command line arguments
+    flag.Parse()
+
+    if len(*nbmaster) == 0 {
+        log.Fatalf("Please specify the name of the NetBackup Master Server using the -nbmaster parameter.\n")
+    }
+    if len(*username) == 0 {
+        log.Fatalf("Please specify the username using the -username parameter.\n")
+    }
+    if len(*password) == 0 {
+        log.Fatalf("Please specify the password using the -password parameter.\n")
+    }
+    if len(*client) == 0 {
+        log.Fatalf("Please specify the name of a NetBackup host using the -client parameter.\n")
+    }
+
+    httpClient := apihelper.GetHTTPClient()
+    jwt := apihelper.Login(*nbmaster, httpClient, *username, *password, *domainName, *domainType)
+    hostUuid := apihelper.GetHostUUID(*nbmaster, httpClient, jwt, *client);
+    apihelper.GetServices(*nbmaster, httpClient, jwt, *client, hostUuid);
+}

recipes/go/assets/README.md

@@ -0,0 +1,27 @@
+### NetBackup API Code Samples in go
+
+This directory contains code samples in golang for NetBackup Asset Service APIs.
+
+#### Disclaimer
+
+The scripts are provided only for reference and not meant for production use.
+
+#### Pre-requisites:
+
+- NetBackup 8.3 or higher
+- go1.10.2 or higher
+
+#### Executing the script
+
+- get_vmware_assets:
+    `go run ./get_vmware_assets.go -nbserver <NetBackup server> -username <username> -password <password> [-domainName <domainName>] [-domainType <domainType>] [-assetsFilter <filter>]`
+
+    The script invokes the NetBackup VMware Asset Service API to get the VMware workload assets (filtered by the given filter criteria if specified). It prints the asset details (delimited by tab) such as asset display name, instance Id, vCenter and the protection plan names that the asset is protected by.
+
+    Note: The _assetsFilter_ option can be used to filter the assets returned. It should be in OData format (refer to the NetBackup API documentation for more details). It is optional; if not specified the script will return all VM assets. Redirect the script output to a file to avoid printing the details on terminal.
+
+    Examples:
+
+    - List all VMs: `go run ./get_vmware_assets.go -nbserver localhost -username user -password password -domainName domain -domainType NT > vm_assets.txt`
+
+    - List VMs with filter condition: `go run ./get_vmware_assets.go -nbserver localhost -username user -password password -domainName domain -domainType NT -assetsFilter "contains(commonAssetAttributes/displayName, 'backup')"`

recipes/go/assets/get_vmware_assets.go

@@ -0,0 +1,136 @@
+//This script can be run using NetBackup 8.3 and higher.
+//It gets the list of VMware assets in NetBackup (based on the given filter if specified, else returns all the VMware assets).
+
+package main
+
+import (
+    "flag"
+    "fmt"
+    "log"
+    "os"
+    "strconv"
+    "net/url"
+    "net/http"
+    "io/ioutil"
+    "encoding/json"
+    "utils"
+)
+
+var (
+    nbserver            = flag.String("nbserver", "", "NetBackup Server")
+    username            = flag.String("username", "", "User name for NetBackup API login")
+    password            = flag.String("password", "", "Password for the given user")
+    domainName          = flag.String("domainName", "", "Domain name")
+    domainType          = flag.String("domainType", "", "Domain type")
+    assetsFilter        = flag.String("assetsFilter", "", "Filter string (odata format) to filter the assets")
+)
+
+const usage = "\n\nUsage: go run ./get_vmware_assets.go -nbserver <NetBackup server> -username <username> -password <password> [-domainName <domainName>] [-domainType <domainType>] [-assetsFilter <filter>]\n\n"
+
+func main() {
+    // Print usage
+    flag.Usage = func() {
+        fmt.Fprintf(os.Stderr, usage)
+        os.Exit(1)
+    }
+
+    // Read command line arguments
+    flag.Parse()
+
+    if len(*nbserver) == 0 {
+        log.Fatalf("Please specify the name of the NetBackup Server using the -nbserver option.\n")
+    }
+    if len(*username) == 0 {
+        log.Fatalf("Please specify the username using the -username option.\n")
+    }
+    if len(*password) == 0 {
+        log.Fatalf("Please specify the password using the -password option.\n")
+    }
+
+    httpClient := apihelper.GetHTTPClient()
+    jwt := apihelper.Login(*nbserver, httpClient, *username, *password, *domainName, *domainType)
+
+    vmwareAssetsApiUrl := "https://" + *nbserver + "/netbackup/asset-service/workloads/vmware/assets"
+    defaultSort := "commonAssetAttributes.displayName"
+    assetTypeFilter := "(assetType eq 'vm')"
+
+    req, err := http.NewRequest("GET", vmwareAssetsApiUrl, nil)
+
+    if err != nil {
+        fmt.Printf("Making new HTTP request failed with error: %s\n", err)
+        panic("Script failed.")
+    }
+
+    req.Header.Add("Authorization", jwt)
+    pageLimit := 100
+    offset := 0
+    next := true
+    params := url.Values{}
+
+    if assetsFilter != nil {
+      filter := ""
+      if *assetsFilter != "" {
+        filter = *assetsFilter + " and " + assetTypeFilter
+      } else {
+          filter = assetTypeFilter
+      }
+      params.Add("filter", filter)
+    }
+
+    params.Add("sort", defaultSort)
+    params.Add("page[offset]", strconv.Itoa(offset))
+    params.Add("page[limit]", strconv.Itoa(pageLimit))
+
+    fmt.Println("\nGetting VMware assets...")
+    fmt.Println("Printing the following asset details: Display Name, VM InstanceId, vCenter, Protection Plan Names\n")
+
+    for next {
+      req.URL.RawQuery = params.Encode()
+      resp, err := httpClient.Do(req)
+
+      if err != nil {
+          fmt.Printf("Get VMware Assets failed with error: %s\n", err)
+          panic("Script failed.")
+      } else {
+          respJson, _ := ioutil.ReadAll(resp.Body)
+          if resp.StatusCode == 200 {
+            var respPayload interface{}
+            json.Unmarshal(respJson, &respPayload)
+            respData := respPayload.(map[string]interface{})
+            assetsData := respData["data"].([]interface{})
+            printAssetDetails(assetsData)
+            next = respData["meta"].(map[string]interface{})["pagination"].
+                (map[string]interface{})["hasNext"].(bool)
+          } else {
+            fmt.Println(string(respJson))
+            next = false
+          }
+      }
+      offset, _ = strconv.Atoi(params["page[offset]"][0])
+      params["page[offset]"][0] = strconv.Itoa(offset + pageLimit)
+    }
+
+    fmt.Println("\nScript completed.\n")
+}
+
+func printAssetDetails(assets []interface{}) {
+  for _, asset := range assets {
+    assetAttrs := asset.(map[string]interface{})["attributes"].(map[string]interface{})
+    assetCommonAttrs := assetAttrs["commonAssetAttributes"].(map[string]interface{})
+    displayName := assetCommonAttrs["displayName"]
+    instanceId := assetAttrs["instanceUuid"]
+    vCenter := assetAttrs["vCenter"]
+
+    var protectionPlans []string
+    if activeProtections, protected := assetCommonAttrs["activeProtection"]; protected {
+      protectionDetailsList := activeProtections.(map[string]interface{})["protectionDetailsList"].([]interface{})
+
+      for _, protectionDetails := range protectionDetailsList {
+        protectionPlans = append(protectionPlans, protectionDetails.
+                (map[string]interface{})["protectionPlanName"].(string))
+      }
+    }
+    fmt.Printf("%s\t%s\t%s\t%v\n", displayName, instanceId, vCenter, protectionPlans)
+  }
+
+}

recipes/go/config/README.md

@@ -0,0 +1,18 @@
+### NetBackup API Code Samples for go (often referred to as golang)
+
+This directory contains code samples to invoke NetBackup configuration REST APIs using go.
+
+#### Disclaimer
+
+These scripts are only meant to be used as a reference. If you intend to use them in production, use it at your own risk.
+
+#### Pre-requisites:
+
+- NetBackup 8.2 or higher
+- go1.10.2 or higher
+
+#### Executing the recipes using go
+
+Use the following commands to run the go samples.
+- `go run ./get_set_host_config.go -nbmaster <masterServer> -username <username> -password <password> [-domainName <domainName>] [-domainType <domainType>] -client <client>`
+- `go run ./manage_access_hosts.go -nbmaster <masterServer> -username <username> -password <password> [-domainName <domainName>] [-domainType <domainType>] [-accessHost <accessHost>]`