1. Oracle ZFS Storage Appliance RESTful API Guide, Release OS8.8.x
  2. System Commands

15 System Commands

System commands are used to obtain Oracle ZFS Storage Appliance system identity information, and to perform top-level system management commands. The following table lists the available system commands.

Appliance System Commands

The following system commands are available.

Table 15-1 Oracle ZFS Storage Appliance System Commands

Request Append to Path /api/system/v{1|2} Description

GET

/version

List the Oracle ZFS Storage Appliance hardware and software version information

PUT

/reboot

Reboot Oracle ZFS Storage Appliance; any queued platform updates will be applied during this reboot

PUT

/reboot?skip_update=true

Reboot Oracle ZFS Storage Appliance without applying any queued platform updates

PUT

/reboot?diag=true

Diagnostic reboot: Reboot Oracle ZFS Storage Appliance, gathering additional diagnostic information in the process

PUT

/poweroff

Turn off Oracle ZFS Storage Appliance

PUT

/restart

Restart the management interface and gather diagnostic information

PUT

/factoryreset

Reset the Oracle ZFS Storage Appliance configuration back to factory settings

GET

/disks

List all system disks

GET

/disks/disk

List the specified system disk properties

GET

/memory

System memory status report

Get Version

This command returns a system structure that contains system identity information. HTTP status 200 (OK) is returned for a successful command.

Example Request:

GET /api/system/v1/version HTTP/1.1
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "version": {
        "hw_csn": "1211FM2009",
        "updated": "20130528T16:21:17",
        "fw_vendor": "American Megatrends Inc.",
        "os_isa": "i386",
        "os_boot": "20130528T16:25:44",
        "hw_product": "Sun Netra X4270 M3",
        "http_version": "Apache/2.2.24 (Unix)",
        "hw_asn": "2f4aeeb3-b670-ee53-e0a7-d8e0ae410749",
        "ssl_version": "OpenSSL 1.0.0k 5 Feb 2013",
        "os_machine": "i86pc",
        "os_nodename": "admin1",
        "os_version": "nas/generic@2013.05.16,1-0",
        "ak_product": "SUNW,iwashiG2",
        "fw_version": "21000208",
        "os_release": "5.11",
        "installed": "20130411T19:50:16",
        "sp_version": "3.1.2.0",
        "os_platform": "i86pc",
        "fw_release": "10/22/2012"
    }
}

Power Off System

This command performs a clean shutdown of Oracle ZFS Storage Appliance. All data services become permanently unavailable unless the appliance is part of a cluster. To power the system back on requires either service processor access or physical access to the power switch. This command runs asynchronously and returns an HTTP status of 202 (Accepted). The appliance must be monitored to follow the status of the actual command.

Example Request:

PUT /api/system/v1/poweroff HTTP/1.1
Host: zfs-storage.example.com:215

Reboot System

This command performs a clean power cycle of Oracle ZFS Storage Appliance. All services are temporarily unavailable. This command runs asynchronously and returns HTTP status 202 (Accepted). The appliance must be monitored to follow the status of the actual command.

Note:

If a pending platform update is available to the appliance, it will be applied during this reboot. To perform a reboot without applying the pending platform update, use the /reboot?skip_update=true command instead.

Example Request:

PUT /api/system/v1/reboot HTTP/1.1
Host: zfs-storage.example.com:215

Example Request:

PUT /api/system/v1/reboot?skip_update=true HTTP/1.1
Host: zfs-storage.example.com:215

Restart System Management

This command restarts the management interface and gathers diagnostic information. This command runs asynchronously and returns HTTP status 202 (Accepted). The Oracle ZFS Storage Appliance system must be monitored to follow the status of the actual command.

Example Request:

PUT /api/system/v1/restart HTTP/1.1
Host: zfs-storage.example.com:215

Diagnostic Reboot

This command reboots Oracle ZFS Storage Appliance, gathering additional diagnostic information in the process. This command runs asynchronously and returns HTTP status 202 (Accepted). The appliance must be monitored to follow the status of the actual command.

Note:

If there is a pending platform update available to the appliance, it will be not applied during this diagnostic reboot.

Example Request:

PUT /api/system/v1/reboot?diag=true HTTP/1.1 
Host: zfs-storage.example.com :215

Factory Reset

This command restores the Oracle ZFS Storage Appliance configuration to the original factory settings. All configuration changes are lost, and the appliance must be taken through initial setup as when first installed. This command runs asynchronously and returns HTTP status 202 (Accepted). The appliance must be monitored to follow the status of the actual command. Because this command can result in a loss of all configuration data, the query parameter ?confirm=true must be added for the command to succeed.

Example Request:

PUT /api/system/v1/factoryreset?confirm=true HTTP/1.1 
Host: zfs-storage.example.com:215

System Support Bundles

The following support bundle commands are available.

Table 15-2 Support Bundle Commands

Request Append to Path /api/system/v{1|2} Description

GET

/bundles

List all support bundles

GET

/bundles/bundle

Get the specified bundle data or properties

POST

/bundles

Build a support bundle and upload it to Oracle Support

PUT

/bundles/bundle/retry

Retry upload of the specified bundle

PUT

/bundles/bundle/cancel

Cancel upload of the specified bundle

PUT

/bundles/bundle/send

Upload the specified bundle to Oracle Support with an optional Service Request (SR) number

DELETE

/bundles/bundle

Destroy the specified bundle

Create Support Bundle

Creates a new support bundle to help resolve a service request. A Service Request (SR) number must be supplied to associate the support bundle with the open service request and send it to Oracle Support. The SR number must be in 3-nnnnnnnnnn format. For the support bundle to be automatically uploaded to Oracle Support, the Phone Home settings must be registered with valid My Oracle Support (MOS) credentials that have upload permissions.

Example Request:

POST /api/system/v1/bundles HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json
Content-Type: application/json
Content-Length: 23

{"srn": "3-0123456789"}

Example Result:

HTTP/1.1 201 Created
X-Zfssa-Appliance-Api: 1.0

If a Service Request Number (SRN) is not provided, the system will build a local bundle instead.

Example Request:

POST /api/system/v1/bundles HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json
Content-Type: application/json
Content-Length: 23

Example Result:

{
  "bundle": {
    "status": "",
    "uuid": "d4431d57-ba4f-4f37-fa1e-a09fcbf3e56b",
    "associated_bundle": [
      {
        "href": "/api/system/v1/bundles/4050963a-4082-663f-99c0-fee915f2839c"
      }
    ],
    "srn": null,
    "filename": "ak.d4431d57-ba4f-4f37-fa1e-a09fcbf3e56b.tar.gz",
    "href": "/api/system/v1/bundles/d4431d57-ba4f-4f37-fa1e-a09fcbf3e56b",
    "date": "Thu Mar 10 2016 19:38:58 GMT+0000 (UTC)",
    "type": "User initiated"
  }
}

List Support Bundles

This command lists all support bundles being processed or collected by the Oracle ZFS Storage Appliance system. After a support bundle is uploaded to Oracle Support, the support bundle is removed from the system.

Example Request:

GET /api/system/v1/bundles HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: */*

Example Result:

{
    "bundles": [{
        "status": "building",
        "step_progress": 6.25,
        "srn": "3-0123456789",
        "filename": "/upload/issue/3-0123456789/3-0123456789_ak.ba8ebd55-2349-c31c-cde3-acf3fb0c3389.tar.gz",
        "href": "/api/system/v1/bundles/ba8ebd55-2349-c31c-cde3-acf3fb0c3389",
        "date": "Wed Apr 30 2014 19:31:06 GMT+0000 (UTC)",
        "type": "User initiated",
        "uuid": "ba8ebd55-2349-c31c-cde3-acf3fb0c3389"
    }],
}

Get Support Bundle

Gets properties from a single bundle.

Example Request:

GET /api/system/v1/bundles/9604155c-928b-cf97-c826-cda9fc17ac57 HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: */*

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 165

{
    "bundle": {
        "status": "building",
        "step_progress": 62.5,
        "srn": "3-0123456789",
        "filename": "/upload/issue/3-0123456789/3-0123456789_ak.ba8ebd55-2349-c31c-cde3-acf3fb0c3389.tar.gz",
        "href": "/api/system/v1/bundles/ba8ebd55-2349-c31c-cde3-acf3fb0c3389",
        "date": "Wed Apr 30 2014 19:31:06 GMT+0000 (UTC)",
        "type": "User initiated",
        "uuid": "ba8ebd55-2349-c31c-cde3-acf3fb0c3389"
    }
}

Cancel Support Bundle

This command cancels automatic upload of a support bundle.

Example Request:

PUT /api/system/v1/bundles/9aef7c38-073c-603f-f35c-be64e26e90e3/cancel HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215

Example Result:

HTTP/1.1 202 Accepted
X-Zfssa-Appliance-Api: 1.0

Retry Support Bundle Upload

This command creates a new bundle upload job that attempts to upload a bundle to Oracle Support. The get bundle command can be used to monitor the status of the support bundle upload.

Example Request:

PUT /api/system/v1/bundles/9aef7c38-073c-603f-f35c-be64e26e90e3/retry HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215

Example Result:

HTTP/1.1 202 Accepted
X-Zfssa-Appliance-Api: 1.0

To retry a bundle upload using a different Service Request (SR) number, use the send command. If an SR number is not provided, the system will retry the upload using the original SR number.

Note:

An SR number is required when running send on a locally generated bundle, or else an error will be thrown.

Example Request:

PUT /api/system/v1/bundles/9aef7c38-073c-603f-f35c-be64e26e90e3/send HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215

{"srn": "3-0123456789"}

Example Result:

HTTP/1.1 202 Accepted
X-Zfssa-Appliance-Api: 1.0

Upload Support Bundle

A support bundle that is not automatically uploaded to Oracle Support can be uploaded manually.

Note:

A Service Request (SR) number is required when running send on a locally generated bundle, or else an error will be thrown.

Example Request:

PUT /api/system/v1/bundles/9aef7c38-073c-603f-f35c-be64e26e90e3/send HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215

{"srn": "3-0123456789"}

Example Result:

HTTP/1.1 202 Accepted
X-Zfssa-Appliance-Api: 1.0

Delete Support Bundle

This command removes a support bundle from Oracle ZFS Storage Appliance.

Example Request:

DELETE /api/system/v1/bundles/9aef7c38-073c-603f-f35c-be64e26e90e3 HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215

Example Result:

HTTP/1.1 204 No Content
X-Zfssa-Appliance-Api: 1.0

System Updates

These commands manage Oracle ZFS Storage Appliance system update images.

Table 15-3 Update Commands

Request Append to Path /api/system/v{1|2} Description

GET

/updates

List all system updates

GET

/updates/update

Get the specified system update properties

GET

/update/platform

Show the update status of platform firmware (refers to the service processor (SP) and system board firmware on the controller)

GET

/update/firmware

Show the update status of component firmware (refers to disk and SSD firmware, and also Oracle Storage Drive Enclosure IOM firmware)

PUT

/updates/update

Modify update settings

PUT

/updates/update/upgrade

Upgrade to the specified update image

PUT

/updates/update/check

Run upgrade health checks for the specified update image

PUT

/updates/update/rollback

Rollback to the specified update image

PUT

/updates-apply

Apply deferred incompatible updates

DELETE

/updates/update

Destroy the specified system update

POST

/updates

Load an update image onto Oracle ZFS Storage Appliance

Table 15-4 Oracle ZFS Storage Appliance System Update Properties

Property Type Description

version

String

Update media version

release_date

DateTime

Update release date

install_date

DateTime

Update latest installation date; if not installed, date of download to Oracle ZFS Storage Appliance

status

String

Update media status (immutable)

update_deferred

ChooseOne

Deferred setting: onreboot or onrequest

Deferred updates notice:

The following updates enable features that are incompatible with earlier
software versions. As these updates cannot be reverted once committed, and
peer system resources are updated across a cluster, verifying first that the
system upgrade is functioning properly before applying deferred updates is
advised.

List System Updates

Example request to get Oracle ZFS Storage Appliance system updates:

GET /api/system/v1/updates HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Appliance-Api: 1.0
Content-Length: 541
Content-Type: application/json

{
    "updates": [
    {
        "release_date": "Tue Aug 13 2013 17:47:32 GMT+0000 (UTC)",
        "install_date": "Wed Aug 14 2013 12:33:08 GMT+0000 (UTC)"
        "href": "/api/system/v1/updates/nas@2013.08.13,1-0",
        "status": "previous",
        "version": "2013.08.13,1-0"
    },
    {
        "release_date": "Sat Aug 24 2013 17:54:23 GMT+0000 (UTC)",
        "install_date": "Sun Aug 25 2013 11:30:14 GMT+0000 (UTC)"
        "href": "/api/system/v1/updates/nas@2013.08.24,1-0",
        "status": "current",
        "version": "2013.08.24,1-0"
    },
    {
        "release_date": "Sun Aug 25 2013 12:56:57 GMT+0000 (UTC)",
        "install_date": "Mon Aug 26 2013 18:50:33 GMT+0000 (UTC)"
        "href": "/api/system/v1/updates/nas@2013.08.25,1-0",
        "status": "waiting",
        "version": "2013.08.25,1-0"
    }]
}

Get System Update

Gets properties for a single update image.

Example Request:

GET /api/system/v1/updates/nas@2013.08.25,1-0 HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Appliance-Api: 1.0
Content-Length: 541
Content-Type: application/json

{
    "update": {
        "release_date": "Sat Aug 24 2013 17:54:23 GMT+0000 (UTC)",
        "install_date": "Sun Aug 25 2013 11:30:14 GMT+0000 (UTC)"
        "href": "/api/system/v1/updates/nas@2013.08.24,1-0",
        "status": "current",
        "version": "2013.08.24,1-0",
        "update_deferred", "on_request"
    }
}

Get Platform Firmware Update Status

Gets the update status for pending platform firmware updates. Platform firmware is a collective term that refers to the service processor (SP) and system board firmware on the Oracle ZFS Storage Appliance controller.

Example Request:

GET /api/system/v1/update/platform HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Appliance-Api: 1.0
Content-Length: 541
Content-Type: application/json

{
    "platform": {
       "href": "/api/system/v1/update/platform",
       "power_down_needed": true,
       "update_needed": "true"
    }
}

Get Component Firmware Update Status

Gets the number of pending, failed, and in-progress component firmware updates. Component firmware a collective term that refers to disk and SSD firmware, and also Oracle Storage Drive Enclosure disk shelf IOM firmware.

Example Request:

GET /api/system/v1/update/firmware HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Appliance-Api: 1.0
Content-Length: 541
Content-Type: application/json

{
    "firmware": {
        "href": "/api/system/v1/update/firmware",
        "upgrades_pending": 0,
        "upgrades_failed": 0,
        "upgrades_in_progress": 0
    }
}

Upload System Update

This command uploads a new Oracle ZFS Storage Appliance system update image.

Example Upload Command Using curl: 

$ curl --user root:root-password -k --data-binary @nas@2013.08.24,1-0.pkg.gz \
         --header "Content-Type: application/octet-stream" \
         https://zfs-storage.example.com/api/system/v1/updates

After the image is uploaded and is unpacked, the properties of the update image are returned. The HTTP status is set to 201 (Created) on success, and the relative location of the new image is returned in the location header.

Example Result:

HTTP/1.1 201 Created
X-Zfssa-Appliance-Api: 1.0
Content-Length: 541
Content-Type: application/json
Location: /api/system/v1/updates/nas@2013.08.24,1-0

{
    "update": {
        "release_date": "Sat Aug 24 2013 17:54:23 GMT+0000 (UTC)",
        "install_date": "Sun Aug 25 2013 11:30:14 GMT+0000 (UTC)"
        "href": "/api/system/v1/updates/nas@2013.08.24,1-0",
        "status": "current",
        "version": "2013.08.24,1-0",
        "update_deferred", "on_request"
    }
}

Upgrade

This command loads the update image and reboots Oracle ZFS Storage Appliance to the specified update image. The specified image status should be equal to "waiting" or the command fails.

Example Request:

PUT /api/system/v1/updates/nas@2013.08.25,1-0/upgrade?force=true
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Content-Length: 0

Example Result:

HTTP/1.1 202 Accepted
X-Zfssa-Appliance-Api: 1.0

Rollback

Rollback reboots Oracle ZFS Storage Appliance to a previous update image.

Example Request:

PUT /api/system/v1/updates/nas@2013.08.24,1-0/rollback
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Content-Length: 0

Example Result:

HTTP/1.1 202 Accepted
X-Zfssa-Appliance-Api: 1.0

Delete Update Image

Removes an unused update image from Oracle ZFS Storage Appliance.

Example Request:

DELETE /api/system/v1/updates/nas@2013.08.13,1-0 HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=

Example Result:

HTTP/1.1 204 No Content
X-Zfssa-Appliance-Api: 1.0