Endpoint

/v3/smb/shares/

GET

List all SMB shares. Refer to the 'Modify SMB Share' method for a description of the returned fields.

Parameters

Name Description Required
populate-trustee-names Populate trustee names in the response. By default, trustee names are not returned. No

Response

Codes

Code Description
200 Return value on success

Schema

{
  "description": "api_smb_shares_v3",
  "type": "object",
  "properties": {
    "entries": {
      "type": "array",
      "items": {
        "description": "List of SMB shares",
        "type": "object",
        "properties": {
          "id": {
            "description": "The unique ID of the SMB share",
            "type": "string"
          },
          "share_name": {
            "description": "The SMB share name",
            "type": "string"
          },
          "tenant_id": {
            "description": "The tenant ID of the tenant that the SMB share is a part of",
            "type": "number"
          },
          "fs_path": {
            "description": "The filesystem path to SMB share",
            "type": "string"
          },
          "description": {
            "description": "Description of this SMB share",
            "type": "string"
          },
          "permissions": {
            "type": "array",
            "items": {
              "description": "The access control list (ACL) for this SMB share",
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "ALLOWED",
                    "DENIED"
                  ],
                  "description": "Type of permissions entry (ALLOWED or DENIED):\n * `ALLOWED` - The permissions entry rights are allowed to the trustee,\n * `DENIED` - The permissions entry rights are denied to the trustee"
                },
                "trustee": {
                  "description": "User/group to apply the permissions entry to",
                  "type": "object",
                  "properties": {
                    "domain": {
                      "type": "string",
                      "enum": [
                        "LOCAL",
                        "API_NULL_DOMAIN",
                        "WORLD",
                        "POSIX_USER",
                        "POSIX_GROUP",
                        "ACTIVE_DIRECTORY",
                        "API_INVALID_DOMAIN",
                        "API_RESERVED_DOMAIN",
                        "API_INTERNAL_DOMAIN",
                        "API_OPERATOR_DOMAIN",
                        "API_CREATOR_DOMAIN"
                      ],
                      "description": "domain:\n * `ACTIVE_DIRECTORY` - ACTIVE_DIRECTORY,\n * `API_CREATOR_DOMAIN` - API_CREATOR_DOMAIN,\n * `API_INTERNAL_DOMAIN` - API_INTERNAL_DOMAIN,\n * `API_INVALID_DOMAIN` - API_INVALID_DOMAIN,\n * `API_NULL_DOMAIN` - API_NULL_DOMAIN,\n * `API_OPERATOR_DOMAIN` - API_OPERATOR_DOMAIN,\n * `API_RESERVED_DOMAIN` - API_RESERVED_DOMAIN,\n * `LOCAL` - LOCAL,\n * `POSIX_GROUP` - POSIX_GROUP,\n * `POSIX_USER` - POSIX_USER,\n * `WORLD` - WORLD"
                    },
                    "auth_id": {
                      "description": "auth_id",
                      "type": "string"
                    },
                    "uid": {
                      "description": "uid",
                      "type": "number"
                    },
                    "gid": {
                      "description": "gid",
                      "type": "number"
                    },
                    "sid": {
                      "description": "sid",
                      "type": "string"
                    },
                    "name": {
                      "description": "name",
                      "type": "string"
                    }
                  }
                },
                "rights": {
                  "description": "Rights pertaining to the permissions entry",
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "READ",
                      "WRITE",
                      "CHANGE_PERMISSIONS",
                      "ALL",
                      "READ_DATA",
                      "READ_EA",
                      "READ_ATTR",
                      "READ_ACL",
                      "WRITE_EA",
                      "WRITE_ATTR",
                      "WRITE_ACL",
                      "CHANGE_OWNER",
                      "WRITE_GROUP",
                      "DELETE",
                      "EXECUTE",
                      "MODIFY",
                      "EXTEND",
                      "ADD_FILE",
                      "ADD_SUBDIR",
                      "DELETE_CHILD",
                      "SYNCHRONIZE"
                    ],
                    "description": "Rights pertaining to the permissions entry:\n * `ADD_FILE` - File creation access,\n * `ADD_SUBDIR` - Directory creation access,\n * `ALL` - All access rights,\n * `CHANGE_OWNER` - Owner write access,\n * `CHANGE_PERMISSIONS` - Rights to change permissions on file objects,\n * `DELETE` - Delete access,\n * `DELETE_CHILD` - Delete from directory access,\n * `EXECUTE` - Execute access,\n * `EXTEND` - File extension access,\n * `MODIFY` - File modification access,\n * `READ` - Read access rights,\n * `READ_ACL` - ACL read access,\n * `READ_ATTR` - Attribute read access,\n * `READ_DATA` - File read access,\n * `READ_EA` - Extended attribute read access,\n * `SYNCHRONIZE` - File synchronize access,\n * `WRITE` - Write access rights,\n * `WRITE_ACL` - ACL write access,\n * `WRITE_ATTR` - Attribute write access,\n * `WRITE_EA` - Extended attribute write access,\n * `WRITE_GROUP` - Group write access"
                  }
                }
              }
            }
          },
          "network_permissions": {
            "type": "array",
            "items": {
              "description": "The network access control list (ACL) for this SMB share. If not specified, the default is to allow any host.",
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "ALLOWED",
                    "DENIED"
                  ],
                  "description": "Type of permissions entry (ALLOWED or DENIED):\n * `ALLOWED` - The permissions entry rights are allowed to the trustee,\n * `DENIED` - The permissions entry rights are denied to the trustee"
                },
                "address_ranges": {
                  "type": "array",
                  "items": {
                    "description": "IP address ranges to apply permissions to. Empty means all hosts.",
                    "type": "string"
                  }
                },
                "rights": {
                  "description": "Rights pertaining to the permissions entry",
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "READ",
                      "WRITE",
                      "CHANGE_PERMISSIONS",
                      "ALL",
                      "READ_DATA",
                      "READ_EA",
                      "READ_ATTR",
                      "READ_ACL",
                      "WRITE_EA",
                      "WRITE_ATTR",
                      "WRITE_ACL",
                      "CHANGE_OWNER",
                      "WRITE_GROUP",
                      "DELETE",
                      "EXECUTE",
                      "MODIFY",
                      "EXTEND",
                      "ADD_FILE",
                      "ADD_SUBDIR",
                      "DELETE_CHILD",
                      "SYNCHRONIZE"
                    ],
                    "description": "Rights pertaining to the permissions entry:\n * `ADD_FILE` - File creation access,\n * `ADD_SUBDIR` - Directory creation access,\n * `ALL` - All access rights,\n * `CHANGE_OWNER` - Owner write access,\n * `CHANGE_PERMISSIONS` - Rights to change permissions on file objects,\n * `DELETE` - Delete access,\n * `DELETE_CHILD` - Delete from directory access,\n * `EXECUTE` - Execute access,\n * `EXTEND` - File extension access,\n * `MODIFY` - File modification access,\n * `READ` - Read access rights,\n * `READ_ACL` - ACL read access,\n * `READ_ATTR` - Attribute read access,\n * `READ_DATA` - File read access,\n * `READ_EA` - Extended attribute read access,\n * `SYNCHRONIZE` - File synchronize access,\n * `WRITE` - Write access rights,\n * `WRITE_ACL` - ACL write access,\n * `WRITE_ATTR` - Attribute write access,\n * `WRITE_EA` - Extended attribute write access,\n * `WRITE_GROUP` - Group write access"
                  }
                }
              }
            }
          },
          "access_based_enumeration_enabled": {
            "description": "Enable Access-based Enumeration on this SMB share",
            "type": "boolean"
          },
          "default_file_create_mode": {
            "description": "Default POSIX file create mode bits on this SMB share (octal, default 0644 if this field is empty)",
            "type": "string"
          },
          "default_directory_create_mode": {
            "description": "Default POSIX directory create mode bits on this SMB share (octal, default 0755 if this field is empty)",
            "type": "string"
          },
          "require_encryption": {
            "description": "Require all traffic to this share to be encrypted. Clients without encryption capabilities will not be able to connect. Default is false if this field is empty.",
            "type": "boolean"
          }
        }
      }
    }
  }
}

POST

Add an SMB share with given options.

Parameters

Name Description Required
allow-fs-path-create Specifies whether the file system path can be created if it does not already exist. No

Request

Schema

{
  "description": "api_smb_share_post_v3",
  "type": "object",
  "properties": {
    "share_name": {
      "description": "The SMB share name",
      "type": "string"
    },
    "tenant_id": {
      "description": "The tenant ID of the tenant that the SMB share is a part of",
      "type": "number"
    },
    "fs_path": {
      "description": "The filesystem path to SMB share",
      "type": "string"
    },
    "description": {
      "description": "Description of this SMB share",
      "type": "string"
    },
    "permissions": {
      "type": "array",
      "items": {
        "description": "The access control list (ACL) for this SMB share",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "ALLOWED",
              "DENIED"
            ],
            "description": "Type of permissions entry (ALLOWED or DENIED):\n * `ALLOWED` - The permissions entry rights are allowed to the trustee,\n * `DENIED` - The permissions entry rights are denied to the trustee"
          },
          "trustee": {
            "description": "User/group to apply the permissions entry to",
            "type": "object",
            "properties": {
              "domain": {
                "type": "string",
                "enum": [
                  "LOCAL",
                  "API_NULL_DOMAIN",
                  "WORLD",
                  "POSIX_USER",
                  "POSIX_GROUP",
                  "ACTIVE_DIRECTORY",
                  "API_INVALID_DOMAIN",
                  "API_RESERVED_DOMAIN",
                  "API_INTERNAL_DOMAIN",
                  "API_OPERATOR_DOMAIN",
                  "API_CREATOR_DOMAIN"
                ],
                "description": "domain:\n * `ACTIVE_DIRECTORY` - ACTIVE_DIRECTORY,\n * `API_CREATOR_DOMAIN` - API_CREATOR_DOMAIN,\n * `API_INTERNAL_DOMAIN` - API_INTERNAL_DOMAIN,\n * `API_INVALID_DOMAIN` - API_INVALID_DOMAIN,\n * `API_NULL_DOMAIN` - API_NULL_DOMAIN,\n * `API_OPERATOR_DOMAIN` - API_OPERATOR_DOMAIN,\n * `API_RESERVED_DOMAIN` - API_RESERVED_DOMAIN,\n * `LOCAL` - LOCAL,\n * `POSIX_GROUP` - POSIX_GROUP,\n * `POSIX_USER` - POSIX_USER,\n * `WORLD` - WORLD"
              },
              "auth_id": {
                "description": "auth_id",
                "type": "string"
              },
              "uid": {
                "description": "uid",
                "type": "number"
              },
              "gid": {
                "description": "gid",
                "type": "number"
              },
              "sid": {
                "description": "sid",
                "type": "string"
              },
              "name": {
                "description": "name",
                "type": "string"
              }
            }
          },
          "rights": {
            "description": "Rights pertaining to the permissions entry",
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "READ",
                "WRITE",
                "CHANGE_PERMISSIONS",
                "ALL",
                "READ_DATA",
                "READ_EA",
                "READ_ATTR",
                "READ_ACL",
                "WRITE_EA",
                "WRITE_ATTR",
                "WRITE_ACL",
                "CHANGE_OWNER",
                "WRITE_GROUP",
                "DELETE",
                "EXECUTE",
                "MODIFY",
                "EXTEND",
                "ADD_FILE",
                "ADD_SUBDIR",
                "DELETE_CHILD",
                "SYNCHRONIZE"
              ],
              "description": "Rights pertaining to the permissions entry:\n * `ADD_FILE` - File creation access,\n * `ADD_SUBDIR` - Directory creation access,\n * `ALL` - All access rights,\n * `CHANGE_OWNER` - Owner write access,\n * `CHANGE_PERMISSIONS` - Rights to change permissions on file objects,\n * `DELETE` - Delete access,\n * `DELETE_CHILD` - Delete from directory access,\n * `EXECUTE` - Execute access,\n * `EXTEND` - File extension access,\n * `MODIFY` - File modification access,\n * `READ` - Read access rights,\n * `READ_ACL` - ACL read access,\n * `READ_ATTR` - Attribute read access,\n * `READ_DATA` - File read access,\n * `READ_EA` - Extended attribute read access,\n * `SYNCHRONIZE` - File synchronize access,\n * `WRITE` - Write access rights,\n * `WRITE_ACL` - ACL write access,\n * `WRITE_ATTR` - Attribute write access,\n * `WRITE_EA` - Extended attribute write access,\n * `WRITE_GROUP` - Group write access"
            }
          }
        }
      }
    },
    "network_permissions": {
      "type": "array",
      "items": {
        "description": "The network access control list (ACL) for this SMB share. If not specified, the default is to allow any host.",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "ALLOWED",
              "DENIED"
            ],
            "description": "Type of permissions entry (ALLOWED or DENIED):\n * `ALLOWED` - The permissions entry rights are allowed to the trustee,\n * `DENIED` - The permissions entry rights are denied to the trustee"
          },
          "address_ranges": {
            "type": "array",
            "items": {
              "description": "IP address ranges to apply permissions to. Empty means all hosts.",
              "type": "string"
            }
          },
          "rights": {
            "description": "Rights pertaining to the permissions entry",
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "READ",
                "WRITE",
                "CHANGE_PERMISSIONS",
                "ALL",
                "READ_DATA",
                "READ_EA",
                "READ_ATTR",
                "READ_ACL",
                "WRITE_EA",
                "WRITE_ATTR",
                "WRITE_ACL",
                "CHANGE_OWNER",
                "WRITE_GROUP",
                "DELETE",
                "EXECUTE",
                "MODIFY",
                "EXTEND",
                "ADD_FILE",
                "ADD_SUBDIR",
                "DELETE_CHILD",
                "SYNCHRONIZE"
              ],
              "description": "Rights pertaining to the permissions entry:\n * `ADD_FILE` - File creation access,\n * `ADD_SUBDIR` - Directory creation access,\n * `ALL` - All access rights,\n * `CHANGE_OWNER` - Owner write access,\n * `CHANGE_PERMISSIONS` - Rights to change permissions on file objects,\n * `DELETE` - Delete access,\n * `DELETE_CHILD` - Delete from directory access,\n * `EXECUTE` - Execute access,\n * `EXTEND` - File extension access,\n * `MODIFY` - File modification access,\n * `READ` - Read access rights,\n * `READ_ACL` - ACL read access,\n * `READ_ATTR` - Attribute read access,\n * `READ_DATA` - File read access,\n * `READ_EA` - Extended attribute read access,\n * `SYNCHRONIZE` - File synchronize access,\n * `WRITE` - Write access rights,\n * `WRITE_ACL` - ACL write access,\n * `WRITE_ATTR` - Attribute write access,\n * `WRITE_EA` - Extended attribute write access,\n * `WRITE_GROUP` - Group write access"
            }
          }
        }
      }
    },
    "access_based_enumeration_enabled": {
      "description": "Enable Access-based Enumeration on this SMB share",
      "type": "boolean"
    },
    "default_file_create_mode": {
      "description": "Default POSIX file create mode bits on this SMB share (octal, default 0644 if this field is empty)",
      "type": "string"
    },
    "default_directory_create_mode": {
      "description": "Default POSIX directory create mode bits on this SMB share (octal, default 0755 if this field is empty)",
      "type": "string"
    },
    "require_encryption": {
      "description": "Require all traffic to this share to be encrypted. Clients without encryption capabilities will not be able to connect. Default is false if this field is empty.",
      "type": "boolean"
    }
  }
}

Response

Codes

Code Description
200 Return value on success

Schema

{
  "description": "api_smb_share_v3",
  "type": "object",
  "properties": {
    "id": {
      "description": "The unique ID of the SMB share",
      "type": "string"
    },
    "share_name": {
      "description": "The SMB share name",
      "type": "string"
    },
    "tenant_id": {
      "description": "The tenant ID of the tenant that the SMB share is a part of",
      "type": "number"
    },
    "fs_path": {
      "description": "The filesystem path to SMB share",
      "type": "string"
    },
    "description": {
      "description": "Description of this SMB share",
      "type": "string"
    },
    "permissions": {
      "type": "array",
      "items": {
        "description": "The access control list (ACL) for this SMB share",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "ALLOWED",
              "DENIED"
            ],
            "description": "Type of permissions entry (ALLOWED or DENIED):\n * `ALLOWED` - The permissions entry rights are allowed to the trustee,\n * `DENIED` - The permissions entry rights are denied to the trustee"
          },
          "trustee": {
            "description": "User/group to apply the permissions entry to",
            "type": "object",
            "properties": {
              "domain": {
                "type": "string",
                "enum": [
                  "LOCAL",
                  "API_NULL_DOMAIN",
                  "WORLD",
                  "POSIX_USER",
                  "POSIX_GROUP",
                  "ACTIVE_DIRECTORY",
                  "API_INVALID_DOMAIN",
                  "API_RESERVED_DOMAIN",
                  "API_INTERNAL_DOMAIN",
                  "API_OPERATOR_DOMAIN",
                  "API_CREATOR_DOMAIN"
                ],
                "description": "domain:\n * `ACTIVE_DIRECTORY` - ACTIVE_DIRECTORY,\n * `API_CREATOR_DOMAIN` - API_CREATOR_DOMAIN,\n * `API_INTERNAL_DOMAIN` - API_INTERNAL_DOMAIN,\n * `API_INVALID_DOMAIN` - API_INVALID_DOMAIN,\n * `API_NULL_DOMAIN` - API_NULL_DOMAIN,\n * `API_OPERATOR_DOMAIN` - API_OPERATOR_DOMAIN,\n * `API_RESERVED_DOMAIN` - API_RESERVED_DOMAIN,\n * `LOCAL` - LOCAL,\n * `POSIX_GROUP` - POSIX_GROUP,\n * `POSIX_USER` - POSIX_USER,\n * `WORLD` - WORLD"
              },
              "auth_id": {
                "description": "auth_id",
                "type": "string"
              },
              "uid": {
                "description": "uid",
                "type": "number"
              },
              "gid": {
                "description": "gid",
                "type": "number"
              },
              "sid": {
                "description": "sid",
                "type": "string"
              },
              "name": {
                "description": "name",
                "type": "string"
              }
            }
          },
          "rights": {
            "description": "Rights pertaining to the permissions entry",
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "READ",
                "WRITE",
                "CHANGE_PERMISSIONS",
                "ALL",
                "READ_DATA",
                "READ_EA",
                "READ_ATTR",
                "READ_ACL",
                "WRITE_EA",
                "WRITE_ATTR",
                "WRITE_ACL",
                "CHANGE_OWNER",
                "WRITE_GROUP",
                "DELETE",
                "EXECUTE",
                "MODIFY",
                "EXTEND",
                "ADD_FILE",
                "ADD_SUBDIR",
                "DELETE_CHILD",
                "SYNCHRONIZE"
              ],
              "description": "Rights pertaining to the permissions entry:\n * `ADD_FILE` - File creation access,\n * `ADD_SUBDIR` - Directory creation access,\n * `ALL` - All access rights,\n * `CHANGE_OWNER` - Owner write access,\n * `CHANGE_PERMISSIONS` - Rights to change permissions on file objects,\n * `DELETE` - Delete access,\n * `DELETE_CHILD` - Delete from directory access,\n * `EXECUTE` - Execute access,\n * `EXTEND` - File extension access,\n * `MODIFY` - File modification access,\n * `READ` - Read access rights,\n * `READ_ACL` - ACL read access,\n * `READ_ATTR` - Attribute read access,\n * `READ_DATA` - File read access,\n * `READ_EA` - Extended attribute read access,\n * `SYNCHRONIZE` - File synchronize access,\n * `WRITE` - Write access rights,\n * `WRITE_ACL` - ACL write access,\n * `WRITE_ATTR` - Attribute write access,\n * `WRITE_EA` - Extended attribute write access,\n * `WRITE_GROUP` - Group write access"
            }
          }
        }
      }
    },
    "network_permissions": {
      "type": "array",
      "items": {
        "description": "The network access control list (ACL) for this SMB share. If not specified, the default is to allow any host.",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "ALLOWED",
              "DENIED"
            ],
            "description": "Type of permissions entry (ALLOWED or DENIED):\n * `ALLOWED` - The permissions entry rights are allowed to the trustee,\n * `DENIED` - The permissions entry rights are denied to the trustee"
          },
          "address_ranges": {
            "type": "array",
            "items": {
              "description": "IP address ranges to apply permissions to. Empty means all hosts.",
              "type": "string"
            }
          },
          "rights": {
            "description": "Rights pertaining to the permissions entry",
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "READ",
                "WRITE",
                "CHANGE_PERMISSIONS",
                "ALL",
                "READ_DATA",
                "READ_EA",
                "READ_ATTR",
                "READ_ACL",
                "WRITE_EA",
                "WRITE_ATTR",
                "WRITE_ACL",
                "CHANGE_OWNER",
                "WRITE_GROUP",
                "DELETE",
                "EXECUTE",
                "MODIFY",
                "EXTEND",
                "ADD_FILE",
                "ADD_SUBDIR",
                "DELETE_CHILD",
                "SYNCHRONIZE"
              ],
              "description": "Rights pertaining to the permissions entry:\n * `ADD_FILE` - File creation access,\n * `ADD_SUBDIR` - Directory creation access,\n * `ALL` - All access rights,\n * `CHANGE_OWNER` - Owner write access,\n * `CHANGE_PERMISSIONS` - Rights to change permissions on file objects,\n * `DELETE` - Delete access,\n * `DELETE_CHILD` - Delete from directory access,\n * `EXECUTE` - Execute access,\n * `EXTEND` - File extension access,\n * `MODIFY` - File modification access,\n * `READ` - Read access rights,\n * `READ_ACL` - ACL read access,\n * `READ_ATTR` - Attribute read access,\n * `READ_DATA` - File read access,\n * `READ_EA` - Extended attribute read access,\n * `SYNCHRONIZE` - File synchronize access,\n * `WRITE` - Write access rights,\n * `WRITE_ACL` - ACL write access,\n * `WRITE_ATTR` - Attribute write access,\n * `WRITE_EA` - Extended attribute write access,\n * `WRITE_GROUP` - Group write access"
            }
          }
        }
      }
    },
    "access_based_enumeration_enabled": {
      "description": "Enable Access-based Enumeration on this SMB share",
      "type": "boolean"
    },
    "default_file_create_mode": {
      "description": "Default POSIX file create mode bits on this SMB share (octal, default 0644 if this field is empty)",
      "type": "string"
    },
    "default_directory_create_mode": {
      "description": "Default POSIX directory create mode bits on this SMB share (octal, default 0755 if this field is empty)",
      "type": "string"
    },
    "require_encryption": {
      "description": "Require all traffic to this share to be encrypted. Clients without encryption capabilities will not be able to connect. Default is false if this field is empty.",
      "type": "boolean"
    }
  }
}