Skip to main content

Cluster licensing licenses endpoint overview

Contributors
PDFs

Overview

Licensing allows you to tailor a system to meet an organization's specific needs. You can enable new features by purchasing a license from a NetApp sales associate. After installation of the license, the new feature is available immediately.

This interface manages licenses according to their supported feature. By default, the interface displays packages with installed licenses, but you can also return unlicensed packages.

Each feature has a compliance state that is indicated at the package level. Individual licenses also contain a compliance state indicated in the "licenses" array. The state of the package is determined by analyzing the underlying licenses according to the following criteria:

  • Licensing terms

  • Cluster state

Licensing terms

The licensing terms define the conditions under which a package is considered "compliant". Individual licenses are evaluated based on the following:

  • Scope

  • Time period

  • Usage

Scope

A package can be licensed under the following scopes:

  • Site - Permits the feature to be used by any node in any cluster.

  • Cluster - Permits the feature to be used by any node in a single specific cluster.

  • Node - Permits the authorized node to use the feature. Within a cluster, if you don't supply every node with a valid license, the package state indicates "noncompliant". You must purchase a license for each node in a cluster for the package to be considered "compliant".

Time period

Some package licenses are only valid for a limited period of time. After a license has expired, the package state changes to "noncompliant". You need to purchase a new license for the package to return to a "compliant" state.

Usage

Some package licenses have additional terms that need to be maintained to keep a license in compliance. These conditions are defined by the individual license. For example, a license might define the maximum amount of storage that a node can allocate for the license to be "compliant".

Cluster state

A cluster's state consists of the following:

  • Node online status

  • Node cluster membership

Some features require that a node be online to display a valid compliance state. If a node cannot be reached or is not known to the cluster, the individual license might indicate an "unknown" state.

Licensing keys

A license is issued in one of the following three formats:

  • 28-character key

  • NetApp License File Version 1 (NLFv1)

  • NetApp License File Version 2 (NLFv2)

Overview of NLFv1 and NLFv2 License Formats

NLFv1 and NLFv2 licenses are both JSON based files that allow features to be enabled.

The difference between the two formats is that a NLFv2 license allows multiple features to be enabled with a single file. A NLFv1 license is capable of enabling a single feature.

These licenses are identified, in the various methods, as follows:

Format Identifying Keys

28 Character Key

name / serial_number

NLFv1

name / serial_number

NLFv2

licenses.installed_license / serial_number

The following is an example of a 28-character key:

AMEPOSOIKLKGEEEEDGNDEKSJDEEE

The following is an example of an NLFv1 key:

{
"statusResp": {
"version": "1",
"serialNumber": "123456789",
"message": "Success",
"licenses": {
  "capacity": "1",
  "type": "capacity",
  "licenseProtocol": "FABRICPOOL-TB",
  "package": "FabricPool",
  "licenseScope": "cluster"
},
"snStatus": "Active",
"product": "fabricpool",
"statusCode": "S007"
},
"Signature": "signatureABC"
}

The following is an example of an NLFv2 key:

{
"statusResp": {
"version": "2",
"serialNumber": "123456789",
"message": "Success",
"product": "Sample NLFv2 License",
"licenses": {
  "capacity": "1",
  "type": "capacity",
  "HostID": "5554444",
  "package": [ "NFS", "CIFS" ],
  "licenseScope": "node"
},
"snStatus": "Active",
"statusCode": "S007"
},
"Signature": "signatureABC"
}

You can use this API to submit any format to enable features.

Examples

Retrieving a collection of licenses organized by package

This example retrieves a collection that contains one entry for each package (filtered to only the 'fabricpool' package).

# API
curl -X GET "https://<mgmt-ip>/api/cluster/licensing/licenses?fields=*&name=fabricpool"

# Response
200 OK

# JSON Body
{
"records": [
{
  "name": "fabricpool",
  "scope": "cluster",
  "state": "compliant",
  "description": "FabricPool License",
  "licenses": [
  {
    "owner": "testcluster-1",
    "serial_number": "4149027342",
    "state": "compliant",
    "capacity": {
    "maximum_size": 1099511627776,
    "used_size": 0
    }
  }
  ],
  "_links": {
  "self": {
    "href": "/api/cluster/licensing/licenses/fabricpool"
  }
  }
}
],
"num_records": 1,
"_links": {
"self": {
  "href": "/api/cluster/licensing/licenses/?fields=*&name=fabricpool"
}
}
}

Retrieving a collection of licenses organized by package - for package cloud

The following example retrieves a collection that contains one entry for each package (filtered to only the 'cloud' package). The cloud package, in this example, is in the enforcement period as the license has expired. The REST GET output displays an additional field 'shutdown_imminent' to indicate that the system will shutdown.

# API
curl -X GET "https://<mgmt-ip>/api/cluster/licensing/licenses?fields=*&name=cloud"

# Response
200 OK

# JSON Body
{
"records": [
  {
    "name": "cloud",
    "scope": "node",
    "state": "noncompliant",
    "description": "Cloud ONTAP License",
    "entitlement": {
      "action": "acquire_license",
      "risk": "unlicensed"
    },
    "licenses": [
      {
        "owner": "test-vsim1",
        "serial_number": "90120130000000000001",
        "active": false,
        "evaluation": true,
        "expiry_time": "2021-10-26T19:57:41Z",
        "shutdown_imminent": true,
        "compliance": {
          "state": "noncompliant"
        }
      }
    ],
    "_links": {
      "self": {
        "href": "/api/cluster/licensing/licenses/cloud"
      }
    }
  }
],
"num_records": 1,
"_links": {
  "self": {
    "href": "/api/cluster/licensing/licenses/?fields=*&name=cloud"
  }
}
}

Retrieving a collection of licenses installed with NLFv2

This example retrieves a collection of licenses that were installed by a NLFv2 formatted license.

Note The license is referenced by the installed license "Core*Bundle" and the license serial number "4212426890" 
# API
curl -X GET "https://<mgmt-ip>/api/cluster/licensing/licenses?fields=*&licenses.installed_license=Core*Bundle&serial_number=4212426890"

# Response
200 OK

# JSON Body
{
"records": [
  {
    "name": "nfs",
    "scope": "node",
    "state": "noncompliant",
    "description": "NFS License",
    "entitlement": {
      "action": "acquire_license",
      "risk": "medium"
    },
    "licenses": [
      {
        "owner": "test-vsim3",
        "active": false,
        "evaluation": false,
        "compliance": {
          "state": "unlicensed"
        }
      },
      {
        "owner": "test-vsim4",
        "installed_license": "Core Bundle",
        "host_id": "4212426890",
        "serial_number": "4212426890",
        "active": true,
        "evaluation": false,
        "compliance": {
          "state": "compliant"
        },
        "capacity": {
          "maximum_size": 10995116277760
        }
      }
    ],
    "_links": {
      "self": {
        "href": "/api/cluster/licensing/licenses/nfs/?licenses.installed_license=Core*Bundle"
      }
    }
  },
  {
    "name": "cifs",
    "scope": "node",
    "state": "noncompliant",
    "description": "CIFS License",
    "entitlement": {
      "action": "acquire_license",
      "risk": "medium"
    },
    "licenses": [
      {
        "owner": "test-vsim3",
        "active": false,
        "evaluation": false,
        "compliance": {
          "state": "unlicensed"
        }
      },
      {
        "owner": "test-vsim4",
        "installed_license": "Core Bundle",
        "host_id": "4212426890",
        "serial_number": "4212426890",
        "active": true,
        "evaluation": false,
        "compliance": {
          "state": "compliant"
        },
        "capacity": {
          "maximum_size": 10995116277760
        }
      }
    ],
    "_links": {
      "self": {
        "href": "/api/cluster/licensing/licenses/cifs/?licenses.installed_license=Core*Bundle"
      }
    }
  },
  {
    "name": "iscsi",
    "scope": "node",
    "state": "noncompliant",
    "description": "iSCSI License",
    "entitlement": {
      "action": "acquire_license",
      "risk": "medium"
    },
    "licenses": [
      {
        "owner": "test-vsim3",
        "active": false,
        "evaluation": false,
        "compliance": {
          "state": "unlicensed"
        }
      },
      {
        "owner": "test-vsim4",
        "installed_license": "Core Bundle",
        "host_id": "4212426890",
        "serial_number": "4212426890",
        "active": true,
        "evaluation": false,
        "compliance": {
          "state": "compliant"
        },
        "capacity": {
          "maximum_size": 10995116277760
        }
      }
    ],
    "_links": {
      "self": {
        "href": "/api/cluster/licensing/licenses/iscsi/?licenses.installed_license=Core*Bundle"
      }
    }
  },
  {
    "name": "fcp",
    "scope": "node",
    "state": "noncompliant",
    "description": "FCP License",
    "entitlement": {
      "action": "acquire_license",
      "risk": "medium"
    },
    "licenses": [
      {
        "owner": "test-vsim3",
        "active": false,
        "evaluation": false,
        "compliance": {
          "state": "unlicensed"
        }
      },
      {
        "owner": "test-vsim4",
        "installed_license": "Core Bundle",
        "host_id": "4212426890",
        "serial_number": "4212426890",
        "active": true,
        "evaluation": false,
        "compliance": {
          "state": "compliant"
        },
        "capacity": {
          "maximum_size": 10995116277760
        }
      }
    ],
    "_links": {
      "self": {
        "href": "/api/cluster/licensing/licenses/fcp/?licenses.installed_license=Core*Bundle"
      }
    }
  },
  {
    "name": "snaprestore",
    "scope": "node",
    "state": "noncompliant",
    "description": "SnapRestore License",
    "entitlement": {
      "action": "acquire_license",
      "risk": "medium"
    },
    "licenses": [
      {
        "owner": "test-vsim3",
        "active": false,
        "evaluation": false,
        "compliance": {
          "state": "unlicensed"
        }
      },
      {
        "owner": "test-vsim4",
        "installed_license": "Core Bundle",
        "host_id": "4212426890",
        "serial_number": "4212426890",
        "active": true,
        "evaluation": false,
        "compliance": {
          "state": "compliant"
        },
        "capacity": {
          "maximum_size": 10995116277760
        }
      }
    ],
    "_links": {
      "self": {
        "href": "/api/cluster/licensing/licenses/snaprestore/?licenses.installed_license=Core*Bundle"
      }
    }
  },
  {
    "name": "flexclone",
    "scope": "node",
    "state": "noncompliant",
    "description": "FlexClone License",
    "entitlement": {
      "action": "acquire_license",
      "risk": "medium"
    },
    "licenses": [
      {
        "owner": "test-vsim3",
        "active": false,
        "evaluation": false,
        "compliance": {
          "state": "unlicensed"
        }
      },
      {
        "owner": "test-vsim4",
        "installed_license": "Core Bundle",
        "host_id": "4212426890",
        "serial_number": "4212426890",
        "active": true,
        "evaluation": false,
        "compliance": {
          "state": "compliant"
        },
        "capacity": {
          "maximum_size": 10995116277760
        }
      }
    ],
    "_links": {
      "self": {
        "href": "/api/cluster/licensing/licenses/flexclone/?licenses.installed_license=Core*Bundle"
      }
    }
  },
  {
    "name": "nvme_of",
    "scope": "node",
    "state": "noncompliant",
    "description": "NVMe-oF License",
     "licenses": [
     {
        "owner": "test-vsim3",
        "active": false,
        "evaluation": false,
        "compliance": {
          "state": "unlicensed"
        }
      },
      {
        "owner": "test-vsim4",
        "installed_license": "Core Bundle",
        "host_id": "4212426890",
        "serial_number": "4212426890",
        "active": true,
        "evaluation": false,
        "compliance": {
          "state": "compliant"
        },
        "capacity": {
          "maximum_size": 10995116277760
        }
      }
    ],
    "_links": {
      "self": {
        "href": "/api/cluster/licensing/licenses/nvme_of/?licenses.installed_license=Core*Bundle"
      }
    }
  },
  {
    "name": "s3",
    "scope": "node",
    "state": "noncompliant",
    "description": "S3 License",
    "entitlement": {
      "action": "acquire_license",
      "risk": "medium"
    },
    "licenses": [
      {
        "owner": "test-vsim3",
        "active": false,
        "evaluation": false,
        "compliance": {
          "state": "unlicensed"
        }
      },
     {
       "owner": "test-vsim4",
        "installed_license": "Core Bundle",
        "host_id": "4212426890",
        "serial_number": "4212426890",
        "active": true,
        "evaluation": false,
        "compliance": {
          "state": "compliant"
        },
        "capacity": {
          "maximum_size": 10995116277760
        }
      }
    ],
    "_links": {
      "self": {
        "href": "/api/cluster/licensing/licenses/s3/?licenses.installed_license=Core*Bundle"
      }
    }
  }
],
"num_records": 8,
"_links": {
  "self": {
    "href": "/api/cluster/licensing/licenses?fields=*&licenses.installed_license=Core*Bundle&serial_number=4212426890"
  }
}
}

Retrieving a collection of installed licenses

This example retrieves a collection containing all packages (except base) that have installed licenses.

# API
curl -X GET "https://<mgmt-ip>/api/cluster/licensing/licenses?fields=*&name=!base"

# Response
200 OK

# JSON Body
{
"records": [
{
  "name": "nfs",
  "scope": "node",
  "state": "compliant",
  "description": "NFS License",
  "entitlement": {
    "action": "none",
    "risk": "low"
  },
  "licenses": [
  {
    "owner": "testcluster-1",
    "serial_number": "1-81-0000000000000004149027492",
    "state": "compliant"
  }
  ],
  "_links": {
  "self": {
    "href": "/api/cluster/licensing/licenses/nfs"
  }
  }
},
{
  "name": "cifs",
  "scope": "node",
  "state": "compliant",
  "description": "CIFS License",
  "entitlement": {
    "action": "acquire_license",
    "risk": "medium"
  },
  "licenses": [
  {
    "owner": "testcluster-1",
    "serial_number": "1-81-0000000000000004149027492",
    "state": "compliant"
  }
  ],
  "_links": {
  "self": {
    "href": "/api/cluster/licensing/licenses/cifs"
  }
  }
}
],
"num_records": 2,
"_links": {
"self": {
  "href": "/api/cluster/licensing/licenses/?fields=*&name=!base"
}
}
}

Retrieving a collection of unlicensed packages

By default, unlicensed packages are filtered from the collection output. This example shows how to use a query to retrieve unlicensed packages.

# API
curl -X GET "https://<mgmt-ip>/api/cluster/licensing/licenses?name=flexcache&state=unlicensed"

# Response
200 OK

# JSON Body
{
"records": [
  {
    "name": "flexcache",
    "_links": {
      "self": {
        "href": "/api/cluster/licensing/licenses/flexcache"
      }
    }
  }
],
"num_records": 1,
"_links": {
  "self": {
    "href": "/api/cluster/licensing/licenses?name=flexcache&state=unlicensed"
  }
}
}

Installing a NLF license

This example installs a single NLFv1 license. A NLFv2 license installs using the same procedure.

Note You must escape all the double quotes and backslash characters of the JSON license before it can be placed in the POST request. 
# API
curl -X POST "https://<mgmt-ip>/api/cluster/licensing/licenses"

# JSON Body
{
"keys" : [ "{\"statusResp\":{\"snStatus\": \"Active\", \"licenses\": {\"package\": \"FabricPool\", \"capacity\": \"1\", \"licenseProtocol\": \"FABRICPOOL-TB\", \"type\": \"capacity\", \"licenseScope\": \"cluster\"}, \"message\": \"Success\", \"statusCode\": \"S007\", \"version\": \"1\", \"product\": \"fabricpool\", \"serialNumber\": \"4149027342\"}, \"Signature\":\"SignatureABC\"}" ]
}

# Response
201 Created

Installing a 28-character key

This example installs a single 28-character key formatted license.

# API
curl -X POST "https://<mgmt-ip>/api/cluster/licensing/licenses"

# JSON Body
{
"keys" : [ "AAAAAAAAAAAAAAAAAAAAAAAAAAAA" ]
}

# Response
201 Created

Installing multiple licenses with one API call

This example shows how multiple keys can be provided to install multiple features in a single API call.

# API
curl -X POST "https://<mgmt-ip>/api/cluster/licensing/licenses"

# JSON Body
{
"keys" : [ "AAAAAAAAAAAAAAAAAAAAAAAAAAAA",
           "BBBBBBBBBBBBBBBBBBBBBBBBBBBB" ]
}

# Response
201 Created

Promoting a capacity tier evaluation node

x-ntap-visibility: type: private This example promotes a capacity tier evaluation node to a capacity tier production node.

Note You must escape all double quotes and backslash characters in the JSON license before it is placed in the POST request. 
# API
curl -X POST "https://<mgmt-ip>/api/cluster/licensing/licenses/?eval_node=nodeX"

# JSON Body
{
"keys": [ "{\"statusResp\":{\"product\": \"FDvM300\", \"serialNumber\": \"230000002\", \"version\": \"1\", \"licenses\": {\"capacity\": \"100\", \"type\": \"capacity\", \"package\": \"ONTAP-SEL-M300_STD\"}, \"message\": \"Success\", \"snStatus\": \"Active\", \"statusCode\": \"S007\"}, \"Signature\":\"SignatureABC\"}" ]
}

# Response
201 Created

Retrieving information for a specific license package

This example shows how to retrieve information about the specific feature package fabricpool.

# API
curl -X GET "https://<mgmt-ip>/api/cluster/licensing/licenses/fabricpool"

# Response
200 OK

# JSON Body
{
"name": "fabricpool",
"scope": "cluster",
"state": "compliant",
"description": "FabricPool License",
"licenses": [
{
  "owner": "testcluster-1",
  "serial_number": "123456789",
  "state": "compliant",
  "capacity": {
  "maximum_size": 109951162777600,
  "used_size": 0
  }
}
],
"_links": {
"self": {
  "href": "/api/cluster/licensing/licenses/fabricpool/"
}
}
}

Deleting a specific license

This example show how to delete a CIFS site license.

# API
curl -X DELETE "https://<mgmt-ip>/api/cluster/licensing/licenses/cifs?serial_number=1-80-000011"

# JSON Body
{}

# Response
200 OK

Deleting with a query

The following example shows how to delete all NFS licenses specified with the '*' query.

# API
curl -X DELETE "https://<mgmt-ip>/api/cluster/licensing/licenses/nfs?serial_number=*"

# JSON Body
{}

# Response
200 OK

Deleting all licenses installed with NLFv2

The following example shows how to delete all licenses installed by a NLFv2 formatted license.

# API
curl -X DELETE "https://<mgmt-ip>/api/cluster/licensing/licenses?licenses.installed_license=Core*Bundle&serial_number=4149026-97-8"

# JSON Body
{
"num_records": 1,
"_links": {
  "self": {
    "href": "/api/cluster/licensing/licenses?licenses.installed_license=Core*Bundle&serial_number=4149026-97-8"
  }
}
}

# Response
200 OK