ActiveScale Management API
1.0 Overview
The management API allows you to interact with the ActiveScale system. This API has the following restrictions:
-
You can’t use it for time-based tasks.
-
You can’t use it to get graphics such as trend maps, heat maps, etc.
1.1 HTTP Verbs
The management API supports four verbs: POST, PUT, DELETE, and GET.
Table 1: HTTP verbs
| Verb | Action |
|---|---|
|
POST |
Create a new resource |
|
PUT |
Update an existing resource |
|
DELETE |
Delete an existing resource |
|
GET |
Retrieve or query existing resource(s) |
1.2 Content Types
The management API supports two content types: text/CSV and application/JSON. Most requests and responses use application/JSON, but some support text/CSV to upload or download content as an alternate format. The APIs that support text/CSV mention that explicitly; all others use application/JSON only.
1.3 URI Layout
The management API is rooted at https://PublicNetworkIP:10443/apiand is divided into modules.
To get a list of supported modules, use the GET /api/call.
1.4 URI Versions
The management API tracks versions at the level of individual modules.
Versions specify major and minor identifiers. Minor identifiers are backward compatible, but major identifier changes can introduce incompatibilities.
If you do not include a specific version on an API call, the system executes your call with the most recent version. For example, if v3.1 is the current version of the s3module, the following calls are equivalent:
GET /api/as-status/summary/v3.1/
GET /api/as-status/summary/v3/
GET /api/as-status/summary/
2.0 Authentication
2.1 POST /login
Description
Authenticate your session by sending a POST /login request to the URL https://PublicNetworkIP:10443/login over HTTPS.
Parameters
|
|
Valid value: |
|
|
Valid value: your password for |
Note: If you specify an invalid username or password, the system returns an HTTP 401 error.
Sample request
In the example below, the --insecure flag is added to the curl command, but best practice is to upload a valid SSL certificate and then replace the --insecure flag with the -k flag,
'https://PublicNetworkIP:10443/login' \
-d '{"username":"admin","password":"mysupersecretpassword"}'
Sample response
The response is a JSON object containing a token property:
{
"message":"Successfully obtained access token",
"payload":{
"token":"your_session_token",
"secToExpire":360,
"generatedPassword":false,
"firstTimeLogin":1,
"roles":["Read","Audit","Service","Admin"],
"role":"admin"
},
"success":true
}
You must specify "your_session_token"in the X-Auth-Token or x-auth-tokenheader of all subsequent REST API calls for this session. For example, in the bash shell:
TOKEN="your_session_token"
...
curl -k -X GET -H "X-Auth-Token:$TOKEN" URL -d '{JSON_DATA}'
Note: If you specify an invalid/expired token X-Auth-Token or x-auth-tokenthe system returns an HTTP 401 error.
The token cannot be explicitly invalidated, but the management API maintains a "sessionless" state. The token times out automatically after the timeout value you specify through ActiveScale SM.
3.0 System Status Operations
3.1 GET /api/as-status/summary
Description
Get a summary of system status.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/as-status/summary'
Sample response
{
"message": "successfully loaded summary of as-status",
"payload": {
"summary": {
"timestamp": 1536777265635,
"companyName": "Amplidata",
"systemHealth": "good",
"capacity": {
"percentUsed": 0.22,
"total": 1.19,
"storageUnit": "TB"
},
"performance": {
"overallRead": {
"value": 0,
"unit": "MB"
},
"overallWrite": {
"value": 0,
"unit": "MB"
},
"objectRead": 0,
"objectWrite": 0
},
"performanceSummary": "No Data",
"dataSafety": {
"warning": 60,
"critical": 40
},
"dataSafetySummary": "good"
}
},
"success": true
}
3.2 GET /api/as-status/version
Description
Get ActiveScale OS version.
Parameters
|
|
Include or exclude details. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/as-status/version?details=false'
Sample response
{
"message": "getEnvironment",
"payload": {
"version": {
"_lock": null,
"additional_packages": [
"mcore",
"activescale"
],
"applied_version": null,
"date_created": 1.536102073329e+15,
"date_modified": 1.536102073329e+15,
"distribution": [
"wd activescale-5.4.0.23"
],
"guid": "826a48b4-a1ee-4c9b-9d20-f3378f4730c9",
"model_version": 0,
"semver": "5.4.0.23",
"version": "activescale 5.4.0.23",
"versiontype": "version"
}
},
"success": true
}
4.0 Event Operations
4.1 GET /api/events/summary
Description
Get a summary of events.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/events/summary'
Sample response
{
"message": "successfully loaded summary of events",
"payload": {
"summary": {
"critical": 0,
"error": 54,
"warning": 1
}
},
"success": true
}
4.2 GET /api/events/all
Description
Download all events.
Parameters
|
|
Output format. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/events/all?format=csv'
5.0 Job Operations
5.1 GET /api/jobs/all
Description
List jobs.
Parameters
|
|
Limit response to jobs with this status. Valid values: |
|
|
Limit response to jobs with this status. Valid values: |
|
|
Limit response to this site. Get valid values from the id field in the response to 7.2 GET /api/resources/data-centers. |
Sample request
'https://PublicNetworkIP:10443/api/jobs/all'
5.2 GET /api/jobs/job/{jobID}
Description
Get details about a specific job.
Parameters
|
|
Job ID. Get this from the response to 5.1 GET /api/jobs/all. |
Sample request
Sample response
{
"success": true,
"payload": {
"_id": "5ba21be1b5a0d770fd9bfea0",
"jobId": "79b82ac8-5a9a-472f-8908-df0739d0946a",
"startTime": 1537350625297,
"endTime": 1537350722228,
"status": "SUCCESS",
"type": "LOG_ARCHIVAL",
"description": {
"message": "Finished executing logArchival",
"logArchivalResultDetails": [
{
"result": null,
"taskId": "09478d91-811f-4129-9d59-f560f1886fdb",
"finished": true,
"status": "SUCCESS",
"dateModified": 1537350722228,
"guid": "2b8034c0-3e44-4de3-937e-e248494906f4",
"success": true
},
{
"result": null,
"taskId": "548cdfba-4771-414f-9e09-574df039958a",
"finished": true,
"status": "SUCCESS",
"dateModified": 1537350691131,
"guid": "d958dc34-7ff9-45c2-a03f-66dd00424ad5",
"success": true
}
]
},
"role": "",
"createHandler": {...},
"updateHandler": {...},
"tasks": [...],
"siteName": "Site1",
"rackName": "R01",
"rackSerial": "USCSJ03815MA0004",
"machineName": "Site1-R01-SG01",
"success": true
}
}
5.3 PUT /api/jobs/job/{jobID}/cancel
Description
Cancel a specific job.
Parameters
|
|
Job ID. Get this from the response to 5.1 GET /api/jobs/all. |
Sample request
'https://PublicNetworkIP:10443/api/jobs/job/0d25ba82-2bc3-4b20-8951-0e9049ef5c80/cancel'
5.4 PUT /api/jobs/job/{jobID}/force
Description
Restart a specific job.
Parameters
|
|
Job ID. Get this from the response to 5.1 GET /api/jobs/all. |
Sample request
'https://PublicNetworkIP:10443/api/jobs/job/0d25ba82-2bc3-4b20-8951-0e9049ef5c80/force'
5.5 GET /api/jobs/task/{taskID}
Description
Get details about a specific task.
Parameters
|
|
Task ID. Get this from the response to 5.1 GET /api/jobs/all. |
Sample request
'https://PublicNetworkIP:10443/api/jobs/task/5678-5678-5678-5678'
6.0 Configuration Operations
6.1 GET /api/config/capacity/threshold
Description
Get thresholds for SLA, capacity, data safety, and disk temperature.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/config/capacity/threshold'
Sample response
"message": "Successfully retrieved threshold data",
"payload": {
"name": "threshold",
"sla": {
"module": "sla",
"description": "percentage threshold for SLA",
"warning": 60,
"critical": 40
},
"capacity": {
"module": "capacity",
"description": "percentage threshold for capacity",
"warning": 80,
"critical": 90
},
"dss": {
"module": "dss",
"description": "percentage threshold for data safety",
"warning": 60,
"critical": 40
},
"disk": {
"module": "disk",
"description": "celsius threshold for disk temperature",
"critical": 55
}
},
"success": true,
"token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWRtaW4iLCJyb2xlcyI6WyJhZG1pbiJdLCJpYXQiOjE1Mz
gwODUzNjgsImV4cCI6MTUzODA4NTc3Nn0.fHEV_iQY-B6QMwpO9OdLjMPrByTEge_l5ntvdVhGQ8c"
}
6.2 GET /api/config/datasafety/threshold
Description
Get the system’s current data safety thresholds.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/config/datasafety/threshold'
Sample response
{
"message": "Successfully retrieved threshold data",
"payload": {
"name": "threshold",
"sla": {
"module": "sla",
"description": "percentage threshold for SLA",
"warning": 60,
"critical": 40
},
"capacity": {
"module": "capacity",
"description": "percentage threshold for capacity",
"warning": 80,
"critical": 90
},
"dss": {
"module": "dss",
"description": "percentage threshold for data safety",
"warning": 60,
"critical": 40
},
"disk": {
"module": "disk",
"description": "celsius threshold for disk temperature",
"critical": 55
}
},
"success": true,
"token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWRtaW4iLCJyb2xlcyI6WyJhZG1pbiJdLCJpYXQiOjE1Mz
gwODUzNjgsImV4cCI6MTUzODA4NjA1Mn0.PMlC_zrd-AlnJz32EIfVN_K3R0OTbwqwJzMA105VkoM"
}
6.3 GET /api/config/durabilitypolicy
Description
Get information about all available durability policies.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/config/durabilitypolicy'
6.4 POST /api/config/healthcheck
Description
Run a health check. This operation is available to the support user only.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/config/healthcheck'
Sample response
{
"payload": {
"jobId": "c9188727-dd59-4ec3-b436-d084ef30cd5a",
"startTime": 1538086756290,
"endTime": -1,
"status": "IN_PROGRESS",
"type": "HEALTH_JOB",
"description": {
"message": "Performing health check"
},
"role": "",
"createHandler": {...},
"updateHandler": {...},
"tasks": [
{...},
{...}
],
"siteName": "Site1",
"rackName": "R01",
"rackSerial": "r00001",
"machineName": "HGST-S3-Site1-R01-SG01",
"success": true
},
"success": true,
"token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiaGdzdHN1cHBvcnQiLCJyb2xlcyI6WyJzdXBwb3J0Il0sIm
lhdCI6MTUzODA4NjcwNSwiZXhwIjoxNTM4MDg4NTUyfQ.wsISBay9vM_azcO_FAIYTqHYIIPerDsOVnfq_EXeGnY"
}
6.5 GET /api/config/marvin/environment
Description
Get information about the Marvin environment. This operation is available to the support user only.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/config/marvin/environment'
Sample response
{
"payload": {
"jobId": "c9188727-dd59-4ec3-b436-d084ef30cd5a",
"startTime": 1538086756290,
"endTime": -1,
"status": "IN_PROGRESS",
"type": "HEALTH_JOB",
"description": {
"message": "Performing health check"
},
"role": "",
"createHandler": {...},
"updateHandler": {...},
"tasks": [
{...},
{...}
],
"siteName": "Site1",
"rackName": "R01",
"rackSerial": "r00001",
"machineName": "HGST-S3-Site1-R01-SG01",
"success": true
},
"success": true,
"token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiaGdzdHN1cHBvcnQiLCJyb2xlcyI6WyJzdXBwb3J0Il0sIm
lhdCI6MTUzODA4NjcwNSwiZXhwIjoxNTM4MDg4NTUyfQ.wsISBay9vM_azcO_FAIYTqHYIIPerDsOVnfq_EXeGnY"
}
6.6 GET /api/config/networks/all
Description
Get information about all networks or a specific network. No IPv6 addresses for public interfaces are listed even if they are configured with IPv6 addresses.
Parameters
|
|
(Optional) Name of the network. Valid values: Site1_PublicNetwork1, Site2_PublicNetwork1, Site3_PublicNetwork1
Site1_PublicNetwork2, Site2_PublicNetwork2, Site3_PublicNetwork2
Site1_ScaleoutNetwork1, Site2_ScaleoutNetwork1, Site3_ScaleoutNetwork1
Site1_ScaleoutNetwork2, Site2_ScaleoutNetwork2, Site3_ScaleoutNetwork2
|
Sample request
'https://PublicNetworkIP:10443/api/config/networks/all?networkName=Site1_PublicNetwork1'
Sample response
{
"payload": {
"data": {
"networkName": "Site1_PublicNetwork1",
"machines": [
{
"name": "Site1-R01-SG01",
"role": "SPXMGMT",
"roleType": "Scaler",
"device": "bond0",
"address": "192.168.1.1"
},
{
"name": "Site1-R01-SG02",
"role": "SPXMGMT",
"roleType": "Scaler",
"device": "bond0",
"address": "192.168.1.2"
},
{
"name": "Site1-R01-SG03",
"role": "SPXMGMT",
"roleType": "Scaler",
"device": "bond0",
"address": "192.168.1.3"
}
]
}
},
"success": true,
"token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWRtaW4iLCJyb2xlcyI6WyJhZG1pbiJdLCJpYXQiOjE1Mz
gwODk4NzUsImV4cCI6MTUzODA5MDI1Mn0.yLiKa2-olZDQMp55JUhkSL1Q1kX-Qb_ozTTVlDRDoJM"
}
6.7 GET /api/config/networks/dns
Description
Get a list of DNS servers in use.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/config/networks/dns'
Sample response
{
"message": "Successfully loaded list of DNS servers",
"payload": {
"dnsServers": [
{
"dnsConnection": {
"_lock": null,
"applied_version": null,
"connectiontype": "DNS",
"date_created": 1.535499880856e+15,
"date_modified": 1.537533253985e+15,
"guid": "3ad042c9-a28d-4d75-b9f3-19a69b0db436",
"login": null,
"model_version": 0,
"name": null,
"password": null,
“ipv6_server”: ['2001:db8::123'],
"server": [
"4.3.1.1",
"4.3.1.3",
"4.3.1.4",
"4.3.1.5",
"4.3.1.8"
],
"ssl_certificate": null,
"ssl_key": null,
"ssl_root_certificate": null
},
"locationType": "DATACENTER",
"locationName": "Site1"
},
{
}
]
}
}
6.8 POST /api/config/networks/dns
Description
Add a DNS server(s) to all sites or to a specific site. It is not possible to add an IPv6 address using the API.
Parameters
|
|
Site GUID. Get this from the first GUID listed in the locations field in the response to 7.2 GET /api/resources/data-centers. |
|
server |
List of new DNS server IP addresses. |
|
guid |
GUID of the DNS connection. Get this from the guid field in the response to 6.8 POST /api/config/networks/dns. |
Sample request
'https://PublicNetworkIP:10443/api/config/networks/dns' \
-d '{ "parameters": {"server": ["8.8.8.8"]}, "guid":"d940c091-d782-49a7-b63b-44c2353b61df", "locationGuid": "e9f08ec0-73fa-489d-91a5-5aa72590dc45" }'
6.9 GET /api/config/networks/ntp
Description
Get a list of NTP servers in use.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/config/networks/ntp'
Sample response
{
"message": "Successfully loaded list of NTP servers",
"payload": {
"ntpServers": [
{
"ntpConnection": {
"_lock": null,
"applied_version": null,
"connectiontype": "NTP",
"date_created": 1.53610208041e+15,
"date_modified": 1.53610208041e+15,
"guid": "842f46c8-869d-4991-b59c-a463f3f8153f",
"login": null,
"model_version": 0,
"name": null,
"password": null,
"server": [
"10.108.32.1",
“2001:db8::123",
"ntp.hgst.com"
],
"ssl_certificate": null,
"ssl_key": null,
"ssl_root_certificate": null
},
"locationType": "DATACENTER",
"locationName": "Site1"
},
{
}
]
}
}
6.10 POST /api/config/networks/ntp
Description
Add an NTP server to all sites or to a specific site.
Parameters
|
|
Site GUID. Get this from the first GUID listed in the |
|
|
The new NTP server’s IP address or FQDN. It is also possible to specify an IPv6 address if the public interfaces are configured with an IPv6 address. |
|
|
GUID of the NTP connection. Get this from the |
Sample request
'https://PublicNetworkIP:10443/api/config/networks/ntp' \
-d '{"parameters": {"server": ["pool.ntp.org1"]}, "guid":"d940c091-d782-49a7-b63b-44c2353b61df", "locationGuid": "e9f08ec0-73fa-489d-91a5-5aa72590dc45" }'
6.11 GET /api/config/reports/capacity
Description
Get a capacity report.
Parameters
|
|
Format of report. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/config/reports/capacity?format=csv'
6.12 GET /api/config/reports/durabilitypolicy
Description
Get durability policy settings.
Parameters
|
format |
Format of report. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/config/reports/durabilitypolicy?format=csv'
6.13 GET /api/config/reports/performance/responsetime
Description
Get response time statistics.
Parameters
|
|
Format of report. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/config/reports/performance/responsetime?format=csv'
6.14 GET /api/config/reports/performance/throughput
Description
Get a report on throughput performance.
Parameters
|
|
Format of report. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/config/reports/performance/throughput?format=csv'
6.15 GET /api/config/reports/performance/transactionsreadandwrite
Description
Get a report on read and write transaction performance.
Parameters
|
|
Format of report. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/config/reports/performance/transactionsreadandwrite \
?format=csv'
6.16 GET /api/config/reports/system/cpuusage
Description
Get a report on CPU usage.
Parameters
|
|
Format of report. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/config/reports/system/cpuusage?format=csv'
6.17 GET /api/config/reports/system/memoryusage
Description
Get a report on memory usage.
Parameters
|
|
Format of report. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/config/reports/system/memoryusage?format=csv'
6.18 GET /api/config/storage/selectedpolicy
Description
Get a summarized description of the durability policy in use.
Parameters
|
|
Format of report. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/config/storage/selectedpolicy?format=csv'
Sample response
{
"payload": {
"data": {
"_lock": null,
"applied_version": null,
"category": "balanced",
"date_created": 1.535500845384e+15,
"date_modified": 1.535500845384e+15,
"guid": "88763263-097d-4cd3-a82c-7dce4108628e",
"model_version": 0,
"small_file_threshold": 524288
}
},
"success": true,
"token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWRtaW4iLCJyb2xlcyI6WyJhZG1pbiJdLCJpYXQiOjE1Mz
gxNTU1NTksImV4cCI6MTUzODE1NTk5N30.BBmRSIuTs5kf6lQgtGFjbnp4A39zmgwfsa6oNfX2ilY"
}
6.19 GET /api/config/storage/selectedpolicy/details
Description
Get a detailed description of the durability policy in use.
Parameters
|
|
Format of report. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/config/storage/selectedpolicy/details?format=csv'
6.20 GET /api/config/userpreferences
Description
Get user preferences.
Parameters
|
|
Format of report. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/config/userpreferences?format=csv'
Sample response
{
"message": "Successfully retrieved user data",
"payload": {
"name": "user",
"session": {
"sessionTimeoutMinutes": 60
}
},
"success": true
}
7.0 Resource Operations
7.1 GET /api/resources/summary
Description
Get inventory report.
Parameters
|
|
Output format. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/resources/summary'
Sample response
{
"message": "successfully loaded summary of resources",
"payload": {
"summary": {
"numberOfGeos": 1,
"datacenters": [
{
"id": "Site1",
"name": "Site1",
"racks": [
{
"id": "R01",
"name": "R01",
"systemName": "MyTestEnvironment",
"software": "activescale",
"componentStatus": {
"diskssd": {
"fail": 0,
"total": 5
},
"diskhdd": {
"fail": 0,
"total": 16
},
"fan": {
"fail": 0,
"total": 0
},
"psu": {
"fail": 0,
"total": 0
},
"nic": {
"fail": 0,
"total": 9
},
"enclosure": {
"sledFail": 0,
"sledTotal": 0,
"fanFail": 0,
"fanTotal": 0,
"psuFail": 0,
"psuTotal": 0,
"diskhdFail": 0,
"diskhdTotal": 0
}
}
}
]
}
]
}
},
"success": true
}
7.2 GET /api/resources/data-centers
Description
List sites.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/resources/data-centers'
Sample response
{
"message": "getMachineHierarchy",
"payload": {
"datacenters": [
{
"name": "Site1",
"displayName": "Site1",
"id": "Site1",
"locations": [
"292c44e2-8b09-496c-89db-a90e986d80c3",
"6c7af182-40b8-4a3b-93ae-0cd8788467f4"
],
"racks": [
{
"name": "R01",
"displayName": "R01",
"id": "R01",
"serialNumber": "r00001",
"locations": [
"fb898585-e25d-4dc2-b24e-e8f573e5f66f",
"e270b0e0-4d7b-4f78-adbf-b90a81e2ddf9"
],
"numberOfSystemNodes": 1,
"numberOfStorageNodes": 1,
"numberOfColumns": 1,
"machines": [
{
"id": "188c5016-8b4e-4ff8-ace8-4010bfb0e538",
"role": "SPXMGMT",
"type": "SERVER",
"name": "HGST-S3-Site1-R01-SG01",
"locationSeqId": 1,
"columnId": null,
"columnSeqId": null,
"backendMachine": false
},
{
"id": "6a8c0dc5-ae29-4e53-9b12-9e7f206280b4",
"role": "CTRLSTORAGEMGMT",
"type": "STORAGE",
"name": "HGST-S3-Site1-R01-C01-SE01",
"locationSeqId": 1,
"columnId": "a27ceca3-d9e5-492d-9e5c-1bdbf7ce1175",
"columnSeqId": null,
"backendMachine": true
}
]
}
]
}
]
},
"success": true
}
7.3 GET /api/resources/data-centers/{siteID}
Description
List sites.
Parameters
|
|
Site ID. Get this from the id field in the response to 7.2 GET /api/resources/data-centers. |
Sample request
'https://PublicNetworkIP:10443/api/resources/data-centers/Site1'
Sample response
{
"message": "getMachineHierarchy",
"payload": {
"datacenter": {
"name": "Site1",
"displayName": "Site1",
"id": "Site1",
"locations": [
"292c44e2-8b09-496c-89db-a90e986d80c3",
"6c7af182-40b8-4a3b-93ae-0cd8788467f4"
],
"racks": [
{
"name": "R01",
"displayName": "R01",
"id": "R01",
"serialNumber": "r00001",
"locations": [
"fb898585-e25d-4dc2-b24e-e8f573e5f66f",
"e270b0e0-4d7b-4f78-adbf-b90a81e2ddf9"
],
"numberOfSystemNodes": 1,
"numberOfStorageNodes": 1,
"numberOfColumns": 1,
"machines": [
{
"id": "188c5016-8b4e-4ff8-ace8-4010bfb0e538",
"role": "SPXMGMT",
"type": "SERVER",
"name": "HGST-S3-Site1-R01-SG01",
"locationSeqId": 1,
"columnId": null,
"columnSeqId": null,
"backendMachine": false
},
{
"id": "6a8c0dc5-ae29-4e53-9b12-9e7f206280b4",
"role": "CTRLSTORAGEMGMT",
"type": "STORAGE",
"name": "HGST-S3-Site1-R01-C01-SE01",
"locationSeqId": 1,
"columnId": "a27ceca3-d9e5-492d-9e5c-1bdbf7ce1175",
"columnSeqId": null,
"backendMachine": true
}
]
}
]
}
},
"success": true
}
7.4 GET /api/resources/data-centers/{siteID}/racks
Description
List systems at a specific site.
Parameters
|
|
Site ID. Get this from the |
Sample request
'https://PublicNetworkIP:10443/api/resources/data-centers/racks'
Sample response
{
"message": "getMachineHierarchy",
"payload": {
"racks": [
{
"name": "R01",
"displayName": "R01",
"id": "R01",
"s erialNumber": "r00001",
"locations": [
"fb898585-e25d-4dc2-b24e-e8f573e5f66f",
"e270b0e0-4d7b-4f78-adbf-b 90a81e2ddf9"
],
"numberOfSystemNodes": 1,
"numberOfStorageNodes": 1,
"numberOfColumns": 1,
"machines": [ ...]
}
]
},
"success": true
}
7.5 GET /api/resources/data-centers/{siteID}/racks/{systemID}
Description
List systems at a specific site, with more details about a specific system ID
Parameters
|
|
Site ID. Get this from the |
|
|
System ID. Get this from the |
Sample request
'https://PublicNetworkIP:10443/api/resources/data-centers/Site1/racks/R01'
Sample response
{
"message": "Successfully got rack information",
"payload": {
"rack": {
"name": "R01",
"displayName": "R01",
"id": "R01",
"serialNumber": "r00001",
"locations": [
"fb898585-e25d-4dc2-b24e-e8f573e5f66f",
"e270b0e0-4d7b-4f78-adbf-b90a81e2ddf9"
],
"numberOfSystemNodes": 1,
"numberOfStorageNodes": 1,
"numberOfColumns": 1,
"machines": [...],
"dc": "Site1",
"switches": [...],
"sla": {
"value": 100,
"state": 0
},
"pdus": [...],
"systemName": "MyTestEnvironment",
"software": "activescale",
"componentStatus": {
"diskssd": {
"fail": 0,
"total": 5
},
"diskhdd": {
"fail": 0,
"total": 16
},
"fan": {
"fail": 0,
"total": 0
},
"psu": {
"fail": 0,
"total": 0
},
"nic": {
"fail": 0,
"total": 9
},
"enclosure": {
"sledFail": 0,
"sledTotal": 0,
"fanFail": 0,
"fanTotal": 0,
"psuFail": 0,
"psuTotal": 0,
"diskhdFail": 0,
"diskhdTotal": 0
}
}
}
},
"success": true
}
7.6 GET /api/resources/data-centers/{siteID}/racks/{systemID}/machines
Description
List nodes in a specific system.
Parameters
|
|
Site ID. Get this from the |
|
|
System ID. Get this from the |
Sample request
'https://PublicNetworkIP:10443/api/resources/data-centers/Site1/racks/R01/machines'
Sample response
{
"message": "Successfully got rack information",
"payload": {
"machines": [
{
"id": "5ec61739-d21a-47da-810d-0b09fe097b12",
"role": "SPXMGMT",
"type": "SERVER",
"name": "scaler-1",
"locationSeqId": 1,
"columnId": null,
"columnSeqId": null,
"backendMachine": false,
"led": "OFF",
"status": "ONLINE",
"componentStatus": {
. . . }
},
"sla": {
"value": 100,
"state": 0
}
},
. . . }
]
},
"success": true
}
7.7 GET /api/resources/data-centers/{siteID}/racks/{systemID}/machines/{machineID}
Description
List nodes in a specific system.
Parameters
|
|
Site ID. Get this from the |
|
|
System ID. Get this from the |
|
|
Machine ID. Get this from the |
Sample request
'https://PublicNetworkIP:10443/api/resources/data-centers/Site1/racks/R01/machines/SG01'
7.8 PUT /api/resources/data-centers/{siteID}/racks/{systemID}/machines/{machineID}
Description
Reboot a node.
Parameters
|
|
Site ID. Get this from the |
|
|
System ID. Get this from the |
|
|
Machine ID. Get this from the |
|
|
Reboot machine. Valid values are |
Sample request
'https://PublicNetworkIP:10443/api/resources/data-centers/Site1/racks/R01/machines/188c5016-8b4e-4ff8-ace8-4010bfb0e538' \
-d '{"reboot": true}'
7.9 PUT /api/resources/data-centers/{siteID}/racks/{systemID}/machines/{machineID}
Description
Enable or disable a node’s identification LED.
Parameters
|
|
Site ID. Get this from the |
|
|
System ID. Get this from the |
|
|
Machine ID. Get this from the |
|
|
Enables or disables the identification LED. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/resources/data-centers/Site1/racks/R01/machines/188c5016-8b4e-4ff8-ace8-4010bfb0e538' \
-d '{"led": true}'
7.10 GET /api/resources/data-centers/{siteID}/racks/{systemID}/machines/{machineID}/disks
Description
List disks.
Parameters
|
|
Site ID. Get this from the |
|
|
System ID. Get this from the |
|
|
Machine ID. Get this from the |
Sample request
'https://PublicNetworkIP:10443/api/resources/data-centers/Site1/racks/R01/machines/188c5016-8b4e-4ff8-ace8-4010bfb0e538/disks
Sample response
{
"message": "Successfully retrieved disks for machine: 188c5016-8b4e-4ff8-ace8-4010bfb0e538",
"payload": {
"disks": [
{
"_lock": null,
"applied_version": null,
"buslocation": "pno-1:2",
"date_created": 1.536102098022e+15,
"date_degraded": null,
"date_modified": 1.536877691333e+15,
"date_status_change": 1.53610218771e+15,
"device": "sda",
"diskid": "ata-VBOX_HARDDISK_VB349873c0-e3a86922",
"disktype": "HDD",
"fw_version": null,
"fw_version_available": null,
"guid": "ff816eb7-fed4-4673-be82-f61b613d1b6e",
"led": "OFF",
"model_version": 0,
"partition": [...],
"role": "os",
"sequence_id": 1,
"serial": "VBOX_HARDDISK_VB349873c0-e3a86922",
"size": 122880,
"sla_weight": null,
"status": "ONLINE",
"unit": "MiB"
},
{...},
{...},
{...},
{...},
{...},
{...},
{...}
]
},
"success": true
}
7.11 PUT /api/resources/data-centers/{siteID}/racks/{systemID}/machines/{machineID}/disks/{diskID}
Description
Decommission a disk.
Note: This action is only possible on a disk that has a MISSING or DEGRADED status. Any attempt to decommission a disk with a different status fails.
Parameters
|
|
Site ID. Get this from the |
|
|
System ID. Get this from the |
|
|
Machine ID. Get this from the |
|
|
Disk ID. Get this from the |
|
|
Decommission the disk. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/resources/data-centers/Site1/racks/R01/machines/188c5016-8b4e-4ff8-ace8-4010bfb0e538/disks/ata-VBOX_HARDDISK_VB349873c0-e3a86922' \
-d '{"decommision": true}'
7.12 PUT /api/resources/data-centers/{siteID}/racks/{systemID}/machines/{machineID}/disks/{diskID}
Description
Enable or disable a disk's identification LED.
Note: This operation is for the HDDs or SSDs on System Nodes and Storage Nodes.
Parameters
|
|
Site ID. Get this from the |
|
|
System ID. Get this from the |
|
|
Machine ID. Get this from the |
|
|
Disk ID. Get this from the |
|
|
Enables or disables the identification LED. Valid values: |
Sample request
-H "Content-Type:application/json"\
'https://PublicNetworkIP:10443/api/resources/data-centers/Site1/racks/R01/machines/188c5016-8b4e-4ff8-ace8-4010bfb0e538/disks/ata-VBOX_HARDDISK_VB349873c0-e3a86922' \
-d '{"led": true}'
Sample response
{
"message": "Successfully took action, set_led_identify_on, on resource path,
machine\/188c5016-8b4e-4ff8-ace8-4010bfb0e538\/disk\/ata-VBOX_HARDDISK_VB349873c0-
e3a86922",
"payload": {
"action": "set_led_identify_on",
"taskid": "3b3726f4-11f6-4a03-bcae-c2bda19f910b",
"guid": "3b3726f4-11f6-4a03-bcae-c2bda19f910b",
"status": "STARTED",
"finished": false,
"resourceid": "188c5016-8b4e-4ff8-ace8-4010bfb0e538",
"resourcetype": "machine"
},
"success": true
}
7.13 GET /api/resources/data-centers/{siteID}/racks/{systemID}/machines/{machineID}/fans
Description
List fans.
Parameters
|
|
Site ID. Get this from the |
|
|
System ID. Get this from the |
|
|
Machine ID. Get this from the |
Sample request
'https://PublicNetworkIP:10443/api/resources/data-centers/Site1/racks/R01/machines/188c5016-8b4e-4ff8-ace8-4010bfb0e538/fans'
7.14 GET /api/resources/data-centers/{siteID}/racks/{systemID}/machines/{machineID}/psus
Description
List power supply units.
Parameters
|
|
Site ID. Get this from the |
|
|
System ID. Get this from the |
|
|
Machine ID. Get this from the |
Sample request
'https://PublicNetworkIP:10443/api/resources/data-centers/Site1/racks/R01/machines/188c5016-8b4e-4ff8-ace8-4010bfb0e538/psus'
7.15 GET /api/resources/data-centers/{siteID}/racks/{systemID}/machines/{machineID}/nics
Description
List network interface cards.
Parameters
|
|
Site ID. Get this from the |
|
|
System ID. Get this from the |
|
|
Machine ID. Get this from the |
Sample request
'https://PublicNetworkIP:10443/api/resources/data-centers/Site1/racks/R01/machines/188c5016-8b4e-4ff8-ace8-4010bfb0e538/nics'
8.0 Notification Operations
8.1 POST /api/smtp/mail
Description
Send email.
Parameters
|
|
Email address of sender |
|
|
Name of sender |
|
|
Email subject |
|
|
Email body |
|
|
Email address of receiver |
Sample request
'https://PublicNetworkIP:10443/api/smtp/mail' \
-d '{"senderEmail":"user85@somedomain.com", "senderName":"user85","subject":"Send test email from user85","body":"This is a test email only from user85","receiver": ["user88@somedomain.com"]}'
8.2 GET /api/smtp/settings
Description
Get and optionally test SMTP settings.
Parameters
|
|
(Optional) Test the SMTP settings. Valid values: 0 (don’t test), 1 (test). |
Sample request
'https://PublicNetworkIP:10443/api/smtp/settings?test=1'
Sample response
{
"message": "Successfully loaded list of SMTP servers",
"payload": {
"smtpServers": [
{
"smtpConnection": {
"_lock": null,
"applied_version": null,
"connectiontype": "SMTP",
"date_created": 1.53550030228e+15,
"date_modified": 1.537505170706e+15,
"guid": "8c8f0a54-44a2-4d3b-8d31-0a5f046de84d",
"login": "admin",
"model_version": 0,
"name": null,
"password": "a420258f95bcc4c5b3360cf8f55f4fe9",
"receiver": [
"firstname.lastname@somedomain.com"
],
"senderemail": "no-reply@yourdomain.com",
"sendername": null,
"server": "10.30.38.18",
"ssl_certificate": null,
"ssl_key": null,
"ssl_root_certificate": null
},
"locationType": "DATACENTER",
"locationName": "Site1"
},
{
}
]
}
}
8.3 GET /api/snmp/settings
Description
Get the SNMP settings.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/snmp/settings'
Sample response
{
"message": "Successfully loaded list of SNMP servers",
"payload": {
"snmpServers": [
{
"snmpConnection": {
"_lock": null,
"applied_version": null,
"community_name": "public",
"connectiontype": "SNMP",
"date_created": 1.53550039247e+15,
"date_modified": 1.537505301841e+15,
"guid": "8dd6d8d3-bd43-45c1-992e-29f8e7842114",
"login": null,
"model_version": 0,
"name": null,
"oid_prefix": null,
"password": null,
"pen": "1.3.6.1.4.1.31563",
"port": 162,
"server": "10.30.38.18",
"ssl_certificate": null,
"ssl_key": null,
"ssl_root_certificate": null,
"version": null
},
"locationType": "DATACENTER",
"locationName": "Site1"
},
{
}
]
}
}
8.4 POST /api/snmp/test
Description
Test the SNMP settings.
Parameters
|
|
Connection GUID. Get this from the |
|
|
TBD |
|
|
TBD |
Sample request
'https://PublicNetworkIP:10443/api/snmp/test' \
-d '{"connectionGuid":"21743879-4704-4acc-80bc-6fc6beae2866", "resourceGuid": "f03f770e-9c0c-489b-8a60-53e62cb39f0c", "resource": "location"}'
8.5 GET /api/snmp/poll_community_string
Description
Get the community string for SNMP polling.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/snmp/poll_community_string'
Sample response
{
"success": true,
"payload": {
"data": "In-House",
"subnet": [
]
}
}
8.6 POST /api/snmp/poll_community_string
Description
Change the community string for SNMP polling.
Parameters
|
|
Community string |
Sample request
'https://PublicNetworkIP:10443/api/snmp/poll_community_string' \
-d '{"communityString": "atatatat"}'
Sample response
{
"configrule": {
"_lock": null,
"date_created": 1.488363246743e+15,
"date_modified": 1.488451143932e+15,
"guid": "012ff6ef-bc4d-406b-a49f-cb232995cf6c",
"id": "58b69eeff1de087a12d8f175",
"name": "snmpd_settings",
"priority": 1,
"resourcetype": "snmpd",
"rule": "",
"settings": [
[
"community_string",
"atatatat"
]
]
},
"links": {
"actions": {
"get_all_settings": "https:\/\/10.132.72.119:9019\/model\/configrule\/012ff6ef-bc4d-406ba49f-cb232995cf6c\/action\/get_all_settings\/",
"get_embedded_attributes": "https:\/\/10.132.72.119:9019\/model\/configrule\/012ff6ef-bc4d406b-a49f-cb232995cf6c\/action\/get_embedded_attributes\/",
"get_location_hierarchy": "https:\/\/10.132.72.119:9019\/model\/configrule\/012ff6ef-bc4d406b-a49f-cb232995cf6c\/action\/get_location_hierarchy\/",
"get_types": "https:\/\/10.132.72.119:9019\/model\/configrule\/012ff6ef-bc4d-406b-a49fcb232995cf6c\/action\/get_types\/",
"getdefaults": "https:\/\/10.132.72.119:9019\/model\/configrule\/012ff6ef-bc4d-406b-a49fcb232995cf6c\/action\/getdefaults\/",
"getresources": "https:\/\/10.132.72.119:9019\/model\/configrule\/012ff6ef-bc4d-406b-a49fcb232995cf6c\/action\/getresources\/",
"match": "https:\/\/10.132.72.119:9019\/model\/configrule\/012ff6ef-bc4d-406b-a49fcb232995cf6c\/action\/match\/"
},
"parent": "https:\/\/10.132.72.119:9019\/model\/",
"self": "https:\/\/10.132.72.119:9019\/model\/configrule\/012ff6ef-bc4d-406b-a49fcb232995cf6c\/"
},
"query": "PUT https:\/\/10.132.72.119:9019\/model\/configrule\/012ff6ef-bc4d-406b-a49fcb232995cf6c\/",
"taskid": null,
"message": "Successfully updated configrule for snmpd_settings",
"success": true
}
9.0 Object Storage Operations
9.1 GET /api/s3/accounts
Description
Download account details.
Parameters
|
|
Output format. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/s3/accounts'
Sample response
{
"message": "successfully retrieved all accounts",
"payload": {
"accounts": [
{
"canonicalId": "11223344",
"identityType": 0,
"displayName": "accountname",
"email": "accountname@somedomain.com",
"parentAccountCanonicalId": null,
"apiKeys": [
{
"accessKey": "11223344key",
"secretKey": null,
"enabled": true,
"creationTime": 1420027491.888
}
],
"enabled": false,
"creationTime": 1420027490.888,
"modificationTime": 1420027492.888,
"emailOriginal": null,
"systemAccount": false
},
{...},
{...}
]
},
"success": true
}
9.2 POST /api/s3/accounts
Description
Add an account.
Parameters
|
|
Email address for the account. Must be unique. |
|
|
Nickname for the account. |
Sample request
'https://PublicNetworkIP:10443/api/s3/accounts' \
-d '{"email": "sourceacct@myemaildomain.com", "name": "sourceacct"}'
9.3 POST /api/s3/accounts
Description
Upload (bulk create) accounts/users.
Parameters
|
|
Name of the input file. Required. |
The CSV file can contain up to 300 lines of comma-separated values with the following syntax:
accountEmail,accountName,userEmail,userName
name1@somedomain.com,accountName1,user1@somedomain.com,userName1
name1@somedomain.com,accountName1,user2@somedomain.com,userName2
name1@somedomain.com,accountName1,user3@somedomain.com,userName3
Note: Account and user names can contain Unicode (non-ASCII) characters and do not need to be unique. Email addresses must be unique across all accounts and users.
For example,
accountEmail,accountName,userEmail,userName
account2@somedomain.com,accountName2,account2user1@somedomain.com,account2user1
account2@somedomain.com,accountName2,account2user2@somedomain.com,account2user2
account2@somedomain.com,accountName2,account2user3@somedomain.com,account2user3
WARNING: Line 1 of the CSV file must be the header row.
Sample request
'https://PublicNetworkIP:10443/api/s3/accounts' \
-d '{"form-data": "myidentities.csv"}'
9.4 GET /api/s3/accounts/{accountID}/keys
Description
List an account's API key(s).
Parameters
|
|
Canonical ID of the account. Get this value from the output of 9.1 GET /api/s3/accounts. |
Sample request
'https://PublicNetworkIP:10443/api/s3/accounts/11223344/keys'
Sample response
{
"message": "successfully retrieved keys for account 11223344",
"payload": {
"accessKeys": [
{
"accessKey": "enabledaccesskeyforadisabledaccount",
"enabled": true,
"creationTime": 1420027491.888
}
]
},
"success": true
}
9.5 POST /api/s3/accounts/{accountID}/keys
Description
Create an API key for a given account.
Parameters
|
|
Canonical ID of the account. Get this value from the output of 9.1 GET /api/s3/accounts. |
Sample request
'https://PublicNetworkIP:10443/api/s3/accounts/11223344/keys'
9.6 PUT /api/s3/accounts/{accountID}/keys/{accessKey}
Description
Enable or disable an account's API key.
Parameters
|
|
Canonical ID of the account. Get this value from the output of 9.1 GET /api/s3/accounts. |
|
|
Access key. Get this from the |
|
|
Enables or disables the key. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/s3/accounts/11223344/keys/11223344key' -d '{"enabled": false}'
Sample response
{
"message": "successfully disabled key 11223344key",
"success": true
}
9.7 DELETE /api/s3/accounts/{accountID}/keys/{accessKey}
Description
Delete an account's API key.
Parameters
|
|
Canonical ID of the account. Get this value from the output of 9.1 GET /api/s3/accounts. |
|
|
Access key. Get this from the |
Sample request
-H "Content-Type:application/json"\
'https://PublicNetworkIP:10443/api/s3/accounts/11223344/keys/11223344key'
9.8 GET /api/s3/accounts/{accountID}/users
Description
List the S3 users belonging to a given account.
Parameters
|
|
Canonical ID of the account. Get this value from the output of 9.1 GET /api/s3/accounts. |
Sample request
'https://PublicNetworkIP:10443/api/s3/accounts/11223344/users'
Sample response
{
"message": "successfully retrieved all users for account 11223344",
"payload": {
"users": [
]
},
"success": true
}
9.9 POST /api/s3/accounts/{accountID}/users
Description
Add an S3 user to a specific account.
Parameters
|
|
Canonical ID of the account. Get this value from the output of 9.1 GET /api/s3/accounts. |
|
|
Email address of the S3 user. Must be unique. |
|
|
Nickname of the S3 user. |
Sample request
'https://PublicNetworkIP:10443/api/s3/accounts/11223344/users' \
-d '{"email": "sourceacctuser1@myemaildomain.com", "name": "sourceacctuser1"}'
Sample response
{
"message": "successfully created user",
"payload": {
"user": {
"canonicalId": "805b9ff4c4ae88df3157e56680",
"identityType": 1,
"displayName": "sourceacctuser1",
"email": "sourceacctuser1@hgst.com",
"parentAccountCanonicalId": "11223344",
"apiKeys": null,
"enabled": true,
"creationTime": 1537209540.627,
"modificationTime": 1537209540.627,
"emailOriginal": null
}
},
"success": true
}
9.10 PUT /api/s3/accounts/{accountID}/users/{userID}
Description
Change an S3 user’s email address and/or name.
Parameters
|
|
Canonical ID of the account. Get this value from the output of 9.1 GET /api/s3/accounts. |
|
|
Canonical ID of the S3 user. Get this value from the output of 9.8 GET /api/s3/accounts/{accountID}/users. |
|
|
Email address of the S3 user. Must be unique. |
|
|
Nickname of the S3 user. |
Sample request
-H "Content-Type:application/json" \
'https://PublicNetworkIP:10443/api/s3/accounts/11223344/users/805b9ff4c4ae88df3157e56680' \
-d '{"email": "sourceacctuser1_newemail@hgst.com", "name": "sourceacctuser1_newusername"}'
Sample response
{
"message": "successfully modified user",
"payload": {
"user": {
"canonicalId": "805b9ff4c4ae88df3157e56680",
"identityType": 1,
"displayName": "sourceacctuser1_newusername",
"email": "sourceacctuser1_newemail@hgst.com",
"parentAccountCanonicalId": "11223344",
"apiKeys": [
],
"enabled": true,
"creationTime": 1537209540.627,
"modificationTime": 1537209948.9548,
"emailOriginal": null
}
},
"success": true
}
9.11 PUT /api/s3/accounts/{accountID}/users/{userID}
Description
Enable or disable an S3 user.
Parameters
|
|
Canonical ID of the account. Get this value from the output of 9.1 GET /api/s3/accounts. |
|
|
Canonical ID of the S3 user. Get this value from the output of 9.8 GET /api/s3/accounts/{accountID}/users. |
|
|
Enables or disables the key. Valid values: |
Sample request
-H "Content-Type:application/json" \
'https://PublicNetworkIP:10443/api/s3/accounts/11223344/users/805b9ff4c4ae88df3157e56680' \
-d '{"enabled": false}'
Sample response
{
"message": "successfully modified user",
"payload": {
"user": {
"canonicalId": "805b9ff4c4ae88df3157e56680",
"identityType": 1,
"displayName": "sourceacctuser1_newusername",
"email": "sourceacctuser1_newemail@hgst.com",
"parentAccountCanonicalId": "11223344",
"apiKeys": [
],
"enabled": false,
"creationTime": 1537209540.627,
"modificationTime": 1537210162.176,
"emailOriginal": null
}
},
"success": true
}
9.12 GET /api/s3/accounts/{accountID}/users/{userID}/keys
Description
List an S3 user's API key(s).
Parameters
|
|
Canonical ID of the account. Get this value from the output of 9.1 GET /api/s3/accounts. |
|
|
Canonical ID of the S3 user. Get this value from the output of 9.8 GET /api/s3/accounts/{accountID}/users. |
Sample request
'https://PublicNetworkIP:10443/api/s3/accounts/11223344/users/805b9ff4c4ae88df3157e56680/keys'
Sample response
{
"message": "successfully retrieved keys for account 805b9ff4c4ae88df3157e56680",
"payload": {
"accessKeys": [
{
"accessKey": "AK04BW7WBQAJ1LK942W7",
"enabled": false,
"creationTime": 1537211360.6682
}
]
},
"success": true
}
9.13 POST /api/s3/accounts/{accountID}/users/{userID}/keys
Description
Create an S3 user's API key.
Parameters
|
|
Canonical ID of the account. Get this value from the output of 9.1 GET /api/s3/accounts. |
|
|
Canonical ID of the S3 user. Get this value from the output of 9.8 GET /api/s3/accounts/{accountID}/users. |
Sample request
'https://PublicNetworkIP:10443/api/s3/accounts/11223344/users/805b9ff4c4ae88df3157e56680/keys'
Sample response
{
"message": "successfully created key",
"payload": {
"accessKey": {
"accessKey": "AK04BW7WBQAJ1LK942W7",
"enabled": true,
"creationTime": 1537211360.6682
}
},
"success": true
}
9.14 PUT /api/s3/accounts/{accountID}/users/{userID}/keys/{accessKey}
Description
Enable or disable an S3 user's specific API key.
Parameters
|
|
Canonical ID of the account. Get this value from the output of 9.1 GET /api/s3/accounts. |
|
|
Canonical ID of the S3 user. Get this value from the output of 9.8 GET /api/s3/accounts/{accountID}/users. |
|
|
Access key. Get this from the accessKeys: accessKey field in the response to 9.12 GET /api/s3/accounts/{accountID}/users/{userID}/keys. |
|
|
Enables or disables the API key. Valid values: true, false. |
Sample request
-H "Content-Type:application/json" \
'https://PublicNetworkIP:10443/api/s3/accounts/11223344/users/805b9ff4c4ae88df3157e56680/keys/AK04BW7WBQAJ1LK942W7' \
-d '{"enabled": false}'
Sample response
{
"message": "successfully disabled key AK04BW7WBQAJ1LK942W7",
"success": true
}
9.15 DELETE /api/s3/accounts/{accountID}/users/{userID}/keys/{accessKey}
Description
Delete an S3 user's API key.
Parameters
|
|
Canonical ID of the account. Get this value from the output of 9.1 GET /api/s3/accounts. |
|
|
Canonical ID of the S3 user. Get this value from the output of 9.8 GET /api/s3/accounts/{accountID}/users. |
|
|
Access key. Get this from the accessKeys: accessKey field in the response to 9.12 GET /api/s3/accounts/{accountID}/users/{userID}/keys. |
Sample request
-H "Content-Type:application/json" \
'https://PublicNetworkIP:10443/api/s3/accounts/11223344/users/805b9ff4c4ae88df3157e56680/keys/AK04BW7WBQAJ1LK942W7'
Sample response
{
"message": "successfully deleted key 805b9ff4c4ae88df3157e56680",
"success": true
}
9.16 GET /bapi/v1/domains/types
Description
Get a list of all domain types. These are the types that can be used for /bapi/v1/{domainType}/domains requests.
Parameters
None.
Sample request
Sample response
{
"domaintypes": ["s3", "iam"]
}
9.17 GET /bapi/v1/domains
Description
Get the list of the configured S3 domains on the system.
Parameters
None.
Sample request
This is sample request for adding the domain mydomain.example.com
curl -k -X GET -H "auth-jwt:$TOKEN"
https://PublicNetworkIP:10443/bapi/v1/s3/domains
Sample response
{
"domains": ["s3.quantum.com", "s3.amazonaws.com"]
}
9.18 PUT /bapi/v1/s3/domains/{S3domainName}
Description
Add an S3 domain. Note that this request might take some time to complete.
Parameters
|
|
Required. The name of the S3 domain. |
Sample request
curl -k -X POST -H "auth-jwt:$TOKEN" -H "Content-Type:application/json" \
'https://PublicNetworkIP:10443/bapi/v1/s3/domains/s3.amazonaws.com'
Sample Response
The response is an empty json.
{
"domain": "s3.amazonaws.com"
}
9.19 DELETE /bapi/v1/s3/domains/{S3domainName}
Description
Delete an S3 domain. Deleting a domain that is not configured will return HTTP 200 OK. Note that this request might take some time to complete.
Parameters
|
|
Required. The name of the S3 domain to be deleted |
Sample request
curl -k -X DELETE -H "auth-jwt:$TOKEN" -H "Content-Type:application/json" \
'https://PublicNetworkIP:10443/bapi/v1/s3/domains/s3.amazonaws.com'
Sample Response
The response is an empty json.
{}
9.20 GET /bapi/v1/iam/domains/
Description
Get the list of the configured IAM domains on the system.
Parameters
None.
Sample request
Sample Response
{
"domains": ["iam.my.first.domain.com", "iam.my.second.domain.com"]
}
9.21 PUT /bapi/v1/iam/domains/{IAMdomainName}
Description
Add an IAM domain. Note that this request might take some time to complete.
Parameters
|
|
Required. The name of the new IAM domain. |
Sample request
Sample Response
{
"domain": "iam.test.example.com"
}
9.22 DELETE /bapi/v1/iam/domains/{IAMdomainName}
Description
Delete an IAM domain. Deleting a domain that is not configured will return HTTP 200 OK. Note that this request might take some time to complete.
Parameters
|
|
Required. The name of the IAM domain to be deleted. |
Sample request
Sample Response
Response is an empty json.
{}
9.23 GET /api/s3/reports/topaccountsbyactivity
Description
Download a report of accounts ordered by activity. The downloaded file is named S3TopAccountsByActivity.format.
Parameters
|
|
Output format. Valid values: csv, json. Default: csv |
Sample request
'https://PublicNetworkIP:10443/api/s3/reports/topaccountsbyactivity\
?format=json'
9.24 GET /api/s3/reports/topaccountsbycapacity
Description
Download a report of accounts ordered by capacity. The downloaded file is named S3TopAccountsByCapacity.format.
Parameters
|
|
Output format. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/s3/reports/topaccountsbycapacity\
?format=json'
9.25 GET /api/s3/summary
Description
Get a summary.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/s3/summary'
Sample response
{
"message": "successfully loaded summary of s3",
"payload": {
"summary": {
"averageObjectSize": 372.13,
"averageObjectSizeUnit": "KB",
"objectCount": 2904,
"bucketCount": 2,
"accountCount": 8
}
},
"success": true
}
9.26 GET /api/s3/system-bucket/info
Description
Get system bucket information.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/s3/system-bucket/info'
Sample response
{
"message": "successfully retrieved system bucket info",
"payload": {
"info": {
"name": "system-91a6a085-3135-4867-9502-2150b257dafc"
}
},
"success": true
}
9.27 GET /api/s3/system-bucket/access
Description
List accounts/users with system bucket access.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/s3/system-bucket/access'
Sample response
{
"message": "successfully retrieved system bucket users",
"payload": {
"users": [
]
},
"success": true
}
9.28 POST /api/s3/system-bucket/access
Description
Grant access to the system bucket to a specific account/user.
Parameters
|
|
Email address of an existing account/user, enclosed in double quotes. |
Sample request
'https://PublicNetworkIP:10443/api/s3/system-bucket/access' \
-d '{"email": "sourceacctuser2@myemaildomain.com"}'
9.29 DELETE /api/s3/system-bucket/access
Description
Revoke access to the system bucket.
Parameters
|
|
Email address of an existing account/user, enclosed in double quotes. |
Sample request
-H "Content-Type:application/json"\
'https://PublicNetworkIP:10443/api/s3/system-bucket/access' \
-d '{"email": "sourceacctuser2@myemaildomain.com"}'
10.0 Telemetry Operations
10.1 GET /api/telemetry/logs
Description
Download audit logs.
Parameters
|
|
Include or exclude latest (current) logs. Valid values are true (include latest logs) and false (exclude latest logs). |
Sample request
'https://PublicNetworkIP:10443/api/telemetry/logs?latest=true'
10.2 PUT /api/telemetry/logs
Description
Collect audit logs.
Parameters
|
|
Start log collection. Set this to true. |
Sample request
'https://PublicNetworkIP:10443/api/telemetry/logs' \
-d '{"collect": true}'
10.3 GET /api/telemetry/snmp
Description
Download the SNMP MIB.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/telemetry/snmp'
10.4 GET /api/telemetry/machine-learning
Description
Get telemetry collection status.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/telemetry/machine-learning'
10.5 POST /api/telemetry/machine-learning
Description
Enable telemetry collection.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/telemetry/machine-learning'
10.6 DELETE /api/telemetry/machine-learning
Description
Disable telemetry collection.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/telemetry/machine-learning'
10.7 POST /api/telemetry/machine-learning
Description
Synchronize telemetry collection.
Parameters
|
|
Starts synchronization. Set this to true. |
Sample request
'https://PublicNetworkIP:10443/api/telemetry/machine-learning' \
-d '{"sync": true}'
11.0 Download Operations
Note: Before downloading log files, first push the system logs to the system bucket and wait for that job to complete.
11.1 GET /download/supportlog
Description
Download system logs.
Parameters
|
|
Limit the log bundle contents to only those logs that pertain to the specified site ID. Valid values are |
|
|
Limit the log bundle contents to only those logs that pertain to the specified host name. For example, |
|
|
If this parameter is specified, it limits the log bundle contents to only those logs that pertain to the specified node type. Valid values are |
|
|
Limit the log bundle contents to only those logs that pertain to the specified component. When |
|
|
If set to |
|
|
Your chosen name for the downloadable log bundle. Defaults to ActiveScale_Support_Logs_YYYYMMDD_HHmmss.zip. |
|
|
Limit the logs in the downloadable bundle to only those with a timestamp equal to or later than this start date and time. Format yyy-mm-dd xx:xx:xx. For example, 2019-02-14T01:00:00. |
|
|
Limit the logs in the downloadable bundle to only those with a timestamp equal to or earlier than this end date and time. Format yyy-mm-dd xx:xx:xx. For example, 2019-02-14T01:00:00. |
Sample request
Calculate the size of the log bundle for a specific site:
'https://PublicNetworkIP:10443/download/supportlog?findSize=true&site=Site2'
Download all logs for a specific node at a specific site:
'https://PublicNetworkIP:10443/download/supportlog?site=Site2&machine=SG01'
Download all logs for a specific timeframe:
'https://PublicNetworkIP:10443/download/supportlog?startDate='Wed, 18 Oct 2017 15:14:02 GMT'&endDate='Wed, 18 Oct 2017 15:20:01 GMT''
Download all logs for a specific component on a specific machine at a specific site:
curl -k -X GET -H "X-Auth-Token:$TOKEN" \
'https://PublicNetworkIP:10443/download/supportlog?site=Site2&machine=SG01&component=Marvin'
12.0 Security Operations
12.1 GET /api/security/encryption
Description
Get the system’s encryption status and mode.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/security/encryption'
Sample response
{
"success": true,
"payload": {
"data": {
"license": null,
"mode": "ENCRYPT_NOTHING"
}
}
}
12.2 PUT /api/security/encryption/mode
Description
Change the system’s mode.
Parameters
|
|
Encription mode. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/security/encryption/mode' \
-d '{"mode": ENCRYPT_EVERYTHING}'
12.3 GET /api/security/ldap-groups
Description
Get the system’s current AD/LDAP group configuration.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/security/ldap-groups'
Sample response
{
"message": "AD groups collection is empty",
"payload": [
],
"success": true
}
12.4 PUT /api/security/ldap-groups
Description
Create an AD/LDAP group.
Parameters
|
|
AD/LDAP group name. |
|
|
Domain name. |
Sample request
'https://PublicNetworkIP:10443/api/security/ldap-groups' \
-d ' {"domainName": "ldapden8.lab", "groupName": "QA"}'
Sample response
{
"message": "Successfully created an AD group",
"payload": {
"domainName": "ldapden8.lab",
"groupName": "QA",
"creationTime": 1535658505043
},
"success": true,
"xAuthToken":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWRtaW4iLCJyb2xlcyI6WyJhZG1pbiJdLCJpYXQiOjE1Mz
U2NTg0ODUsImV4cCI6MTUzNTY1ODg0NX0.H1JbRlAwM7nrJlOkdFkvf112p_gMp1vrga4EePCwtqQ"
}
12.5 GET /api/security/ldap-servers
Description
Get the system’s current AD/LDAP server configuration.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/security/ldap-servers'
Sample response
{
"message": "AD servers collection is empty",
"payload": [
],
"success": true
}
12.6 PUT /api/security/ldap-servers
Description
Create an AD/LDAP server configuration.
Parameters
|
|
Domain name. |
|
|
URL of the AD/LDAP server |
Sample request
'https://PublicNetworkIP:10443/api/security/ldap-servers' \
-d '{"domainName": "ldapden8.lab", "serverUrl": "ldapden8.dcs.hgst.com"} '
Sample response
{
"secure": false,
"domainName": "ldapden8.lab",
"serverUrl": "ldapden8.dcs.hgst.com",
"creationTime": 1535574065694
}
12.7 GET /api/security/ldap-servers/validate
Description
Validate the system’s current AD/LDAP server configuration.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/security/ldap-servers/validate'
Sample response
{
"message": "Unknown domain name",
"success": false
}
12.8 GET /api/security/ms
Description
Get the current MS list.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/security/ms'
Sample response
{
"success": true,
"data": [
"6df1c04b96b7ae3c0fbc354fd53ce576fea1772ba078fc37efdcd06bb2daeff5"
],
"message": "Successfully fetched MS list"
}
12.9 POST /api/security/ssl/s3certificate
Description
Upload a new SSL certificate for the S3 interface.
Parameters
|
|
PEM file contents, enclosed in double quotes. Note: Each line ending in the PEM file must be be in |
Sample request
'https://PublicNetworkIP:10443/api/security/ssl/s3certificate' \
-d '{"signedPem": "long_JSON_string"}'
12.10 POST /api/security/ssl/samuraicertificate
Description
Upload a new SSL certificate for the ActiveScale SM interface.
Parameters
|
|
PEM file contents, enclosed in double quotes. Note: Each line ending in the PEM file must be in |
Sample request
'https://PublicNetworkIP:10443/api/security/ssl/samuraicertificate' \
-d '{"signedPem": "long_JSON_string"}'
12.11 GET /api/security/token/validate
Description
Validate the management API security token currently in use.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/security/token/validate'
Sample response
{
"message": "Successfully validated access token",
"payload": {
"token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWRtaW4iLCJyb2xlcyI6WyJhZG1pbiJdLCJpYXQiOjE1Mz
czMTUxNjYsImV4cCI6MTUzNzMxNTY3NH0.Y8jGiUkJnA6LCRvgRaQs0sRVTrH05H7cLh8eTdPEnRo",
"secret": "f76fe692-27f4-4e51-92dd-314fed02a2c5",
"username": "admin",
"secToExpire": 360
},
"success": true
}
12.12 GET /api/security/token/sessiontimeout
Description
Get the management API security token’s timeout value.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/security/token/sessiontimeout'
Sample response
{
"sessionTimeoutMinutes": 60,
"message": "Successfully retrieved user data"
}
12.13 POST /api/security/token/sessiontimeout
Description
Change the management API security token’s timeout value.
Parameters
|
sessionTimeoutMinutes |
Timeout, in minutes. Valid values: |
Sample request
'https://PublicNetworkIP:10443/api/security/token/sessiontimeout' \
-d '{"sessionTimeoutMinutes": "30"}'
Sample response
{
"updateSessionTimeout": {
"message": "Successfully updated User data",
"success": true
},
"updateTo kenExpiry": {
"message": "Successfully validated access token",
"payload": {
"token": "longstring",
"secret": "anotherlongstring",
"username": "admin",
"secToExpire": 1800
},
"success": true
}
}
13.0 Streaming Operations
13.1 GET /api/logstream/settings
Description
Get log stream connection details.
Parameters
|
|
Site name. For example, |
|
|
parameters { |
|
|
|
|
|
The fully qualified domain name (FQDN) or IP address of the remote server. It is also possible to specify an IPv6 address in case the public interfaces are configured to have an IPv6 address. |
|
|
transport_mechanism |
The communication protocol for the event stream. Valid values are |
|
|
port |
The port number on which to receive the event stream on your remote server. This value must be between 0 and 65535, inclusive. |
|
|
logtypes |
Comma separated list of components to stream. Valid values are |
|
|
ssl_root_certificate |
Remote server CA certificate. Required only if you select TCP with TLS. Upload a security certificate in PEM format. (
Customer remote server certificates are used to update the rsyslog configuration file. |
|
|
ssl_certificate |
Your SSL certificate for the client.
Customer remote server certificates are used to update the rsyslog configuration file. |
|
|
ssl_key |
Your private SSL key for the client. |
Sample request
curl -i -k -X GET -H "X-Auth-Token:$TOKEN" -H "Content-Type: application/json"
'https://PublicNetworkIP:10443/api/logstream/settings' \
-d '{
"locationName": "Site1",
"parameters": {
"server": "ost-9.mydomain.net",
"transport_mechanism": "UDP",
"port": 5530,
"logtypes":["events"],
"ssl_root_certificate": null,
"ssl_certificate": null,
"ssl_key": null
}
}'
Sample response
Response Body:
HTTP/1.1 200 OK
Server: nginx/1.10.1
Date: Sat, 06 Jan 2018 07:08:11 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 536
Connection: keep-alive
token:
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwiaWF0IjoxNTE1MjIyNDA1LCJleHAiOjE
1MTUyMjI4NTF9.sYtv5UcLlKhijbXHJnbHl_FfP9-lv-WGN12pI880rYY
ETag: W/"218-df74e9c5"
Vary: Accept-Encoding
{"message":"Successfully loaded list of remote log
servers","payload":{"logServers":[{"streamLogConnection":{"_lock":null,"connectiontype":"StreamL
og","date_created":1514448886464000,"date_modified":1515129647336000,"guid":"385ddb97-ef85-4b0b8882-
61c18ae3ec60","login":null,"logtypes":["events"],"name":null,"password":null,"port":1163,"server
":"localhost","ssl_certificate":null,"ssl_key":null,"ssl_root_certificate":null,"stream_status":
"disable","transport_mechanism":"UDP"},"locationType":"DATACENTER","locationName":"Site1"},{}]}}
13.2 PUT /api/logstream/settings
Description
Enable or disable rsyslog streaming.
Supported log types:
-
Events
-
Operating system logs
-
S3 connection statistics
-
S3 operation statistics
-
S3 access logs
-
System metrics
On your remote server, you need an analytics tool that supports the RFC 5424 format to be compatible with the rsyslog stream.
Parameters
|
|
Site name. For example, |
|
|
parameters { |
|
|
|
|
server |
The fully qualified domain name (FQDN) or IP address of the remote server. It is also possible to specify an IPv6 address in case the public interfaces are configured to have an IPv6 address. |
|
|
transport_mechanism |
The communication protocol for the event stream. Valid values are |
|
|
port |
The port number on which to receive the event stream on your remote server. This value must be between 1024 and 65535, inclusive. |
|
|
|
Comma separated list of components to stream. Valid values are |
|
|
stream_status |
Enables or disables the stream. Valid values: enable, disable. |
|
|
ssl_root_certificate |
Remote server CA certificate. Required only if you select TCP with TLS. Upload a security certificate in PEM format. (
Customer remote server certificates are used to update the rsyslog configuration file. |
|
|
ssl_certificate |
Your SSL certificate for the client.
Customer remote server certificates are used to update the rsyslog configuration file. |
|
|
ssl_key |
Your private SSL key for the client. |
Sample request
curl -i -k -X PUT -H "X-Auth-Token:$TOKEN" -H "Content-Type: application/json" 'https://
PublicNetworkIP:10443/api/logstream/settings' \
-d '{
"locationName": "Site1",
"parameters": {
"server": "ost-9.mydomain.net",
"transport_mechanism": "UDP",
"port": 5530,
"logtypes":["oslogs"],
"stream_status": "enable",
"ssl_root_certificate": null,
"ssl_certificate": null,
"ssl_key": null
}
}'
Sample response
Sample response upon successful enabling of syslog streaming:
{"message":"Successfully loaded list of remote event log servers",
"payload":
{"eventLogServers":
[{"streamLogConnection":
{"_lock":null,
"connectiontype":"StreamLog",
"date_created":1514891295094000,
"date_modified":1514893233228000,
"guid":"a14055b8-4a9d-4d8f-bdc3-232e9a15737c",
"login":null,
"name":null,
"password":null,
"port":5530,
"logtypes":["oslogs"],
"server":"ost-9",
"ssl_certificate":null,
"ssl_key":null,
"ssl_root_certificate":null,
"stream_status":"enable",
"transport_mechanism":"UDP"},
"locationType":"DATACENTER",
"locationName":"Site1"},
{}
]
}
}
14.0 Replication Operations
14.1 GET /api/replication/systeminfo
Description
Get the device ID for a specific System Node. This device ID is a mandatory parameter for all replication API and is returned in the response body as part of the payload field.
Parameters
None.
Sample request
'https://PublicNetworkIP:10443/api/replication/systeminfo'
Sample response
deviceId is returned as part of the payload field:
{
"status": 200,
"message": "Successfully retrieved Scaler system information",
"payload": {
"deviceId": "72d86367-a9af-4995-b7f1-531798c3cb70",
"softwareVersion": "scalermgmt 5.2.0.1 build 86 / 3e5addb4faf64c44bffa7eedb7cdc29ed6baba4a /
Wed, 23 Aug 2017 20:44:38 +0000",
"numBytesTotal": {
"buffer": {
"type": "Buffer",
"data": [0,0,0,0,0,0,0,0]
},
"offset": 0
},
"numBytesFree": {
"buffer": {
"type": "Buffer",
"data": [0,0,0,0,0,0,0,0]
},
"offset": 0
},
"numObjectsTotal": {
"buffer": {
"type": "Buffer",
"data": [0,0,0,0,0,0,0,0]
},
"offset": 0
},
"numObjectsFree": {
"buffer": {
"type": "Buffer",
"data": [0,0,0,0,0,0,0,0]
},
"offset": 0
},
"meteringBucket": "metering-72d86367-a9af-4995-b7f1-531798c3cb70",
"success": true
},
"token": "your_session_token"
}
14.2 GET /api/replication/configuration
Description
Get the current configuration of the ActiveScale OS replication pipeline for a given device ID.
Parameters
|
|
Device ID as returned by 14.1 GET /api/replication/systeminfo. |
Sample request
curl -k -X GET -H "X-Auth-Token:$TOKEN" \
'https://PublicNetworkIP:10443/api/replication/configuration?deviceId=deviceID'
Sample response
If a replication pipeline has been configured, the response is similar to the sample below.
{
"status": 200,
"message": "Successfully retrieved replication configuration",
"payload": {
"id": 0,
"sequenceId": 0,
"sourceAccessInfo": {
"email": "sourceacct@myemaildomain.com",
"accessKey": "MjZykG8wSAm2sLcMovwn",
"secretKey": "secret_key"
},
"destinationSystemName": "Honolulu_Hawaii",
"destinationAccessInfo": {
"email": "destinationacct@myemaildomain.com",
"accessKey": "Si4DnUcZ1KkDGJGZhdrH",
"secretKey": ""
},
"destinationS3IpPorts": [
"192.168.110.202:443",
"192.168.110.203:443"
],
"shouldCheckDestinationSSLCert": true,
"destinationSSLCertSHA1Fingerprint": "ED D7 FA 2D 2E D2 BB D@ D2 9b 1F 8D 14",
"status": 2,
"queueObjectCountThreshold": 100000,
"queueMaxSizeThreshold": 100000,
"success": true
},
"token": "your_session_token"
}
If a replication pipeline has not been configured for this device, the operation returns an HTTP 500 error and the response:
14.3 POST /api/replication/configuration
Description
Create a replication pipeline if no replication pipeline exists on the system. To update the replication pipe line refer to A. 14.4 PUT /api/replication/configuration.
Run this command on the source system only.
When replication is enabled, ActiveScale OS continuously forwards the contents of the source bucket(s) to the destination bucket(s) through designated accounts (replication accounts) on the source and destination systems. The destination system can be another ActiveScale system or Amazon Web Services (AWS). Replication can be unidirectional or bidirectional.
The source and destination buckets must be in separate namespaces, with each namespace at a different site.
Note: ActiveScale OS does not replicate content that exists in a bucket prior to enabling replication.
Caution: The system may not preserve version ordering; an object on the destination system has the same version and timestamp information as that object on the source system. Also, the system might send more than one copy of the same version of an object to the destination system.
Replication Pipeline Worksheet
Click here to open the Replication Pipeline Worksheet. This worksheet enumerates settings you need to determine prior to changing/configuring a replication pipeline. Some settings are applicable only to a particular destination type.
Parameters
Most parameters are described above in ActiveScale Management API. In addition, you need to specify deviceId and sequenceId parameters:
|
deviceId |
Device ID as returned by 14.1 GET /api/replication/systeminfo. |
|
sequenceId |
Since this is your initial configuration, set this to 0. |
Sample request
curl -k -X POST -H "X-Auth-Token:$TOKEN" -H "Content-Type:application/json"\
'https://PublicNetworkIP:10443/api/replication/configuration ' \
-d '{
"deviceId": "264f104e-dab2-4c54-92c6-c93199c34c90",
"sequenceId": 0,
"sourceAccessInfo": {
"email": "sourceacct@myemaildomain.com",
"accessKey": "MjZykG8wSAm2sLcMovwn",
"secretKey": "secret_key"
},
"destinationSystemName": "Honolulu_Hawaii",
"destinationAccessInfo": {
"email": "destinationacct@myemaildomain.com",
"accessKey": "Si4DnUcZ1KkDGJGZhdrH",
"secretKey": "secret_key"
},
"destinationS3IpPorts": [
"192.168.110.202:443",
"192.168.110.203:443"
],
"shouldCheckDestinationSSLCert": true,
"destinationSSLCertSHA1Fingerprint": "ED D7 FA 2D 2E D2 BB D@ D2 9b 1F 8D 14",
"status": 2,
"queueObjectCountThreshold": 100000,
"queueMaxSizeThreshold": 100000
}'
Sample response
If the operation succeeds, the response is similar to the sample below.
{
"status": 200,
"message": "Successfully created replication configuration",
"payload": {
"message": "Successfully created or updated replication policy.",
"success": true
},
"token": "your_session_token"
}
If the operation fails, the response is similar to the sample below.
{
"status": 500,
"message": "Error in creating replication configuration:
Scaler_ConcurrentModificationException: Scaler_ConcurrentModificationException",
"token": "your_session_token"
}
14.4 PUT /api/replication/configuration
Description
Update your replication pipeline settings when a replication pipeline is already configured. For more information on how to create a replication pipeline see 14.3 POST /api/replication/configuration.
Parameters
Most parameters are described above in ActiveScale Management API. In addition, you need to specify deviceId and sequenceId parameters:
|
deviceId |
Device ID as returned by 14.1 GET /api/replication/systeminfo. |
|
sequenceId |
Pipeline version number. Set this to the value returned in the sequenceId field of 14.2 GET /api/replication/configuration. |
Sample request
curl -k -X PUT -H "X-Auth-Token:$TOKEN" -H "Content-Type:application/json"\
'https://PublicNetworkIP:10443/api/replication/configuration' \
-d '{
"deviceId": "264f104e-dab2-4c54-92c6-c93199c34c90",
"sequenceId": 5,
"sourceAccessInfo": {
"email": "sourceacct@myemaildomain.com",
"accessKey": "MjZykG8wSAm2sLcMovwn",
"secretKey": "secret_key"
},
"destinationSystemName": "Wailea_Hawaii",
"destinationAccessInfo": {
"email": "destinationacct@myemaildomain.com",
"accessKey": "Si4DnUcZ1KkDGJGZhdrH",
"secretKey": "secret_key"
},
"destinationS3IpPorts": [
"1.1.1.1:443",
"2.2.2.2:443"
],
"shouldCheckDestinationSSLCert": true,
"destinationSSLCertSHA1Fingerprint": "ED D7 FA 2D 2E D2 BB D@ D2 9b 1F 8D 14",
"status": 2,
"queueObjectCountThreshold": 100000,
"queueMaxSizeThreshold": 100000
}'
Sample response
If the operation succeeds, the response is similar to the sample below.
{
"status": 200,
"message": "Successfully updated replication configuration",
"payload": {
"message": "Successfully created or updated replication policy.",
"success": true
},
"token": "your_session_token"
}
If the operation fails, the response is similar to the sample below.
{
"status": 500,
"message": "Error in updating replication configuration:
Scaler_ConcurrentModificationException: Scaler_ConcurrentModificationException",
"token": "your_session_token"
}
14.5 GET/api/replication/statistics/series/replicator_object_replicated_throughput
Description
Get a time series of the number of bytes per second that have been replicated
Parameters
|
start |
(optional) start timestamp (in seconds since the epoch) (default : timestamp corresponding to 24 hours ago) |
|
end |
(optional) end timestamp (in seconds since the epoch) (default : current timestamp) |
|
step |
(optional) the period between samples in the time series (eg. 30s, 1m, 2h, 7d) (default : 30m) |
|
scope |
(optional) the aggregation scope (default : overall) - possible values :
|
Sample request
(default) get the overall replicated object throughput for the last 24 hours :
get the replicated object throughput for the given time range per rack
14.6 GET /api/replication/statistics/series/replicator_object_replicated_rate
Description
Get a time series of the number of objects per second that have been replicated.
Parameters
|
start |
(optional) start timestamp (in seconds since the epoch) (default : timestamp corresponding to 24 hours ago) |
|
end |
(optional) end timestamp (in seconds since the epoch) (default : current timestamp) |
|
step |
(optional) the period between samples in the time series (eg. 30s, 1m, 2h, 7d) (default : 30m) |
|
scope |
(optional) the aggregation scope (default : overall) - possible values :
|
Sample request
(default) get the overall replicated object rate for the last 24 hours:
get the replicated object rate for the given time range per rack:
15.0 Unified Data Access Commands
15.1 POST /bapi/v1/file/volumes/{name}
Description
Creates a new volume.
Parameters
|
name |
Name of the volume to be created. Must comply with S3 bucket name restrictions. |
|
|
(Optional) Email address of the account to own this volume. |
|
canonicalId |
(Optional) Canonical ID of the account to own this volume canonical-id (base64 encoded). |
|
encryptionSettings |
(Optional) Encryption setting for this volume. |
Note: Exactly one of email or canonical ID must be set.
Note: encryptionSettings can only be used when the current encryption mode is client selection.
Sample request
Create a volume named ‘myvolume’ with encryption enabled.
15.2 PUT /bapi/v1/file/volumes/{name}
Description
Updates an existing volume.
Parameters
|
name |
Name of an existing volume. |
|
|
(Optional) Email address of the new owner of this volume. |
|
canonicalId |
(Optional) Canonical ID of the new owner of this volume (base64 encoded). |
|
encryptionSettings |
(Optional) New encryption setting for this volume. |
Note: email or canonical ID cannot be both set.
Note: encryptionSettings can only be used when the current encryption mode is client selection.
Sample request
Change the owner and disable encryption for the volume 'myvolume'.
15.3 GET /bapi/v1/file/volumes
Description
Lists volumes alphabetically.
Parameters
|
marker |
(Optional) Where to start listing from. |
|
includeMarker |
(Optional, default False) Whether or not to include to marker in the result. |
|
maxResults |
(Optional, default 100) The maximum number of results. |
|
|
(Optional) Restrict to volumes owned by the owner with this email address. |
Sample request
List at most 50 volumes owned by 'myemail@company.com'
Sample response
{
"volumes": [{
"name": "vol1",
"canonicalId": "gF2kiQsvg/AOunCZCA==",
"creationTime": "1571064080430",
"email": "myemail@company.com"
}, {
"name": "vol2",
"canonicalId": "gF2kiQsvg/AOunCZCA==",
"creationTime": "1571064087590",
"email": "myemail@company.com"
}, {
"name": "vol3",
"canonicalId": "gF2kiQsvg/AOunCZCA==",
"creationTime": "1571064089033",
"email": "myemail@company.com"
}]
"nextMarker": ""
}
Note: Times are returned in milliseconds since epoch.
15.4 GET /bapi/v1/file/volumes/{name}
Description
Show information of a volume with given name.
Parameters
|
name |
Name of the volume. |
Sample request
Show the volume with name 'vol2'
Sample response
{
"volume": {
"name": "vol2",
"canonicalId": "gF2kiQsvg/AOunCZCA==",
"creationTime": "1571064087590",
"modificationTime": "1571064126814",
"encryptionEnabled": false,
"email": "myemail@company.com"
}
}
15.5 DELETE /bapi/v1/file/volumes/{name}
Description
Delete the volume with the given name.
Parameters
|
name |
Name of the volume to delete. |
|
wipe |
(Optional, default false) When this flag is set, permanently wipe all data within the volume |
Note: Deleting a nonempty volume without wipe set to true will result in an error.
Sample request
Delete the volume 'myvolume' and its contents.
15.6 GET /bapi/v1/file/volumes:count
Description
Return the number of volumes.
Sample request
Sample response
{
"count": "2"
}
15.7 POST /bapi/v1/file/exports/
Description
Creates a new export.
Parameters
|
volume |
The volume to create the export in. |
|
path |
The path to export. |
|
exportAttrs |
(Optional) Key-value list of export attributes. |
|
pathAttrs |
(Optional) Set gid, uid, and permissions of the exported path. |
|
createPath |
(Optional, default false) Create the path if it does yet exist. |
Note: PathAttrs is required when createPath is set to true.
Note: The mount point is the path obtained by combining volume and path.
On how to set the exportAttrs and pathAttrs we refer to the examples. The available export attributes are:
|
access_type |
none (default), RW, RO, MDONLY, MDONLY_RO |
|
squash |
no_root_squash, root_id_squash, root_squash (default), all_squash |
|
anonymous-uid |
default 65534 |
|
anonymous-gid |
default 65534 |
|
clients |
restrict access list of clients, specified by hostname, ip address, netgroup, ... |
|
sec |
sys (default), krb5, krb5i, krb5p |
|
manage_gids |
false (default), true |
|
tag |
alternative access for mounting, should not have a leading slash |
Note: Creating an export with the same tag as an existing export is not allowed, nor having two exports with the same mountpoints without a tag specified
Sample requests
Export the root of the volume 'myvolume'.
Export a to be created directory 'dir' in the volume 'myvolume', with tag 'myexport'.
Sample response
The export id of the new export returned.
{
"id": "1"
}
15.8 PUT /bapi/v1/file/exports/{id}
Description
Updates an existing export.
Parameters
|
id |
The id of the export to be updated . |
|
exportAttrs |
(Optional) Key-value list of export attributes to update. An empty value can be used to remove the existing setting. |
|
pathAttrs |
(Optional) Set gid, uid, and permissions of the exported path. |
Note: For details on exportAttrs and pathAttrs see the previous section on export creation.
Sample request
Set the tag for the export with id 1 to 'mytag'.
15.9 GET /bapi/v1/file/exports
Description
Lists exports alphabetically on export id.
Parameters
|
marker |
(Optional) Where to start listing from. |
|
includeMarker |
(Optional, default False) Whether or not to include to marker in the result. |
|
maxResults |
(Optional) Limit the output to this many results. |
|
volume |
(Optional) Restrict to exports in this volume. |
Sample request
List at most 5 exports.
Sample response
{
"list": [{
"path": "/",
"id": "1",
"exportAttrs": {
"map": [{
"key": "tag",
"value": "mytag"
}, {
"key": "access_type",
"value": "RW"
}]
},
"volume": "myvolume"
}, {
"path": "/dir",
"id": "2",
"exportAttrs": {
"map": [{
"key": "tag",
"value": "myexport"
}, {
"key": "access_type",
"value": "RW"
}]
},
"volume": "myvolume"
}],
"nextMarker": ""
}
15.10 GET /bapi/v1/file/exports/{id}
Description
Show the volume with the given id.
Parameters
|
id |
Export id. |
Sample request
Show the export with id 2.
Sample response
{
"info": {
"path": "/dir",
"id": "2",
"exportAttrs": {
"map": [{
"key": "tag",
"value": "myexport"
}, {
"key": "access_type",
"value": "RW"
}]
},
"volume": "myvolume"
}
}
15.11 DELETE /bapi/v1/file/exports/{id}
Description
Delete the export with the given id.
Parameters
|
id |
Id of the export to be deleted. |
Note: Deleting an export does not remove any files or their contents from the volume.
Sample request
Delete the export with id 2.
15.13 GET /bapi/v1/file/pathinfo/{volume}/{path}
Description
Show information (UID, GID and permissions settings) of a path with the given name belonging to the specified volume.
Parameters
|
volume |
Name of the volume to which the path belongs. |
|
path |
Name of the path to show information. |
Sample request
Show information of the path /my/example of the volume volume0.
Note: "/" characters in the path must be escaped as "%2F" in the URL
Sample response
{
"pathAttrs": {
"uid": "1000",
"gid": "1000",
"permissions": "775"
}
}
15.14 DELETE /bapi/v1/file/pathinfo/{volume}/{path}
Description
Permanently deletes all data in a directory specified by the path within a volume.
Parameters
|
volume |
The name of the volume to which the path belongs. |
|
path |
The name of the path to be deleted. |
Sample request
Remove the path /my/example of the volume volume0 and all of its content.
Note: "/" characters in the path must be escaped as "%2F" in the URL.
16.0 S3 Activity-Distribution API Examples
This section presents the S3 activity-distribution APT GET and PUT examples.
16.1 GET /bapi/v1/s3/requests/limits
Description
Get the current configured activity distribution.
Parameters
None.
Sample request
Sample response
The response is a json object with the current activity distribution as percentages
{
"publicRequestsLimitPercentage": 33.4,
"replicationInLimitPercentage": 33.3,
"replicationOutLimitPercentage": 33.3
}
16.2 PUT /bapi/v1/s3/requests/limits
Description
Configure the S3 activity distribution. The S3 activity distribution API takes a JSON payload with the desired percentage of the replication in and replication out traffic. The percentage for the S3 public traffic will be the remaining connection budget. For example setting replication in to 10% and replication out to 30%, will result in a S3 public traffic percentage of 60%. The replication in or replication out parameter can be omitted, the server will in that case use the current configured value. Note that this call might take some time to complete.
Parameters
|
replicationOutLimitPercentage |
(Optional) The percentage allocated to replication out traffic. If this parameter is not set, its current value will be used. The percentage allocated to public S3 traffic will be calculated by the server. |
|
replicationInLimitPercentage |
(Optional) The percentage allocated to replication in traffic. If this parameter is not set, its current value will be used. The percentage allocated to public S3 traffic will be calculated by the server. |
Sample request
Sample response
The response is a json object with the new activity distribution as percentages
{
"publicRequestsLimitPercentage": 59.97001499250375,
"replicationInLimitPercentage": 10.044977511244378,
"replicationOutLimitPercentage": 29.985007496251875
}
16.3 S3 activity-distribution Use Cases
1500 client requests per system node:
-
Customers who need increased connection counts to ActiveScale can now make use of 1500 requests per system node while still operating at the optimal throughput.
Ability to change S3 activity-distribution:
-
Throttle down outgoing replication requests temporarily to favor urgent S3 client requests
-
Favor incoming and outgoing replication requests to reduce the amount of objects pending replication by throttling down S3 client requests
