USAGE

Copyright (c) 2016 - 2025 Storage Networking Industry Association. All rights reserved. All other trademarks or registered trademarks are the property of their respective owners.

Storage Networking Industry Association (SNIA) hereby grants permission for individuals to use this document for personal use only, and for corporations and other business entities to use this document for internal use only (including internal copying, distribution, and display) provided that:

1. Any text, diagram, chart, table or definition reproduced must be reproduced in its entirety with no alteration, and,

2. Any document, printed or electronic, in which material from this document (or any portion hereof) is reproduced must acknowledge SNIA copyright on that material, and must credit SNIA for granting permission for its reuse.

Other than as explicitly provided above, you may not make any commercial use of this document, or any portion thereof, or distribute this document to third parties. All rights not explicitly granted are expressly reserved to SNIA.

Permission to use this document for purposes other than those enumerated above may be requested by emailing tcmd@snia.org. Please include the identity of the requesting individual and/or company and a brief description of the purpose, nature, and scope of the requested use.

All code fragments, scripts, data tables, and sample code in this SNIA document are made available under the following license:

BSD 3-Clause Software License

Copyright (c) 2025, Storage Networking Industry Association.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Neither the name of Storage Networking Industry Association nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

DISCLAIMER

The information contained in this publication is subject to change without notice. SNIA makes no warranty of any kind with regard to this publication, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The SNIA shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use.

Suggestions for revisions should be directed to http://www.snia.org/feedback/.

Current Revision

SNIA is actively engaged in expanding and refining the Swordfish documentation. The most current revision can be found on the SNIA web site at
https://www.snia.org/tech_activities/standards/curr_standards/swordfish.

Contact SNIA

Current SNIA practice is to make updates and other information available through their web site at http://www.snia.org.

FEEDBACK AND INTERPRETATIONS

Requests for interpretation, suggestions for improvement and addenda, or defect reports are welcome. They should be sent via the SNIA Feedback Portal at http://www.snia.org/feedback/ or by mail to SNIA, 5201 Great America Parkway, Suite 320, Santa Clara, CA 95054, USA.

INTENDED AUDIENCE

This document is intended for use by individuals and companies engaged in storage management.

VERSIONING POLICY

This document is versioned material. Versioned material shall have a three-level revision identifier, comprised of a version number ‘v’, a release number ‘r’ and an errata number ‘e’. Future publications of this document are subject to specific constraints on the scope of change that is permissible from one revision to the next and the degree of interoperability and backward compatibility that should be assumed between products designed to this standard. This versioning policy applies to all SNIA Swordfish versioned materials.

Version Number: Versioned material having version number ‘v’ shall be backwards compatible with all of revisions of that material that have the same version number ‘v’. There is no assurance of interoperability or backward compatibility between revisions of a versioned material with different version numbers.

Release Number: Versioned material with a version number ‘v’ and release number ‘r’ shall be backwards compatible with previous revisions of the material with the same version number, and a lower release number. A minor revision represents a technical change to existing content or an adjustment to the scope of the versioned material. Each minor revision causes the release number to be increased by one.

Errata Number: Versioned material having version number ‘v’, a release number ‘r’, and an errata number ‘e’ should be backwards compatible with previous revisions of the material with the same version number and release number (“errata versions”). An errata revision of versioned material is limited to minor corrections or clarifications of existing versioned material. An errata revision may be backwards incompatible, if the incompatibility is necessary for correct operation of implementations of the versioned material.

Revision History

The evolution of this document is summarized in Table 1.

About SNIA

SNIA is a not-for-profit global organization made up of corporations, universities, startups, and individuals. The members collaborate to develop and promote vendor-neutral architectures, standards, and education for management, movement, and security for technologies related to handling and optimizing data. SNIA focuses on the transport, storage, acceleration, format, protection, and optimization of infrastructure for data. Learn more at www.snia.org.

Acknowledgements

The SNIA Scalable Storage Management Technical Work Group, which developed and reviewed this work in progress, would like to recognize the significant contributions made by the following members listed in Table 2.

1 Abstract

The Swordfish Scalable Storage Management API (“Swordfish”) defines a RESTful interface and a standardized data model to provide a scalable, customer-centric interface for managing storage and related data services. It extends the Redfish Scalable Platforms Management API Specification from the DMTF.

2 Scope

This document defines the Swordfish Scalable Storage Management API.

Swordfish is designed as an extension of the Redfish specification. This document is written with the presumption that the reader has a detailed understanding of the Redfish specification. This document cannot be fully understood without that context.

Swordfish extends the Redfish Scalable Platforms Management API Specification to define a comprehensive, RESTful API for storage management that addresses block storage, file systems, object storage, and storage network infrastructure. It is centered around common operational and business concerns of storage management, including:

• Configuration and provisioning
• Monitoring
• Event and log management
• Performance assessment
• Diagnostics
• Fault detection and remediation
• Security
• Accounting and resource consumption

The Redfish specification provides the protocols and a core set of data models and behaviors for the management of systems. It defines the elements and behaviors that are mandatory for all Redfish implementations. Additionally it defines additional elements and behaviors that can be chosen by system vendors or manufacturers. The specifications also defines points at which OEM (system vendor) extensions can be provided by a given implementation. The specifications specifies normative requirements for Redfish Services and associated materials, such as Redfish Schema files. The Redfish specifications does not set requirements for Redfish clients, but will indicate what a Redfish client should do in order to access and utilize a Redfish Service successfully and effectively.

A Swordfish implementation conforms to all requirements specified in the Redfish specifications.

The Swordfish specification defines additional data models and behaviors for the management of storage systems and storage infrastructure.

Swordfish is suitable for a wide range of storage, from small-scale object drives, integrated RAID cards or RBODs providing storage services, to external disk arrays or file servers, to infrastructure providing storage services for converged, hyperscale and large scale cloud environments. It includes support for multiple protocol types, including NVMe and NVMe-oF. Supporting documentation is provided to detail the mapping of Swordfish objects and properties to NVMe and NVMe-oF standard interfaces.

In addition to its storage model, Swordfish includes emerging functionality, such as clearly-defined classes of service, which provide a consistent means to map high-level business goals and objectives to specific, storage-based actions and requirements, and can be applied uniformly across a broad spectrum of storage configurations and storage types (e.g., block storage, file systems, object stores). Common storage management functionality covered by a class of service interface includes snapshots, replication, mapping and masking, and provisioning.

3 Normative References

3.1 Overview

The documents referenced in Table 3 are indispensable for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

3.2 Approved references

The approved references that contribute to this document are summarized in Table 3.

3.3 References under development

None defined in this document.

3.4 Other references

None defined in this document.

4 Terms and Definitions

4.1 Overview

In this document, some terms have a specific meaning beyond the normal English meaning. Those terms are defined in this clause. New terms, frequently used Redfish terms.

4.2 Swordfish-specific Terms

4.2.1 Definitions

The terms listed in Table 4 are used in this document.

4.2.2 Symbols and abbreviated terms

None in this document.

4.3 Reference to Redfish terms

Many terms in this document were originally defined in the Redfish Specification. Some of the more common terms and definitions are reproduced in Table Table 5, as an aid to the reader.

4.4 Keywords (normative language terms)

This document conforms to ISO/IEC Directives, Part 2 for keyword usage. The most common terms and their intended meanings are summarized Table Table 6.

5 Swordfish Overview

5.1 Introduction

The Swordfish Scalable Storage Management API (“Swordfish”) defines a RESTful interface and a standardized data model to provide a scalable, customer-centric interface for managing storage and related data services. It extends the Redfish Scalable Platforms Management API Specification from the DMTF.

5.2 Relation to Redfish

The Swordfish service interface extends the Redfish service interface. As such, a Swordfish service is a Redfish service and includes all required elements of the Redfish model, as illustrated by Figure 1.

The storage systems shall be instantiated in one of two places in the hierarchy:

• directly in the Storage resource collection, or
• attached to a ComputerSystems, with an associated reference link in the StorageSystems resources collection at the ServiceRoot. In this case, there shall also be a reference link to the Storage resource in the Storage resource collection at the ServiceRoot.

As a result, a Swordfish client is always able to locate the storage systems managed by the Swordfish service in the ServiceRoot via the Storage resource collection; this may be a combination of references to instances and instantiated instances.

The physical infrastructure is modeled using Redfish Chassis.

As modeling for storage systems may cover both logical and physical constructs, Swordfish management clients that are focused on logical storage management use cases may choose to manage functionality entirely by way of logical resources.

Each Swordfish service is accessed via well known URLs on the system supporting the Swordfish Service. Since Swordfish is an extension of Redfish, these URLs are the same as for accessing the Redfish defined aspects of the service.

5.3 Storage System Models

Swordfish has been designed to support a broad range of configurations, requirements, size and complexity, as well as logical and physical architectures. As a result, there are two primary methods of modelling the storage system for a Swordfish implementation:

1. Swordfish Standalone Configuration

The standalone configuration instantiates the logical storage system instance representation in the Storage resource collection directly off the Service Root. The logical storage system is modeled using the Redfish Storage and StorageController resources, as shown in Figure 2. Managed resources are connected to the Storage resource, including Volumes and StoragePools.

This configuration works well for standalone devices or storage systems. An example of a Storage System for an standalone configuration is shown in Figure 3.

2. Swordfish Integrated Configuration

The integrated configuration attaches to the Storage collection within the same ComputerSystem model instantiation as the server where the physical element resides.

The logical storage system is modeled using the Redfish Storage and StorageController resources. The Storage resource is located in the Redfish hierarchy contained by ComputerSystems, typically running as ApplicationServers. The physical infrastructure is modeled using Redfish Chassis. Managed resources are connected to the Storage resource, including Volumes and StoragePools.

The integrated configuration is illustrated in Figure 4.

This configuration works well when the storage system can be modeled by simply instantiating a new Storage object within an existing computer system. An example of a Storage System for an integrated configuration is shown in Figure 5.

5.4 Swordfish model overview

5.4.1 The ServiceRoot

The service root serves as the base for any Redfish or Swordfish service. It is always published at a well-known URI of /redfish/v1. The base service root can be accessed without a secure connection.

There are multiple required services and resources defined in the Redfish specification for any Redfish or Swordfish service; these include components such as the OData service document at /redfish/v1/odata, the schema metadata at /redfish/v1/$metadata, and services to provide authentication. Refer to the Redfish Specification for full details.

For Swordfish management, the following elements are common:

• Storage: A reference to the Storage resource collection.
• Systems: A reference to a Systems resource collection.
• Chassis: A reference to a Chassis resource collection.
• Registries: A set of administrative elements containing a Features registry and other components.
• Managers: A reference to a Managers resource collection.
• Fabrics: A reference to a Fabrics resource collection.
• EventService: The event management service.
• StorageSystems: An optional reference to a StorageSystems resource collection.

5.4.1.1 The Storage resource collection

A resource collection that references a set of Storage resources that each represents a storage subsystem. This collection can contain either resources or references to instances of Storage resources. Each Storage resource represents an instance of a storage subsystem. For Swordfish subsystems, refer to the Swordfish model overview for details on required elements.

5.4.1.2 The Systems resource collection

A resource collection that references a set of ComputerSystem resources that each represents a general purpose application server. Each ComputerSystem resource will have an entry with the value of “ApplicationServer” in its HostingRoles property. A particular ComputerSystem resource can be in both the StorageSystems and Systems collections.

5.4.1.3 The Chassis resource collection

A resource collection that references a set of Chassis resources. Each Chassis resource represents physical containers (i.e., sheet-metal confined spaces and logical zones like racks, enclosures, chassis, and all other containers). Subsystems (e.g., sensors), which operate outside of a system’s data plane (meaning the resources are not accessible to software running on the system) are linked either directly or indirectly through this resource.

5.4.2 The StorageSystems resources collection

An optional reference to a ComputerSystemCollection with members of type ComputerSystem that have Swordfish managed storage attached. They will have an entry with the value of “StorageServer” in their HostingRoles property. This collection, then, is a resource collection that references a set of ComputerSystem resources that each represents a storage server. Each ComputerSystem resource will have an entry with the value of “StorageServer” in its HostingRoles property. A particular ComputerSystem resource can be a member of both the StorageSystems resource collection and the Systems resource collection.

5.4.3 The Storage resource

The storage system exposes logical storage, associated resources and related functionality. Storage resources can be found in the service root or service container via the Storage resource collection, and are attached to the Storage object within the Storage resource collection.

The storage system typically provides the ability to create, manage and present block, file or object store from a set of back-end media, presented to one or more hosts. Storage controllers can work in coordinated sets of one or more to present value-add capabilities, such as failover, data protection, and data path management within the storage system, that are represented through the various resources within the storage system.

The following are the principal properties of Storage that point to resources managed or defined by the storage system:

• Controllers: A reference to a collection of StorageController resources.
• Drives: A reference to a collection of Drive resources used for storage.
• Enclosures: A reference to a collection of Chassis resources that contain storage related resources.
• FileSystems: A reference to a collection of FileSystem resources.
• StorageGroups: Deprecated in favor of ConsistencyGroups.
• ConsistencyGroups: A reference to a collection of ConsistencyGroup resources.
• StoragePools: A reference to a collection of StorageGroup resources.
• Volumes: A reference to a collection of Volume resources.

Key properties of Storage used for access rights management, connectivity management, and consistency management, include:

• Endpoints: A reference to a collection of Endpoint resources used to access storage.
• EndpointGroups: A reference to a collection of EndpointGroup resources.

The following properties are created in the /redfish/v1/Fabrics to support access rights management, connectivity management, and consistency management, include:

• Fabrics: A reference to a collection of Fabric resources.
• Connections: A reference to a collection of Connection resources.
• Zones: A reference to a collection of Zone resources.
• Switches: A reference to a collection of Switch resources.

5.4.3.1 The StorageController resource

The storage controller presents the foundational resources used by the storage system. It generally contains connectivity resources between the system and connected consumers.

A StorageController may represent either a physical or logical controller.

For direct-attach configurations, a StorageController instance is commonly used to represent the host-side physical controller, such as an HBA, or RAID controller. This includes properties such as Port to enumerate connectivity information.

Other key properties, when representing a physical controller:

• SpeedGbps
• SupportedControllerProtocols and SupportedDeviceProtocols
• Controller capabilities, such as cache, battery backup information, and SupportedRAIDTypes
• AttachedVolumes
• EnvironmentMetrics - only used for physical representations
• Ports

For NVMe devices, a storage controller is the interface between a host and an NVM subsystem. When PCI Express is used as the transport, a controller is also a PCI Express function.

It may represent the following capabilities:

• Modeling the interface between hosts and Volumes (IO controller)
• Access to administrative / management capabilities (admin controller)
• Network discovery of available volumes, and subsystems (discovery controller)

Key properties when representing a logical NVMe controller:

• Endpoints
• SupportedControllerProtocols
• AttachedVolumes
• NVMeControllerAttributes, NVMeControllerProperties

5.4.3.2 The Endpoint resource

Endpoints represent one end of a protocol specific connection that supports sending or receiving messages according to a particular protocol. Endpoints are used for access rights management, connectivity management, and consistency management. Endpoint objects are instantiated in the /redfish/v1/Fabrics/Endpoints collection, and referenced elsewhere.

For access rights management, the Endpoint is used in conjunction with Connections. This use case reflects the target’s view of configured access to initiators.

For connectivity rights management, the Endpoint is used in conjunction with Switches and Zones. In this case, the endpoints reflect the fabric view of both the initiator and target endpoint identifiers.

Key properties for Endpoints for both access rights management and connectivity management include:

• EndpointProtocol
• identifiers
• ConnectedEntities

5.4.3.3 The Endpoint Collection resource

The EndpointCollection is a resource collection that references a set of Endpoint resources.

5.4.3.4 The EndpointGroup resources

EndpointGroup resources contain a set of Endpoints to be used for the same purpose, such as for access management, connectivity management, and consistency management. EndpointGroups can be used to simplify operations against large groups of Endpoints.

For consistency management, Endpoints are used to group together to provide single access and connectivity management for volumes in consistency groups.

5.4.4 The ConsistencyGroup resource

ConsistencyGroups represent a set of volumes that are managed as a group. Group level management allows system and application level activities to be performed on a set of data that spans volumes. ConsistencyGroups are typically used to enforce write-order consistent behavior throughout a set of members. Other activities include device-level replication operations, as well as system level functions, such as reset.

When ConsistencyGroups are implemented, they are attached to a Storage resource, and its internal Volumes collection is constructed from a subset of the Volumes collection of the Storage resource. The ConsistencyGroup can also be used to manage across replicas.

ConsistencyGroups should be used in place of the deprecated StorageGroups.

5.4.5 The ConsistencyGroup Collection resource

The ConsistencyGroupCollection is a resource collection that references a set of ConsistencyGroup resources.

5.4.6 The StorageGroup resource

StorageGroup usage has been deprecated in favor of ConsistencyGroup usage.

StorageGroups represent a set of volumes that are managed as a group in order to facilitate mapping and masking, in which the volumes of a storage group are collectively exposed or hidden to a set of clients.

The set of volumes is specified by the Mapped Volumes attribute. MappedVolumes is a resource collection of the Mapped Volume construct (a tuple of a pointer to a volume and a corresponding Logical Unit Number for that volume).

The set of client endpoints to which the volumes can be exposed is specified by the ClientEndpointGroupsattribute. The ClientEndpointGroup resource specifies a collection of EndpointGroup resources.

The set of server endpoints to which the volumes can be exposed is specified by the ServerEndpointGroupsattribute. The ServerEndpointGroup resource specifies a collection of EndpointGroup resources.

5.4.7 The StoragePool resource

The StoragePool resource represents unassigned storage capacity that can be used to produce storage volumes or other storage pools.

The following are the principal properties of StoragePool that are used to create or identify resources provisioned or supported by the storage pool:

• AllocatedVolumes: A reference to a collection of Volume resources that have been provisioned from the storage pool.

• AllocatedPools: A reference to a collection of StoragePool resources that have been provisioned from the storage pool.

• CapacitySources: A reference to a resource collection that provides pointers to the capacity sources that are used to provide the underlying capacity for this storage pool.

• RAIDTypes[]: The set of RAIDTypes supported by this StoragePool. This may be set upon StoragePool creation, or may be a reflection of the implementation’s ability to support different RAID types. Consumers may use this property to determine what RAID types are available from specific StoragePool instances for additional Volume creation requests, or what RAIDTypes have been applied to Volumes already allocated.

• Capacity (allocated and consumed)

• IO / performance and other metrics

• Spare management

• Pool type

Key operations include managing efficiency, protection and replication capabilities (e.g., deduplication, compression, encryption).

For NVMe and NVMe-oF devices, StoragePools continue to represent the underlying storage capacity. StoragePools are used to map to collections of storage capacity that have specific, related properties. These include NVMe Endurance Groups and NVM Sets.

5.4.7.1 The Volume resource

Volume resource represents an addressable container of storage, sometimes referred to as a “Logical Unit”, “LU”, “LUN”, or “StorageVolume” in the storage industry.

Volume is a foundational object for storage, and is extended in many ways, dependent on the desired system feature set. Potential usages for Volume include:

• providing for block-addressable storage, Volumes can also be further refined for particular implementations, such as key-value, object store, or other technologies;
  
• serving as building block for FileSystems, FileShares, datastores, and object stores;
• being grouped into write-order consistent ConsistencyGroups;
• virtualizing physical media (e.g., drives, memory);
• providing protection from underlying media failures;
• allowing for aggregation or slicing of physical resources into desired size;
• facilitating storage efficiency and protection representation and management (e.g., compression, deduplication);
• supportng replication and protection (e.g., encryption).

Key related elements: - Endpoint: Access to the volume is modeled through Endpoints. These cover direct connect protocols (e.g., SAS and SATA), as well as fabric-capable connection protocols. - StoragePool: Many of the characteristics of a Volume can be also managed across a set of Volumes from its StoragePool.

For block-addressable applications, key properties include information representing the block usage:

• BlockSizeBytes
• Capacity, including allocated and consumed
• RAIDType
• Access capabilities - modeled through Endpoints
• Relationship to underlying storage constructs (physical or logical) is typically represented through the StoragePool
• Usage (when known by the system)
• IO / performance and other metrics

Operations for block-addressable Volume may include:

• Expand
• Create / manage replicas
• Encrypt / SecureErase
• Initialize
• Change RAID layout and / or type

The Operations property presents a list of Operations currently running on the Volume. As Operations are both long-running and may be invoked from either the Redfish/Swordfish interface or via independent means, the Operations property provides a mechanism independent of the task service to show their status.

A GET on the Volume during specific long-running operations should also clearly indicate the in-process change, setting the Volume’s Status.Health and State.State correspondingly.

• While transformational changes are in progress, the Status.Health should be set to “Updating” and Status.State should be set to “Warning”. This includes:

  • Change RAID layout and / or type
  • Encrypt / decrypt

• Set Status.State to “UnavailableOffline” when in the process of creating a Volume and the volume is not yet available for use:

  • Initialize

Volumes are also central to application-specific extensions to storage modeling. For example:

• When using replication, StorageReplicaInfo contains descriptions and pointers to the Volumes employed.
• For storage devices with NVMe interfaces, Volumes:
  • Represent NVMe namespaces
  • Namespaces can be block, object, ZNS (zoned namespace), and KV (key value), which can be determined by the Type property within NVMeNamespaceProperties
  • Contain indications of NVMe capabilities via NamespaceFeatures
  • Show relationships to NVMe logical controllers

Additional information can be found in the NVMe Command Set Specification.

5.4.8 The FileSystem resource

This FileSystem resource represents a file system. Each FileSystem may contain a collection of FileShares that can be presented to hosts.

5.4.8.1 The Fabric resource

The Fabric resource is used to reflect both access rights and connectivity.

When representing access rights, a Fabric contains:

• Endpoints
• Connections
• EndpointGroups, as needed

In this role, the Fabric contains objects that define access capabilities, and the scope that they apply to. This includes the logical data storage entities (e.g., volumes, filesystems) to which the defined access rights apply, as well as the protocol connection information for each included object.

A fabric modelling connectivity management contains objects that define the corresponding transport protocol’s access and configuration information, as well as the protocol connection information for logical objects within the storage system. Connectivity is reflected by describing the allowed or restricted connections. Connectivity-related objects within a Fabric include:

• Endpoints
• EndpointGroups
• Switches
• Zones

5.4.8.2 The Connection resource

The Connection resource describes the access permissions that Endpoints (or groups of endpoints) have with other resources. It also describes the association of access capabilities to specified logical data storage entities.

Key properties for Connections include:

• ConnectionType
• VolumeInfo
• Endpoints and EndpointGroups (in Links)

5.4.8.3 The Zone resource

The Zone resource describes the allowed / disallowed connectivity between endpoints.

5.4.8.4 The Switch resource

The Switch resource describes physical interconnect information, including physical port configuration information.

Key properties include:

• SupportedProtocols
• SwitchType
• Ports
• Other properties as needed to describe the physical switch attributes for monitoring, asset management, and configuration

6 Features and Profiles

6.1 Overview

Features are high-level descriptions of functionality which an implementation uses to advertise what functionality it currently supports, and for some features, is capable of supporting.

The detailed definitions required to describe to implementers how to implement a feature are written in profile definition files. A feature is generally represented in one (but may be more) profile definition file, or profile.

Profiles are detailed descriptions that describe down to the individual property level what functionality is required in order to advertise features. Different profile definitions can exist for the same feature type but for various types of storage configurations: Swordfish.Block.Provisioning, Swordfish.File.Provisioning

The Swordfish Features Registry shall be used to advertise what standard and Oem Features an implementation supports.

6.2 Requirement for SupportedFeatures

SupportedFeatures entries in the Features registry represent the client’s primary initial runtime view of the capabilities of a Swordfish implementation. Without properly formed entries in this registry, there is no visibility to an implementation’s functionality.

Swordfish implementations shall implement the Features registry and advertise at least one supported feature from the SwordfishFeaturesRegistry in order to be considered a Swordfish implementation.

Features define coarse-grained sets of functionality. In order to advertise a feature (using the SupportedFeature mechanism in the SupportedFeatures Registry), the implementation must support the complete set of functionality as defined in the corresponding profile.

The Swordfish Features Registry publishes the official list of supported SNIA Features, and provides a high-level description of their functionality. Many of those features are self-explanatory (e.g., local replication, remote replication), but there are some features where additional context is appropriate:

• Energy Star for Storage
• NVMe and NVMe-oF
• Class of Service

6.3 EnergyStar for Storage Feature

The EnergyStar for Storage Feature and profile has been created to formalize the requirements from the ENERGY STAR Data Center Storage Program Requirements on storage products. The profile indicates what properties Swordfish implementations need to support in order to properly instrument EnergyStar reporting capability. This functionality is intended to support EnergyStar data gathering requirements as part of the EnergyStar certification process.

6.4 NVMe and NVMe-oF Features

NVMe features and profiles are defined to provide definitions for specific NVMe devices and configurations. The NVMe profiles also include references to non-NVMe specific profiles, such as those specifying the features for discovery, access rights, connectivity rights, and management controllers.

Profiles defined specifically for NVMe device types all use a common naming scheme, and typically start with SwordfishNVMe.

6.5 Class of Service Feature

6.5.1 Overview

Swordfish supports a ClassOfService feature. The ClassOfService functionality supports systems that are capable of providing a greater level of management automation, where a higher-level set of goals is provided as direction rather than requiring parameterized inputs for all configuration actions.

The Class of Service feature uses a combination of device-defined capabilities to structure LinesOfService, which are sets of available functionality in a given system, that can then be grouped together to provide classes of service.

When Class of service functionality is implemented, the Swordfish functionality may be entirely exposed through the StorageService resource. Each Swordfish StorageService is located in the ServiceRoot (and ServiceContainer) via the StorageServices resource collection.

6.5.2 Class of Service Model

For Swordfish with a class of service interface, the following two models apply. Either model choice results in the same storage service, regardless of the storage system model.

1. Integrated Service Configuration

The storage systems managed by the Swordfish storage service are modeled using the Redfish Storage resource and StorageController resource collections. The Storage resource is located in the Redfish hierarchy contained by ComputerSystems, typically running as ApplicationServers. The physical infrastructure is modeled using Redfish Chassis, as shown in Figure 6.

This configuration works well when the storage service is hosted by a storage resource within a computer system. An example of a Storage Service for an integrated service configuration is shown in Figure 7.

Note: This diagram and the discussion of the configuration description have been simplified slightly to avoid confusion. A full implementation would likely include additional links to the logical storage controller resources.

2. Standalone Service Configuration

The storage systems managed by the Swordfish storage service are located in the ServiceRoot (and ServiceContainer) via the Storage resource collection. They model the logical storage system using Redfish Storage and ‘StorageController’ resources. The physical infrastructure is modeled using Redfish Chassis. This is shown in Figure 8.

This configuration works well when the standalone storage system directly hosts the storage service(s). An example of a Storage Service for a hosted service configuration is shown in Figure 9.

Note: This diagram and the discussion of the configuration description have been simplified slightly to avoid confusion. A full implementation would likely include additional links to the logical storage controller resources.

6.5.3 ServiceRoot Additions

When the StorageService feature is implemented, the following is added to the ServiceRoot:

• StorageServices: A resource collection that references a set of StorageService resources. Each StorageService resource represents the resources and behaviors supported by that storage service.

6.5.4 The StorageService resource

6.5.4.1 Principal Properties

The storage service is hosted on a storage system and exposes logical storage, associated resources and related functionality. Storage service resources can be found in the service root or service container via the StorageServices resource collection.

The following are the principal properties of StorageService that point to resources managed or defined by the storage service:

• ClassesOfService: A reference to a resource collection that specifies the supported ClassOfService resources.
• Drives: A reference to a resource collection that collects Drive resources used for storage.
• Enclosures: A reference to a resource collection that collects Chassis resources that contain storage related resources.
• Endpoints: A reference to a resource collection that collectsEndpoint resources used to access storage.
• FileSystems: A reference to a resource collection that collects FileSystem resources.
• EndpointGroups: A reference to a resource collection that collects EndpointGroups resources.
• StorageGroups: A reference to a resource collection that collects StorageGroup resources.
• StoragePools: A reference to a resource collection that collects StorageGroup resources.
• Volumes: A reference to a resource collection that collects Volume resources.
• HostingSystem: A reference to the ComputerSystem instance that hosts this StorageService.

6.5.4.2 Capabilities and Lines of ServiceRoot

The following properties each define a set of attributes, which describe capabilities that the storage service may support:

• DataProtectionLoSCapabilities: Replicas that protects data from loss.
• DataSecurityLoSCapabilities: Data security service level requirements. The data security characteristics enable the storage system to be used in an environment where compliance with an externally-specified security standard or standards is required. Examples of such standards include FIPS-140, HIPAA and PCI.
• DataStorageLoSCapabilities: Provisioning and access characteristics for storage of the data.
• IOConnectivityLoSCapabilities: IO connectivity requirements for access to the data.
• IOPerformanceLoSCapabilities: IO performance requirements for access to the data.

In each of the above, not all combinations of attribute values defined within a capability are likely to be supported by the storage service.

Known, supported combinations of attribute values are used to construct entries in the LinesOfService array property. Not all attributes of a line of service entry need be specified (i.e. some may be Null). If an attribute has no value, the storage service may choose any supported values when provisioning for that entry. Otherwise, the line of service attribute values specifies the kind or level of service to be provided.

6.5.4.3 The ClassOfService resource

A class of service represents a choice of utility or warranty offered to customers by a service. (ITIL uses the term service option. See the Normative References.)

Each ClassOfService resource is a uniquely named description of the characteristics of one choice of utility or warranty for a service. Each ClassOfService is a description of the kind and quality of service to provide and is not intended to describe how the service provides that service.

Each ClassOfService is defined by an aggregation of lines of service. Supported lines of service are listed in the corresponding capabilities attributes of the storage service, (see above).

Currently defined lines of service are:

• Data Protection: Describes the characteristics of a replica that protects data from loss.
• Data Security: Describe data security service level requirements. The data security characteristics enable the storage system to be used in an environment where compliance with an externally-specified security standard or standards is required. Examples of such standards include FIPS-140, HIPAA and PCI.
• Data Storage: Describes provisioning and access characteristics for storage of the data.
• IO Connectivity: Describes IO connectivity requirements for access to the data.
• IO Performance: Describes the IO performance requirements for access to the data under a particular workload.

Some advertised ClassOfService resources are created by the service implementation. These are generally not changeable and are intrinsic to the implementation.

A service may support creation or modification of ClassOfService resources. All must be consistent with the capabilities of the service.

6.5.4.4 The StoragePool resource

When a Swordfish implementation advertises support for the Class of Service feature, the StoragePool resource now presents a new method to the client to allocate unassigned storage capacity. This is automated by the system as conformance to one or more classes of service. Requests to StoragePool shall automatically allocate capacity based on the constraints of the selected class of service and any other selected parameters, with priority given to the class of service constraints.

The following are the principal properties of StoragePool that are used to identify resources provisioned or supported by the storage pool related to Class of Storage:

• ClassesOfService: A reference to a resource collection that specifies the set ClassOfService resources that can be specified when provisioning resources from the storage pool.
• DefaultClassOfService: A reference to the default ClassOfService resources used for provisioning from the storage pool.

6.5.4.5 The Volume resource

Volume resource represents a block-addressable container of storage, sometimes referred to as a “Logical Unit”, “LU”, “LUN”, or “StorageVolume” in the storage industry. Volumes optionally adhere to a ClassOfService, which defines added functionality. Examples include:

• Access capabilities
• Capacity and capacity sources
• Consumption tracking (e.g., LowSpaceWarningThresholdPercents)
• Replication details
• StorageGroup Information

6.5.4.6 The FileSystem resource

In a Swordfish implementation that advertises support for the Class of Service feature, File systems represent file-addressable capacity that are conformant to a ClassOfService.

7 Schema Considerations

7.1 Schema Introduction

7.1.1 Overview

A Swordfish implementation is a Redfish implementation, and as such it minimally includes support for some Redfish-defined schema, including ServiceRoot, ComputerSystem, and Storage (which has been enhanced to include many Swordfish-centric properties). Swordfish implementations also include support for Swordfish-defined schema.

The Swordfish model focuses primarily on the logical model of a storage system, and does not require full representation of a physical instantiation. This is left to the implementer to complete from available Redfish schema models.

Swordfish schema is conformant with the rules used to define Redfish schema. Redfish schema is conformant with the Common Schema Definition Language, see CSDL. This section provides additional definition and context for the CSDL elements used to define Swordfish schema.

7.1.2 Schema Primacy

Redfish and Swordfish schema are made available in multiple formats, including CSDL, JSON and yaml. The development source for the Swordfish specification is CSDL; other variants are derived from the CSDL source. If conflicts and questions arise between the definitions, CSDL shall be treated as the definitive source.

7.1.3 Swordfish Extension of the Redfish ServiceRoot

The Redfish ServiceRoot has properties that provide access to Swordfish resources.

For implementations that advertise support for the ClassOfService feature, the implementation shall instantiate a collection of StorageServicesat the ServiceRoot with at least one member. The collection provides the client an efficient means to search across all StorageService resources, regardless of which ComputerSystem is supporting the service.

7.2 Default values and NULLABLE attributes

The interaction of Nullable and DefaultValue needs to be clearly understood by both implementers and client developers. The possible combinations of are summarized in Table 7. The table contains:

• Nullable: True, if a given property may be NULL
• DefaultValue: True, if a default value is provided for a given property
• Client: True, if a client value is supplied for a given property in a query or response
• Result: The resultant value of the given property. One of:
  • C: The client-provided value
  • D: The default value
  • Null: Null
  • I: Implementation defined
  • Error: Error state

7.3 Common schema annotations

Table 8 lists common annotation used in the definition of Swordfish. For details see OData Capabilities Vocabulary, OData Core Vocabulary, OData Measures Vocabulary, and Redfish Extensions.

7.4 Property implementation requirements

The client and the implementer should understand that, regardless of the schema declaration, an implementer may choose to not implement a property. If not implemented, a representation of the property will not be present in a reply. This should not be confused with a response that indicates that a property has been implemented, but has no value (i.e. propertyName = null).

There are several factors that could affect the implementation choice. Implementation requirements can be defined in many documents. At a minimum, a developer should review, in order: 1. the Redfish specification, 2. this document, and 3. associated profile specifications.

7.5 Schema repository

The primary online source for the Swordfish schema shall be co-located on the DMTF schema site with the Redfish schema: http://redfish.dmtf.org/schemas/swordfish/v1.

Developers may also download the schema as part of the Swordfish bundle from snia.org (refer to snia.org/swordfish for pointers to the bundle locations).

Implementations should refer either to the versions available on the dmtf.org site or to locally provided instances of the schema.

7.6 Referencing other schemas

Swordfish directly references many Redfish schemas when functionality is already defined and can be leveraged. Other Redfish schema may be added by inference or directly to implementations. Examples are available in the Swordfish mockups.

7.7 Swordfish online repositories

7.7.1 Registries

The primary online source for the Swordfish registries shall be co-located on the DMTF registry site with the Redfish registry:
http://redfish.dmtf.org/registries/swordfish/v1

Developers may also download the schema as part of the Swordfish bundle from snia.org (refer to snia.org/swordfish for pointers to the bundle locations).

Implementations should refer either to the versions available on the dmtf.org site or to locally provided instances of the registries.

7.7.2 Profiles

The primary online source for the Swordfish registries shall be co-located on the DMTF profile site with the Redfish profile: http://redfish.dmtf.org/profiles/swordfish/v1

Developers may also download the profiles as part of the Swordfish bundle from snia.org (refer to snia.org/swordfish for pointers to the bundle locations).

Implementations should refer either to the versions available on the dmtf.org site or to locally provided instances of the profiles.

8 Implementation requirements

8.1 Security

This document generally adheres to the security requirements defined in the Redfish Specification. It extends the Redfish security model in one important way:

Swordfish implementations shall implement TLS as per the guidance in ISO/IEC 20648 and the TLS Specification for Storage Systems.

8.2 General constraints

8.2.1 Redfish elements

The Swordfish service interface extends the Redfish service interface. As such, a Swordfish service is a Redfish service and all required elements of the Redfish model shall be present in a Swordfish model.

A Swordfish implementation shall conform to all requirements specified in the Redfish specifications.

Swordfish functionality shall not conflict with any previously defined Redfish functionality but it may add to or extend it, and it may add additional constraints on Redfish functionality.

Additionally, any functionality desired in a Swordfish implementation that is specified in Redfish shall follow the requirements as specified in the Redfish specification.

8.2.2 Storage Events

8.2.2.1 Overview

A Swordfish implementation should implement an event service. Redfish defines the Event Service framework, client subscription model, event delivery mechanism, as well as standard message registries. Swordfish extends the standard message registries to provide additional message registries that correspond to Swordfish-specific services and properties.

The Redfish event service publishes a list of event types supported, and maintains a list of clients that have subscribed. Each subscription maps clients, subscribed events, and the resources that generate them.

8.2.2.2 Message Registry Selection and Management

Swordfish constrains the existing event model to provide a more consistent handling of event notifications and the related messages, in order to assure that client systems can easily and consistently parse and respond to system-level events.

8.2.2.3 Required Usage

• The Resource Event Message Registry defines the underlying messaging model, and shall be used to map messages to resources for storage implementations.
• The Redfish Base Message Registry shall be used to support HTTP connection/error/protocol issues, and general errors.
• The Swordfish Message Registry shall be used as a supplement for the resource event message registry.
• If the Swordfish service implements Redfish tasks (i.e., long-running operations), the implementation shall use the messages defined in the Task Event Message Registry to report status.

8.2.2.4 Recommended Usage

• Standard Messages should be used, wherever possible.
• OEM messages should be avoided. Suggestions for clarification or expansion of the existing registries are encouraged. (submissions should be sent to the SNIA Feedback Portal)

8.2.3 Health and HealthRollup Propagation

8.2.3.1 Overview

The Status object includes both a Health property, intended to reflect the health of a given resource or component in a standardized way, and a HealthRollup property, which is meant to aggregate the health of a hierachy of subordinate or associated resources or components. Swordfish introduces some additional guidance around the proper use of these two properties.

8.2.3.2 Status.Health

The Redfish schema requires that Status.Health “represent the health state of the resource without considering its dependent resources.” While Swordfish defines no change to that usage, implementors are encouraged to assure that the information reflected in Status.Health reflects solely the state of the reporting object. For example, a given StoragePool instance can report OK for its own Status.Health, even if a volume is reporting a Status.Health value of Critical because it has exceeded a space quota and been taken offline, as the storage pool itself has no issues.

8.2.3.3 Status.HealthRollup

The Redfish schema requires that Status.HealthRollup “represent the health state of the resource and its dependent resources”. As a general rule, Status.HealthRollup is intended to aggregate any error conditions found in subordinate levels in a hierarchy of components or subsystems, and allow a client to traverse the hierarchy to locate the underlying source of a problem or error state. At the same time, an implementation should not blindly retain the severity of a component-level problem, when higher-level objects or systems provide additional protection against serious failure or data loss. Accordingly:

• Status.HealthRollup shall represent the general health of the reporting resource and its dependent resources, and shall not report an value of OK if the status.health value of any dependent resource reports a value other than OK;
• Status.HealthRollup should propagate a lower-level error status and its severity, particularly if the reporting resource doesn’t introduce additional redundancy or error protection;
• Status.HealthRollup may report a lower level of severity than that returned by Status.Health of one of its dependent resources, provided that the ability to traverse the resource hierarchy to the root cause of a subordinate error is preserved. In particular, while a Status.Health value of Critical may be downgraded to Warning, a Warning value should not be downgraded to OK, as the ability to locate the root cause the subordinate error would be lost.

8.3 Discovering Swordfish resources

Each Swordfish implementation supports the following well-known URLs, as defined in Redfish. Specifically:

• /Redfish, which contains one or more version properties for the integrated Swordfish and Redfish implementation, starting with v1.
• /Redfish/v1, which addresses a ServiceRoot instance, which defines the Redfish default principal starting information for version 1 implementation of an integrated Redfish and Swordfish service. A GET operation to it shall retrieve the value of an instance of a ServiceRoot EntityType as defined in the ServiceRoot_v1.xml file.
• /Redfish/v1/$metadata, an OData metadata document containing descriptions of all top-level service resources and resource types used in the implementation. $metadata contains a list of all the current schema instrumented in the service. Clients querying the $metadata URI will get a comprehensive view of all implemented schema.
• /Redfish/v1/odata, which addresses a ServiceContainer instance, which defines OData conformant principal starting information for the same version 1 implementation of an integrated Redfish and Swordfish service. A GET operation shall retrieve the value of an instance of a ServiceContainer EntityContainer as defined in the ServiceRoot_v1.xml file.

Note: Since the ServiceContainer is required to return an @odata.context value of /redfish/v1, all other elements accessed via it will be the same elements found via the ServiceRoot.

A Swordfish service is a Redfish service with extensions to support storage management. No additional service entry-points are required by Swordfish.

Both the ServiceRoot and ServiceContainer provide access to the same resource collections. The ServiceContainer additionally has a Service attribute that references the ServiceRoot resource. Regardless of starting point, the property values of the ServiceRoot instance enable navigation to all other resources exposed by the Swordfish service.

8.3.1 Required Collections for Storage implementations

Swordfish implementations shall include the use of either Storage or StorageService objects.

If an implementation contains a Storage instance, the redfish/v1/Storage collection shall be implemented, and shall contain references to all Storage objects. This collection may also contain the primary instances of Storage objects.

If an implementation contains a StorageService instance, the redfish/v1/StorageServices collection shall be implemented, and contain references to all StorageService objects. This collection shall serve as the primary collection to contain StorageService instances.

8.4 ClassOfService requirements

Each ClassOfService shall include at least one line of service. The providing server shall assure that the line of service values of a ClassOfService collectively represent a supported choice of service.

8.5 HTTP status codes

8.5.1 Overview

Status codes are generally defined as part of the general HTTP protocol definition. In addition, the Redfish specification calls out general usage for HTTP status codes. This section provides additional usage guidance and constraints for Swordfish implementations.

In some instances, Redfish and Swordfish expand the standard use of HTTP status codes by associating additional system status with specific status codes. In addition, error response data may be included via standardized message registry entries. The specific messaging requirements will be defined in the following sections.

In cases where Swordfish adds additional constraints or expands on the Redfish handling of a given issue, this document will include a small wording extract from the Redfish specification for additional context. For example:

Swordfish refines the requirements in the Redfish Specification: Redfish has no constraint on external storage functionality to require that all references to external storage functionality shall be compliant with the current release of Swordfish.

8.5.2 Create

If a request to create a resource can be completed successfully without additional time, the Redfish service shall return a status code of 201, and the body of the response shall contain the JSON representation of the newly created resource.

If the create resource request has been accepted, but no information about the resource can be returned at this point, the Redfish service shall return a status code of 204. The payload of the response shall be empty, but the Location header shall contain the resource URI. The client will be required to poll the appropriate resource to determine both when and if the operation is complete.

Swordfish refines the requirements in of the Redfish Specification (see “Data modification requests overview” and “Asynchronous operations”).

If a request to create a resource cannot be completed without additional time, the implementation shall:

• Populate an initial object. It shall contain, at a minimum, a valid URI, required properties (e.g., ID, name), and Status.State;

• Set Status.State of the partially populated resource to “Creating”;

• Return the appropriate status code, based on the following guidance:

  • If a Task Service has been implemented, the Redfish service shall return a status code of 202, with the Location header set to the URI of the Task Monitor. Once the provider has returned a Task Monitor to the client, the Client can then query the provided task URI to track the task completion status. Upon task completion, a GET against the task monitor may return a status code of 201, and the body of the message shall contain the created resource, provided the task monitor URI remains valid . Refer to the Redfish Task Manager documentation for the lifecycle of the task monitor URI.

  • If a Task Service has not been implemented, the Redfish service shall return a status code of 201, and the body of the response shall contain the URI of the skeletal resource created as part of accepting the request. The client will be required to poll the URI provided to determine when the operation is complete.

• Update Status.State for the object, once the create operation completes.

8.5.3 Update, Replace, Delete

If a request to modify or delete a resource can be completed without additional time, the Redfish service shall return a status code of 200, and the body of the response shall contain the JSON representation of the modified (or deleted) resource.

If the resource modification or deletion request has been accepted, but no information about the resource can be returned at this point, the Redfish service shall return a status code of 204. The payload of the response shall be empty. The client will be required to poll the appropriate collection to determine both when and if the operation is complete.

If a request to modify a resource cannot be completed without additional time, the implementation shall:

• Set Status.State of the partially populated resource to “Updating” or “Deleting”, as appropriate;

• Return the appropriate status code, based on the following guidance:

• If a Task Service has been implemented, the Redfish service shall return a status code of 202, with the Location header set to the URI of the Task Monitor. Once the provider has returned a Task Monitor to the client, the Client can then query the provided task URI to track the task completion status. Upon task completion, a GET against the task monitor may return a status code of 201, and the body of the message shall contain the created resource, provided the task monitor URI remains valid . Refer to the Redfish Task Manager documentation for the lifecycle of the task monitor URI.

• If a Task Service has not been implemented, the Redfish service shall return a status code of 200, and the body of the response shall contain the URI of the skeletal resource created as part of accepting the request. The client will be required to poll the URI provided to determine when the operation is complete.

• For an update or replace request, the implementation shall update Status.State for the resource, once the modify operation completes.

8.5.4 Actions

Swordfish supports the approach to Actions in the Redfish Specification:

Actions are Redfish operations that do not easily map to RESTful interface semantics. These types of operations may not directly affect properties in the Redfish Resources.

Swordfish refines the requirements in the Redfish Specification: Services shall support the POST method to send actions to Resources.

If a Task Service has been implemented, the Redfish service shall return a status code of 202, with the Location header set to the URI of the Task Monitor. Once the provider has returned a Task Monitor to the client, the Client can then query the provided task URI to track the task completion status. Once the task has completed successfully, a GET against the task monitor shall return the created object.

If a Task Service has not been implemented, the Redfish service shall return a status code of 200, and the body of the response shall contain the URI of the skeletal resource created as part of accepting the request. The client will be required to poll the URI provided to determine when the operation is complete. When processing actions, the handling of HTTP status codes is slightly different than that seen when processing CREATE or MODIFY requests. The HTTP status code is used to reflect the acceptance and formatting of the request. The outcome of any requested processing is reflected in the body of the returned message and its associated Error response structure. For example, a properly formatted request to execute a system reset may return an HTTP status code of 200 (OK), to reflect that the request has been received, was validly formatted, and has been accepted for processing, while the reset of the system may not complete successfully. The Error response structure would contain further detail of the success of failure of the system reset. The implementation must check both the HTTP status code and the underlying Error response message structure to confirm the successful execution of the action.

9 Swordfish type definitions

9.1 Overview

The following sections define the schema and type definitions that make up a Swordfish implementation. Each data type or entity within the schema includes a description that defines its implementation requirements and their interaction.