Get group mappings associated with a virtual server

NAS File Storage REST API Reference

Version

15.6.x

File Size

1291 KB

Audience

anonymous

Part Number

MK-92HNAS100-07

ft:lastEdition

2026-04-07

get /v9/storage/virtual-servers/{virtualServerId}/mappings/group

Get the group mappings associated with a specific virtual server.

If the virtual server is configured in the global security context, the mappings retrieved will be those from the global context. Specify a virtual server ID of 0 to ensure the global mappings are retrieved. If the virtual server is configured to have an individual security context, the mappings will only be associated with the specified virtual server.

The number of groups present can potentially be very large, so additional filters are provided to allow the number returned to be restricted to specific types.

Note: Accepted parameter values may be restricted based on the virtual server access granted by the API key used for authentication.

Authentication: x_subsystem_user Api Key "X-Subsystem-User"

Authentication: x_subsystem_password Api Key "X-Subsystem-Password"

Authentication: api_key Api Key "X-Api-Key"

Authentication: basicAuth HTTP - basic scheme

Path parameters

virtualServerId required

Either the virtual server ID or the object ID of the virtual server

Query parameters

includeFixed Boolean

Include all fixed mappings in the response

Example: true

includeFixedNfs4 Boolean

Include all fixed NFSv4 mappings in the response

Example: true

includeFixedNt Boolean

Include all fixed NT mappings in the response

Example: true

includeFixedUnix Boolean

Include all fixed Unix mappings in the response

Example: true

includeInvalid Boolean

Include all invalid mappings in the response

Example: true

includeInvalidNfs4 Boolean

Include all invalid NFSv4 mappings in the response

Example: true

includeInvalidNt Boolean

Include all invalid NT mappings in the response

Example: true

includeInvalidUnix Boolean

Include all invalid Unix mappings in the response

Example: true

CLIENT REQUEST

          curl -X 'GET'

         -H "X-Subsystem-User: [[apiKey]]"
        
         \
      
         -H "X-Subsystem-Password: [[apiKey]]"
        
         \
      
         -H "X-Api-Key: [[apiKey]]"
        
         \
      
         -H "Authorization: Basic [[basicHash]]"
         \
      
        -H
        'Accept: application/json'
      
      'https://172.27.146.40:8444/v9/storage/virtual-servers/{virtualServerId}/mappings/group?includeFixed=true&includeFixedNfs4=true&includeFixedNt=true&includeFixedUnix=true&includeInvalid=true&includeInvalidNfs4=true&includeInvalidNt=true&includeInvalidUnix=true'

import http.client

conn = http.client.HTTPSConnection("172.27.146.40:8444")

headers = { 'Authorization': "Basic REPLACE_BASIC_AUTH" }

conn.request("GET", "/v9/storage/virtual-servers/1/mappings/group?includeFixed=SOME_BOOLEAN_VALUE&includeFixedNfs4=SOME_BOOLEAN_VALUE&includeFixedNt=SOME_BOOLEAN_VALUE&includeFixedUnix=SOME_BOOLEAN_VALUE&includeInvalid=SOME_BOOLEAN_VALUE&includeInvalidNfs4=SOME_BOOLEAN_VALUE&includeInvalidNt=SOME_BOOLEAN_VALUE&includeInvalidUnix=SOME_BOOLEAN_VALUE", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://172.27.146.40:8444/v9/storage/virtual-servers/1/mappings/group?includeFixed=SOME_BOOLEAN_VALUE&includeFixedNfs4=SOME_BOOLEAN_VALUE&includeFixedNt=SOME_BOOLEAN_VALUE&includeFixedUnix=SOME_BOOLEAN_VALUE&includeInvalid=SOME_BOOLEAN_VALUE&includeInvalidNfs4=SOME_BOOLEAN_VALUE&includeInvalidNt=SOME_BOOLEAN_VALUE&includeInvalidUnix=SOME_BOOLEAN_VALUE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic REPLACE_BASIC_AUTH'

response = http.request(request)
puts response.read_body

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://172.27.146.40:8444/v9/storage/virtual-servers/1/mappings/group?includeFixed=SOME_BOOLEAN_VALUE&includeFixedNfs4=SOME_BOOLEAN_VALUE&includeFixedNt=SOME_BOOLEAN_VALUE&includeFixedUnix=SOME_BOOLEAN_VALUE&includeInvalid=SOME_BOOLEAN_VALUE&includeInvalidNfs4=SOME_BOOLEAN_VALUE&includeInvalidNt=SOME_BOOLEAN_VALUE&includeInvalidUnix=SOME_BOOLEAN_VALUE");
xhr.setRequestHeader("Authorization", "Basic REPLACE_BASIC_AUTH");

xhr.send(data);

HttpResponse<String> response = Unirest.get("https://172.27.146.40:8444/v9/storage/virtual-servers/1/mappings/group?includeFixed=SOME_BOOLEAN_VALUE&includeFixedNfs4=SOME_BOOLEAN_VALUE&includeFixedNt=SOME_BOOLEAN_VALUE&includeFixedUnix=SOME_BOOLEAN_VALUE&includeInvalid=SOME_BOOLEAN_VALUE&includeInvalidNfs4=SOME_BOOLEAN_VALUE&includeInvalidNt=SOME_BOOLEAN_VALUE&includeInvalidUnix=SOME_BOOLEAN_VALUE")
  .header("Authorization", "Basic REPLACE_BASIC_AUTH")
  .asString();

import Foundation

let headers = ["Authorization": "Basic REPLACE_BASIC_AUTH"]

let request = NSMutableURLRequest(url: NSURL(string: "https://172.27.146.40:8444/v9/storage/virtual-servers/1/mappings/group?includeFixed=SOME_BOOLEAN_VALUE&includeFixedNfs4=SOME_BOOLEAN_VALUE&includeFixedNt=SOME_BOOLEAN_VALUE&includeFixedUnix=SOME_BOOLEAN_VALUE&includeInvalid=SOME_BOOLEAN_VALUE&includeInvalidNfs4=SOME_BOOLEAN_VALUE&includeInvalidNt=SOME_BOOLEAN_VALUE&includeInvalidUnix=SOME_BOOLEAN_VALUE")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8444",
  CURLOPT_URL => "https://172.27.146.40:8444/v9/storage/virtual-servers/1/mappings/group?includeFixed=SOME_BOOLEAN_VALUE&includeFixedNfs4=SOME_BOOLEAN_VALUE&includeFixedNt=SOME_BOOLEAN_VALUE&includeFixedUnix=SOME_BOOLEAN_VALUE&includeInvalid=SOME_BOOLEAN_VALUE&includeInvalidNfs4=SOME_BOOLEAN_VALUE&includeInvalidNt=SOME_BOOLEAN_VALUE&includeInvalidUnix=SOME_BOOLEAN_VALUE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic REPLACE_BASIC_AUTH"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://172.27.146.40:8444/v9/storage/virtual-servers/1/mappings/group?includeFixed=SOME_BOOLEAN_VALUE&includeFixedNfs4=SOME_BOOLEAN_VALUE&includeFixedNt=SOME_BOOLEAN_VALUE&includeFixedUnix=SOME_BOOLEAN_VALUE&includeInvalid=SOME_BOOLEAN_VALUE&includeInvalidNfs4=SOME_BOOLEAN_VALUE&includeInvalidNt=SOME_BOOLEAN_VALUE&includeInvalidUnix=SOME_BOOLEAN_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Basic REPLACE_BASIC_AUTH");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://172.27.146.40:8444/v9/storage/virtual-servers/1/mappings/group?includeFixed=SOME_BOOLEAN_VALUE&includeFixedNfs4=SOME_BOOLEAN_VALUE&includeFixedNt=SOME_BOOLEAN_VALUE&includeFixedUnix=SOME_BOOLEAN_VALUE&includeInvalid=SOME_BOOLEAN_VALUE&includeInvalidNfs4=SOME_BOOLEAN_VALUE&includeInvalidNt=SOME_BOOLEAN_VALUE&includeInvalidUnix=SOME_BOOLEAN_VALUE");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
IRestResponse response = client.Execute(request);

Responses

Successful operation

Body

application/json

groupMappingsarray

[

isNfs4NameFixedboolean

True indicates that the NFSv4 name value is fixed and not discovered

isNfs4NameValidboolean

True if the NFSv4 name is valid

isNtIdFixedboolean

True indicates that the NT ID value is fixed and not discovered

isNtIdValidboolean

True if the NT ID value is valid

isNtNameFixedboolean

True indicates that the NT name value is fixed and not discovered

isNtNameValidboolean

True if the NT name value is valid

isUnixIdFixedboolean

True indicates that the Unix ID value is fixed and not discovered

isUnixIdValidboolean

True if the Unix ID value is valid

isUnixNameFixedboolean

True indicates that the Unix name value is fixed and not discovered

isUnixNameValidboolean

True if the Unix name is valid

nfs4Namestring

NFSv4 user/group name

Example:"user1@localdomain"

ntIdstring

CIFS/SMB Security ID (SID) associated with the user/group

Example:"S-1-5-32-21061"

ntNamestring

CIFS/SMB user/group name

Example:"EXAMPLE\\User1"

objectIdstring

Unique ID of the object

Example:"333a3a3a3a3a3a303a3a3a4f49445f24232140255f56"

unixIdinteger

Unix ID associated with the user/group

Example:"500"

unixNamestring

Unix name associated with the user/group

Example:"User1"

]

RESPONSE
{
  "groupMappings": [
    {
      "isNfs4NameFixed": false,
      "isNfs4NameValid": false,
      "isNtIdFixed": false,
      "isNtIdValid": false,
      "isNtNameFixed": false,
      "isNtNameValid": false,
      "isUnixIdFixed": false,
      "isUnixIdValid": false,
      "isUnixNameFixed": false,
      "isUnixNameValid": false,
      "nfs4Name": "user1@localdomain",
      "ntId": "S-1-5-32-21061",
      "ntName": "EXAMPLE\\User1",
      "objectId": "333a3a3a3a3a3a303a3a3a4f49445f24232140255f56",
      "unixId": "500",
      "unixName": "User1"
    }
  ]
}

Bad Request

Body

application/json

errorCodeintegerint32

Generic error code

Example:1081353

errorMsgstring

Main error message

Example:

"Invalid description parameter - the optional parameter must be between 2 and 30 characters long to be valid, if supplied"

RESPONSE
{
  "errorCode": 1081353,
  "errorMsg": "Invalid description parameter - the optional parameter must be between 2 and 30 characters long to be valid, if supplied"
}

Unauthorized - the request was rejected because the credentials or API key were either missing or invalid

Forbidden - the client does not have the required permissions to perform the operation

Body

application/json

errorMsgstring

Main error message

Example:"Forbidden request - the client does not have the required permissions to perform the operation"

RESPONSE
{
  "errorMsg": "Forbidden request - the client does not have the required permissions to perform the operation"
}

Not Found - a resource specified was not found

Body

application/json

errorCodeintegerint32

Generic error code

Example:1081345

errorDetailobject

Detailed error information

detailstring

More details on why the error occurred

faultstring

fileNamestring

Source file where the error occurred

Example:"RestApiFilesystems.cpp"

functionstring

Internal function name where the error occurred

Example:"mountFilesystem"

lineNumberintegerint32

Line number within the source file, where the error occurred

messagestring

Reason why the error(s) occurred

Example:"The file system is currently unassigned"

reasonstring

Reason why the error(s) occurred

Example:"The file system is currently unassigned"

returnedValueintegerint32

Not used

subCodeintegerint32

Specific failure error code

errorMsgstring

Main error message

Example:"Cannot find the object of the operation on the device"

RESPONSE
{
  "errorCode": 1081345,
  "errorDetail": {
    "detail": "",
    "fault": "",
    "fileName": "RestApiFilesystems.cpp",
    "function": "mountFilesystem",
    "lineNumber": 0,
    "message": "The file system is currently unassigned",
    "reason": "The file system is currently unassigned",
    "returnedValue": 0,
    "subCode": 0
  },
  "errorMsg": "Cannot find the object of the operation on the device"
}

Internal Server Error

Body

application/json

errorCodeintegerint32

Generic error code

errorDetailobject

Detailed error information

detailstring

More details on why the error occurred

faultstring

fileNamestring

Source file where the error occurred

Example:"RestApiFilesystems.cpp"

functionstring

Internal function name where the error occurred

Example:"mountFilesystem"

lineNumberintegerint32

Line number within the source file, where the error occurred

messagestring

Reason why the error(s) occurred

Example:"The file system is currently unassigned"

reasonstring

Reason why the error(s) occurred

Example:"The file system is currently unassigned"

returnedValueintegerint32

Not used

subCodeintegerint32

Specific failure error code

errorMsgstring

Main error message

Example:"Failed to mount file system"

RESPONSE
{
  "errorCode": 0,
  "errorDetail": {
    "detail": "",
    "fault": "",
    "fileName": "RestApiFilesystems.cpp",
    "function": "mountFilesystem",
    "lineNumber": 0,
    "message": "The file system is currently unassigned",
    "reason": "The file system is currently unassigned",
    "returnedValue": 0,
    "subCode": 0
  },
  "errorMsg": "Failed to mount file system"
}