Spectra Logic

1-800-833-1132 : 1-303-449-6400

Create Storage Domain

Description

Create a storage domain.

Requests

Syntax

POST http[s]://{datapathDNSname}/_rest_/storage_domain​?name={string}[&auto_eject_media_full_threshold={64‑bit integer}]​[&auto_eject_upon_cron={string}]​[&auto_eject_upon_job_cancellation=TRUE|FALSE]​[&auto_eject_upon_job_completion=TRUE|FALSE]​[&auto_eject_upon_media_full=TRUE|FALSE]​[&ltfs_file_naming=OBJECT_NAME|OBJECT_ID]​[&max_tape_fragmentation_percent={32‑bit integer}]​[&maximum_auto_verification_frequency_in_days={32‑bit integer}]​[&media_ejection_allowed=TRUE|FALSE]​[&secure_media_allocation=TRUE|FALSE]​[&verify_prior_to_auto_eject=CRITICAL|URGENT|HIGH|NORMAL|LOW|​BACKGROUND][&write_optimization=CAPACITY|PERFORMANCE]

Request Parameters 

Parameter	Description	Required
name	The name for the storage domain.	yes
auto_eject_media_full_threshold	The minimum available capacity (in bytes) at which media is not considered full and eligible for auto-eject. If not configured, the auto-eject threshold is computed based on the preferred chunk size.	no
auto_eject_upon_ cron	A CRON expression to indicate when to auto eject tape cartridges. If set, a CRON job is created based on the CRON string specified. Once the CRON job is executed, all tape cartridges assigned to the storage domain, not already pending ejection are queued for ejection. Note: This parameter is only valid if media_ejection_allowed=TRUE.	no
auto_eject_upon_ job_cancellation	Determines whether all media assigned to the storage domain, not already pending ejection, is queued for ejection whenever a job is canceled. Note: This parameter is only valid if media_ejection_allowed=TRUE. Values: TRUE, FALSE (default)	no
auto_eject_upon_ job_completion	Determines whether all media assigned to the storage domain, not already pending ejection, is queued for ejection whenever a job completes. Note: This parameter is only valid if media_ejection_allowed=TRUE. Values: TRUE, FALSE (default)	no
auto_eject_upon_media_full	Determines whether all media assigned to the storage domain, not already pending ejection, is queued for ejection whenever the media cannot fit the amount of data specified by auto_eject_media_full_threshold. Note: This parameter is only valid if media_ejection_allowed=TRUE. Values: TRUE, FALSE (default)	no
ltfs_file_naming	Determines the LTFS file naming mode used on tapes in the storage domain. Values: § Object Name — LTFS file names use the format {bucket name}/{object name}, for example bucket1/video1.mov. Object names must comply with LTFS file naming rules. If the tapes are ejected from the BlackPearl system and loaded into a non-BlackPearl tape partition, the file names match the object names. Notes:   § The colon character (:) is not allowed in LTFS file names and therefore not allowed in BlackPearl object names. The slash character (/) is also technically not allowed in LTFS file names; however, the BlackPearl software can accommodate a slash in the object name and translates it as a directory in the LTFS file system (for example, directory1/directory2/video1.mov). § Spectra Logic does not recommend the following characters in LTFS file names or BlackPearl object names for reasons of cross-platform compatibility: control characters such as carriage return (CR) and line feed (LF), double quotation mark (“), asterisk (*), question mark (?), less than sign (<), greater than sign (>), backslash (\), forward slash (/) vertical line (|). § Object ID — LTFS file names use the format {bucket name}/{object id}, for example bucket1/1fc6f09c-dd72-41ea-8043-0491ab8a6d82. Object names do not need to comply with LTFS file naming rules. The BlackPearl system saves object names as LTFS extended attributes allowing any third party application to reconstruct all the data including the object names.	no
max_tape_ fragmentation_ percent	Not currently used.	no
maximum_auto_ verification_ frequency_in_days	The number of days since the last data modification before an unverified piece of media is scheduled for auto verification. Default: null (data will never be verified)	no
media_ejection_ allowed	Whether the storage domain or a piece of media assigned to the storage domain, can be ejected from the BlackPearl system without generating a failure. Values: TRUE (default), FALSE	no
secure_media_ allocation	Whether media must remain within the storage domain. Note: secure_media_allocation should only be set to TRUE when, for compliance purposes, the user must be certain which media ever contained any data for the storage domain (usually, to physically destroy the media once the data is no longer needed), or to force rotating through media when new backups are created and old backups are deleted. Values: § TRUE — Media assigned to the storage domain can only be reclaimed for use within the same storage domain. § FALSE (default) — Media assigned to a storage domain can be reclaimed into the general pool if all data on the media is deleted.	no
verify_prior_to_ auto_eject	The priority for verifying tapes being ejected automatically due to any of the auto-eject triggers. The priority is null if verification is not required prior to ejection. The priority determines the resources assigned and the processing order. Values: CRITICAL, URGENT, HIGH, NORMAL, LOW, BACKGROUND	no
write_optimization	Specifies whether job chunks are written as quickly as possible or across as few pieces of media as possible. For example, when PERFORMANCE mode is set for a tape partition, job chunks are written as quickly as possible, using all tape drive resources, even if that means that more tapes are allocated to the storage domain than are necessary to write the data. It is better to use CAPACITY mode if the tapes will be ejected after the job completes or if the storage domain is written to very rarely and capacity in the library is of concern. PERFORMANCE mode is recommended for tape partitions in all other cases. Storage domains for pool partitions should generally have a CAPACITY write optimization because pools are very fast and under less contention. It is rare for a pool storage domain to benefit from PERFORMANCE mode. Values: CAPACITY (default), PERFORMANCE	no

Responses

Response Elements

<Data>
   <AutoEjectMediaFullThreshold>
      {64‑bit integer}
   </AutoEjectMediaFullThreshold>
   <AutoEjectUponCron>{string}</AutoEjectUponCron>
   <AutoEjectUponJobCancellation>
      TRUE|FALSE
   </AutoEjectUponJobCancellation>
   <AutoEjectUponJobCompletion>
      TRUE|FALSE
   </AutoEjectUponJobCompletion>
   <AutoEjectUponMediaFull>
      TRUE|FALSE
   </AutoEjectUponMediaFull>
   <Id>{string}</Id>
   <LtfsFileNaming>OBJECT_ID|OBJECT_NAME</LtfsFileNaming>
   <MaxTapeFragmentationPercent>
      {32‑bit integer}
   </MaxTapeFragmentationPercent>
   <MaximumAutoVerificationFrequencyInDays>
      {32‑bit integer}
   </MaximumAutoVerificationFrequencyInDays>
   <MediaEjectionAllowed>
      TRUE|FALSE
   </MediaEjectionAllowed>

   <Name>{string}</Name>
   <SecureMediaAllocation>TRUE|FALSE</SecureMediaAllocation>

   <VerifyPriorToAutoEject>
      CRITICAL|URGENT|HIGH|NORMAL|LOW|BACKGROUND
   </VerifyPriorToAutoEject>
   <WriteOptimization>CAPACITY|PERFORMANCE</WriteOptimization>
</Data>

where the response elements are defined as follows:

Parameter	Description
Data	The container for the response.
AutoEjectMedia FullThreshold	The minimum available capacity (in bytes) at which media is not considered full and eligible for auto-eject.
AutoEjectUpon Cron	The CRON expression that indicate when to auto eject tape cartridges. If set, a CRON job is created based on the CRON string specified. Once the CRON job is executed, all tape cartridges assigned to the storage domain, not already pending ejection are queued for ejection.
AutoEjectUponJobCancellation	Whether all media assigned to the storage domain, not already pending ejection, is queued for ejection whenever a job is canceled. Values: TRUE, FALSE
AutoEjectUponJobCompletion	Whether all media assigned to the storage domain, not already pending ejection, is queued for ejection whenever a job completes. Values: TRUE, FALSE
AutoEjectUpon MediaFull	Determines whether all media assigned to the storage domain, not already pending ejection, is queued for ejection whenever the media cannot fit the amount of data specified by AutoEjectMediaFullThreshold. Values: TRUE, FALSE
Id	The UUID for the storage domain.
LtfsFileNaming	The LTFS file naming mode used on tapes in the storage domain. Values: OBJECT_ID, OBJECT_NAME. See ltfs_file_naming for descriptions.
MaxTape Fragmentation Percent	Not currently used.
MaximumAuto Verification FrequencyInDays	The number of days since the last verification when a piece of unchanged media is not considered for verification.
Name	The name of the storage domain.
SecureMedia Allocation	Whether media must remain within the storage domain. Values: § TRUE — Media assigned to the storage domain can only be reclaimed for use within the same storage domain. § FALSE — Media assigned to a storage domain can be reclaimed into the general pool if all data on the media is deleted.
VerifyPriorToAuto Eject	The priority for verifying tapes being ejected automatically due to any of the auto-eject triggers. The priority is null if verification is not required prior to ejection. The priority determines the resources assigned and the processing order. Values: CRITICAL, URGENT, HIGH, NORMAL, LOW, BACKGROUND
WriteOptimization	Whether job chunks are written as quickly as possible (PERFORMANCE) or across as few pieces of media as possible (CAPACITY). Values: CAPACITY, PERFORMANCE

Example

Sample Request

This request creates a storage domain with the name “sd1” that uses all storage domain defaults.

POST http://blackpearl-hostname/_rest_/storage_domain?name=sd1 HTTP/1.1

Sample Response

HTTP/1.1 200 OK

<Data>
   <AutoEjectMediaFullThreshold/>
   <AutoEjectUponCron/>
   <AutoEjectUponJobCancellation>
      FALSE
   </AutoEjectUponJobCancellation>
   <AutoEjectUponJobCompletion>FALSE</AutoEjectUponJobCompletion>
   <AutoEjectUponMediaFull>FALSE</AutoEjectUponMediaFull>
   <Id>3d306463-8fbc-4bb5-9d0d-98c2cb9e8aa2</Id>
   <LtfsFileNaming>OBJECT_ID</LtfsFileNaming>
   <MaxTapeFragmentationPercent>65</MaxTapeFragmentationPercent>
   <MaximumAutoVerificationFrequencyInDays>
      365
   </MaximumAutoVerificationFrequencyInDays>
   <MediaEjectionAllowed>TRUE</MediaEjectionAllowed>
   <Name>sd1</Name>
   <SecureMediaAllocation>FALSE</SecureMediaAllocation>
   </VerifyPriorToAutoEject>
   <WriteOptimization>CAPACITY</WriteOptimization>
</Data>