StorageGRID API Reference Guide -...

StorageGRID® 9.0StorageGRID API Reference

NetApp, Inc.495 East Java DriveSunnyvale, CA 94089 U.S.A.Telephone: +1 (408) 822-6000Fax: +1 (408) 822-4501Support telephone: +1 (888) 463-8277Web: http://www.netapp.comFeedback: [email protected]

Part number: 215-06990_B0February 2013

http://www.netapp.com

mailto:[email protected]

Copyright and trademark information

Copyright information

Copyright © 1994-2013 NetApp, Inc. All rights reserved. Printed in the U.S.A.

No part of this document covered by copyright may be reproduced in any form or by any means—graphic, electronic, or mechanical, including photocopying, recording, taping, or storage in an electronic retrieval system—without prior written permission of the copyright owner.

Software derived from copyrighted NetApp material is subject to the following license and disclaimer:

THIS SOFTWARE IS PROVIDED BY NETAPP "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, WHICH ARE HEREBY DISCLAIMED. IN NO EVENT SHALL NETAPP 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.

NetApp reserves the right to change any products described herein at any time, and without notice. NetApp assumes no responsibility or liability arising from the use of products described herein, except as expressly agreed to in writing by NetApp. The use or purchase of this product does not convey a license under any patent rights, trademark rights, or any other intellectual property rights of NetApp.

The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications.

RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.277-7103 (October 1988) and FAR 52-227-19 (June 1987).

Trademark information

NetApp, the NetApp logo, Network Appliance, the Network Appliance logo, Akorri, ApplianceWatch, ASUP, AutoSupport, BalancePoint, BalancePoint Predictor, Bycast, Campaign Express, ComplianceClock, Cryptainer, CryptoShred, Data ONTAP, DataFabric, DataFort, Decru, Decru DataFort, DenseStak, Engenio, Engenio logo, E-Stack, FAServer, FastStak, FilerView, FlexCache, FlexClone, FlexPod, FlexScale, FlexShare, FlexSuite, FlexVol, FPolicy, GetSuccessful, gFiler, Go further, faster, Imagine Virtually Anything, Lifetime Key Management, LockVault, Manage ONTAP, MetroCluster, MultiStore, NearStore, NetCache, NOW (NetApp on the Web), Onaro, OnCommand, ONTAPI, OpenKey, PerformanceStak, RAID-DP, ReplicatorX, SANscreen, SANshare, SANtricity, SecureAdmin, SecureShare, Select, Service Builder, Shadow Tape, Simplicity, Simulate ONTAP, SnapCopy, SnapDirector, SnapDrive, SnapFilter, SnapLock, SnapManager, SnapMigrator, SnapMirror, SnapMover, SnapProtect, SnapRestore, Snapshot, SnapSuite, SnapValidator, SnapVault, StorageGRID, StoreVault, the StoreVault logo, SyncMirror, Tech OnTap, The evolution of storage, Topio, vFiler, VFM, Virtual File Manager, VPolicy, WAFL, Web Filer, and XBB are trademarks or registered trademarks of NetApp, Inc. in the United States, other countries, or both.

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. A complete and current list of other IBM trademarks is available on the Web at www.ibm.com/legal/copytrade.shtml.

Apple is a registered trademark and QuickTime is a trademark of Apple, Inc. in the U.S.A. and/or other countries. Microsoft is a registered trademark and Windows Media is a trademark of Microsoft Corporation in the U.S.A. and/or other countries. RealAudio, RealNetworks, RealPlayer, RealSystem, RealText, and RealVideo are registered trademarks and RealMedia, RealProxy, and SureStream are trademarks of RealNetworks, Inc. in the U.S.A. and/or other countries.

All other brands or products are trademarks or registered trademarks of their respective holders and should be treated as such.

NetApp, Inc. is a licensee of the CompactFlash and CF Logo trademarks. NetApp, Inc. NetCache is certified RealSystem compatible.

2 Copyright and trademark information

ContentsCopyright and trademark information . . . . . . . . . . . 2

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12About the StorageGRID System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12About the StorageGRID API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

StorageGRID API Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Object Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Object Retrieval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Object Deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Object Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Metadata Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Grid Topology Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Auditing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2 UUID Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

UUIDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Predefined Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Metadata Available to Applications . . . . . . . . . . . . . . . . . . . . . . . . . 24

StorageGRID Data Management Features . . . . . . . . . . . . . . . . . . . . . . . 26DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Request Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Request Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Response Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Response Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Request Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Object and Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Request Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Request Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Response Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Response Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

NetApp StorageGRID 3215-06990_B0

StorageGRID API Reference

Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Request Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Metadata Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Request Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Request Message Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Response Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Response Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Request Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Last Access Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Request Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Request Message Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Response Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Response Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Request Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Request Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Request Message Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Response Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Response Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Request Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Request Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Request Message Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Response Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Response Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Request Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

4 NetApp StorageGRID215-06990_B0

Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Request Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Request Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Response Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Response Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Request Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Request Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Request Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Response Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Request Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Response Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Object Query Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Application Design Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Object Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Submitting Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Updating Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Computing and Verifying Hash Values . . . . . . . . . . . . . . . . . . . . . . 66Using Predefined Metadata XAID, XTYP, XVER . . . . . . . . . . . . . . 66Query Number of Copies Before Deleting Local Copy . . . . . . . . . 67Query Number of Copies When Using Dual Commit . . . . . . . . . . 67Embedding UUIDs into Stored Objects . . . . . . . . . . . . . . . . . . . . . . 67PUT Response Delays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Object Containerization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Object Retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Requesting Location Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Requesting Metadata Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Retrieval During “Islanding” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Object Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70WAN Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Network Transfer Compression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

3 GRID Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Request Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74



Request Message Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Response Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Response Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Request Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Request Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Request Message Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Response Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Response Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Request Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Grid Query Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

4 AUDIT Namespace . . . . . . . . . . . . . . . . . . . . . . . . . 91Audit Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

HTTP Audit Feed Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Best Practices for HTTP Audit Feed Messages. . . . . . . . . . . . . . . . . 92

HTTP Audit Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Request Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Request Message Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Response Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Response Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Request Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Request Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Request Message Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Response Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Response Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Request Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99


Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Request Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Request Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Response Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Response Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Request Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Request Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Request Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Response Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Response Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Request Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Best Practices for POST Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Multiple Audit Messages per POST Transaction . . . . . . . . . . . . . . 107Dedicated Session for Audit Messages . . . . . . . . . . . . . . . . . . . . . . . 107

Audit Message XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

5 HTTP Session Management . . . . . . . . . . . . . . . . . . . 109Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Establishing an HTTP Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Port Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Gateway Node IP Address Configuration . . . . . . . . . . . . . . . . . . . . . . . 112Session Duration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Idle Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Active Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Concurrent Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Number of Concurrent Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Read and Write Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Configuring Pool Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Balancing Load Across Multiple Gateway Nodes. . . . . . . . . . . . . . 116

Time Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Time Differences Between Grid and Application . . . . . . . . . . . . . . . . . 117Using Grid Time in Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Secure Connections with TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Hashing and Encryption Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

HTTP Transaction Coverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Interaction Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119HTTP Transaction Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120



OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Request Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Request Message Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Response Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Response Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Response Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Request Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

A Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Configure the Grid to Accept Connections . . . . . . . . . . . . . . . . . . . . . . . . . 125

Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Acquire the Grid’s CA Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Security Partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Security Partition Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Partitions and HTTP Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Partitions and Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Acquiring Client Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Security Partitions and Deduplication . . . . . . . . . . . . . . . . . . . . . . . . . . 134Enable Security Partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Configure Security Partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Finding IP Addresses for Grid Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Test HTTP Access to the Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Enable the HTTP Audit Feed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Duplicate OIDs in Grid Node Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . 147

B Reference Information . . . . . . . . . . . . . . . . . . . . . . 149Standards Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149HTTP Standard Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150HTTP Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156XML Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

C Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

About the Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Find LDR for Object Storage (POST Grid Query) . . . . . . . . . . . . . . . . . . . . 159Store Object (PUT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Find Object (POST Object Query) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165


Find LDR for Object Retrieval (POST Grid Query) . . . . . . . . . . . . . . . . . . 167Retrieve Object (GET) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Delete Object (DELETE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Confirm Object Deletion (HEAD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Submit Audit Message (POST) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Retrieve an Audit Message (GET) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Delete an Audit Message (DELETE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179




1
IntroductionStorageGRID system and StorageGRID API capabilities
Revision History

Table 1: Revision History

Date Release Comments

14 Feb. 2013 9.0.1 Removed references to custom metadata.

19 July, 2012 9.0

Obsoleted DICOM.

Introduced acronym for StorageGRID API: SGAPI.

Added information about last access time.

Added GET & PUT for updating metadata.

Deprecated deduplication.

20 Aug., 2010 8.5.3 Updated X-SYS-ENCRYPT to add AES128, AES256, and DISABLE.

Update to TSM Management Classes section: TSM/SSAM updated to TSM server.

Accept-Encoding updated.

Updated SHA-1 to SHA-256 for X-HASH header.

Update DELETE and GET to include bulk retrievals and deletions for the HTTP audit feed.

Accept-Encoding and Content-Encoding added. Related Response Status updated.

Updated “Configure Security Partitions” procedure.

Updated encryption and compression to stored object encryption stored object compression.

Updates for network transfer compression functionality. Added new header for GET and DETLE for UUID namesapce and new Response Status codes 406 and 415.

Updated HTTP Status Codes to include 406 Not Acceptable.

Updated event feed to include default audit messages that are retrieved.

Updated event feed name to HTTP audit feed.



Intended AudienceThis guide is intended for technical managers who wish to gain a basic understanding of the StorageGRID API (SGAPI) and for developers who are creating applications that interface with the StorageGRID system.

This document assumes familiarity with the many terms related to computer operations and programming, network communications, and operating system file operations. There is wide use of acronyms.

About the StorageGRID System

The StorageGRID system is a storage management solution that stores, protects, and preserves fixed-content data over its lifetime. Content and content metadata storage is managed using a set of Information Lifecycle Management (ILM) business rules.

A StorageGRID deployment consists of a collection of nodes running on multiple servers. Each node performs a specialized set of tasks.

Added list of messages queued in the HTTP audit feed.

Added the X-SYS-ENCRYPT request header in the HTTP PUT request to control storage encryption on a per-object basis.

Added X-SYS-COMPRESS header in the HTTP PUT request to control storage compression on a per-object basis.

Added GET and DELETE for event feed to the Audit Namespace chapter.

GET and PUT in the UUID namespace now return the X-HASH header.

18 Jan., 2010 8.1 Reorganized content. Added new illustrations, best practices, and Ruby examples.

20 July, 2009 8.1 Updated for the release of StorageGRID 8.1.

Table 1: Revision History (cont.)

Date Release Comments


Introduction

Figure 1: StorageGRID System Logical Components

E-mail Server

Network Management

System

HTTPClients

NFS/CIFS Clients

AuditClients

Web Admin Clients

HTTP Clients

Custom

er Client N

etwork

SMTP

SNMP

HTTPS

CIFS/NFS

NFS/CIFS

HTTPS

HTTPS

File System Interface

(FSG)

HTTP Load Balancer

(CLB)HTTPS

NFS/CIFS

NFS/CIFS

AdminInterface

(CMN/NMS)

Audit Repository

(AMS)

HTTPS

SG

AP

I or CD

MI Internal N

etwork / Internet

HTTPS

HTTPS

Grid S

torage Netw

ork

SNMP

SMTP

Object Store (LDR)

Object Store (LDR)

Object Store (LDR)

HTTPS

HTTPS

HTTPS

GRID

GRID

GRID

GRID

GRID

GRID

GRID

ObjectManager

(CMS/ADC)

Object Store(LDR)

CustomerStorage

SCSI/SAS/SATA/FC/

NetAppStorage

GRID Object Store(ARC)

CustomerStorage(TSM)

TSM API

FC/SAS/NFS/iSCSI

Table 2: StorageGRID Nodes

Node Name Description Belongs to

ADC Administrative Domain Controller

Maintains topology information and provides authentication services.

Control Node

AMS Audit Management System

Tracks grid activity and events. Admin Node or Audit Node

ARC Archive Communicates with archiving mid-dleware to store and retrieve data to and from archive media.

Archive Node

CLB Connection Load Balancer

Acts as switchboard for connecting remote entities to the most efficient LDR. Primary connection point for remote entities using the HTTP protocol.

Gateway Node

CMN ConfigurationManagement Node

Manages grid-wide configurations, for example, connection profiles, grid tasks, and grid options.

Primary Admin Node

CMS Content Management System

Keeps track of the data stored in the grid. Stores content metadata and manages content replication based on ILM rules.

Control Node

FSG File System Gateway Allows connections to the grid via standard file sharing protocols (CIFS/NFS).

Gateway Node



For an introduction to the StorageGRID system, see the Grid Primer. For technical information and configuration procedures, see the Administrator Guide.

About the StorageGRID API

The simplest way to interface to the StorageGRID system is through the FSG on the Gateway Node. The FSG acts as a client to the grid. It presents a CIFS or NFS file system to external entities and manages content submission to the grid for storage. The FSG also replicates its file system to multiple FSGs within the grid for redundancy. If your current storage application saves data to a file system, you can simply redirect it to write and retrieve data from an FSG that is configured to accept connections from your application. This does not require the use of the StorageGRID API (SGAPI).

Developing a custom application that uses the StorageGRID API removes the file system layer of abstraction and gives a greater degree of control over how and where data is stored. By using HTTP commands submitted over a network connection that uses Transport Layer Security (TLS), the StorageGRID API enables the storage and retrieval of objects; the storage, retrieval, and update of object meta-data; and provides a notification mechanism for stored objects and the operational state of the grid.

The StorageGRID API allows the use of metadata that can be used to facilitate object identification and retrieval and enable the execution of custom business rules based on the metadata. As well, this metadata can be updated so that business rules based on the metadata can be reapplied to an object.

LDR Local Distribution Router

Stores, moves, verifies, and retrieves object data stored on disks.

Storage Node

NMS Network Management System

Used to monitor grid status and to configure the grid.

Admin Node

SSM Server Status Monitor

Monitors hardware performance such as key operating system metrics and network metrics.

Present on all servers

Table 2: StorageGRID Nodes (cont.)

Node Name Description Belongs to


Introduction

Each object stored within the StorageGRID system is assigned a uni-versally unique identifier (UUID) or “content handle” which can be used to retrieve the object. Third-party application manage access to the data by maintaining a database of content handles (UUIDs), or through a system of queries based on metadata submitted at the time the object was stored.

StorageGRID API CapabilitiesFor compatibility with internal legacy tools, HTTP 1.0 messages are accepted without triggering a 505 error. However, it is recommended that you not rely upon this behavior.

The StorageGRID API provides the ability to store, retrieve and delete objects, use and update metadata, and generate an application-specific audit trail.

The StorageGRID API uses standard HTTP commands that conform to the HTTP version 1.1 RFC. The use of standard commands allows rapid development and prototyping, and allows existing HTTP librar-ies to be used without requiring custom development for low level communication and protocol handling. For information about the HTTP protocol and its uses, see the references listed in Appendix B: “Reference Information”.

The StorageGRID API does not support pipelining of client requests as defined in section 8.1.2.2 of RFC 2616.

As the StorageGRID system is concerned with the storage, query, and retrieval of content, only the core HTTP storage and retrieval function-ality are supported by the StorageGRID API and covered in this document. In addition, the StorageGRID API includes several exten-sions to provide enhanced metadata management.

As well, the StorageGRID API optionally supports gzip compression for both ingest and retrieval.

Object Storage

Object storage is provided by the HTTP PUT method. To store objects via the StorageGRID API, the client application must establish a con-nection directly with the grid, usually via a CLB. The CLB identifies the optimal LDR to receive the object and forwards the storage request to that LDR. The LDR stores the object and assigns the object a unique identifier (UUID).

A simple transaction consists of the interactions shown in Figure 2:1. The application opens a TCP/IP connection to the configured

HTTP port on a CLB.2. The connection is acknowledged.



3. The application issues an HTTP PUT request that includes the object and object metadata.

4. The CLB identifies the optimal LDR to satisfy the request and forwards the request to that LDR.

5. After the LDR has stored a copy of the object, the LDR returns the object’s UUID.

Figure 2: Simplified PUT Transaction

After an object has been ingested, the grid makes additional copies of the object in other storage locations as needed to meet the business rules established for the data. If desired, the application can retrieve information about the number of copies, the location, and the location type of these copies in the grid. This information can be used to confirm the operation of business rules, enabling the application to take action based on the completion of grid replication tasks.

For information on storing objects and metadata, see “PUT” on page 52 in Chapter 2: “UUID Namespace”.

Object Retrieval

StorageGRID API retrieval transactions are performed when stored content is retrieved from the grid (HTTP GET method).

In addition to retrieving the contents of stored objects and the metadata associated with stored objects, an application can request to receive either a count of the number of locations where the object is stored, or the actual list of servers and location type (LDR or ARC) for

2. Connection established

Application CLB Optimum LDR for storage

3. PUT transaction specifying metadata

and including content 4. Identify optimum LDR and forward request to LDR including

content

5. PUT responseStatus code 201 Created

Return UUID

1. Open TCP/IP connection to port 8081 on a CLB


Introduction

each location where the object is stored. This list can be filtered to return only the count or locations of a specific type.

The application can retrieve an object by directly specifying its UUID, or can first identify the object to be retrieved using a query on the metadata.

A simple transaction consists of the interactions shown in Figure 3:1. The application opens a TCP/IP connection to the configured

HTTP port on a CLB.2. The connection is acknowledged.3. The application issues an HTTP GET request, specifying the UUID

of the object to be retrieved.4. The CLB identifies the optimal LDR to satisfy the request and

forwards the request to that LDR. 5. If the requested object is found, the LDR returns the actual object

and any requested metadata.

Figure 3: Simplified GET Transaction

For information on retrieving objects and metadata, see “GET” on page 30 and “HEAD” on page 38 in Chapter 2: “UUID Namespace”.

Object Deletion

StorageGRID API object removal transactions are performed when existing stored objects are marked as no longer referenced by the API client.

2. Connection established

Application CLB Optimum LDR for retrieval

1. Open TCP/IP connection to port 8080 on a CLB

3. GET transaction specifying UUID

4. Identify optimum LDR and forward request to LDR

5. GET responseStatus code 200 OKReturn content and

any requested metadata



When an application no longer needs the grid to retain a stored object, it can indicate that the object is no longer needed by performing an HTTP DELETE transaction for the object. Once a DELETE transaction is performed, the specified object can no longer be retrieved and will no longer show up in queries.

However, a DELETE transaction does not necessarily correspond to the actual deletion of the object. The behavior when a DELETE transaction is performed is based on the ILM rules for the content that has been deleted. For example, the grid can be configured such that when an object has been marked for deletion via the StorageGRID API, it is placed on a tape tier of storage. Another grid or type of content may be configured to be deleted at the time a DELETE transaction is per-formed. For information on deleting objects, see “DELETE” on page 28 in Chapter 2: “UUID Namespace”.

Object Queries

The StorageGRID API provides the ability to specify metadata associ-ated with stored objects, and the ability to retrieve and query the metadata.

Metadata query is provided by the HTTP POST method. Metadata associated with objects use a standard extension to the HTTP headers; the request and response are encoded in XML. For information on creating object queries, see “POST” on page 44 in Chapter 2: “UUID Namespace”.

Metadata Updates

As well as specifying metadata, the StorageGRID API provides the means to update the metadata associated with stored objects. Metadata can be updated, added, and deleted from any ingested object to which the StorageGRID API client has access. Metadata update is provided by the HTTP PUT method.

Updating an object’s metadata triggers an ILM reevaluation of the object and may result in a change to an object’s placement in the grid based on an ILM rule’s metadata filters. For more information on ILM rules, see the Administrator Guide. For more information on updating metadata, see Chapter 2: “UUID Namespace”.


Introduction

Grid Topology Queries

Through the StorageGRID API, external applications can assess the operational state of the grid and determine which grid services are avail-able to handle transactions. This is done using the POST method; the request and response are encoded in XML. For information on creating grid queries, see Chapter 3: “GRID Namespace”.

Auditing

The grid provides secure and reliable transportation of audit messages from each service within the grid to one or more audit repositories. The audit messages generated by the grid provide critical security, opera-tions and performance monitoring data.

Through the StorageGRID API, external applications can also generate and publish audit messages through to the grid. This enables applica-tion-specific audit messages to be included in the grid audit log. Typically, this is used to build integrated monitoring and management systems around the grid audit facility; for example, QoS monitoring in a large multi-site distributed application and cross-department billing systems for shared storage grids.

Generating custom audit messages is done using the POST method; the request and response are encoded in XML. As well, the audit feed can be enabled to allow specific messages to be queued and retrieved through the StorageGRID API using GET and DELETE.

For more information on audit messages, see Chapter 4: “AUDIT Namespace”.




2
UUID NamespaceHow to work with objects
Introduction

External applications use the UUID namespace to store, access, query, and delete objects using the unique identifier (UUID) assigned to each object stored in the grid.

The HTTP methods allowed in the UUID namespace are:• DELETE

• GET

• HEAD

• OPTIONS

• POST

• PUT

UUIDsThe UUID assigned by the grid for external access provides an abstracted primary key for stored content. UUIDs are 128 bits with an internal binary structure and a string representation in the form A-B-C-D-E, where:• A is 8 hex digits• B is 4 hex digits• C is 4 hex digits• D is 4 hex digits • E is 12 hex digits

Each hex digit can take the values from 0 to 9, A through F (or lower-case a through lowercase f). This is an example of a UUID:

F81D4fAE-7DEC-11D0-A765-00A0C91E6BF6

The UUIDs generated by the grid use randomly generated values as described in section 4.4 of IETF RFC 4122 found at:



http://www.ietf.org/rfc/rfc4122.txt. Client applications should not depend on the use of this type of UUID.

It is possible for multiple UUIDs to map to a single object. For example:1. An object is submitted by a first user and is assigned UUID

“AA111111-AA11-AA11-AA11-1111111111111”.2. A second user, unaware that the object has already been stored into

the grid, submits the same object which is assigned UUID “BB222222-BB22-BB22-BB22-222222222222”.

Figure 4: UUID to Object Mapping3. As the grid works through its business rules, it recognizes the two

objects as being identical. In this example, a rule is imposed to con-solidate duplicate objects. The grid deletes one of the objects and maps both UUIDs to a single object. Now, a single managed object is the target of two UUID mappings.

Figure 5: Two UUIDs Mapped to a Single Object

Copy # 1Lorem ipsum dolor sitamet, consectetueradipiscing elit, sed ...


AA111111-AA11-AA11-AA11-111111111111

BB222222-BB22-BB22-BB22-222222222222

Client

Client

/UUID Object



AA111111-AA11-AA11-AA11-111111111111

BB222222-BB22-BB22-BB22-222222222222

Client

Client

/UUID /CBID


http://www.ietf.org/rfc/rfc4122.txt

UUID Namespace

Both users still have access to the stored object, using either UUID. Neither is aware that the grid is managing this as a single object. Should one user delete their “copy”, the grid retains the object and access to it using the alternate UUID. Should both UUID handles be deleted, the file continues to exist under grid management as an object but without any UUID access. Business rules may permit the grid to purge objects that no longer have UUID handles.

Metadata

Predefined Metadata

Predefined metadata is associated with an object either by the Storage-GRID API (SGAPI) client or, if ingested via an FSG, by the FSG at the time of ingest. Unless otherwise noted, once ingested into the grid, predefined metadata becomes read-only and cannot be deleted. Pre-defined metadata have the form X-BYC-XXXX where XXXX is one of the following:

Table 3: Predefined Metadata

Metadata Writable Description

XAID Read-only Set by StorageGRID API client or on ingest via an FSG. Identi-fies the external application that stored the object. For details, see “X-BYC-XAID” on page 54.

XTYP Read-only Set by StorageGRID API client or on ingest via an FSG. Identi-fies the type of object saved to the grid. For details, see “X-BYC-XTYP” on page 54.

XVER Read-only Set by StorageGRID API client or on ingest via an FSG. Defined by the application. For details, see “X-BYC-XVER” on page 54.

MCLS Read-only Set by StorageGRID API client on ingest. Indicates the TSM management class. Defined by the application. For details, see “Multiple TSM Management Classes” on page 26 and “X-BYC-MCLS” on page 54.

STR0-STR9 Read-write

Can be deleted

Set by StorageGRID API client. Identifies a string value. Value defined by the application.

NUM0-NUM9 Read-write

Can be deleted

Set by StorageGRID API client. Identifies a numerical value. Value defined by the application.

FPTH Read-only Set on ingest via an FSG. Indicates the FSG file path at ingest.



Metadata Available to Applications

The StorageGRID API provides the ability to specify metadata associ-ated with stored objects. The metadata can then be retrieved, queried, updated, or deleted.

For example, an application that has an application-specific identifier (XAID) for objects can store this identifier with each object, and then use a metadata query to identify which object corresponds to the application-specific identifier. The application can also use metadata to perform object introspection by examining the associated metadata, and can use the metadata to query for specific objects that match metadata criteria.

MODE Read-only Set on ingest via an FSG. Indicates the file system status for the object at ingest.

FUID Read-only Set on ingest via an FSG. Indicates the user ID associated with the object at ingest.

FGID Read-only Set on ingest via an FSG. Indicates the group ID associated with the object at ingest.

CTIM Read-only Set on ingest via an FSG. Indicates the Linux ctime associated with the file at ingest.

MTIM Read-only Set on ingest via an FSG. Indicates the modification time asso-ciated with the object at ingest.

FGRP Read-only Set on ingest via an FSG. Indicates the FSG replication group of the FSG via which the object is ingested.

FSGN Read-only Set on ingest via an FSG. Indicates the FSG backup node ID for the object.

RPLG Read-only Set on ingest via an FSG. Indicates the FSG replication group for the FSG backup.

NSID Read-only Set on ingest via an FSG. Indicates the next FSG backup pending session ID.

NXSC Read-only Set on ingest via an FSG. Indicates the sequence count of the next FSG replication message to be processed in the next session pending.

NSNI Read-only Set on ingest via an FSG. Indicates the node ID of the next session pending.

BUID Read-only Set on ingest via an FSG. Indicates the FSG backup ID.

Table 3: Predefined Metadata

Metadata Writable Description


UUID Namespace

As the grid implements metadata storage and query over a distributed database, the way that metadata is used can have a major impact on the performance of the application. For this reason, it is important to specify what metadata fields are used by the application and whether they need to be indexed and queried.

If metadata for an object is modified (updated, added, or deleted) an ILM reevaluation against the object is triggered, which can control the placement of objects. For example, if several ILM rules filter on the value X-BYC-STR0 and the value of X-BYC-STR0 is changed for an object, the placement of this object can be controlled via metadata. For more information on ILM rules, see the Administrator Guide.

Table 4: Metadata Types

Item Description

Name The name must consist of four alphanumeric characters from the set a – z, A – Z, 0 – 9 and cannot be the same as any predefined metadata.

Names are case-insensitive (abcd and ABCD are equivalent) for HTTP PUT, GET and HEAD requests; however, for HTTP POST object queries, the metadata tag names are case-sensitive.

Data Type • CSTR for string dataX-BYC header values consisting of characters delimited by the " character are treated as strings. The characters permitted in string metadata (including escaping rules) are outlined in “Character Sets” on page 156.

• SI64 for numerical dataX-BYC header values consisting of decimal numbers preceded by an optional “+” or “-” character are treated as signed 64 bit integer (SI64) numbers. If no “+” or “-” is present, the number is assumed to be positive. The numeric value must be within the range from +9223372036854775807 to -9223372036854775808 (+263 - 1 to -263).



StorageGRID Data Management FeaturesThe custom application can be designed to make use of the following StorageGRID data management features:• Multiple TSM Management Classes • Dual Commit• Deduplication• GE Optimized Store

NOTE Deduplication and GE Optimized Store are deprecated and no longer supported.

Multiple TSM Management Classes

The Tivoli® Storage Management (TSM) management class is used by the TSM server to apply rules for data location or retention after objects are stored to the TSM by the Archive Node. TSM management classes and rules are managed and defined entirely by the TSM mid-dleware. Contact your TSM administrator to define appropriate

Queryability Describe how the metadata will be used in queries: • Unqueryable — Metadata cannot be used to identify objects to be retrieved from

the grid. The value of these items may be retrieved in the results of an object query or via a HEAD transaction. Use for metadata that you intend to store and retrieve but which will not be used to identify objects for retrieval. Consumes the least amount of storage.

• Queryable/Unindexed —Metadata may be used to help identify objects to be retrieved from the grid, usually in conjunction with Queryable/Indexed items. Queryable/Unindexed metadata items make poor database indexes, often because many objects have the same value for this metadata item.

• Queryable/Indexed — Metadata used to identify objects to be retrieved from the grid via object queries. Consume the most database space. Designating too many items as queryable/indexed can affect grid ingest performance.

If you plan to retrieve files based on their metadata (rather than based on their UUID), the metadata used in these queries must be specified as being “Queryable”.

Consider the nature of the data before deciding which metadata items to index: data with low cardinality (many objects have the same value) make poor database indexes. Specify a minimum of metadata items as indexed since indexed metadata consumes much more database space.

Table 4: Metadata Types (cont.)

Item Description


UUID Namespace

management classes and to configure the TSM appropriately for use with the Archive Node. For more information on TSM management classes, see the Installation Guide and the Administrator Guide.

Dual Commit

Dual commit forces two initial copies to be made of each object stored to the grid. These initial copies are made without consulting the grid’s ILM policy: objects are simultaneously queued for ILM evaluation. When the ILM rules are evaluated, additional copies may be made in different locations and the initial copies may be purged to free storage space. The two initial copies are made on a best effort basis: if creation of one initial copy fails, it is not retried. For more information on dual commit, see the Administrator Guide.

Deduplication

NOTE Deduplication is deprecated and no longer supported.

Applications storing multiple identical objects can use the deduplica-tion feature to reduce the total number of copies permanently stored to the grid. This feature is specifically intended for GE Enterprise Archive Server.

Because the computational load of deduplication is high, the cost of enabling deduplication is higher than that of storing extra copies of the objects except in specific circumstances. The use of this feature by custom applications is not recommended. Contact a NetApp Solutions Engineer for an evaluation before implementing any solution that uses deduplication. For more information on deduplication, see the Admin-istrator Guide.

GE Optimized Store

NOTE GE Optimized Store is deprecated and no longer supported.

Applications that store TAR files created by a GE Enterprise Archive (version 3.0 or later) can use the GE Optimized Store feature to reduce the total number of copies of data permanently stored to the grid.

Because the computational load of slicing and deduplication is high, the cost of enabling GE Optimized Store is higher than that of storing extra copies of the objects except in specific circumstances. The use of



this feature by custom applications is not recommended. Contact a NetApp Solutions Engineer for an evaluation before implementing any solution that uses GE Optimized Store. For more information on GE Optimized Store, see the Administrator Guide.

DELETE

SyntaxDELETE /UUID/uuid HTTP/1.1

where uuid = a UUID in the format specified in “UUIDs” on page 21.

Description

Make content unavailable to the client. Once a DELETE transaction is performed, the specified object can no longer be retrieved and will no longer show up in queries.

The behavior of a DELETE transaction depends on the ILM rules for the content that has been deleted. For example, the content can be con-figured such that an object marked for deletion via the StorageGRID API is placed on a tape tier of storage. Another type of content may be configured to be purged from the grid at the time a DELETE transac-tion is performed. The object can only be purged under business rules, not by an outside client.

Request Headers

For more on these headers, see “HTTP Standard Headers” on page 150.

Header Notes

Connection Default is KEEP-ALIVE

Optional

Date Optional

Host Mandatory

User-Agent Optional


UUID Namespace

Request Message Body

N/A

Response Status

For more on these status codes, see “HTTP Status Codes” on page 152.

Response Headers


Response Message Body

N/A

Request Example

This example shows the deletion of an object by an authorized client, where the object is specified by its UUID.

Code

202 Accepted

400 Bad Request

403 Forbidden

405 Method Not Allowed

408 Request Timeout

500 Internal Server Error

503 Service Unavailable

505 HTTP Version Not Supported

Header Notes

Content-Length Always 0 for DELETE

Date

DELETE /UUID/97D7C690-A4BE-4697-91EE-488C9B271B19 HTTP/1.1 Host: example.com



Response Example

The response from the server indicates that the deletion request was accepted (202 Accepted).

To confirm that the deletion was successful, use a HEAD transaction for the same UUID. See “HEAD” on page 38.

GET

Object and Metadata

Syntax

GET /UUID/uuid HTTP/1.1


Description

Retrieve content and all specified metadata.

Request Headers

For more on the standard headers, see “HTTP Standard Headers” on page 150.

HTTP/1.1 202 Accepted Date: Mon, 07 Jan 2008 08:49:37 GMTContent-Length: 0

Header Description


Optional

Date Optional

Host Mandatory

User-Agent Optional


UUID Namespace

NOTE Multiple NLOC or LOCS requests cannot be used in the same transaction.


N/A

Accept-Encoding Indicates whether the entity should be com-pressed in the response. I.e., the client is requesting that the server compress the response.

Allowable values are:• gzip — enabled• identity — uncompressed

If no encoding is specified, the default is identity

If both gzip and identity are presented by the client, regardless of weighting (for example, iden-tity;q=2,gzip=1), the grid always uses gzip.

Optional

X-BYC-XXXX One or more metadata tags, as described in “Metadata” on page 23.

Optional

X-SYS-LOCS To request the locations of an object, regardless of location type

Optional

X-SYS-LOCS: TYPE To request the locations of an object based on location type. TYPE is one of: • CLDI (for content stored on an LDR)• CLNL (for content stored on an ARC)

Optional

X-SYS-NLOC To request the number of locations where an object is stored, regardless of location type.

Optional

X-SYS-NLOC: TYPE To request the number of locations (based on location type) where an object is stored. TYPE is one of: • CLDI (for content stored on an LDR)• CLNL (for content stored on an ARC)

Optional



Response Status


Response Headers

For more on headers, see “HTTP Standard Headers” on page 150.

Code

200 OK

400 Bad Request

403 Forbidden

404 Not Found


406 Not Acceptable

408 Request Timeout




Header Notes

Connection

Content-Encoding Indicates whether the entity is actually com-pressed by the client for network transfer.

Allowable values are:• gzip — enabled• identity — compressed

Optional

Content-Length

Content-Type

Date

Last-Modified

Transfer-Encoding Allowable values are Chunked and Identity

Optional

Default if nothing is specified is Identity


UUID Namespace


If the object is successfully retrieved, the response body is the object content. Otherwise, the response body is an HTML page providing a human readable error message.

Request Example

This example shows a client requesting the retrieval of an object by specifying the specific UUID of the object. As part of the request, the metadata tag ”SOID” is requested. ”SOID” is a metadata field that was specified by the client when the object was originally stored into the grid system. The number of LDRs where the object is stored is requested (X-SYS-NLOC:CLDI) and that entity be compressed for network transfer.

X-BYC-XXXX If requested, the metadata tag XXXX.

X-CBID An internal identification tag for the object.

X-HASH The hash identifier and the hash value.

As of release 8.5, by default, the grid software uses the SHA-256 hash algorithm. Objects ingested into the grid before it is upgraded to release 8.5 continue to use the SHA-1 hash algorithm after an upgrade to release 8.5.

X-SYS-LOCS If requested, the location type with node ID where each instance of the object is stored, separated by commas.

X-SYS-NLOC If requested, the number of locations where the object is stored.

For segmented objects, X-SYS-NLOC is calculated from the segment with the fewest number of copies (this includes the container object). For example, an ingested large object that has been segmented into one gigabyte (GB) segments will return 1 if copies where made of all but one segment. For more information on object segmen-tation, see the Administrator Guide.

GET /UUID/C06CB196-52CB-41F3-940A-E5857DF2D73E HTTP/1.1Host: example.comX-BYC-SOID:X-SYS-NLOC:CLDIAccept-Encoding: gzip



Response Example

This example shows the response to a client requesting a specific object, including the metadata tag ”SOID” and the number of locations where the object is stored. The server response indicates that:• the object was found (200 OK)• its content type is msword• the metadata tag ”SOID” does not exist (there is no associated

value) • the object is stored on two LDRs • the object is compressed for network transfer

The response also includes the object’s content identifier and its hash value that can be used for integrity checks.

The body is returned as chunked gzip-encoded binary data that can be saved as a file by the client and used as a Microsoft Word document.

The following example shows the response from the server when the content requested does not exist (404 Not Found). The body is an HTML page providing a human readable version of the error message with additional information about why the request failed.

HTTP/1.1 200 OKDate: Mon, 07 Jan 2008 08:49:37 GMTConnection: KEEP-ALIVEContent-Encoding: GZIPTransfer-Encoding: CHUNKEDLast-modified: Mon, 07 Jan 2008 08:18:29 GMTX-CBID: " 19827ABC0FFED199"X-HASH: " SHA2,A948904F2F0F479B8F8197694B30184B0D2ED1C1CD2A1EC0FB85D299A192A447"X-BYC-SOID: X-SYS-NLOC: 2

<chunked gzip-encoded binary data; the object file, a Word doc>

HTTP/1.1 404 Not FoundDate: Mon, 07 Jan 2009 08:49:37 GMTConnection: KEEP-ALIVEContent-Length: 144

<HTML><HEAD>

<TITLE>404 Not Found</TITLE></HEAD><BODY>

<H1> Error 404 Not Found</H1><H2> Object Not Found</H2>

</BODY></HTML>


UUID Namespace

Metadata Only

Syntax

GET /UUID/uuid?metadata HTTP/1.1


Description

Retrieve all predefined metadata. Does not return object.

Request Headers

For more on the standard headers, see “HTTP Standard Headers” on page 150.


N/A

Response Status


Header Description


Optional

Date Optional

Host Mandatory

User-Agent Optional

Code

204 No Content

400 Bad Request

404 Not Found


408 Request Timeout




Response Headers



N/A if successful. Otherwise, the response body is an HTML page pro-viding a human readable error message.

Request Example

This example shows a client requesting the retrieval of an object’s metadata by specifying the specific UUID of the object.



Header Notes

Connection

Content-Length

Date

Last-Modified

X-BYC-XXXX If defined, the metadata tag XXXX.




GET /UUID/C06CB196-52CB-41F3-940A-E5857DF2D73E?metadata HTTP/1.1


UUID Namespace

Response Example

This example shows the response to a client request for a specific object’s metadata.

This example shows the response from the server when the content requested does not exist (404 Not Found). The body is an HTML page providing a human readable version of the error message with addi-tional information about why the request failed.

Last Access TimeYou can enable Last Access Time in the NMS Management Interface (MI) for an HTTP profile when you configure the grid to accept con-nections. (See “Configure the Grid to Accept Connections” on page 125.) When a StorageGRID API client whose assigned HTTP

HTTP/1.1 200 OKDate: Thu, 25 Nov 2010 21:32:43 GMTConnection: KEEP-ALIVEContent-Length: 0Last-Modified: Thu, 25 Nov 2010 21:32:15 GMTX-CBID: "EEAB729E747341BE"X-HASH:"SHA2,E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855"X-BYC-CTIM: 1290720724X-BYC-FGID: 0X-BYC-FGRP: 10X-BYC-FPTH: "/fsg/test1"X-BYC-FUID: 0X-BYC-MODE: 33188X-BYC-MTIM: 1290720724X-BYC-XAID: "BFSG"X-BYC-XTYP: "FILE"X-BYC-XVER: 1


<HTML><HEAD>

<TITLE>404 Not Found</TITLE></HEAD><BODY>

<H1> Error 404 Not Found</H1><H2> Object Not Found</H2>

</BODY></HTML>



profile includes Last Access Time uses GET to retrieve an object, the grid saves the retrieval time in internal object metadata called last access time metadata.

Only the grid can use internal metadata. For example, Information Lifecycle Management (ILM) policies can use last access time metadata to identify when an object was last retrieved. For more information about last access time metadata and ILM policies, see the Administrator Guide.

By default all Gateway Nodes use the FSG_HTTP profile. When the FSG_HTTP profile has Last Access Time enabled, last access time metadata updates when the Gateway Node retrieves objects from the grid. Last access time metadata does not update when the Gateway Node retrieves objects from the cache.

NOTE Because last access time metadata updates each time that the Stor-ageGRID API client retrieves an object, it can affect grid performance. It is recommended to disable Last Access Time in the NMS Manage-ment MI when no ILM policies use last access time metadata.

HEAD

Syntax

HEAD /UUID/uuid HTTP/1.1

where uuid = a UUID in the format specified in “UUIDs” on page 21

Description

Retrieve specified metadata.

HEAD is similar to GET except that HEAD only returns specified metadata and does not return the object. A HEAD request with no metadata header tags can be used to determine whether an object exists. A response status of “200 OK” indicates that the object does exist.


UUID Namespace

Request Headers


NOTE Multiple NLOC or LOCS requests cannot be used in the same transaction.


N/A

Header Description


Optional

Date Optional

Host Mandatory

User-Agent Optional

X-BYC-XXXX One or more metadata tags, as described in “Metadata” on page 23.

Optional

X-SYS-LOCS To request the locations of an object, regardless of location type

Optional

X-SYS-LOCS: TYPE To request the locations of an object based on location type. TYPE is one of: • CLDI (for content stored on an LDR)• CLNL (for content stored on an ARC)

Optional

X-SYS-NLOC To request the number of locations where an object is stored, regardless of location type

Optional

X-SYS-NLOC: TYPE To request the number of locations (based on location type) where an object is stored. TYPE is one of: • CLDI (for content stored on an LDR)• CLNL (for content stored on an ARC)

Optional



Response Status


Response Headers


Code

200 OK

400 Bad Request

403 Forbidden

404 Not Found


408 Request Timeout




Header Notes

Connection

Content-Length The length of the requested object (the length of the HEAD response itself is zero since HEAD never has a response body).

Content-Type

Date

Last-Modified

X-BYC-XXXX If requested, the metadata tag XXXX.





UUID Namespace


N/A

Request Example

In this example, the locations of the object with the specified UUID and the value of associated metadata ”SOID” are requested.

Response Example

In this example, the response includes the node IDs of the two LDRs where the object is stored (CLDI 12130010, CLDI 12110048) and the value of the ”SOID” metadata (B415). The X-HASH header contains the hash value of the object that can be used for integrity checks. The length of the requested object is 102.

If the object is not found, the response 404 Not Found is returned.

X-SYS-LOCS If requested, the location type with node ID where each instance of the object is stored, separated by commas.

X-SYS-NLOC If requested, the number of locations where the object is stored.

For segmented objects, X-SYS-NLOC is calculated from the segment with the fewest number of copies (this includes the container object). For example, an ingested large object that has been segmented into one gigabyte (GB) segments will return 1 if copies where made of all but one segment. For more information on object segmen-tation, see the Administrator Guide.

HEAD /UUID/F5BC3175-A0FF-4EA3-BCA6-41633923FA6E HTTP/1.1Host: example.comX-SYS-LOCS:X-BYC-SOID:

HTTP/1.1 200 OKDate: Thu, 21 Feb 2009 22:11:32 GMTConnection: KEEP-ALIVEContent-Length: 102Last-Modified: Thu, 21 Feb 2008 20:18:29 GMTX-SYS-LOCS: CLDI 12130010, CLDI 12110048X-BYC-SOID: "B415"Content-Type: application/octet-streamX-HASH: "SHA2,A948904F2F0F479B8F8197694B30184B0D2ED1C1CD2A1EC0FB85D299A192A447"X-CBID: "261CD0D33F69A425"



OPTIONS

Syntax

OPTIONS /UUID HTTP/1.1

— or —

OPTIONS /UUID/ HTTP/1.1

Description

List the HTTP methods enabled for the UUID namespace.

Request Headers



N/A

Response Status


Header Notes


Optional

Date Optional

Host Mandatory

User-Agent Optional

Code

200 OK

400 Bad Request

403 Forbidden



UUID Namespace

Response Headers



N/A

Request Example

Response Example

408 Request Timeout



Header Notes

Allow The HTTP methods allowed in the UUID name-space (DELETE, GET, HEAD, OPTIONS, POST, PUT).

Connection

Content-Length Always 0 for OPTIONS

Date

OPTIONS /UUID/ HTTP/1.1Host: example.com

HTTP/1.1 200 OKDate: Thu, 21 Feb 2008 22:11:41 GMTContent-Length: 0Allow: OPTIONS, GET, HEAD, PUT, POST, DELETEConnection: KEEP-ALIVE



POST

Syntax

POST /UUID HTTP/1.1

Description

Return information about objects that match a specified set of metadata.

To query for information about a specific object identified by its UUID, use the HEAD method. See “HEAD” on page 38.

Request Headers


Header Usage


Optional

Content-Length Ignored if Chunked encoding is specified

Required if Identity encoding is used

Date Optional

Host Mandatory


Optional


User-Agent Optional


UUID Namespace


NOTE Insert a <CR><LF> after the last request header before submitting the content.

The object query is encoded in XML and takes the following form:

The XML elements are described in Figure 6 and Table 5. See also “Object Query Schema” on page 63 and “XML Structure” on page 157.

Content-Encoding Indicates whether the entity is actually com-pressed by the client for network transfer.

Allowable values are:• gzip — enabled• identity — compressed

Optional

<?xml version ="1.0" encoding="UTF-8"?><containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">

<container name="CBQA"><atom name="MRIQ" type="UI32" value=value /><container name="QINP">

<container name="APPM"><container name=Metadata>

<atom name="RELA" type="FC32" value=operator /> <atom name="VALU" type=nnnn value=value />

</container><container name=Metadata>

<atom name="RELA" type="FC32" value=operator /> <atom name="VALU" type nnnn value=value />

</container></container>

</container><container name="QOUT">

<atom name="CBID" type="NULL" value="" /><atom name="CHND" type="NULL" value="" /><container name="APPM">

<atom name=Metadata type="NULL" value="" /><atom name=Metadata type="NULL" value="" />


</container></containerxml>



Figure 6: Elements of an XML Object Query

CBQA MRIQ

QINP Namespace

QOUT

VALU

RELA

CBID

Namespace

Container

Atom

Metadata

CHND

Metadata

Table 5: Object Query XML Elements

Element Type Description Notes

CBQA container

N/A Contains the query

MRIQ atom UI32 Specifies the maximum number of results to be returned

Parent: CBQA

If the value is set to 0, no results are returned. If the atom is not included, or is set to 0xFFFFFFFF, all objects that match the criteria specified in the query are returned.

QINP container

N/A Contains one or more criteria used to determine which subset of content to return

Parent: CBQA

Namespace container

N/A The namespace container for the metadata items.

Parent: QINP

The only allowable value is /APPM.

/APPM holds the metadata defined by third party applications.

Metadata container

N/A Specifies the metadata name to be used as a filter and contains the two atoms that complete the definition of a single filter condition

Parent: APPM

Multiple filter criteria have a logical AND relationship.


UUID Namespace

RELA atom FC32 Operator used to evaluate the metadata against the speci-fied value.

Parent: Metadata

Allowable values are:• EQUL: Equals to• NEQL: Not equal to• GREA: Greater than • GREE: Greater than or equal to• LESS: Less than• LESE: Less than or equal to• LIKE: Like

Queries on string metadata that use operators other than EQUL and NEQL have a greater impact on grid opera-tions than EQUL and NEQL.

If an object does not have the metadata item in question, the com-parison evaluates as false.

VALU atom nnnn The value against which to evaluate the metadata.

Parent: Metadata

The value must have the same data type as the metadata being queried against.

If the operator is LIKE, you can use the wildcards * and ?. Asterisks (*) represent multiple characters and question marks (?) represent a single character. If you do not include a wildcard in the comparison value, LIKE evaluates the same as EQUL.

QOUT container

N/A Defines the information to be returned for each object that meets the criteria specified in the query.

Parent: CBQA

CBID atom NULL To return the internal identi-fier of the object.

Parent: QOUT

Value is empty ("")

Optional

CHND atom NULL To return the UUID of the object

If you know the UUID of an object, you can retrieve it using the GET method.

Parent: QOUT

Value is empty ("")

Optional

Table 5: Object Query XML Elements (cont.)




Response Status


Response Headers


Namespace container

NULL The namespace container for the metadata items

Parent: QOUT

The only allowable name is /APPM

Value is empty ("")

Metadata atom

NULL The name of the metadata to return

Parent: /APPM

Value is empty ("")

Table 5: Object Query XML Elements (cont.)


Code

200 OK

400 Bad Request

403 Forbidden


408 Request Timeout

411 Length Required



Header

Connection

Content-Length

Date


UUID Namespace


The query response is encoded in XML and takes the following form:

The XML elements are described in Figure 7 and Table 6.

Figure 7: Elements of an XML Object Query Response

<?xml version ="1.0" encoding="UTF-8"?><containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">

<container name="CBQN"><atom name="NRES" type="UI32" value=value /><atom name="RSLT" type="FC32" value="SUCS" /><atom name="QSTS" type="FC32" value=status /><container name="QRSL">

<container name="0x00000001">information about object 1

</container><container name="0x00000002">

information about object 2</container>


</containerxml>

CBQN NRES

QRLS

RSLT

Container

Atom

QSTS

0x00000001

0x00000002

0x0000000n

CBID

Namespace

CHND

Metadata

Table 6: Object Query Results XML Elements


CBQN container

N/A Contains the results

NRES atom UI32 The number of results returned Parent: CBQN



RSLT atom FC32 The result of the query Parent: CBQN

If the query completes successfully, SUCS is returned.

If the query is malformed and cannot be processed, the server returns a 400 Bad Request or 500 Internal Server Error.

The HTML body of the error response may include the value TMFM. This indicates that the query was malformed, could not be pro-cessed, and should not be retried.

QSTS atom The current status of the query Parent: CBQN

The following values may be returned:• CFUL: Query completed, all

records returned• CPAR: Query completed,

records returned up to the speci-fied limit of results

If the query is malformed and cannot be processed, the server returns a 400 Bad Request or 500 Internal Server Error.

QRSL container

N/A Holds numbered containers (for example, 0x00000001) that describe the objects that meet the criteria.

Parent: CBQN

If no objects match the query criteria, QRSL is empty.

0x0000000n container

N/A Describes the objects that meets the query’s criteria. Includes atoms that contain the informa-tion requested about the object.

Parent: QRSL

There is one container per result.

CBID atom UI64 The internal identifier of the object.

Parent: 0x0000000n

CHND atom CSTR The UUID of the object Parent: 0x0000000n

If an object does not have a UUID, the atom is returned with type="NULL" and an empty value.

Table 6: Object Query Results XML Elements (cont.)



UUID Namespace

Request Example

This example is an XML container containing a query for an object where the value of metadata ”SOID” is A555.

Response Example

This example is an XML container containing a response to the above query. There is one result. The information about the object in the result includes the value of the object identifier UUID (CHND) and the value of the metadata ”SOID”.

Metadata atom nnnn The value of the metadata spec-ified in the query.

Parent: 0x0000000n

If an object does not have the metadata tag, the atom is returned with type="NULL" and an empty value.

Table 6: Object Query Results XML Elements (cont.)


POST /UUID HTTP/1.1content-length:1137connection: CLOSE

<?xml version="1.0" encoding="UTF-8"?> <containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">

<container name="CBQA"><container name="QINP">

<container name="APPM"> <container name="SOID">

<atom name="RELA" type="FC32" value="EQUL" /> <atom name="VALU" type="CSTR" value="A555" />

</container> </container>

</container> <container name="QOUT">

<atom name="CHND" type="NULL" value="" /> <container name="APPM">

<atom name="SOID" type="NULL" value="" /> </container>


</containerxml>



HTTP/1.Date: MConnectContentLast-mo

<?xml v<contai

<con

</co</conta

PUT

Object

Syntax

PUT /UUID HTTP/1.1

Description

Store content and metadata into the grid.

The total amount of metadata attached to any single object should not exceed 4 KiB.

Request Headers


1 200 OKon, 07 Jan 2008 08:49:37 GMTion: KEEP-ALIVE-Length: 547dified: Mon, 07 Jan 2008 08:18:29 GMT

ersion ="1.0" encoding="UTF-8"?>nerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">tainer name="CBQN"><atom name="NRES" type="UI32" value="1" /><atom name="RSLT" type="FC32" value="SUCS" /><atom name="QSTS" type="FC32" value="CFUL" /><container name="QRSL">

<container name="0x00000001"><atom name="CHND" type="CSTR" value="2FAC1234-31F8-11B4-A222-08002B34C003" /><container name="APPM">

<atom name="SOID" type="CSTR" value="A555" /></container>

</container></container>ntainer>inerxml>


UUID Namespace

Header Description

Date Optional


Optional



Content-Type Indicates the data type of the entity that is con-tained in the message, in the format described in RFC 2045 http://www.ietf.org/rfc/rfc2045.txt.

Recommended: If stored objects are accessed by industry-standard web browsers, the MIME type is important to allow the browser to render the contents correctly.

If no media type is specified, none is assigned.

Optional

Expect: 100-continue To determine if the grid is willing to accept a given object before sending the object.

When this header is specified, the grid will return additional headers to the application before the application begins sending the object data to the grid. Unless the application requires information contained within the 100-continue headers (for example, the UUID) before the application can start sending the object, this capability should not be used.

See also “Embedding UUIDs into Stored Objects” on page 67.

Host Mandatory

Transfer-Encoding Chunked encoding is preferred.

User-Agent Optional

Content-Encoding Indicates whether the entity is compressed by the client for network transfer. Allowable values are:• gzip — enabled• identity — uncompressed

If no encoding is specified, the default is identity

Optional




X-BYC-MCLS For grids integrated with a TSM server.

Indicates the management class to be assigned to the data by a TSM middleware integrated with an Archive Node. See “Multiple TSM Management Classes” on page 26.

The name can include no more than 30 characters, is not case-sensitive, and can include only the fol-lowing characters:• alphabetic characters: A – Z• numerals: 0 – 9• the following “special” characters:

. (period), - (hyphen), + (plus sign), & (ampersand), _ underscore

If no management class is specified or the man-agement class does not exist on the TSM server, objects are saved using the default management class specified in the NMS MI.

CSTR data type

Optional

X-BYC-XAID Identifies the external application that stored the object.

CSTR data type

Optional

X-BYC-XTYP Identifies the type of object saved to the grid, as defined by the external application.

Every application receives a unique External Application Identifier (XAID) from a NetApp Solutions Engineer as part of the formal integra-tion process.

CSTR data type

Optional

X-BYC-XVER Indicates the version of the object type as defined by the external application.

SI64 data type

Optional

X-BYC-XXXX One or more metadata tags to be stored with the object into the grid. See “Metadata Available to Applications” on page 24.

Optional


UUID Namespace

X-SYS-COMPRESS Indicates whether the file should be compressed. Allowable values are:• ENABLE

• DISABLE

Optional. If this header is not present, stored object compression behavior is determined by the stored object compression grid option in the NMS MI (under Grid Management Grid Configuration Configuration).

X-SYS-DUAL Indicates that two initial copies of the object should be created on ingest without waiting for the grid’s ILM rules to be evaluated. See “Dual Commit” on page 27.

Any value submitted in the header is ignored (a value may be required for compatibility with certain StorageGRID API client libraries that do not support headers with empty values.)

Optional. Recommended.

X-SYS-DDUP Indicates that the file is eligible for “deduplica-tion”. See “Deduplication” on page 27.

NOTE Deduplication is deprecated.

Any value submitted in the header is ignored (a value may be required for compatibility with certain StorageGRID API client libraries that do not support headers with empty values.)

The X-SYS-DDUP header is only accepted if the deduplication feature is enabled for the grid.

Optional

X-SYS-ENCRYPT Indicates whether to encrypt the file. Allowable values are:• AES128

• AES256• DISABLE

Optional. If this header is not present, stored object encryption behavior is determined by the stored object encryption grid option in the NMS MI (under Grid Management Grid Configuration Configuration).



NOTE The four letter codes XAID, XTYP, and XVER are also used for audit messages (as described on page 103). The XAID, XTYP, and XVER audit atoms have different data types than shown above. Make sure that you use the correct data type when you submit items.


N/A

Response Status


X-SYS-SLICE:GESIS Indicates that the file stored should be “sliced” and “deduplicated” for use with the GE Opti-mized Store feature. See “GE Optimized Store” on page 27.

The X-SYS-SLICE:GESIS header is only accepted if the deduplication feature is enabled for the grid and the file ingested with this header is a TAR file.

NOTE Deduplication and GE Optimized store are deprecated.

Optional

Code

100 Continue

200 OK

201 Created

400 Bad Request

403 Forbidden

404 Not Found


408 Request Timeout

411 Length Required

415 Unsupported Media Type



UUID Namespace

Response Headers




Header Notes

Connection

Content-Length Always 0 for PUT. For compatibility with some client libraries, and for conformance with the HTTP 1.1 RFC.

Date

X-CBID Internal identification tag for the object.


The application can use the hash value to verify end-to-end data integrity, for example, to ensure that the data stored by the grid is indeed the data that the application sent.


X-SYS-NLOC Only included if an X-SYS-DUAL header is included in the request.

Indicates whether one or two initial copies of the object were made. Two copies are normally made unless an issue with the grid prevents the creation of the second copy.

For segmented objects, X-SYS-NLOC is calculated from the segment with the fewest number of copies (this includes the container object). For example, an ingested large object that has been segmented into one gigabyte (GB) segments will return 1 if copies where made of all but one segment. For more information on object segmentation, see the Administrator Guide.

This response indicates only the number of initial copies that are made. To determine the permanent number of locations after ILM rules are evaluated, use the HEAD or GET method that includes the X-SYS-NLOC header.

X-UUID Unique identifier assigned by the grid




N/A

Request Example

This example is a request for storing a Microsoft Word object to the grid. Dual commit is requested. The file is to be compressed, but not encrypted. ”SOID” is a metadata and that the entity is compressed by the client for network transfer.

See also Chapter C, “Examples” on page 159.

Response Example

This example shows the response to a client requesting to store an object. The object was ingested as indicated by the 201 Created header. The UUID assigned by the grid to the object is returned. The X-HASH header contains the hash value of the object that can be used for integ-rity checks.

Because the X-SYS-DUAL header was included in the request, the response includes an X-SYS-NLOC header that indicates how many initial copies of the data were made. Dual Commit is on a best effort basis. In this example, X-SYS-NLOC has a value of 1, indicating that only one of the two requested initial copies was created. This could have occurred if only one Storage Node in the grid was writable when the object was ingested or if network issues prevented the second initial copy from being made.

PUT /UUID/ HTTP/1.1Content-Type: application/mswordHost: example.comContent-Length: 1243563X-SYS-DUAL: X-BYC-SOID: "A555"X-SYS-ENCRYPT:DISABLEX-SYS-COMPRESS:ENABLEContent-Encoding: gzip

contents of gzip-encoded file exactly 1243563 bytes long


UUID Namespace

The Content-Length header of a PUT response is always 0.


Metadata

Syntax

PUT /UUID/uuid?metadata HTTP/1.1


Description

Add, update, or delete metadata of an existing object.

The metadata specified in the request replaces the currently assigned metadata. To keep all existing metadata, they must be included in the request with identical values (as retrieved via the GET request for metadata, see “Metadata Only” on page 35). Any metadata not included in the request is deleted.

The total amount of metadata attached to any single object should not exceed 4 KiB.

NOTE Modifications to metadata do not affect the Content Block stored on the LDR disks.

If multiple metadata updates are queued by the owner CMS for pro-cessing, the latest metadata update (by time) is the update that wins. Note that the grid does not manage concurrent metadata updates beyond applying updates atomically and enforcing the “newest wins” logic. For example, a StorageGRID API client wants to delete objects where X-BYC-NUM0 == 10 because this represents data that is no longer required:

HTTP/1.1 201 CreatedDate: Mon, 09 Jan 2007 08:49:37 GMTConnection: KEEP-ALIVEX-UUID: "D83F7D18-A8A8-46FF-8FA5-4C6F94C52FB2"X-CBID: "A489B9EF96237023"X-HASH: "SHA2,A948904F2F0F479B8F8197694B30184B0D2ED1C1CD2A1EC0FB85D299A192A447"X-SYS-NLOC: 1Content-Length: 0



• Time 0 — The client at DC site queries the grid (POST, HEAD, or GET (for metadata)) and finds that UUID_A has X-BYC-NUM0 == 10

• Time 1 — The client at the DR site would like to keep UUID_A and updates X-BYC-NUM0 to 20

• Time 2 — The client at the DC site issues a DELETE on UUID_A

without knowing that X-BYC-NUM0 has been set to 20

In the above example, the StorageGRID API client spanning both sites needs to manage concurrency itself (i.e., do not set NUM0 to 20 if it intends to delete UUID_A).

Metadata updates for a single object (an object that is not replicated) are always consistent as the client must include all metadata for an object with a PUT.

Request Headers



N/A

Header Description

Date Optional


Optional

Content-Length Always 0 for PUT. Ignored if Chunked encoding is specified.

Host Optional

User-Agent Optional

X-BYC-XXXX One or more predefined metadata tags to be stored with the object into the grid. See “Metadata Available to Applications” on page 24.

Optional


UUID Namespace

Response Status



N/A

Request Examples

The following is an example request to update the metadata of an existing object.

GET returns the object’s metadata

Code

204 No Content

400 Bad Request

403 Forbidden

404 Not Found




504 Gateway Timeout


GET /UUID/9E0AF27B-A97E-42A6-A01C-D66416E2C783?metadata HTTP/1.1

HTTP/1.1 200 OKDate: Thu, 16 Dec 2010 18:25:37 GMTConnection: KEEP-ALIVEContent-Length: 5Last-Modified: Thu, 16 Dec 2010 18:25:10 GMTX-CBID: "ECA7C63F54922D9A"X-HASH:"SHA2,C9D04C9565FC665C80681FB1D829938026871F66E14F501E08531DF66938A789"X-BYC-NUM0: 1234X-BYC-STR0: "ABCD"X-BYC-XVER: 5678



PUT updates the value of X-BYC-NUMO from "1234" to "999" and deletes X-BYC-STR0.

GET returns the result of updating the value of X-BYC-NUMO from "1234" to "999" and deleting X-BYC-STR0“.

Response Examples

This example shows the response to a client request to update the FSG read-only metadata X-BYC-FPTH.

PUT /UUID/9E0AF27B-A97E-42A6-A01C-D66416E2C783?metadata HTTP/1.1X-BYC-NUM0: 999X-BYC-XVER: 5678Content-Length: 0

HTTP/1.1 204 No ContentDate: Thu, 16 Dec 2010 18:26:45 GMTConnection: KEEP-ALIVE

GET /UUID/9E0AF27B-A97E-42A6-A01C-D66416E2C783?metadata HTTP/1.1

HTTP/1.1 200 OKDate: Thu, 16 Dec 2010 18:26:59 GMTConnection: KEEP-ALIVEContent-Length: 5Last-Modified: Thu, 16 Dec 2010 18:25:10 GMTX-CBID: "ECA7C63F54922D9A"X-HASH:"SHA2,C9D04C9565FC665C80681FB1D829938026871F66E14F501E08531DF66938A789"X-BYC-NUM0: 999X-BYC-XVER: 5678

HTTP/1.1 403 ForbiddenDate: Sat, 20 Nov 2010 01:07:18 GMTConnection: CLOSEContent-Length: 171Content-Type: text/html

<HTML> <HEAD> <TITLE>Error 403 Forbidden</TITLE> </HEAD> <BODY> <H1>Error 403 Forbidden</H1> <H2>Some requested metadata cannot be changed.</H2> </BODY></HTML>


UUID Namespace

default

grammarFc32Ip32Ipad 4}(:[0-

9a-fA-FSi64Ui64

star

}Inpu

}

Appm

}

Cond

} }

}

Object Query Schema

Due to space constraints in this guide, the schema is broken over two pages.

namespace = "http://www.bycast.com/schemas/XML-container-1.0.0"

{ = xsd:string {pattern = "([0-9A-Za-z_]{4})|(0x[0-9a-fA-F]{8})"} = xsd:string {pattern = "(\d{1,3})(\.\d{1,3}){3}"} = xsd:string {pattern = "(([0-9a-fA-F]{0,4}:){0,6}(\d{1,3})(\.\d{1,3}){3})|([0-9a-fA-F]{0,]{0,4}){0,7})"} = xsd:integer {minInclusive="-9223372036854775808" maxInclusive="9223372036854775807"} = xsd:integer {minInclusive="0" maxInclusive="18446744073709551615"}

t = element containerxml {attribute version { "1" },element container {

attribute name { string "CBQA" },element atom {

attribute name { string "MRIQ" },attribute type { string "UI32" },attribute value { (xsd:unsignedInt | "0xFFFFFFFF") }

}?,Input,Output

}

t = element container {attribute name { string "QINP" },Appm

= element container {attribute name { string "APPM" },Condition+

ition = element container {attribute name { Fc32 },element atom {

attribute name { string "RELA" },attribute type { string "FC32" },attribute value { xsd:string { pattern = "(EQUL)|(NEQL)|(GREA)|(GREE)|(LESS)|(LESE)|(LIKE)"

},element atom {

attribute name { string "VALU" },(

( attribute type { string "SI32" }, attribute value { xsd:int }) |( attribute type { string "UI32" }, attribute value { xsd:unsignedInt }) |( attribute type { string "SI64" }, attribute value { Si64 }) |( attribute type { string "UI64" }, attribute value { Ui64 }) |( attribute type { string "FP64" }, attribute value { xsd:double }) |( attribute type { string "IP32" }, attribute value { Ip32 }) |( attribute type { string "IPAD" }, attribute value { Ipad }) |( attribute type { string "CSTR" }, attribute value { xsd:string }) |( attribute type { string "USTR" }, attribute value { xsd:string }) |( attribute type { string "FC32" }, attribute value { Fc32 })

)}



Output

}}

Best Practices

Application Design ProcessWhen integrating an external application using the StorageGRID API, carefully consider the use of metadata:• Determine the value in XAID that is used to identify the external

application; for example, ACME-WIDGET

• Optionally, determine the value in XVER that is used to identify the version of metadata stored by the external application. This metadata value can be used by the external application to help identify what metadata values where used with a particular object; for example, 16

• Determine which pre-determined metadata fields that are avail-able to the external application (STR0-9 and NUM0-9) will be used to store application specific metadata. For more information on selecting the correct metadata field to optimize the use of database space and performance, see Table 4: “Metadata Types” on page 25.

• If the external application will submit application-specific audit messages into the audit system, ensure that the total rate of audit messages will not cause audit message backlogs. In the NMS MI,

= element container {attribute name { string "QOUT" },element atom {

attribute name { string "CBID" },attribute type { string "NULL" },attribute value { string "" }

}?,element atom {

attribute name { string "CHND" },attribute type { string "NULL" },attribute value { string "" }

}?,element container {

attribute name { string "APPM" },element atom {

attribute name { Fc32 },attribute type { string "NULL" },attribute value { string "" }

}+}?


UUID Namespace

see the Audit Messages Queued attribute at <grid node> ADC or

AMS Events Overview Main.

In addition, also consider:• Chapter 2, Chapter 3, and Chapter 4, which describe the HTTP

methods allowed in the UUID, GRID, and AUDIT namespace respectively.

• Chapter 5: “HTTP Session Management”, which explains how to establish HTTP sessions.

• Appendix A: “Integration”, which provides instructions on how to integrate the application with the grid.

• Examples are included throughout the guide. Appendix C: “Exam-ples” on page 159 includes Ruby code examples.

Object Storage

Submitting Metadata

Choose the metadata that you include with objects carefully and consider the trade-off between metadata size and grid object capacity.

Always specify the smallest and simplest set of metadata that meets the needs of your application. The amount and type of metadata affects grid capacity and performance. All metadata must be stored in the CMS database, consuming CMS database space that could other-wise be used to track ingested objects. Indexed metadata must be processed as files are ingested, which can reduce ingest performance and lead to grid backlogs.

Grid metadata is used to drive ILM business rules. For example using the Object Type (XTYP) metadata field the grid can apply different ILM policies to medical images vs. database backups based on their business value.

The grid storage solution is not suitable for use as a general purpose metadata repository or a metadata query engine.

As a rule of thumb, each byte of metadata attached per object reduces the capacity of a CMS group by at least 100,000 objects. In other words, the object capacity of a grid that would normally support 200 million objects is reduced to approximately 193.6 million objects (a reduction of 6.4 million objects) if a 64-byte metadata field is attached to each object.



Updating Metadata

When updating metadata (PUT), include all metadata with the request. Any metadata not included with the request is deleted. Therefore, it is recommended that you first use GET to retrieve all metadata to deter-mine exactly what metadata is associated with an object and can thus be updated. This will ensure that a complete list of metadata is included with the PUT so that metadata is not accidentally deleted.

Computing and Verifying Hash Values

Compute and verify the SHA-256 hash of the object after committing it to the grid before deleting the local copy.

A key design aspect of storage systems is providing a layered and overlapping set of protection domains that guard against corruption and alteration of the content. When content is transferred from one system to another, it is important to know that the resulting object stored on the destination system is the same as the original object.

In order to ensure object integrity between the application and the grid, the application should compute the SHA-256 hash of the object as it is sent. Once the object is successfully stored, the object should be retrieved and the SHA-256 hash re-computed. If the two hashes match, the object was stored successfully, and the local copy may be deleted by the application.

NOTE As of release 8.5, by default, the grid software uses the SHA-256 hash algorithm. Objects ingested into the grid before it is upgraded to release 8.5 or later continue to use the SHA-1 hash algorithm after an upgrade to release 8.5 or later.

You can also use the hash value returned in the X-HASH response header of the HTTP GET, HTTP HEAD, and HTTP PUT requests. See “GET” on page 30, “POST” on page 44, and “PUT” on page 52.

Using Predefined Metadata XAID, XTYP, XVER

Predefined metadata such as X-BYC-XAID, X-BYC-XTYP, and X-BYC-XVER can be used to help you track applications, objects, and meta-data. For instance, internally, the StorageGRID software uses these predefined metadata as follows:• XAID identifier is used to identify the external application that

stored the object. This permits an application to only see its own


UUID Namespace

objects by adding the XAID as a query field when performing metadata queries on a grid that is shared with other applications.

• XTYP is used to assign an object type. For example, objects stored by client applications have a different XTYP value than FSG backup. This permits an application to easily identify objects of a specific type when performing metadata queries.

• XVER is used to indicate the version of the metadata. For example, backups stored in an older format should have a different XVER value than backups stored in a newer format.

Query Number of Copies Before Deleting Local Copy

Query the grid to determine if there are two copies of the object in the grid before deleting the local copy.

It is critically important to ensure that multiple copies of the object exist in the grid before the application removes its local copy. Given that the probability of data loss increases dramatically when only one copy of a given object exists, the application should not delete its local object until it has determined that a minimum of two copies of the object exist within the grid.

The application can use the X-SYS-NLOC header as part of a HEAD method to request the number of locations of a given object. Using the returned information, the application can then choose to delete the local copy only when two or more locations exist.

Query Number of Copies When Using Dual Commit

An application may use the X-SYS-NLOC header returned in the PUT response when dual commit is used to determine the initial number of copies and avoid the overhead of performing a separate HEAD request.

Embedding UUIDs into Stored Objects

In some applications, it is advantageous to store the assigned UUID into the object itself. In these cases, the application can include a 100-

continue request header in the PUT request and incorporate the UUID returned in the X-UUID response header into the object prior to com-pleting the PUT transaction.

If the application does not need to embed the UUID into the object and only uses the UUID as a pointer to the stored object, the application



should obtain the UUID from the 201 Created header instead of using 100-continue.

PUT Response Delays

Expect situations when the response to a PUT will take up to ten minutes.

In situations where network connectivity is lost between a site where only Storage Nodes are located and the remainder of the grid, the grid may take about ten minutes after the last data is received before an error result code is returned to the application. This length of time is considered normal and the application should be capable of handling this scenario.

Similarly, in situations where network connectivity is disrupted and then restored before the transaction times out, the application may receive a successful result for the object storage after waiting for up to ten minutes after the last data is sent.

Error Recovery

Ensure that the application recovers gracefully if a transaction fails due to character encoding issues.

Care must be taken to ensure that metadata and other headers are cor-rectly encoded. Given that HTTP and Unicode encoding rules are complex, situations where an application will fail the encoding valida-tion while deployed in a production environment is a fairly common occurrence. Since the probability of this failure condition is reasonably high, it is important that when an encoding failure does result in a transaction being rejected as malformed, the application is able to recover from this failure and alert the operator or administrator that there is a problem, as well as providing details of the transaction that triggered the failure for troubleshooting purposes.

Object Containerization

“Containerize” objects that are stored together and will always be retrieved together: these objects should be managed as a single object.

If a custom container format is used, it is recommended that the con-tainer index be located at the beginning of the container object. This reduces the latency of access, as the grid will stream the first bytes of the file to the application sooner than the remainder of the file.


UUID Namespace

An application may wish to store a collection of related files as a single object. These objects are always retrieved together and are desired to be managed as a single object. In these situations, the objects should be "containerized" into a single larger object before being stored to the grid. Containerization provides the following benefits:• A smaller number of managed objects reduces the cost of the grid

by reducing the computational load required to manage objects.• Atomic management ensures that all of the sub-objects within a

container are managed as a single object.• Larger object size can lead to increased throughput.

These advantages can be especially significant for applications where there are hundreds or even thousands of sub-objects that always need to be stored and retrieved together.

The average number of sub-objects within a container provides a good guideline of the reduction in the number of objects that need to be managed when containerization is enabled. The average number of objects per container and the average object size together provide a simple metric for capacity planning and allow the cost savings of con-tainerization to be quantified.

To facilitate recovery, the format of containerized objects should follow the USTAR TAR format. Containerized objects, when retrieved directly from the grid, should be able to be run through GNU TAR, resulting in all of the sub-objects being extracted.

Object Retrieval

Requesting Location Information

In addition to retrieving stored objects and the metadata associated with stored objects, an application can request either a count of the number of locations where the object is stored, or the actual list of node IDs and location types (CLDI for LDR or CLNL for ARC) for each location where a copy of the object is stored. This list can be filtered to return only the count or locations of a specific type (LDR or ARC).

There are two common uses for location data:• Ensure that an object has been stored in at least two locations

before deleting it from the local storage.For a detailed discussion, see “Object Storage” on page 65.



• Determine if the object is stored on a low latency or high latency stored medium in order to present users with a different indication of retrieve time.

The location information that is returned is a snapshot: the application should not use the location information for any other uses since the actual location of the object can change.

Requesting Metadata Information

The retrieval of metadata associated with stored objects can be per-formed as part of object retrieval (GET) or independently of object retrieval (GET or HEAD). In general, the use of object metadata is con-sidered part of normal application integration, and documenting the flow of metadata through the system is an important aspect of under-standing the integration of the application.

Retrieval During “Islanding”

Many grid topologies are designed such that a subset of the grid can continue to operate when it is disconnected from the remainder of the grid. This condition is known as "islanding".

When the application is communicating with an islanded section of a grid, the results for a GET request message depend on whether:• All stored objects are available • A subset of the stored objects are available• Only newly stored objects are available

For grids which are configured such that not all stored objects are available during islanded operation, the StorageGRID API will return a 503 Service Unavailable result code if an application attempts to retrieve an object that is not reachable. Ensure that when the applica-tion receives a 503 Service Unavailable result code, it represents to the end user that the inability to retrieve content is a temporary condition.

Object QueriesSend the queries to a NetApp Solutions Engineer for evaluation prior to the implementation.

As the grid implements metadata storage and query over a distributed database layer, the way that metadata is used can have a major impact


UUID Namespace

on the performance of the application. Avoid making queries that could potentially return many results. A query that returns every object stored in the grid can have a severe impact on the performance of the grid as a whole (such as its ability to ingest data, make copies of ingested data, and retrieve data on request).

Always include queryable/indexed metadata in object queries to increase their efficiency.

In order to determine if the queries performed by the application will be responded to in large grids (hundreds of millions to billions of objects) in varying topologies, it is important to evaluate the types of queries that are being performed. As part of the integration process, the queries should be analyzed in conjunction with a NetApp Solu-tions Engineer to ensure that the required performance characteristics are maintained as the number of managed objects grows.

WAN Connectivity

Network Transfer Compression

Using gzip compression for PUT and GET transactions can increase the throughput of network data transfer between the StorageGRID API client and LDR for objects that are highly compressible. Note that this increase to the throughput for network data transfers does come at the cost of some additional processing time on both the client and the LDR. It is recommended that you use gzip compression for PUT and GET transactions over a WAN, except in such cases where the objects are NOT highly compressible. For example, .jpg image files.




3
GRID NamespaceHow to select suitable LDRs for object storage and retrieval
Introduction

External applications use the GRID namespace to assess the opera-tional state of the grid and determine which grid services are available to handle transactions.

The HTTP methods allowed in the GRID namespace are:• OPTIONS

• POST

OPTIONS

Syntax

OPTIONS /GRID HTTP/1.1

— or —

OPTIONS /GRID/ HTTP/1.1

Description

List the HTTP methods enabled for the GRID namespace.



Request Headers



N/A

Response Status


Response Headers


Header Notes


Optional

Date Optional

Host Mandatory

User-Agent Optional

Code

200 OK

400 Bad Request

403 Forbidden


408 Request Timeout



Header Notes

Allow The HTTP methods allowed in the GRID namespace (OPTIONS, POST)


GRID Namespace


N/A

Request Example

Response Example

POST

Syntax

POST /GRID HTTP/1.1

Description

Return information about services within the grid. Use to determine which services are available to handle transactions and to get a ranking of their suitability to handle the transaction.

Request Headers


Connection


Date

OPTIONS /GRID/ HTTP/1.1Host: example.com

HTTP/1.1 200 OKDate: Thu, 21 Feb 2008 22:11:41 GMTContent-Length: 0Allow: OPTIONS, POSTConnection: KEEP-ALIVE

Header Usage


Optional



<<

.

<



The grid query is encoded in XML and takes the following form:

The XML elements are described in Figure 8 and Table 7. See also “Grid Query Schema” on page 89 and “XML Structure” on page 157.



Date Optional

Host Mandatory


Optional

Default if nothing is specified is Identity.

User-Agent Optional

?xml version ="1.0" encoding="UTF-8"?>containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">

<container name="SQRY"><atom name="NRES" type="UI32" value="5" /><container name="QURY">

<container name="QFLT"><container name="SVFI">

<atom name="PTYN" type="FC32" value="property" /><atom name="RELA" type="FC32" value="operator" /><atom name="VALU" type="nnn" value="value" />

</container><container name="SVFI">

..</container>

</container><container name="QRNK">

<atom name="PTYN or PROF" type="FC32" value="value" /><atom name="SORT" type="FC32" value="order" />

</container><container name="QSHW">

<atom name="property" type="NULL" value="" /><atom name="property" type="NULL" value="" />


</container>/containerxml>


GRID Namespace

Figure 8: Elements of an XML Grid Query

SQRY NRES

QURY SVFI PTYNQFLT

QRNK

VALU

RELA

PTYN

SORT

QSHW

Container

Atom

PROFor

Name

Table 7: Grid Query XML Elements


SQRY container

N/A Defines the content of the POST request as a grid query.

NRES atom UI32 The maximum number of results.

Parent: SQRY

Optional

If not included or the value is set to 0xFFFFFFFF, all results are returned.

QURY container

N/A Contains the elements that make up the query.

Parent: SQRY

QFLT container

N/A Contains the list of filtering criteria. Each filter is defined by a SVFI container.

Parent: QURY

Optional

SVFI container

N/A Contains the three atoms that specify a single filter condition.

Parent: QFLT

Multiple SVFI filter containers within QFLT have a logical AND relationship.

PTYN atom nnnn Four-letter code of a service property.

Parent: SVFI

For the list of available properties, see Table 8: “Service Properties” on page 80.



RELA atom FC32 Operator used to evaluate the service property against the specified value.

Parent: SVFI

The allowable values are:• EQUL: Equals to• NEQL: Not equal to• GREA: Greater than • GREE: Greater than or equal to• LESS: Less than• LESE: Less than or equal to

VALU atom nnnn The value against which the service property is evaluated.

Parent: SVFI

QRNK container

N/A Contains the parameters which define the ranking criteria for the results.

Parent: QURY

PTYN atom FC32 The service property used to rank the results.

Parent: QRNK

Simple ranking sorts nodes in numer-ical order, based on the value of the chosen property.

For the list of available service prop-erties, see Table 8: “Service Properties” on page 80. Use any property that has one of these data types: UI64, UI32, SI32, FP64, or FC32.

You can use PROF (see below) instead of PTYN.

Table 7: Grid Query XML Elements (cont.)



GRID Namespace

PROF atom FC32 The ranking profile to use to rank the results

Parent: QRNK

Ranking profiles are used internally by LDRs and CLBs and rely on a weighted combination of several service properties to rate the suitabil-ity of a node for a particular purpose.

Allowable values are:• RTRV: Tuned to determine the

best service to retrieve content. Uses SCAS (computational capac-ity) and several other criteria.

• STOR: Tuned to determine the best service to store content. Uses SCAS (computational capacity), STAS (storage capacity avail-able), and several other criteria.

You can use PTYN (see above) instead of PROF.

SORT atom FC32 Specifies whether to rank results in ascending or descending order.

Parent: QRNK

Allowable values are ASCE and DESC.

Ranking profiles impose their own sort order on results. For example, RTRV does a primary sort by link cost, and then sorts results within link cost groups by other properties. RTRV also specifies that results be "fuzzied" within these groups to add an element of randomness to the results. On the assumption that services with a similar ranking are equivalent, and that it is desirable to spread requests across multiple services for load-balancing, any one of a group of roughly equivalent services may be returned as the first query result if the results are “fuzz-ied”. The specified ranking order affects only how results are ranked within link cost groups, before fuzzying is applied.





QSHW container

N/A Specifies what service prop-erties to return for each service that meets the query criteria.

Parent: QURY

XXXX NULL Four-letter code of a service property.

Parent: QSHW

Include one atom for each property to be returned

For the list of available properties, see Table 8: “Service Properties” on page 80.

Value is always empty.



Table 8: Service Properties

Property Name Notes Type

SVID Service ID Can be one of the following services:• CERT: Certificate Virtual Service

As each node may provide many services (for example, an LDR may provide HTTP Ingest and HTTP Query/Retrieve services), the certificate service (CERT) is a special “virtual” service used to query for nodes rather than for specific services provided by those nodes. It is used in combination with one of the certificate virtual service properties listed below in this table.

• NPRP: Node Property ServiceThe Node Property Service contains properties which are inherited by all other services registered on the same node. It is used in combination with one of the NPRP properties listed below in this table.

• HCLN: Query/Retrieve Service • HING: HTTP Ingest Service

FC32

SVST Service State A value of ENBL indicates the service is enabled.

A value of DABL indicates that the service is disabled.

FC32

SVVS Service Version

Identifies the version of the service.a UI32


GRID Namespace

CERT Certificate Virtual Service Properties

NOID Node ID The node ID assigned to a node during grid provision-ing.

UI32

DTYP Device Type The device type of a node is defined by the type of ser-vices it provides. The available device types are:• BADC: Administrative Domain Controller (ADC) • BAMS: Audit Management Service (AMS)• BARC: Archive Service (ARC)• BCLB: Connection Load Balancer (CLB)• BCMN: Configuration Management Node (CMN)• BCMS: Content Management System (CMS)• BLDR: Local Distribution Router (LDR)• BFSG: File System Gateway (FSG)• BSSM: Server Status Monitor (SSM)• BNMS: Network Management System (NMS)

FC32

IPAD IP Address For legacy compatibility only. IP32

IADR IP Address IP Address of a node that is providing services. It is assigned to a node during grid provisioning.

IPAD

GRUP Group ID Group ID of the physical or logical group that the service belongs to.

UI32

DPTH Device Path Numerical representation of the hierarchy of locations, servers, and services that exist in a grid deployment. It is used by the NMS service to create the navigational tree shown in the NMS MI.

A device path is assigned to a node during grid provi-sioning.

CSTR

Table 8: Service Properties (cont.)




CONN Connection Status

The connection status of the node providing services. The supported values are:• ONLN: Online• OFLN: Offline• EXIS: Exists in grid, in either online or offline status

EXIS does not show up in the query results. The query results always report the actual connection status of the service as being either ONLN or OFLN.

To find all nodes in the grid and their connection status, you must explicitly filter for the CERT service. Other-wise, the results will not include information about offline nodes. For example:

FC32

LINK Link Cost The relative cost of accessing the service. UI64

RANK Rank The relative rank of a service in the query results.

Rank is shown in the query results but cannot be used as a filter item or ranking item.

FP64

NPRP Node Property Service Propertiesb

SNTS Network capacity

The maximum network capacity of a device, corre-sponding to the theoretical limit of the network band-width that the device is connected to. Expressed in bits per second.

UI64

SNAS Network capacity available

The portion of the total bandwidth available to the device.

UI64




<atom name="PTYN" type="FC32" value="SVID" /><atom name ="RELA" type="FC32" value="EQUL" /><atom name="VALU" type ="FC32" value="CERT" />


<atom name="PTYN" type="FC32" value="DTYP" /><atom name ="RELA" type="FC32" value="EQUL" /><atom name="VALU" type ="FC32" value="BLDR" />


<atom name="PTYN" type="FC32" value="CONN" /><atom name ="RELA" type="FC32" value="EQUL" /><atom name="VALU" type ="FC32" value="EXIS" />



GRID Namespace

If you omit the CERT or NPRP filter items, the query returns the list of services (where services are offered by nodes such as LDRs, for example HTTP Ingest and HTTP Query/Retrieval) with the Certificate

SNGS Network grade

A constant used to identify different classes of network (such as T1, T3, etc.) and to distinguish between them based on speed.

UI32

STTS Storage capacity

The total amount of content storage space on a device, based on the number of bytes of usable storage provi-sioned for the device. Expressed in bytes.

UI64

STAS Storage capacity avail-able

The portion of the total storage capacity of the device that is currently available for storing content. Expressed in bytes.

UI64

STGS Storage grade The storage grade of the device. A constant used to identify different classes of storage (such as SCSI or IDE) and different generations of I/O, and to distinguish between them based on speed.

UI32

SCTS Computa-tional capacity

The maximum computational capacity of the device. This is a constant derived from the type of processor(s) being used on the node. It is based on the speed of the CPU, scaled by a factor that normalizes the processing power of different CPU architectures so that a direct comparison can be made between them.

UI64

SCAS Computa-tional capacity available

The portion of the total computational capacity on the device that is not currently being used.

UI64

SCGS Computa-tional grade

A constant assigned to different classes of computers to indicate which class is preferential to others.

UI32

DVER Device Version

The software version of the device (for example, 4.13.1). This property has the same value as the Version attri-bute reported in the NMS MI.

CSTR

DBLD Device Build The software build of the device (for example, 75617). This property has the same value as the Build attribute reported by each service in the NMS MI.

CSTR

DMVR Device Model Version

The version of the device model used to display infor-mation about the service in the NMS MI.

CSTR

a. The properties available for a service may vary between versions. However, all services available in a single release of the software are of the same version.

b. All nodes register a special Node Property Service (NPRP) which contains properties which are inherited by all other services registered on the same node.





Virtual Service Properties or Node Property Service Property that you specify. Because there may be multiple services on an LDR that have a given property, you may see more results than you expect. To return a list of nodes instead of a list of services, use two filters as shown in the example below.

To query for all nodes (as opposed to all services) that have at least 500 GB of storage capacity available, include a filter for NPRP in the query:

Response Status


Code

200 OK

400 Bad Request

403 Forbidden


408 Request Timeout

411 Length Required




<atom name="PTYN" type="FC32" value="SVID" /><atom name="RELA" type="FC32" value="EQUL" /><atom name="VALU" type ="FC32" value="NPRP" />


<atom name="PTYN" type="FC32" value="STAS" /> <atom name="RELA" type="FC32" value="GREE" /> <atom name="VALU" type ="UI64" value="500000000000" />



GRID Namespace

<<

<

Response Headers



The query results are encoded in XML and take the following form:

The XML elements are described in Figure 9 and Table 9.

Figure 9: Elements of an XML Grid Query Response

Header

Connection

Content-Length

Date

?xml version ="1.0" encoding="UTF-8"?>containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">

<container name="SQRT"><atom name="NRES" type="UI32" value="value" /><atom name="RSLT" type="FC32" value="SUCS" /><container name="QRSL">

<container name="0x00000001"><atom name="property" type="type" value="value" />...


<atom name="property" type="type" value="value" />...



SQRT NRES

RSLT

0x00000001QRSL

0x00000002

0x0000000n

Container

Atom

Metadata



Table 9: Grid Query Results XML Elements


SQRT container

N/A Contains the results

NRES atom UI32 The number of results returned Parent: SQRT

RSLT atom FC32 The result of the query Parent: SQRT

See Table 10 for the list of result codes.

QRSL container

N/A Holds numbered containers (for example, 0x00000001) that describe the services or nodes that meet the query’s criteria

Parent: SQRT

The items are listed in the ranking order you specified in the query.

0x0000000n container

N/A Includes atoms that contain the information requested about the service.

Parent: QRSL

There is one container per result.

XXXX NULL The property specified in the QSHW container of the query.

Parent: 0x0000000n

If a service does not have a property specified in QSHW, the correspond-ing atom is returned with no value.

RANK FP64 Relative rank of the service. Parent: 0x0000000n

May be returned even if not explicitly requested in the query.

LINK UI64 Relative cost of accessing the service.

Parent: 0x0000000n

May be returned even if not explicitly requested in the query.

Table 10: Values of RSLT Atom

Value Description

SUCS The query completed successfully.

FMFD The query was malformed and could not be processed.

FTMM The query failed because the data type of the value specified in the filter does not match the data type of the property.

FBRK The query failed because the ranking criteria is malformed.

FBFT The query failed because the filter uses an invalid property name.


GRID Namespace

Pcc

< <

Request Example

This example shows a request container to obtain the list of LDRs: Service ID (SVID) is CERT and device type (DTYP) is BLDR.

The query specifies the following for the results:• Include a maximum of 80 results (NRES atom)• Rank results in ascending order of suitability using the STOR

ranking profile• For each LDR, include node ID (NOID), IP address (IADR), device

type (DTYP), total storage capacity (STTS), and storage capacity available (STAS)


OST /GRID HTTP/1.1ontent-length:1137onnection: CLOSE

containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0"> <container name="SQRY"> <atom name="NRES" type="UI32" value="80" /> <container name="QURY"> <container name="QFLT"> <container name="SVFI"> <atom name="PTYN" type="FC32" value="SVID" /> <atom name="RELA" type="FC32" value="EQUL" /> <atom name="VALU" type="FC32" value="CERT" /> </container> <container name="SVFI"> <atom name="PTYN" type="FC32" value="DTYP" /> <atom name="RELA" type="FC32" value="EQUL" /> <atom name="VALU" type="FC32" value="BLDR" /> </container> </container> <container name="QRNK"> <atom name="PROF" type="FC32" value="STOR" /> <atom name="SORT" type="FC32" value="ASCE" /> </container> <container name="QSHW"> <atom name="NOID" type="NULL" value="" /> <atom name="IPAD" type="NULL" value="" /> <atom name="DTYP" type="NULL" value="" /> <atom name="STTS" type="NULL" value="" /> <atom name="STAS" type="NULL" value="" /> </container> </container> </container>/containerxml>



Response Example

This is a sample response container that includes two results (0x00000001 and 0x00000002 containers).

As specified in the request, the response includes a list of LDRs, and for each LDR, indicates the node ID, IP address, device type, total storage capacity, and available storage capacity. The rank and link cost of each LDR are also returned, even if not specified in the request.

If the LDR is offline, the STTS and STAS fields will be present, but empty.

HTTP/1.1 200 OKDate: Mon, 07 Jan 2008 08:49:37 GMTConnection: CLOSEContent-Length: 1146

<?xml version="1.0" encoding="UTF-8"?><containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">

<container name="SQRT"><atom name="NRES" type="UI32" value="2" /><atom name="RSLT" type="FC32" value="SUCS" /><container name="QRSL">

<container name="0x00000001"><atom name="NOID" type="UI32" value="2170092" /><atom name="IADR" type="IPAD" value="192.168.100.192" /><atom name="DTYP" type="FC32" value="BLDR" /><atom name="STTS" type="UI64" value="19334316032" /><atom name="STAS" type="UI64" value="19151515648" /><atom name="LINK" type="UI64" value="10" /><atom name="RANK" type="FP64" value="0.7939283" />


<atom name="NOID" type="UI32" value="2170093" /><atom name="IADR" type="IPAD" value="192.168.100.193" /><atom name="DTYP" type="FC32" value="BLDR" /><atom name="STTS" type="UI64" value="19677314022" /><atom name="STAS" type="UI64" value="18252435669" /><atom name="LINK" type="UI64" value="10" /><atom name="RANK" type="FP64" value="0.7226283" />




GRID Namespace

defa

gramFII

F]{0SU

s

}

F

}

F

}

Grid Query Schema

Due to space constraints in this guide, the schema is broken over two pages.

ult namespace = "http://www.bycast.com/schemas/XML-container-1.0.0"

mar {c32 = xsd:string {pattern = "([0-9A-Za-z_]{4})|(0x[0-9a-fA-F]{8})"}p32 = xsd:string {pattern = "(\d{1,3})(\.\d{1,3}){3}"}pad = xsd:string {pattern = "(([0-9a-fA-F]{0,4}:){0,6}(\d{1,3})(\.\d{1,3}){3})|([0-9a-fA-,4}(:[0-9a-fA-F]{0,4}){0,7})"}i64 = xsd:integer {minInclusive="-9223372036854775808" maxInclusive="9223372036854775807"}i64 = xsd:integer {minInclusive="0" maxInclusive="18446744073709551615"}

tart = element containerxml {attribute version { "1" },element container {

attribute name { string "SQRY" },element atom {

attribute name { string "NRES" },attribute type { string "UI32" },attribute value { (xsd:unsignedInt | "0xFFFFFFFF") }

}?,element container {

attribute name { string "QURY" },Filters?,Rankings?,Shows

}}

ilters = element container {attribute name { string "QFLT" },Filter*

ilter = element container {attribute name { string "SVFI" },element atom {

attribute name { string "PTYN" },attribute type { string "FC32" },attribute value { Fc32 }

},element atom {

attribute name { string "RELA" },attribute type { string "FC32" },attribute value { xsd:string { pattern = "(EQUL)|(NEQL)|(GREA)|(GREE)|(LESS)|(LESE)" } }

},element atom {

attribute name { string "VALU" },(

( attribute type { string "SI32" }, attribute value { xsd:int }) |( attribute type { string "UI32" }, attribute value { xsd:unsignedInt }) |( attribute type { string "SI64" }, attribute value { Si64 }) |( attribute type { string "UI64" }, attribute value { Ui64 }) |( attribute type { string "FP64" }, attribute value { xsd:double }) |( attribute type { string "IP32" }, attribute value { Ip32 }) |( attribute type { string "IPAD" }, attribute value { Ipad }) |( attribute type { string "CSTR" }, attribute value { xsd:string }) |( attribute type { string "USTR" }, attribute value { xsd:string }) |( attribute type { string "FC32" }, attribute value { Fc32 })

)}



Rankings = element container {attribute name { string "QRNK" },element atom {

attribute name { ( string "PTYN" | string "PROF") },attribute type { string "FC32" },attribute value { Fc32 }

},element atom {

attribute name { string "SORT" },attribute type { string "FC32" },attribute value { xsd:string { pattern = "(ASCE)|(DESC)" } }

}}

Shows = element container {attribute name { string "QSHW" },element atom {

attribute name { Fc32 },attribute type { string "NULL" },attribute value { string "" }

}*}

}


4
AUDIT NamespaceHow to work with audit messages
Audit Messages

The AUDIT namespace is used to work with the audit messages gener-ated by the grid. There are two capabilities supported by the AUDIT namespace: accessing the HTTP audit feed and generating application-specific audit messages.

HTTP Audit Feed MessagesThe HTTP audit feed queues audit messages triggered by grid transac-tions. Audit messages can then be retrieved from the HTTP audit feed queue. To retrieve HTTP audit feed messages, the HTTP audit feed must be enabled. For more information and the procedure, see “Enable the HTTP Audit Feed” on page 143.

By default, the following messages are queued in the HTTP audit feed:• FSTG

• FMFY

• FSWI

• FDEL

• ORLM

The HTTP methods specific to the HTTP audit feed in the AUDIT namespace are:• DELETE

• GET

Audit messages can be retrieved and deleted from the HTTP audit feed queue one at a time or in bulk.

When retrieving messages one at a time, in order to retrieve the next message, after the message is retrieved, it must be deleted from the HTTP audit feed queue. If the retrieved message is not deleted from the HTTP audit feed queue after it is retrieved, it will be retrieved



again with the GET command and the next message will not be retrieved; thus, the DELETE and GET commands must always be used together.

Similarly, when retrieving messages in bulk, in order to retrieve the next set of messages, the bulk retrieved messages must be deleted in bulk from the HTTP audit feed. It is recommended that the maximum number of messages that should be retrieved or deleted at one time is 500.

Best Practices for HTTP Audit Feed Messages

The HTTP audit feed assumes a single client session when retrieving and deleting messages from the audit queue. Concurrent access to the HTTP audit feed queue from multiple clients is not recommended and may result in the loss of messages. This can be enforced by restricting access to the GET and DELETE methods in the /AUDIT namespace to a single client IP address and/or client certificate.

For best performance, it is recommended that the limit for the retrieval and acknowledgement of messages be set to 500 messages at one time.

Unacknowledged audit messages are queued on the grid node hosting the AMS (Admin Node or Audit Node). If the HTTP audit feed is enabled, messages should be retrieved and deleted from the queue at a sufficiently high rate to prevent the disk on the AMS from filling up. Older queued messages are not automatically deleted if the disk fills.

Duplicate and out-of-order messages may be returned in the HTTP audit feed response.

HTTP Audit MessagesHTTP audit message transactions are performed to generate applica-tion-specific audit messages which will be managed as part of the grid audit facility. These messages are appended to the grid’s audit log file stored on the grid node hosting the AMS service (either the Admin Node or Audit Node).

The first stage of determining if the audit functionality is of use to an application is looking at the business value of audit in general, the value of correlating events within the grid, and the cost of building distributed, reliable and secure audit infrastructure.


AUDIT Namespace

Assuming that there is a business driver for audit information, the typical process is to determine which points (usually involving inter-actions between system components) should be audited, writing an audit schema for each audit message that will be generated, and building software infrastructure to collect the audit information and deliver it to the grid.

The HTTP methods allowed in the AUDIT namespace are:• DELETE

• GET

• OPTIONS

• POST

DELETE

Syntax

DELETE /AUDIT/FEED?values:<number_of_events> HTTP/1.1

Description

Delete the next event or bulk number of events in the HTTP audit feed queue. DELETE is performed after GET and acts as an acknowledg-ment that the message was retrieved.

The integer <number_of_events> specifies the requested number of messages to be deleted from the HTTP audit feed queue. If the number of messages in the HTTP audit queue is less than the <num-ber_of_events> value, all messages are deleted.

The maximum recommended value for <number_of_events> is 500

messages.

The value of <number_of_events> should match the number of events returned in the previous GET request. Note that the number returned in the GET response can be less than the <number_of_events> asked for in the GET request.



Request Headers



N/A

Response Status


Header Notes


Optional

Date Optional

Host Mandatory

User-Agent Optional

Code

204 No Content

400 Bad Request

403 Forbidden

404 Not Found


408 Request Timeout



504 Gateway Timeout



AUDIT Namespace

Response Headers



N/A

Request Example

Response Example

In this example, the event is acknowledged:

Response Example

In this example, there is no event to acknowledge:

Header Notes

Connection

Content-Length

Date

DELETE /AUDIT/FEED?values:1 HTTP/1.1Host: example.com

HTTP/1.1 204 No ContentDate: Mon, 07 Jan 2009 08:49:37 GMTConnection: KEEP-ALIVEContent-Length: 0


<HTML> <HEAD> <TITLE>Error 404 Not Found</TITLE> </HEAD> <BODY> <H1>Error 404 Not Found</H1> <H2>HTTP Audit Feed queue is empty.</H2> </BODY></HTML>



GET

Syntax

GET /AUDIT/FEED?values:<number_of_events> HTTP/1.1

Description

Retrieve the next event or bulk number of events in the HTTP audit feed queue.

The integer <number_of_events> specifies the requested number of messages to be retrieved from the HTTP audit feed queue. If the number of messages in the HTTP audit queue is less than the <num-ber_of_events> value, all messages are retrieved.

The maximum recommended value for <number_of_events> is 500

messages.

Request Headers



N/A

Header Notes


Optional

Date Optional

Host Mandatory

User-Agent Optional


AUDIT Namespace

Response Status


Response Headers


Request Example

Code

200 OK

400 Bad Request

403 Forbidden


408 Request Timeout



504 Gateway Timeout


Header Notes

Connection

Content-Length

Date

GET /AUDIT/FEED?values:1 HTTP/1.1Host: example.com



HTDaCoCoCo

<?<c </

HDCCC

<< <


The HTTP audit feed message is encoded in XML and takes the follow-ing form:

Response Example

In this example there is no event:

TP/1.1 200 OKte: Mon, 07 Jan 2009 08:49:37 GMTnnection: KEEP-ALIVEntent-Length: 822ntent-Type: text/xml

xml version="1.0" encoding="UTF-8"?>ontainerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0"> <container name="AUDS"> <container name="AUDT"> <atom name="ATYP" type="FC32" value="FDEL" /> <atom name="ANID" type="UI32" value="20591902" /> <atom name="AVER" type="UI32" value="9" /> <atom name="ATIM" type="UI64" value="1265422036709332" /> <atom name="ATID" type="UI64" value="2145065030581231444" /> <atom name="AMID" type="FC32" value="FSGC" /> <atom name="ASQN" type="UI64" value="10" /> <atom name="ASES" type="UI64" value="1265308233627009" /> <atom name="FPTH" type="CSTR" value="/fsg/documents/name.txt" /> <atom name="UUID" type="CSTR" value="D1323D85-C1DE-491E-837B-35A8F9C5278B" /> <atom name="FGRP" type="UI32" value="1" /> </container> </container>containerxml>

TTP/1.1 200 OKate: Mon, 07 Jan 2009 08:49:37 GMTonnection: KEEP-ALIVEontent-Length: 166ontent-Type: text/xml

?xml version="1.0" encoding="UTF-8"?>containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0"> <container name="AUDS"/>/containerxml>


AUDIT Namespace

OPTIONS

Syntax

OPTIONS /AUDIT HTTP/1.1

— or —

OPTIONS /AUDIT/ HTTP/1.1

Description

List the HTTP methods enabled for the AUDIT namespace.

Request Headers



N/A

Response Status


Header Notes


Optional

Date Optional

Host Mandatory

User-Agent Optional

Code

200 OK

400 Bad Request

403 Forbidden




Response Headers



N/A

Request Example

Response Example

408 Request Timeout



Header Notes

Allow The HTTP commands allowed in the AUDIT namespace (OPTIONS, POST, GET, DELTE)

Connection


Date

OPTIONS /AUDIT/ HTTP/1.1Host: example.com

HTTP/1.1 200 OKDate: Thu, 21 Feb 2008 22:11:41 GMTContent-Length: 0Allow: OPTIONS, GET, POST, DELETEConnection: KEEP-ALIVE


AUDIT Namespace

POST

Syntax

POST /AUDIT HTTP/1.1

Description

Submit audit messages generated by the application.

Application-specific audit messages contain user-supplied attributes and the following system-generated attributes:AVER ATYP

ATIM ATID

ANID AMID

ASQN ASES

Audit messages supplied by an external application via the Storage-GRID API are assigned an ATYP of EXTL (external).

This is an example of an audit message generated with the POST

method, as it appears in the audit log file:

For detailed information on the StorageGRID audit log and the audit message format, see the Audit Message Reference.

Request Headers


Header Usage


Optional

2006-08-14T01:40:37.775242 [AUDT:[XAID(FC32):BTIM][XTYP(FC32):OPER] [XVER(UI32):4][XABC(UI32):323511][CNID(UI64):135988298858][PNAM (USTR):"Jim Smith"][RSLT(FC32):SUCS][AVER(UI32):9][ATIM(UI64):1146620437775242][ATYP(FC32):EXTL][ANID(UI32):9990056][AMID(FC32):HTPO][ATID(UI64):619557531566285967][ASQN(UI64):13657][ASES(UI64):1146600838125065]]



<?<c

..

</



The audit message is encoded in XML and takes the following form:

The total size of the XML submitted per POST transaction must be less than 20 KiB.

The XML elements are described in Table 11. See also “Audit Message XML Schema” on page 108 and “XML Structure” on page 157.



Date Optional

Host Mandatory


Optional


User-Agent Optional

xml version="1.0" encoding="UTF-8"?>ontainerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0"><container name="AUDS">

<container name="AUDT"><atom name="RSLT" type="FC32" value="SUCS" /><atom name="XAID" type="FC32" value="value" /><atom name="XTYP" type="FC32" value="value" /><atom name="XVER" type="UI32" value="value" /><atom name="XXXX" type="type" value="value" />

</container><container name="AUDT">

<atom name="RSLT" type="FC32" value="SUCS" />.


containerxml>


AUDIT Namespace

Figure 10: Elements of an XML Audit Message

AUDS AUDT RSLT

XAID

XTYP

XVER

XXXX

Container

Atom

Table 11: Audit Message XML Elements


AUDS container

N/A Defines the content of the POST request to be an audit message

AUDT container

N/A Contains the atoms that specify the audit message

Parent: AUDS

There is one container per audit message.

RSLT atom FC32 The result of the action being audited

Parent: AUDT

Used to filter audit messages and identify error conditions.

Must be assigned the value SUCS when the operation being audited is successful.

User-defined values are permitted for the value of RSLT. However, any value other than SUCS is interpreted as an error when audit events are being filtered to the audit log according to the settings configured in the NMS MI under Grid Management Grid Config-uration Audit Main.

Required

XAID atom FC32 External Application Identifier

Parent: AUDT

The external application that created the audit message. Used to differentiate audit messages submitted to the same grid by different external applications.

Recommended



XTYP atom FC32 External Audit Type Parent: AUDT

The type of audit message, as defined by the external application.

Recommended

XVER atom UI32 External Audit Version Parent: AUDT

The version of the audit message, as defined by the external application. Allows the application to differentiate between audit messages of the same type but with different versions.

Recommended

XXXX atom Any valid data type

User-defined atom name Parent: AUDT

The name must consist of four upper-case alphabetic characters, and may not begin with “A”.

The value assigned to a user-defined atom must be consistent with the data type provided for the atom. Can use any of the data types described in “Data Type Definitions” on page 154.

Any number of user-defined atoms may be included in an AUDT container. However, the complete POST request must be smaller than 20 KiB.

Validation of user-defined atoms must be performed by the external applica-tion. The grid does not perform validation on user-defined atoms. If the application assigns inconsistent data types to two atoms with the same name in different AUDT containers, the grid accepts both audit messages.

Follow the escaping rules described in “Character Sets” on page 156. As audit messages often contain text strings that are taken directly from user-controlled sources, ensure that escaping is per-formed correctly. Any escaping rules violations will result in an undeliverable audit message.

Mandatory

Table 11: Audit Message XML Elements (cont.)



AUDIT Namespace

Response Status


Response Headers



The response for a successful POST request is:<HTML><HEAD><TITLE></TITLE></HEAD><BODY></BODY></HTML>

For an unsuccessful POST, an appropriate error response is returned.

Code

200 OK

400 Bad Request

403 Forbidden


408 Request Timeout

411 Length Required



Header

Connection

Content-Length

Date



Request Example

The client submits two audit messages (there are two AUDT contain-ers). The atoms EVNT, XABC, USER, CNID, and PNAM are user-defined.


Response Example

POST /AUDIT HTTP/1.1content-length:1511connection: CLOSE


<container name="AUDS"><container name="AUDT">

<atom name="RSLT" type="FC32" value="SUCS" /><atom name="XAID" type="FC32" value="BTIM" /><atom name="XTYP" type="FC32" value="OPER" /><atom name="XVER" type="UI32" value="4" /><atom name="EVNT" type="FC32" value="OPEN" /><atom name="XABC" type="UI32" value="131341" /><atom name="CNID" type="UI64" value="1152024121828" /><atom name="PNAM" type="USTR" value="John Doe" />

</container><container name="AUDT">

<atom name="RSLT" type="FC32" value="SUCS" /><atom name="XAID" type="FC32" value="BTIM" /><atom name="XTYP" type="FC32" value="OPER" /><atom name="XVER" type="UI32" value="4" /><atom name="EVNT" type="FC32" value="VIEW" /><atom name="XABC" type="UI32" value="131341" /><atom name="USER" type="USTR" value="A. Doctor" /><atom name="PNAM" type="USTR" value="John Doe" />


</containerxml>

«HTTP/1.1 200 OK«Content-Length: 54«Date: Thu, 22 Feb 2007 22:43:22 GMT«Connection: CLOSE

«<HTML><HEAD><TITLE></TITLE></HEAD><BODY></BODY></HTML>


AUDIT Namespace

Best Practices for POST Transactions

Error Recovery

Ensure that the application recovers gracefully if a transaction fails due to character encoding issues or is malformed.

If an encoding failure is encountered, the POST transaction will fail. If the application retries to post the same audit message with the same encoding problem, the failure will be repeated. The application must have the ability to flag errors while delivering audit messages, quaran-tine the problematic audit message, and continue on to the next audit message.

Multiple Audit Messages per POST Transaction

When possible, submit multiple audit messages as part of a single POST transaction.

In order to increase efficiency, the XML schema used for posting audit messages allows multiple audit messages to be submitted as part of a single POST transaction. This reduces the overhead and increases the throughput of audit delivery. Typically, this is used in situations where there are backlogs of audit messages that need to be delivered from the application to the grid. When audit messages are being generated in real-time and there are no backlogs, the application should deliver an audit message as soon as it is triggered.

Dedicated Session for Audit Messages

Use a dedicated HTTP connection for the delivery of audit messages.

There are two different design approaches for audit integration. The first approach is to post audit messages on the sessions where the content the audit messages are related to are being stored and received. This approach provides minimal latency and is synchronous to the content transactions. However, it tends to result in more complex code.

The alternative is to have a dedicated session just for the delivery of audit messages. In this case, when an audit message is generated, it is sent to a specific component of the application which queues the audit messages and delivers them over this dedicated session. This approach has the advantages of being simpler to implement, but delays the posting of audit messages and, as it is asynchronous to the transac-tions that generate the audit message, may open additional windows where audit messages can be lost during failure conditions.



defaul

grammaFc3Ip3Ipa [0-9a-

fA-F]{Si6Ui6

Fie ER") }

sta

}

Aud

}

Aud

}

Res

}

Ext

}

Ext

}

Ext

}

Ato

}}

Audit Message XML Schemat namespace = "http://www.bycast.com/schemas/XML-container-1.0.0"

r {2 = xsd:string {pattern = "([0-9A-Za-z_]{4})|(0x[0-9a-fA-F]{8})"}2 = xsd:string {pattern = "(\d{1,3})(\.\d{1,3}){3}"}d = xsd:string {pattern = "(([0-9a-fA-F]{0,4}:){0,6}(\d{1,3})(\.\d{1,3}){3})|([0-9a-fA-F]{0,4}(:0,4}){0,7})"}4 = xsd:integer {minInclusive="-9223372036854775808" maxInclusive="9223372036854775807"}4 = xsd:integer {minInclusive="0" maxInclusive="18446744073709551615"}

ldName = attribute name { xsd:string {pattern = "[B-Z][A-Z]{3}"} - ("RSLT" | "XAID" | "XTYP" | "XV

rt = element containerxml {attribute version { "1" },AuditSequence

itSequence = element container {attribute name { string "AUDS" },( Audit )*

it = element container {attribute name { string "AUDT" },Result,ExtId?,ExtType?,ExtVersion?,# An atom with a particular name may appear only once in an Audit container.Atom*

ult = element atom {attribute name { string "RSLT" },attribute type { string "FC32" },attribute value { Fc32 }

Id = element atom {attribute name { string "XAID" },attribute type { string "FC32" },attribute value { Fc32 }

Type = element atom {attribute name { string "XTYP" },attribute type { string "FC32" },attribute value { Fc32 }

Version = element atom {attribute name { string "XVER" },attribute type { string "UI32" },attribute value { xsd:unsignedInt }

m = element atom {FieldName,(

( attribute type { string "SI32" }, attribute value { xsd:int }) |( attribute type { string "UI32" }, attribute value { xsd:unsignedInt }) |( attribute type { string "SI64" }, attribute value { Si64 }) |( attribute type { string "UI64" }, attribute value { Ui64 }) |( attribute type { string "FP64" }, attribute value { xsd:double }) |( attribute type { string "IP32" }, attribute value { Ip32 }) |( attribute type { string "IPAD" }, attribute value { Ipad }) |( attribute type { string "CSTR" }, attribute value { xsd:string }) |( attribute type { string "USTR" }, attribute value { xsd:string }) |( attribute type { string "NULL" }, attribute value { string "" }) |( attribute type { string "FC32" }, attribute value { Fc32 })

)


5
HTTP Session Management
Introduction

The processes and behaviors associated with the establishment, main-tenance and tear-down of TCP/IP connections made from the application to the grid for the purposes of performing StorageGRID API transactions is a critical part of a successful integration. This chapter describes best practices related to HTTP session management.

Establishing an HTTP Session

To communicate with the grid, the client application must establish a connection directly with one of the grid’s CLBs or LDRs. Figure 11 compares the use of CLB and LDR connections for object retrieval.

Figure 11: CLB and LDR Connections for Object Retrieval

Application establishes TCP/IP connection with an LDR

Application sends POST request to identify suitable LDR

(grid topology query)

LDR returns list of suitable LDRs

Application chooses LDR for storage and establishes connection with that LDR

Application sends GET request to LDR specifying UUID

LDR returns content and any requested metadata

LDR Connection

Application establishes TCP/IP connection with a CLB

Application sends GET request specifying UUID

CLB identifies optimum LDR and forwards request to LDR

LDR returns content and any requested metadata

CLB Connection



CLB Connection — The application establishes a connection with a CLB and simply issues an HTTP GET request in the UUID namespace, speci-fying the identifier of the object to be retrieved. The CLB identifies the optimal LDR to satisfy the request and forwards the request to that LDR. If the requested object is found, the LDR returns the object and any requested metadata.

LDR Connection — The application establishes a connection with an LDR and then issues an HTTP POST command in the GRID namespace to discover the optimal LDR to use to retrieve data. If one or more suitable LDRs are found, their identities are returned to the client appli-cation. The application then establishes a connection with a suitable LDR and issues an HTTP GET request in the UUID namespace, specify-ing the identifier of the object to be retrieved. If the requested object is found, the LDR returns the object and any requested metadata.

The use of the CLB is recommended, particularly for smaller “appli-ance” grid configurations. Using the CLB frees the application from the necessity of identifying specific LDRs for transactions and enables the grid to use its own ranking criteria to identify the nodes that can best meet requests.

For larger grids with custom configurations, it may be preferable to communicate directly with LDRs. The application can issue a query in the GRID namespace to identify and rank grid servers according to criteria defined by the application, for example the link cost of access-ing a server or server available storage or computational capacity. Moreover, the application can connect directly with multiple LDRs. This enables high-performance parallel transfers and eliminates the single point of failure associated with connecting to a CLB.

Port ConfigurationStorageGRID includes the default HTTP ports for ingest and query/retrieval listed in Table 12.

Table 12: Default Port Configuration

Service Purpose Port

CLB Query and retrieve 8080

Ingest 8081

LDR Query and retrieve 18080

Ingest 18081



The grid might be configured with default ports or customized ports. You can view the ports as configured in the grid in the NMS MI on Grid

Management Grid Configuration Storage Main.

Figure 12: Ingest and Query/Retrieve Ports

Although the ingest port can be used for query and retrievals, using the ports for their suggested purposes is more efficient. For example, as a grid matures some LDRs and CMSs fill and become read-only. When queries are directed to an ingest port, the CLB directs queries to resources that support both read and write operations. Therefore, the query may not be dealt with as efficiently as it would had it been sub-mitted via the query/retrieve port. In addition, directing an ingest request to the query/retrieve port may fail as it may be directed to an LDR that is read-only.

By populating the application with the default ports on initial applica-tion start, the amount of configuration required to communicate with an "out of the box" grid is reduced.

Allow the application to configure the ports used to access the grid.

The StorageGRID system allows the ports on which the StorageGRID API services are provided to be configured on a grid by grid basis. By allowing users of the application to configure the ports that will be



used when establishing HTTP sessions to the grid, the application will be able to connect even when the ports have been configured to values other than the default.

The user should be able to configure both the Ingest and the Query/Retrieve ports individually. No restrictions should be put on the port ranges, and the user should be permitted to configure both ports to the same value.

Gateway Node IP Address ConfigurationAllow the configuration of the IP address and hostname of the Gateway Node used to communicate with the grid in the application.

The CLB node used to establish HTTP sessions is located on the Gateway Node server. As part of standard IT practices, the IP address of the Gateway Nodes may need to be changed over the lifecycle of the deployment. The IT group may also place the grid behind a load-balancer or content switch. By allowing users of the application to con-figure and modify the IP address or hostname of the Gateway Nodes used to establish HTTP sessions to the grid, the application provides increased administrative flexibility.

If the application supports more than one Gateway Node, the IP address or hostname of the alternate Gateway Nodes should also be configurable. In addition, the preference of the order in which Gateway Nodes should be tried should be specified and configurable.

Session Duration

Idle Sessions

Keep HTTP sessions established even if there are no immediate HTTP transactions that need to be performed.

The application should establish HTTP sessions and keep them open even when the transaction that initiated the establishment of the session has completed. Subsequent transactions should then be per-formed over the already open session.

Keeping TCP/IP connections open to the grid even when idle (HTTP session persistence) provides these advantages:



• Reduced latency from the time the need for an HTTP transaction is determined to the time the transaction can be performed

• Increased data transfer rate by priming the TCP/IP slow-start algo-rithm with previously performed transfers

• Instantaneous notification of several classes of fault conditions that interrupt connectivity between the application and the grid

Reducing latency is the main advantage, especially when the TCP/IP and TLS connection establishment time are taken into account.

Determining the optimal duration that an idle session should be held open is a trade-off between the benefits of slow-start associated with the existing session and the ideal allocation of the session to internal grid resources.

As load-balancing is performed on a session-by-session basis at the time of session establishment, a session that was originally directed to a compute resource that was lightly loaded may no longer be optimal after time has passed. The most finely-grained load balancing is obtained when a separate session is established for each transaction, but this negates the much more valuable gains associated with persis-tent sessions.

Based on system measurements and integration experience, the rec-ommended maximum duration to keep an idle session held open is ten minutes. A session kept idle for longer than ten minutes may be automatically closed by the LDR.

Active Sessions

The maximum lifetime of an HTTP session should be bounded even if an HTTP session is not idle and is being used continuously to perform transactions. This ensures the following:• Enable optimal load balancing, as sessions are periodically re-

balanced across the grid.• Allow maintenance procedures that wait until all in-progress

sessions complete to begin in a timely fashion.• Ensure that PUT transactions are directed to LDRs and ARCs that

have available space.

In order to prevent long-lived connections, the application should keep track of the age of each session and should close the session if the maximum age has been exceeded at the end of a transaction.



Determining the maximum duration that a session should be held open is a trade-off between the benefits of session persistence and the ideal allocation of the session to internal grid resources.

Based on system measurements and integration experience, the rec-ommended maximum duration to keep a session held open is ten minutes.

Concurrent SessionsKeeping multiple TCP/IP connections open to the grid at any given time extends the benefits of session persistence by allowing idle sessions to be ready to perform transactions even when other transac-tions are being performed in parallel. Support for parallel sessions provides the following:• Reduced latency by allowing transactions to start immediately

instead of waiting for the completion of other transactions• Increased throughput by leveraging the parallel nature of the grid

to provide near-linear increases in aggregate transaction throughput

The application should establish multiple parallel HTTP sessions, either on a client by client basis, or arranged into a session pool. When a transaction needs to be performed, any established session that is not currently processing a transaction can be selected and immediately used.

Number of Concurrent Sessions

Each grid topology has a different peak throughput for concurrent transactions and sessions before performance begins to degrade. Peak throughput depends on factors such as computing resources, network resources, storage resources, WAN links, number of servers and ser-vices, and the number of applications being supported by the grid.

Based on system measurements and integration experience, the rec-ommended maximum number of concurrent sessions that each instance of an application should keep established at any given time is 50 per Gateway Node.

Each Gateway Node has a hard limit of 450 concurrent sessions. In a typical smaller grid configuration, performance will degrade when more than 50 sessions are performing PUT or GET transactions at the same time.



The fact that grids often support multiple applications should always be taken into account when determining the maximum number of con-current sessions used by an application. If the application consists of multiple software entities that each establishes sessions to the grid, be sure to add up all of the sessions across the entities.

Situations where the maximum number of concurrent sessions may need to be adjusted include:• Different grid topologies will result in a different optimal

maximum number of concurrent transactions and sessions.• Applications interacting with the grid over a bandwidth-limited

network often need to reduce the degree of concurrency to ensure that individual transactions complete in a reasonable time.

• When a grid is being shared with many other applications, the degree of concurrency may need to be reduced to avoid exceeding the limits of the grid.

Given these situations, it is very important for the degree of concur-rency to be configurable.

Read and Write Pools

Applications frequently assign different priorities for retrieval and storage operations. For example, in many situations, retrievals are directly related to user requests, where stores are batch background processes. In this case, there is a desire to ensure that the entire pool of sessions does not become busy handling storage operations as this would result in additional latency for a retrieve operation (the applica-tion would have to wait for one of the store operations to complete before beginning the retrieve operation).

When a given storage resource fills up, it is no longer available for storing data but is still capable of performing retrieve operations. By splitting the session pool into two different groups (read operations and write operations), the grid is able to increase the degree of paral-lelism used to handle transactions.

As a result, the optimal integration consists of two separate pools, one for read operations and one for write operations. Sessions established in the read pool would be established to the "Query/Retrieve" port of the grid, and sessions established for the write pool would be estab-lished to the "Ingest" port of the grid.



Configuring Pool Size

Maintain separate pools of sessions maintained for Read and Write operations.

Different uses of the application may result in loads that are retrieve-dominant or store-dominant. Given varying use profiles, the ability to individually adjust the percentage of the session pool that is dedicated for read or write can allow additional performance tuning.

Balancing Load Across Multiple Gateway Nodes

In larger deployments where multiple Gateway Nodes have been deployed and configured, an application can distribute the load asso-ciated with concurrent sessions across multiple Gateway Nodes.

This provides benefits during both normal operations and fault condi-tions. During normal operations, each Gateway Node is handling a reduced subset of the sessions, and data is being transferred across multiple independent network interfaces. During fault conditions, only a subset of the sessions are lost, reducing the disruption from the fault and allowing rapid recovery using already established sessions through the Gateway Nodes that were not affected.

Balancing load across multiple Gateway Nodes is required to push the aggregate transaction throughput beyond 1 Gb/s.



Time Synchronization

Time Differences Between Grid and ApplicationIssue a log message or alert when there is a time difference between the grid and the application.

As part of providing secure storage and audit services, the grid provides reliable and NIST (National Institute of Standards and Tech-nology) traceable UTC timestamps associated with every HTTP transaction performed. This timestamp can be used to compare against the local time (after UTC conversion) to determine if the application has the correct time. If the application time does not match the grid time, it could indicate a configuration problem that may have security implications.

When first connecting to the grid, the application should perform an OPTIONS transaction to get the current time (see “OPTIONS” on page 121). If the time difference between the application and the grid is greater than ten minutes, either a log message or an alert should be generated.

Using Grid Time in ApplicationUse the time returned by the grid in the application.

The grid provides reliable and NIST traceable UTC time services on the Gateway Node via the NTP protocol. This time service can be used to synchronize the application server time to the time provided by the grid. By using the grid time, applications can provide traceable time stamps for events and transactions that can enable temporal correla-tion in security audit logs.

Alternatively, the HTTP timestamp obtained from OPTIONS transac-tions can be used to provide coarser time synchronization (+/- 10 seconds) for application uses, or the HTTP timestamp associated with individual PUT transactions can be used to record the time of storage.



Secure Connections with TLS

StorageGRID software only accepts HTTP commands submitted over a network connection that uses Transport Layer Security (TLS) to provide application authentication and, optionally, transport encryp-tion. This enables the exchange of certificates as entity credentials and allows a negotiation of which hashing and encryption algorithms will be used.

Hashing and Encryption AlgorithmsThe TLS libraries used by the grid support a limited set of hashing and encryption algorithms that can be used when establishing a TLS session. The following cipher suites are supported:• AES128-SHA• AES256-SHA• NULL-SHA• NULL-MD5

Based on system measurements and general security domain knowl-edge, AES128-SHA and AES256-SHA provide a reasonable degree of security without requiring inordinate amounts of computational resources. The choice between AES128-SHA and AES256-SHA depends on the application’s requirements (performance versus encryption security).

Use one of the NULL ciphers if encryption is not required and there is a desire to eliminate the overhead associated with encryption. The client application must explicitly request the NULL cipher.

CertificatesWhen an application establishes a TLS session to the grid, the grid sends a server certificate to the application as part of the session estab-lishment process. This certificate can be verified using the grid certificate that is generated at the time the grid is originally installed (see “Acquire the Grid’s CA Certificate” on page 131).

The application should permit the grid certificate to be loaded such that it can be used to verify that the application is indeed talking with



the expected grid at the time sessions are established. This protects against man-in-the-middle and impersonation attacks.

NOTE The Common Name (CN) field in the SSL server certificate returned by the grid to the client application has a node ID as its value rather than the hostname or IP address of the server. The application should therefore not perform hostname verification on the CN in the server certificate, as this verification will fail.

Similarly, the application should send a client certificate to the grid as part of the session establishment process. A certificate is required if the client has been assigned to a security partition or if the HTTP profile assigned to the client requires certificate authentication. This certificate and its associated CA certificate must be loaded into the grid as part of configuring the grid. See “Configure the Grid to Accept Connections” on page 125 and “Configure Security Partitions” on page 136.

HTTP Transaction Coverage

Different applications have different transaction profiles. For example, an application that primarily stores content places a transaction load on the grid that consists mostly of PUT and HEAD transactions, whereas an application that queries and retrieves content consists mostly of POST and GET transactions.

Interaction DiagramsAs part of the process of designing the integration with the grid, the interaction sequences between the application and the grid should be planned and diagrammed in order to determine the transactions per-formed for each application-specific set of functionality. This allows the grid transaction coverage to be mapped to application-specific operations.

For example, Figure 13 shows the StorageGRID API transactions per-formed by a hypothetical satellite imaging archiving application. Figure 13 represents the interactions performed over the store session pool. Another diagram would represent the query and retrieval operations.



Figure 13: Transaction Interaction Diagram

HTTP Transaction LoadOnce the HTTP transactions associated with each type of application-specific functionality have been determined, the transaction load on the grid can be calculated based on the use profiles of the application.

For example, if 100 new objects are stored each hour, the PUT and HEAD rate is 0.027 transactions per second.

By providing a translation between application-specific tasks and the corresponding load on the grid, users of the application can size the grid based on their use of the application.

Many applications are designed such that multiple instances of the application can be deployed to handle multiple sites, workgroups or devices. When multiple instances of an application are deployed to use a common grid, the transaction load numbers should reflect the load placed on the grid by a single instance of the application. Calculating the load placed on the grid by multiple instances of the application can be performed by summing the application-specific loads, then convert-ing into the corresponding grid load.

HTTP PUT

HTTP HEAD

HTTP PUT Result

HTTP HEAD Result

CLBArchive ApplicationWeb Repository

Image Retrieve

Image Request

Sleep

Sleep



OPTIONS

Syntax

OPTIONS * HTTP/1.1

Description

List the HTTP methods supported by the server.

OPTIONS lists the commands the server implements, not which commands are currently available. For example, the response from an OPTIONS command for an LDR that has become read-only includes PUT, even though the LDR cannot accept new content.

The primary reason to use OPTIONS against a server is as a “ping” to verify that the application can successfully communicate with the server, or as a NOP (no operation operator) to keep a persistent con-nection from timing out. If an established HTTP session is left idle, the grid closes the session after ten minutes of inactivity (time since the completion of the last transaction).

In order to prevent the grid from automatically closing sessions, the application should periodically issue an OPTIONS transaction to indicate that it is still alive and wishes to keep the session established. This will also catch certain TCP/IP fault conditions that can only be detected when data is written.

Periodically send HTTP OPTIONS requests to instruct the grid to keep sessions established.

The optimal frequency at which to perform OPTIONS transactions on an idle session is a trade-off between the speed at which a connectivity problem can be detected and the resources consumed by performing the transactions. Sending an OPTIONS transaction infrequently increases the time to detect interruptions in connectivity. Sending an OPTIONS transaction too frequently creates larger amounts of logging output, audit messages and system load. Based on system measure-ments and integration experience, the recommended frequency for sending OPTIONS is once every 180 seconds.



Request Headers



N/A

Response Status


Response Headers


Header Notes

Date Optional


Optional

Host Mandatory

User-Agent Optional

Code

200 OK

400 Bad Request

403 Forbidden


408 Request Timeout



Header Notes

Allow The HTTP methods allowed in the UUID namespace (DELETE, GET, HEAD, OPTIONS, POST, PUT)

Connection


Date




N/A

Request Example

This example shows a client requesting a listing of supported HTTP commands for the server.

Response Example

The response from the server indicates that it supports the methods OPTIONS, PUT, GET, HEAD, POST, and DELETE.

OPTIONS * HTTP/1.1Host: example.com

HTTP/1.1 200 OKDate: Thu, 21 Feb 2008 22:11:39 GMTContent-Length: 0Allow: OPTIONS, PUT, GET, HEAD, POST, DELETEConnection: KEEP-ALIVE




A
IntegrationConfiguring connections, certificates, and security partitions
Introduction

Once the grid software has been installed, you need to:• configure the grid to accept connections from the application • copy the grid certificate to the client if the client requires server

authentication• configure security partitions (optional)• test HTTP access to the grid

Configure the Grid to Accept Connections

Client connections to the grid are made via the HTTP protocol. Within the protocol, the grid grants or declines permission for an external application to carry out specific operations. These permissions are defined in “profiles” that can be allocated to individual applications or groups of applications, based on their IP address and, optionally, a client certificate.

When configuring a connection profile for the client application, there are two levels of authentication to the StorageGRID API that can be set: IP address and client certificate, or IP address only.

Before a TCP/IP connection is opened, the grid authenticates the request. The external application is first validated for connection per-missions against the set IP address or range of IP addresses. If this validation passes, the application is permitted to connect. If a client certificate is also set, the grid then validates against the certificate. This validation is for operational permissions. If this validation passes, then the application is allowed to perform set operations (for example, GET and DELETE).



Each namespace can have any number of defined profiles, each with a unique user-defined, case-sensitive name. To create a profile that provides an application with capabilities in more than one namespace, repeat the same profile name in each namespace.

Procedure

1. Log in to the NMS MI using the Vendor account.2. Specify the link cost group that the application will use to commu-

nicate with the grid. The grid can improve performance by knowing which grid server group the external application is asso-ciated with. This helps the grid route data more efficiently by using services that operate at a lower “cost”. a. Go to Grid Management Grid Configuration Link Cost

Groups Configuration Main.

Figure 14: Configuring Access to Link Cost Groups

b. In the Client Group IP Ranges table, click Edit (or Insert if this is not the first entry).

c. Enter a value for IP Range Name.The IP Range Name can be anything meaningful. It is not refer-enced elsewhere in the configuration.


Integration

d. Enter a value for IP Range.This is the IP address or range of IP addresses that the applica-tion will be calling from. A hyphen or slash indicates a range, inclusive of the values entered. For example:• 192.168.120.0/24 (CIDR format)• 192.168.142.20-192.168.142.28 (dotted decimal)An abbreviated format for masks in eight-bit steps is available. For example: 192.168.142.0 is equivalent to the CIDR notation 192.168.142.0/24. This can be extended: n.n.0.0 is equivalent to n.n.0.0/16.

e. Enter a value for Group ID.This is the ID of the group that the caller with the specified IP address should connect to.

f. Click Apply Changes.g. Repeat from step b for each IP range that will access the grid.

3. Create an HTTP profile for the appropriate HTTP namespaces:

NOTE All of the HTTP namespaces are optional; however, at least one must be configured to create a connection. The selection and configuration of the appropriate HTTP namespace is based on the functional requirements of the client.

a. Go to Grid Management HTTP Management Permissions

Configuration Main.



Figure 15: Configuring Permissions Settings

b. In the HTTP /CDMI and /UUID Namespaces table, click Insert , then enter a value for Profile Name and select Modify/Create, Read, Query, and Delete (as needed). The following table shows which HTTP method each permis-sion enables.

Permission HTTP Method Used for Permission

Modify/Create PUT

Read GET

Query POST

Delete DELETE


Integration

The HTTP /CBID Namespace is dep-recated in favor of HTTP /UUID Namespaces.

External HTTP applications can use the HTTP /CDMI and /UUID

namespace to store, access, query, and delete objects using the unique identifier (UUID) assigned to each object stored in the grid. For more information, see Chapter 2: “UUID Namespace”.

NOTE Do not delete or modify the default profile “FSG_HTTP” as this may interfere with expected FSG behavior.

c. Select Last Access Time and Read if you want an Information Lifecycle Management policy to use last access time metadata. Otherwise clear the Last Access Time check box to improve grid performance.For more information, see “Last Access Time” on page 37.

d. In the HTTP /GRID Namespace table, click Edit (or Insert if this is not the first entry), enter the same Profile Name as in step b above and select POST.The HTTP /GRID namespace is used by external applications to assess the operational state of the grid and determine which grid services are available to handle transactions.For more information, see Chapter 3: “GRID Namespace”.

e. In the HTTP /AUDIT Namespace table, click Edit (or Insert if this is not the first entry) enter a value for Profile Name and select GET, POST, and DELETE (as needed).The HTTP /AUDIT namespace is used to work with the audit messages generated by the grid. For more information, see Chapter 4: “AUDIT Namespace”.

f. Click Apply Changes.4. Optionally, add the client certificate:

a. Go to Grid Management HTTP Management Certificates

Configuration Main.

b. In the Certificate Authorities table, click Edit (or Insert if this is not the first certificate).

c. Enter a new value for CA Name.d. Paste the CA certificate or, if the client certificate is self-signed,

the client certificate into CA Certificate.



e. In the Clients table, click Edit (or Insert if this is not the first client certificate).

f. Enter a new value for Client Name.g. Paste the client certificate into Client Certificate.

Figure 16: Adding a Client Certificateh. Click Apply Changes.

5. Add the new profile to the HTTP configuration:a. Go to Grid Management HTTP Management Clients

Configuration Main.

b. In the HTTP Entities table, click Edit (or Insert if this is not the first client certificate).


Integration

Figure 17: Adding the HTTP Profile

c. Enter a value for Description.d. Enter a value for IP Range.

Enter an IP address or range of remote devices to which the grid assigns the profile, that is the IP addresses used in step 2.

e. Select a Profile Name.Profile names were defined in step 3. The profile governs the permitted activities for connections from this IP range.

f. Optionally, select a Client Name.Select a client certificate to authenticate the client application and allow it to perform configured operations. This is the client configured in step 4.

g. Click Apply Changes.

Acquire the Grid’s CA Certificate

If the client requires server verification, obtain the grid’s CA certificate from the NMS MI.

1. In the NMS MI, go to Grid Management Grid Configuration

Overview Main.2. Under Grid Information, click to expand CA Certificate.3. Select and copy the grid’s CA certificate including the BEGIN

CERTIFICATE header and the END CERTIFICATE footer.



Figure 18: Copying the Grid’s Certificate

Security Partitions

Security partitions is a grid-wide setting that restricts access such that an HTTP client (StorageGRID API or CDMI) or FSG replication group can only interact with objects associated with security partitions to which the HTTP client or FSG replication group has been granted access. This partitioning is not a physical location within the grid, but rather a security mechanism that associates objects to access group-ings. Once enabled security partitions cannot be disabled.

Security Partition PermissionsAn HTTP client can be configured with read-write permission to one security partition only. Multiple HTTP clients can be configured with


Integration

read-write permission to the same security partition. An HTTP client can be configured with read-only permission to multiple security par-titions including an FSG replication group security partition. HTTP clients cannot be granted read-write access to FSG replication groups. FSG replication groups are automatically assigned read-write permis-sion to their own security partition, but cannot be granted access to other security partitions.

Figure 19: Security Partition Permissions

Partitions and HTTP TransactionsWhen an HTTP client assigned to a read-write security partition ingests an object into the grid, the object is tagged with a metadata field that identifies the security partition assigned to that object.

HTTP PUT or CDMI POST/PUT requests are denied unless the security partition of the target object matches the read-write security partition associated with the HTTP client.

HTTP GET/HEAD or CDMI GET requests are denied unless the security partition of the target object matches the read-write or read-only security partitions associated with the HTTP client.

HTTP POST (object query) requests filter out any matching objects that have a security partition that does not match the read-write or read-only security partitions associated with the HTTP client.

HTTP DELETE or CDMI DELETE requests are denied unless the security partition of the target object matches the read-write security partition associated with the HTTP client.

Objects stored by an HTTP client that is not associated with a read-write security partition are not assigned to any security partition. Sim-ilarly, objects stored into the grid before security partitioning is

Read-OnlyRead-Write

Read-Only

Read-Write

Read-Only

Read-Write

Read-Only

Security Partition 2Security Partition 1 Security Partition 3

HTTP Client A

HTTP Client B

HTTP Client C

FSG Replication

Group



enabled are not assigned to any partition when security partitions is enabled. Objects that are not assigned to a security partition can be retrieved, queried, and deleted by any HTTP client. An FSG replica-tion group can still only access objects in its own security partition.

Partitions and CertificatesConfiguring an HTTP client for security partitioning involves mapping an HTTP client certificate to a security partition. FSG replica-tion groups are automatically assigned a security partition and cannot be configured.

When an HTTP client establishes a session to the grid, the HTTP client presents an HTTP client certificate during TLS authentication. This certificate is verified against the certificates loaded into the grid. Fur-thermore, if the HTTP client presents a certificate signed by a certificate authority (CA), the grid performs another layer of validation by not only validating the certificate against its list of permitted certifi-cates, but also against its list of CA certificates. After the certificate has been accepted, the grid looks up the HTTP client name associated with the certificate. If a matching HTTP client name is found, the grid looks up the security partitions associated with the HTTP client name.

If the HTTP client does not present a certificate or the certificate is not associated with a security partition, the HTTP client can only access objects that are not assigned to a security partition.

Acquiring Client Certificates

The HTTP client must be issued a certificate that uniquely identifies the HTTP client to the grid. There are two ways to acquire an HTTP client certificate: from a CA or by creating a self-signed certificate.

CA-issued certificates are signed certificates available from commer-cially available CAs. You can also host your own CA and issue your own certificates. Details on managing and generating certificates are beyond the scope of this guide. For more information, see third party products.

Security Partitions and Deduplication

NOTE Deduplication is deprecated and no longer supported.


Integration

When Deduplication is enabled, the data of identical unsegmented objects from different security partitions is deduplicated. The data of identical segmented objects from different security partitions is not deduplicated. Identical items (segmented or not) in the same security partition are deduplicated. The metadata associated with deduplicated objects is preserved.

For two objects to be identical, their size, hash, and security partition must be the exactly the same. For more information on deduplication, see the Administrator Guide.

Enable Security PartitionsAll content ingested into the grid before security partitioning is enabled is accessible to all HTTP clients and FSG replication groups. It is recommended that you configured HTTP client access before enabling security partitioning. It is also recommended that you enable security partitioning before a grid becomes operational so that all data is secure. When security partitions is enabled, FSG replication groups are automatically assigned to their own security partition.

NOTE Once enabled, security partitioning cannot be disabled.

1. Log in to the NMS MI using the Vendor account.2. Go to Grid Management Grid Configuration Configuration

Main.3. Change Security Partitions to Enabled.



Figure 20: Enabling Security Partitions 4. Click Apply Changes.

Configure Security PartitionsUnlike an FSG replication group, you must manually associate HTTP clients with a security partition and set permissions.

1. Log in to the NMS MI using the Vendor account.2. Add the HTTP client certificate:

a. Go to Grid Management HTTP Management Certificates

Configuration Main.

b. In the Certificate Authorities table, click Edit (or Insert if this is not the first certificate).

c. Enter a new value for CA Name.d. Paste the CA certificate or, if the HTTP client certificate is self-

signed, the HTTP client certificate into CA Certificate.

e. In the Clients table, click Edit (or Insert if this is not the first HTTP client certificate).

f. Enter a new value for Client Name.


Integration

g. Paste the client certificate into Client Certificate.

Figure 21: Adding a Client Certificateh. Click Apply Changes.

3. Configure the security partition:a. Go to Grid Management HTTP Management Security

Partitions Configuration Main.



Figure 22: Configuring Security Partitions

a. In the Partitions table, click Edit (or Insert if this is not the first partition) and enter a value for Partition Name. The unique partition ID number is automatically assigned.

b. Click Apply Changes.A new security partition is created.

NOTE Once created, a security partition cannot be removed.

c. Optionally, in the Client Partitions table, click Edit (or Insert

if this is not the first mapping), select a Client Name and then a Partition Name.This will assign the HTTP client to a read-write security partition.


Integration

d. Optionally, in the Read-Only Client Partitions table, click Edit

(or Insert if this is not the first mapping), select a Client

Name and then a Partition Name.This will grant clients read-only access to a security partition.

e. Optionally, in the Read-Only FSG Partitions table, click Edit

(or Insert if this is not the first mapping), select a Client

Name and then an FSG Replication Group.This will grant clients read-only access to FSG replication group security partitions.

f. Click Apply Changes.

Finding IP Addresses for Grid Nodes

You can find the IP address in the NMS MI for Storage Nodes that host the LDR service or Gateway Nodes that host the CLB service. You need the IP address to connect StorageGRID API clients to the LDR service or the CLB service.

Procedure

1. Go to SSM Resources Overview Main and scroll to the Network Address table. Depending on your grid configuration, IP addresses appear for one or more of the following: eth0, eth1, eth2, and so on.

2. Perform one of the following actions:

To Connect Clients to Choose This IP Address...

API Gateway Node, Basic Gateway Node, or Storage Node

If the Network Address table only lists eth0, use the IP address for eth0.

If the Network Address table lists both eth0 and eth1 (and a dedicated NFS storage network does not exist), use the IP address for eth1.

High Availability Gateway Node

If the Network Address table lists both eth0 and eth1, use either of the IP addresses for eth0 or eth1.

If the Network Address table lists eth0, eth1, and eth2, use the IP Address for eth1.



You can establish HTTP connections from StorageGRID API clients to any of the listed IP addresses. However, you typically want to use the IP address on the customer network instead of the IP address on the grid network or the heartbeat network.

You also need the port number for the CLB service or the LDR service to which you want to connect the StorageGRID API client. See “Port Configuration” on page 110.

Test HTTP Access to the Grid

Use this procedure to confirm that the grid has been configured properly to accept connections from the application.

Prerequisites• The grid software has been installed using the grid specification

file obtained from a NetApp Solutions Engineer.• The HTTP profile has been configured. See “Configure the Grid to

Accept Connections” on page 125.• If the client requires server authentication, the grid certificate has

been copied to the client. See “Acquire the Grid’s CA Certificate” on page 131.

• The routing tables and firewall rules are set up to allow access to the grid’s HTTP and NMS interfaces.

• Metadata have been imported in the grid. Confirm that they are listed in the NMS MI in the HTTP Metadata Indexing table on the Grid

Management HTTP Management Metadata Overview Main

page.

Procedure

In this example, the IP address of the grid server hosting the CLB is 192.168.120.97.

1. Test the connection. From a host within the IP range configured to access the grid, attempt to telnet to the CLB. For example:

NOTE This example assumes you are connecting to the CLB port. For information on other ports, see the Installation Guide.

telnet 192.168.120.97 8081Trying 192.168.120.97...Connected to 192.168.120.97.Escape character is '^]'.


Integration

If the IP range has been configured correctly, there is a delay of several seconds and then the CLB drops the connection:

If the IP range has not been configured correctly, the connection is closed immediately.If the CLB service is not running, or if there is a network error, you will see a Connection refused message:

2. Perform a capability query test to determine if the Clients and Per-

missions options have been set correctly:a. Use the openssl client to establish a connection to the CLB.

Enter: openssl s_client -tls1 -connect 192.168.120.97:8080

Lines starting with ... indicate content removed for brevity.

You may also optionally include the arguments -cert <cert_file-name> and -key <key_filename> in the following form:openssl s_client -tls1 -connect <IP_address> -cert \<cert_filename> -key <key_filename>

Note that the above -cert and -key arguments are required if you have configured your connection to include certificates.A response should look similar to the example below.

b. Test access to the /UUID namespace. Type: OPTIONS /UUID HTTP/1.1

and press Enter twice.

Connection closed by foreign host.

telnet 192.168.120.97 8081Trying 192.168.120.97...telnet: connect to address 192.168.120.97: Connection refusedtelnet: Unable to connect to remote host

CONNECTED(00000003) depth=1 /C=US/ST=California/L=Sunnyvale/O=NetApp Inc./OU=NetApp StorageGRID/CN=GPT verify error:num=19:self signed certificate in certificate chain verify return:0 ...Server certificate -----BEGIN CERTIFICATE----- ... ... -----END CERTIFICATE----- ...



The expected response is similar to:

c. Confirm that the methods listed in the Allow response corre-spond to the options selected on the Permissions page in the NMS MI. See “Configure the Grid to Accept Connections” on page 125.

d. Test access to the /GRID namespace. Type:OPTIONS /GRID HTTP/1.1

and press Enter twice.The expected response is similar to:

3. Test object storage:a. Create a test file. For example, enter:

echo “Hello World” >test.dat

b. Use curl to store the file into the grid. For example, enter:curl -v -k -T test.dat https://192.168.120.97:8081/UUID

If the client has been configured with a certificate, the follow-ing additional options must be added for ingest and retrieval:--cert <cert_filename> --key <key_filename>

An expected response is similar to the following:

HTTP/1.1 200 OKDate: Wed, 13 Aug 2008 00:03:53 GMTContent-Length: 0Allow: OPTIONS, GET, HEAD, PUT, POST, DELETEConnection: KEEP-ALIVE

HTTP/1.1 200 OKDate: Wed, 13 Aug 2008 00:03:53 GMTContent-Length: 0Allow: OPTIONS, POSTConnection: KEEP-ALIVE

About to connect() to 192.168.120.97 port 8081 Trying 192.168.120.97... connected Connected to 192.168.120.97 (192.168.120.97) port 8081 successfully set certificate verify locations: CAfile: /usr/local/share/curl/curl-ca-bundle.crt CApath: none ...PUT /UUID HTTP/1.1 ...HTTP/1.1 100 ContinueHTTP/1.1 201 CreatedDate: Wed, 13 Aug 2008 00:33:48 GMTConnection: KEEP-ALIVEX-UUID: "75162A1F-6D83-4FD3-9474-BE30AE2B2898"X-CBID: "B160E561CEBACC6D"Content-Length: 0...


Integration

c. Confirm that the response header 201 Created is displayed, indicating that the file was stored successfully.

d. Note the UUID returned in the X-UUID response header. 4. Test object retrieval:

a. Use curl to retrieve the file stored in step 3. For example, enter:

curl -v -k -o compare.dat https://192.168.120.97:8080/UUID/<uuid>

where <uuid> is the UUID you recorded in step 3.The expected response includes the following:

b. Verify that the contents of test.dat and compare.dat are identical. Enter: diff test.dat compare.dat

5. Perform a location query. Enter:openssl s_client -tls1 -connect 192.168.120.97:8080

HEAD /UUID/<uuid> HTTP/1.1

X-SYS-LOCS:

and press Enter twice. The response is similar to:

The node IDs returned in the response are different for every grid. 6. Verify that the number of locations returned is consistent with the

grid’s active ILM policy.

Enable the HTTP Audit Feed

Use the NMS MI to enable the HTTP audit feed, set the audit messages to be retrieved, and then enable client access to that feed.

When enabling the HTTP audit feed, you must also use the Storage-GRID API to retrieve messages from the HTTP audit feed queue. If you enable the HTTP audit feed without retrieving messages, the HTTP audit feed queue will continue to grow consuming space on the server where the AMS service is installed. For more information on retrieving messages from the HTTP audit feed queue, see“HTTP Audit Feed Messages” on page 91.

...HTTP/1.1 200 OK...

HTTP/1.1 200 OK ... ... X-SYS-LOCS: CLDI 12023060, CLDI 12603993



1. Log in to the NMS MI using the Vendor account.2. Go to Grid Management Grid Configuration Audit

Configuration Main.3. Under HTTP Audit Feed, select Source <AMS_service>.

NOTE Selecting None disables the HTTP audit feed.

Figure 23: Enabling the HTTP Audit Feed 4. Optionally, add or delete messages types from Accepted Message

Types.These are the messages added to the HTTP audit feed queue with GET. By default, the audit messages added are FSTG, FMFY, FSWI, FDEL, and ORLM. For more information on audit messages, see the Audit Message Reference.

5. Optionally, set audit message filtering in the Audit Levels table. For more information on audit messages, see the Audit Message Reference.

6. Click Apply Changes.7. Enable client access to the HTTP audit feed by creating an HTTP

profile that includes GET and DELETE in the /AUDIT namespace:a. Go to Grid Management HTTP Management Permissions

Configuration Main.


Integration

b. In the HTTP /AUDIT Namespace table, click Edit (or Insert if this is not the first entry).

Figure 24: Configuring HTTP /AUDIT Namespace for HTTP Audit Feedc. Enter a value for Profile Name and select the permissions GET

and DELETE.

NOTE Always select both GET and DELETE. For more information, see “HTTP Audit Feed Messages” on page 91.

d. Click Apply Changes.8. Add the new profile to the HTTP configuration:

a. Go to Grid Management HTTP Management Clients

Configuration Main.

b. Click Edit (or Insert if this is not the first entry).



Figure 25: Configuring the HTTP Profilec. Enter a value for Description.d. Enter a value for IP Range.

This is the IP address or range of IP addresses that the applica-tion will be calling from. A hyphen or slash indicates a range, inclusive of the values entered. For example:• 192.168.120.0/24 (CIDR format)• 192.168.142.20-192.168.142.28 (dotted decimal)An abbreviated format for masks in eight-bit steps is available. For example: 192.168.142.0 is equivalent to the CIDR notation 192.168.142.0/24. This can be extended: n.n.0.0 is equivalent to n.n.0.0/16

e. Select a Profile Name. This is the profile that includes the /AUDIT namespace defined in step 7. The profile governs the permitted activities for con-nections from this IP range.

f. Optionally, validate incoming messages by associating the profile with the client certificate. Select Client Name <client_name>.If a client name is not selected, only the source IP address is used to validate incoming connections.For more information on configuring a client certificate, see “Configure the Grid to Accept Connections” on page 125.

g. Click Apply Changes.The HTTP audit feed is enabled and configured to retrieve audit messages.


Integration

Duplicate OIDs in Grid Node Certificates

Grid node certificates have multiple extensions that use the same OID. This may be interpreted as a violation of the X509v3 standard accord-ing to RFC 3280. As a result, some third party libraries may reject grid node certificates when interfacing with the StorageGRID API.

If the grid is integrated with a third-party application via the Storage-GRID API and the grid node certificates are rejected, use the following procedure to update the certificates.

1. Log in to the primary Admin Node as root using the password listed in the Password.txt file.

2. Generate a new certificate with no extensions. Enter: add-client-certificate

3. Run the Update Flags grid task generated by the add-client-certificate command:a. In the NMS MI, go to <grid_root> Configuration Tasks.

b. In the Pending table, locate the grid task Update Flags. Under Actions, select Start.

c. Click Apply Changes.The grid task moves to the Active table.

d. Wait until the grid task moves to the Historical table with a status of Successful.




B
Reference Information
Standards Listing

Using the StorageGRID API requires familiarity with standards defined by the documents listed in Table 13.

Table 13: Standards

Standard Available At

HTTP/1.1 (RFC 2616) . The definition of the Hyper-Text Transfer Protocol.


Uniform Resource Identifiers (URI) RFC 2396 http://www.ietf.org/rfc/rfc2396.txt

Multipurpose Internet Mail Extensions (MIME) Part One (RFC 2045) . Includes Base64 Encoding Standard.


UTF-8, a transformation format of ISO 10646 (RFC 2279) http://www.ietf.org/rfc/rfc2279.txt

ASCII. Internet standard version, based on ANSI X3.4-1986, as described in RFC 1345


Universal Multiple-Octet Coded Character Set (UCS) (ISO/IEC 10646:2003)

http://www.iso.org/

Data elements and interchange formats – Information interchange — Representation of dates and times (ISO 8601:2000)

http://www.iso.org/

Universally Unique IDentifier (UUID) URN Namespace (RFC 4122)


Extensible Markup Language (XML) 1.0 http://www.w3.org/TR/REC-xml/







http://www.iso.org/

http://www.iso.org/


http://www.w3.org/TR/REC-xml/


HTTP Standard Headers

The standard HTTP headers used in the StorageGRID API are listed in Table 14.

Table 14: Standard HTTP Headers

Header Description

Allow The HTTP commands allowed in the namespace,in a comma-delimited list.

See section 14.7 of HTTP/1.1 (RFC 2616).

Connection Indicates whether the connection is to be maintained for more transactions or should be closed after the request has been serviced.

Allowable values are KEEP-ALIVE and CLOSE.

Default for HTTP/1.1 is KEEP-ALIVE.


Content-Length The length, in decimal bytes, of the response. Does not include the headers or any other information that may follow or precede the entity.

Ignored if Chunked encoding is specified.

Required if Identity encoding is used.


Content-Type Indicates the data type of the entity that is contained in the message, in the format described in RFC 2045 http://www.ietf.org/rfc/rfc2045.txt.

Recommended: If stored objects are accessed by industry-standard web browsers, the MIME type is important to allow the browser to render the contents correctly.

If no media type is specified, none is assigned.

Date The date and time of the message, in the format described in section 3.3.1 of RFC 2616. For example:

Date: Tue, 15 Nov 1994 08:12:31 GMT

See also section 14.18 of HTTP/1.1 (RFC 2616).

Host The hostname and port number of the server the client is making the request to. Indicates the network identity of the entity that is performing the transaction.













Last-Modified The date and time when the requested object was last changed. It is pri-marily used in determining when cached data must be refreshed.


User-Agent Information about the client software that is making the request. The contents of the user-agent field is up to the application, but should follow the guidelines for HTTP user agents.


Accept-Encoding Indicates what network transfer encodings are supported by the client.

Allowable values are gzip and Identity:

• gzip — The object is compressed for network transfer.

• Identity — The object is not compressed for network transfer.



Content-Encoding Indicates the network transfer encoding applied to the message body.

Allowable values are gzip and Identity:

• gzip — The object is compressed for network transfer.

• Identity — The object is not compressed for network transfer.



Transfer-Encoding Indicates how the transfer is to be encoded. If multiple encodings are applied to the message body they must be listed in the order applied.

Allowable values are Chunked and Identity:• Identity — The data is sent in a single block within the request or

response.• Chunked — The content is split into multiple parts or “chunks”. Each

chunk is preceded by the size of the chunk in hexadecimal. This size does not include the <CR><LF> that terminates the chunk contents. The end of the transfer is indicated with a chunk of size zero.



Table 14: Standard HTTP Headers (cont.)

Header Description








HTTP Status Codes

The standard HTTP status codes used in the StorageGRID API are listed in Table 15. For more information, see HTTP/1.1 (RFC 2616) at http://www.ietf.org/rfc/rfc2616.txt.

Table 15: Standard HTTP Status Codes

Header Description

100 Continue Indicates that the server has parsed the request and is willing to receive the entity associated with the command. This is only in response to the request header Expect: 100-continue. The server also sends a response to the command after the entity is transferred.

200 OK Successful request

201 Created Returned in response to a successful PUT request to indicate that the object sent in the request was successfully stored in the grid.

202 Accepted Returned in response to a correctly formatted DELETE command. This is an advisory response that indicates that the request has been accepted and will be processed by the grid. The deletion of the UUID is not guaranteed.

400 Bad Request The request is not properly formed, either according to the HTTP standard or the conventions established in this guide. The returned HTML page indicates what was incorrect, if possible.

403 Forbidden The request was not executed because the client does not have the appro-priate permissions. The returned HTML page indicates why the request was forbidden. For example:• The client may not have permission to use HTTP, that is, the client IP

address has not been mapped to an HTTP profile in the NMS MI and the grid is not configured to accept HTTP connections from the client. For more information, see “Configure the Grid to Accept Connections” on page 125.

• Objects are submitted with the X-SYS-DDUP or X-SYS-SLICE headers when the GE Optimized Store feature is not enabled.

NOTE GE Optimized Store is deprecated.

• Security partitioning is enabled and the HTTP client has made a GET, HEAD, or DELETE request for an object for which the HTTP client does not have read or write permission. For more information on security partitions, see “Security Partitions” on page 132.




404 Not Found The UUID specified in the URI of the request was not found, and is defini-tively known not to exist in the StorageGRID grid. If part of the grid is not accessible, so that the grid can not definitively tell if the UUID exists in the grid, the response is 503 Service Unavailable.

Avoid requesting content that does not exist as this is an expensive operation.


The action specified in the request is not allowed in the namespace.

A client receives this response if the grid has not been configured to permit the particular method that it has attempted. For more information, see “Configure the Grid to Accept Connections” on page 125.

408 Request Timeout The client did not send the complete request (header and content) within the time that the server was configured to wait. The connection is closed.

411 Length Required The request specified Identity encoding, but did not include a header to specify content length.


There is a data type error in the PUT request. For example:• The data type of metadata submitted does not match its defined type. • An object is submitted with a metadata field that has not been defined.• An object submitted with the X-SYS-SLICE:GESIS header is not a valid

tar file.


The server encountered a problem when processing the request that pre-vented it from completing the request. The body of the response indicates the nature of the problem, for example, the HTTP request headers are too large or there was an abnormal software event.


Part of the grid is not accessible. For example:• The UUID specified in a GET or HEAD request was not found but the

software cannot definitively determine if the object is in the grid because part of the grid is not accessible.

• An LDR cannot connect to any CMS to release a content handle for an HTTP DELETE request.


The server does not support the version indicated in the request.

Table 15: Standard HTTP Status Codes (cont.)



Data Type Definitions

Table 16 lists the data type abbreviations used with the POST method.

Data types are case-sensitive. For example, you must specify type = “FC32“, not type=”fc32”.

Table 16: Supported Data Types for POST Method

Data Type Description

CSTR String values

CSTR values must be escaped according to the rules as outlined in “Character Sets” on page 156.

Cannot contain null characters.

Example: <atom name="DESC" type="CSTR" value="This string \\ includes a backslash" />

FC32 A 32 bit unsigned integer value represented as four ASCII characters. Used as a mecha-nism to make numeric constants more readable. It is recommended that only printable alphanumeric characters be used to construct an FC32, although in some cases non-printable FC32 are used.

FP64 Floating point, 64-bits

Provides higher precision floating point numbers with a range magnitude minimum of 2.2250E-308 and a range magnitude maximum of 1.7976E+308 (either can be positive or negative). The precision is usually to 16 decimal places.

IPAD IP addresses. Supports IPv4 and IPv6 protocols.

IPv4: Use the representation nnn.nnn.nnn.nnn, where n is an integer.

IPv6: Use hexadecimal digits and colon separators.

IPv4 example: <atom name="IPAD" type="IPAD" value="192.168.170.93" />

IPv6 example: <atom name="IPAD" type="IPAD" value="2001:db8:1a4c::c850:21fe:3cd7:adeb" />

IP32 IP addresses. For legacy compatibility only.

Use the representation nnn.nnn.nnn.nnn, where n is an integer.

Example: <atom name="IPAD" type="IP32" value="192.168.170.93" />

NULL The data type of the atoms that encode the information requested in an object query (atoms in the QOUT container) or in a grid query (atoms in the QSHW container).



Ensure that the data type of any value that you submit as part of a filter matches the data type of the property being filtered. For example, the following container encodes a filter to find all objects with a value of DTYP equal to nnnn where the value you substitute for nnnn must be of type FC32:

SI32 Signed integer, 32-bits

Can store numbers that range from +2147483647 to -2147483648 (231 - 1 to -231 )

SI64 Signed integer, 64-bits

Can store numbers from +9,223,372,036,854,775,807 to -9,223,372,036,854,775,808 (263 - 1 to -263)

UI32 Unsigned integer, 32-bits

Can store numbers from 0 through 4294967295. (232 -1)

UI64 Unsigned integer, 64-bits

Used for decimal numbers from 0 through 18446744073709551615. (264 -1)

USTR Unicode string. Used internally to store Unicode multibyte character text.

UUID A 128 bit binary object identifier. UUIDs used by StorageGRID are 128 bits with an internal binary structure and a string representation as described in the IETF RFC 4122 found at http://www.ietf.org/rfc/rfc4122.txt. The string representation is not delimited by double quotes. For more information on UUIDs, see “UUIDs” on page 21.

Table 16: Supported Data Types for POST Method (cont.)

Data Type Description

<container name="SVFI"><atom name="PTYN" type="FC32" value="DTYP" /><atom name ="RELA" type="FC32" value="EQUL" /><atom name="VALU" type ="FC32" value="nnnn" />

</container>




Character Sets

When using strings in the custom headers of the PUT and POST requests, you must escape the characters shown in Table 17. All of these rules are compatible with the HTTP standard.

For example, to submit the string \\&\"7 as metadata, you must escape it as: X-BYC-AAAA: "\\\\&\\\"7"

The double quotes surrounding the string identify it to the grid as string metadata to be stored as the CSTR data type.

In general, string escaping uses a subset of the backslash escaping rules used in the C/C++ programming languages. Do not use any valid C/C++escaped characters that are not listed in Table 17. For example, \t is not valid.

You must escape characters before submitting strings to the grid because StorageGRID accepts non-UTF-8 characters and some UTF-8 characters that are not supported for use in XML. Invalid UTF-8 sequences are one or more high ASCII bytes (bytes with values greater than 0x7F) which are not mappable to a UTF-8 character. These sequences may occur in character sets such as Latin-1, or in binary data. It is permitted, but not encouraged, to use the \xHH escaped version of characters listed in Table 17, or the \xHH version of standard printable characters (such as \x41 for “A”).

Table 17: Valid Escaped Characters in Strings

Character Escaped Format

Backslash \\

Line feed (new line) \n

Carriage Return \r

Double Quote (") \"

Control Character \xHH

where HH is the hexadecimal value of the speci-fied character

Byte in an invalid UTF-8 sequence

\xHH

where HH is the hexadecimal value of the speci-fied byte sequence



XML Structure

The requests and responses of the POST method are encoded in XML. The StorageGRID API includes an XML parser that validates the XML included in a POST method against these XML schemas:• “Object Query Schema” on page 63• “Grid Query Schema” on page 89• “Audit Message XML Schema” on page 108

These schema are specified in RELAX NG compact format. For more information on the RELAX NG schema language, see http://relaxng.org/.

All requests and responses include a wrapper that identifies the content as XML and defines the contents of the XML to be a container:

Inside that wrapper, XML elements describe the information exchange. The XML elements are either containers or atoms. Contain-ers can contain atoms to further specify the information contained in the container. Containers and atoms within a POST XML query must be placed in correct order specified by the XML schema.

For a description of the rules governing character usage in POST XML, including escaping rules for restricted characters, see “Character Sets” on page 156.

NOTE The examples in this guide use double quotes to delimit values in XML statements; single quotes are also accepted.

<?xml version="1.0" encoding="UTF-8"?><containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">...</containerxml>


http://relaxng.org/

http://relaxng.org/


<<

<

This is an example of the XML used for a grid query:

?xml version="1.0" encoding="UTF-8"?>containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">



<atom name="PTYN" type="FC32" value="SVID" /><atom name="RELA" type="FC32" value="EQUL" /><atom name="VALU" type="FC32" value="CERT" />


<atom name="PTYN" type="FC32" value="CONN" /><atom name="RELA" type="FC32" value="EQUL" /><atom name="VALU" type="FC32" value="ONLN" />


<atom name="PTYN" type="FC32" value="DTYP" /><atom name="RELA" type="FC32" value="EQUL" /><atom name="VALU" type="FC32" value="BLDR" />


<atom name="PTYN" type="FC32" value="STAS" /> <atom name ="RELA" type="FC32" value="GREA" /> <atom name="VALU" type ="UI64" value="500000000000" />

</container></container><container name="QRNK">

<atom name="PTYN" type="FC32" value="LINK" /><atom name="SORT" type="FC32" value="ASCE" />


<atom name="NOID" type="NULL" value="" /><atom name="IPAD" type="NULL" value="" /><atom name="SVST" type="NULL" value="" /><atom name="STAS" type="NULL" value="" /><atom name="LINK" type="NULL" value="" /><atom name="RANK" type="NULL" value="" />




C
ExamplesSample Ruby code
Introduction

This section includes sample Ruby code that demonstrates how to:

1. Perform a grid topology query to determine on which LDR to store the object.

2. Store an object to that LDR.3. Perform an object query to find the object created in step 2.4. Perform a grid topology query to determine from which LDR to

retrieve the object found in step 3.5. Retrieve the object found in step 3.6. Delete the object found in step 3.7. Submit an audit message.8. Retrieve an audit message from the HTTP audit feed queue.9. Delete the next audit message from the HTTP audit feed queue.

About the ExamplesThe examples are based on the following assumptions:• The examples are for illustration purposes only. They do not con-

stitute a complete application. • The application connects to the grid via an LDR and not a CLB.• The IP addresses and port numbers are hard-coded.• Security partitioning is enabled.

Find LDR for Object Storage (POST Grid Query)

In this example, the client application submits a query to identify on which LDR to store the object. The query looks for enabled services



that offer the HTTP Ingest service (HING), listed in descending order of suitability according to the STOR ranking profile.

#!/usr/bin/env ruby ###################################################################### Grid topology query to identify a suitable LDR for object storage# Example provided for illustration purposes only#####################################################################require 'socket'require 'openssl'

# Encode query in XML# Define query: look for nodes that are enabled (ENBL) # and provide the HTTP Ingest service (HING)# Return a maximum of 80 results# Rank results in descending order of suitability, using the STOR ranking profile# For each LDR, include node ID, IP address, device type# total storage capacity and storage capacity availableQUERY_STRING =<<"END"<?xml version="1.0" encoding="UTF-8"?><containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">



<atom name="PTYN" type="FC32" value="SVID" /><atom name="RELA" type="FC32" value="EQUL" /><atom name="VALU" type="FC32" value="HING" />


<atom name="PTYN" type="FC32" value="SVST" /><atom name="RELA" type="FC32" value="EQUL" /><atom name="VALU" type="FC32" value="ENBL" />


<atom name="PROF" type="FC32" value="STOR" /><atom name="SORT" type="FC32" value="DESC" />


<atom name="NOID" type="NULL" value="" /><atom name="IADR" type="NULL" value="" /><atom name="DTYP" type="NULL" value="" /><atom name="STTS" type="NULL" value="" /><atom name="STAS" type="NULL" value="" />


</container></containerxml>END

print "Querying grid topology...\n"


Examples

# Establish HTTP session with grid server. Use IP address of any LDR on the grid.# Port 18080 is LDR Query/Retrieve portsocket = TCPSocket.new('192.168.100.192', 18080)# # Present client certificate and keyssl_context = OpenSSL::SSL::SSLContext.new()ssl_context.cert = OpenSSL::X509::Certificate.new(File.open("client.crt"))ssl_context.key = OpenSSL::PKey::RSA.new(File.open("client.key"))

ssl_socket = OpenSSL::SSL::SSLSocket.new(socket, ssl_context)ssl_socket.sync_close = truessl_socket.connect

# Submit POST request in GRID namespace# Include mandatory headers host and content length and optional header connectionssl_socket.write("POST /GRID/ HTTP/1.1\r\n")ssl_socket.write("host: 192.168.100.192\r\n")ssl_socket.write("connection: close\r\n")ssl_socket.write("content-length: " + QUERY_STRING.length.to_s + "\r\n")# Insert carriage return/line feed between last header and query contentssl_socket.write("\r\n")ssl_socket.write(QUERY_STRING)

print "--------------------------------------------------------------------------\n"while line = ssl_socket.gets

print lineendprint "--------------------------------------------------------------------------\n"



This is a sample result container in response to the topology query above. As specified in the request, the response includes a list of LDRs, and for each LDR, indicates the node ID, IP address, device type, total storage capacity, and available storage capacity. The link cost and rank of each LDR are also returned, even if not specified in the request.

Store Object (PUT)

In this example, the client application stores an object on the LDR that had the highest rank in the previous topology query , that is, LDR with IP address 192.168.100.192. The predefined metadata ”XAID” is submit-ted and dual commit is requested.




<container name="0x00000001"><atom name="NOID" type="UI32" value="2170092" /><atom name="IADR" type="IPAD" value="192.168.100.192" /><atom name="DTYP" type="FC32" value="BLDR" /><atom name="STTS" type="UI64" value="19334316032" /><atom name="STAS" type="UI64" value="19151515648" /><atom name="LINK" type="UI64" value="10" /><atom name="RANK" type="FP64" value="0.7939283" />


<atom name="NOID" type="UI32" value="2170093" /><atom name="IADR" type="IPAD" value="192.168.100.193" /><atom name="DTYP" type="FC32" value="BLDR" /><atom name="STTS" type="UI64" value="19677314022" /><atom name="STAS" type="UI64" value="18252435669" /><atom name="LINK" type="UI64" value="10" /><atom name="RANK" type="FP64" value="0.7226283" />




Examples

#!/usr/bin/env ruby ###################################################################### PUT transaction in UUID namespace to store content into the grid# Example provided for illustration purposes only#####################################################################require 'socket'require 'openssl'

print "Enter data to be stored as an object. Type CTRL-D to end.\n"body = $stdin.read

# Establish HTTP session with grid server# Use IP address of LDR that will store object# Port 18081 is LDR Ingest portsocket = TCPSocket.new('192.168.100.192', 18081)

# Present client certificate and keyssl_context = OpenSSL::SSL::SSLContext.new()ssl_context.cert = OpenSSL::X509::Certificate.new(File.open("client.crt"))ssl_context.key = OpenSSL::PKey::RSA.new(File.open("client.key"))


# Submit PUT request in UUID namespace. # Include mandatory headers host and content length and optional header connectionssl_socket.write("PUT /UUID/ HTTP/1.1\r\n")ssl_socket.write("host: 192.168.100.192\r\n")ssl_socket.write("connection: close\r\n")ssl_socket.write("content-length: " + body.length.to_s + "\r\n")

# Specify dual commit. Dual commit is on a best-effort basis.ssl_socket.write("X-SYS-DUAL: \r\n")ssl_socket.write("content-type: text/plain\r\n")

# XAID is a predefined metadata tag. # Enclose metadata value between quotation marks and use escape charactersssl_socket.write("X-BYC-XAID: \"ABCD\"\r\n")

# Insert carriage return/line feed between last header and object datassl_socket.write("\r\n")ssl_socket.write(body)





This is a sample response for the request above.

The object was ingested as indicated by the 201 Created header. The UUID assigned by the grid to the object is returned. The X-HASH header contains the hash value of the object that can be used for integrity checks.

Because the X-SYS-DUAL header was included in the request, the response includes a X-SYS-NLOC header that indicates how many initial copies of the data were made. Dual commit is on a best effort basis. In this example, X-SYS-NLOC has a value of 1, indicating that only one of the two requested initial copies was created. This may occur if only one Storage Node in the grid was writable when the object was ingested, or if network issues prevented the second initial copy from being made. The Content-Length header of a PUT response is always 0.

HTTP/1.1 201 CreatedDate: Mon, 09 Jan 2010 08:49:37 GMTConnection: CLOSEX-UUID: "2FAC1234-31F8-11B4-A222-08002B34C003"X-CBID: "A489B9EF96237023"X-HASH: "SHA2,A948904F2F0F479B8F8197694B30184B0D2ED1C1CD2A1EC0FB85D299A192A447"X-SYS-NLOC: 1Content-Length: 0


Examples

Find Object (POST Object Query)

In this example, the client application submits a POST query in the UUID namespace to find the object stored in the previous example. The query looks for objects where the predefined metadata XAID is “ABCD”.

#!/usr/bin/env ruby ###################################################################### POST transaction in UUID namespace to find an object stored# Example provided for illustration purposes only#####################################################################require 'socket'require 'openssl'

# Encode query in XML# Look for object where the value of XAID is "ABCD"# Include the UUID (CHND) in the result so that object can be retrieved using UUID# CHND must precede all other atoms in QOUT container# Return the application identifier(XAID predefined metadata)QUERY_STRING =<<"END"<?xml version="1.0" encoding="UTF-8"?> <containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">

<container name="CBQA"><container name="QINP">

<container name="APPM"> <container name="XAID">

<atom name="RELA" type="FC32" value="EQUL" /> <atom name="VALU" type="CSTR" value="ABCD" />


</container> <container name="QOUT">

<atom name="CHND" type="NULL" value="" /> <container name="APPM">

<atom name="XAID" type="NULL" value="" /> </container>


</containerxml>END



print "Querying for objects containing metadata in grid...\n"# Establish HTTP session with grid server. Use IP address of any LDR on the grid.# Port 18080 is LDR Query/Retrieve portsocket = TCPSocket.new('192.168.100.192', 18080)



# Submit POST request in UUID namespace# Include mandatory headers host and content-lengthssl_socket.write("POST /UUID/ HTTP/1.1\r\n")ssl_socket.write("host: 192.168.100.192\r\n")ssl_socket.write("connection: close\r\n")ssl_socket.write("content-length: " + QUERY_STRING.length.to_s + "\r\n")# Insert carriage return/line feed between last header and query contentssl_socket.write("\r\n")ssl_socket.write(QUERY_STRING)




Examples

HTTP/Date:ConneConte

<?xml<contxmlns

<c

</</con

This is a sample result container in response to the object query above. There is one result. The information returned includes the value of the object identifier UUID and the value of the predefined metadata ”XAID”.

Find LDR for Object Retrieval (POST Grid Query)

In this example, the client application submits a query to identify which LDR to retrieve the object from. The query looks for enabled services that offer the query/retrieve service (HCLN), listed in descend-ing order of suitability according to the RTRV ranking profile.

1.1 200 OK Mon, 07 Jan 2008 08:49:37 GMTction: CLOSEnt-Length: 571

version="1.0" encoding="UTF-8"?>ainerxml version="1" ="http://www.bycast.com/schemas/XML-container-1.0.0">ontainer name="CBQN"><atom name="NRES" type="UI32" value="1" /><atom name="RSLT" type="FC32" value="SUCS" /><atom name="QSTS" type="FC32" value="CFUL" /><container name="QRSL">

<container name="0x00000001"><atom name="CHND" type="CSTR" value="2FAC1234-31F8-11B4-A222-08002B34C003" /><container name="APPM"><atom name="XAID" type="CSTR" value="ABCD" /></container>


container>tainerxml>



#!/usr/bin/env ruby ###################################################################### Grid topology query to identify a suitable LDR for object retrieval# Example provided for illustration purposes only#####################################################################require 'socket'require 'openssl'

# Encode query in XML# Define query: look for nodes that are enabled (ENBL)# and provide the query/retrieve service (HCLN)# Return a maximum of 80 results# Rank results in descending order of suitability, using the RTRV ranking profile# For each LDR, include node ID, IP address, device typeQUERY_STRING =<<"END"<?xml version="1.0" encoding="UTF-8"?><containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">



<atom name="PTYN" type="FC32" value="SVID" /><atom name="RELA" type="FC32" value="EQUL" /><atom name="VALU" type="FC32" value="HCLN" />


<atom name="PTYN" type="FC32" value="SVST" /><atom name="RELA" type="FC32" value="EQUL" /><atom name="VALU" type="FC32" value="ENBL" />


<atom name="PROF" type="FC32" value="RTRV" /><atom name="SORT" type="FC32" value="DESC" />


<atom name="NOID" type="NULL" value="" /><atom name="IADR" type="NULL" value="" /><atom name="DTYP" type="NULL" value="" />


</container></containerxml>END

print "Querying grid topology...\n"


Examples

This is a sample response to the topology query above. As specified in the request, the response includes a list of LDRs, and for each LDR, indicates the node ID, IP address, and device type. The link cost and rank of each LDR are also returned, even if not specified in the request.

# Establish HTTP session with grid server. Use IP address of any LDR on the grid.# Port 18080 is LDR Query/Retrieve portsocket = TCPSocket.new('192.168.100.192', 18080)# # Present client certificate and keyssl_context = OpenSSL::SSL::SSLContext.new()ssl_context.cert = OpenSSL::X509::Certificate.new(File.open("client.crt"))ssl_context.key = OpenSSL::PKey::RSA.new(File.open("client.key"))


# Submit POST request in GRID namespace# Include mandatory headers host and content length and optional header connectionssl_socket.write("POST /GRID/ HTTP/1.1\r\n")ssl_socket.write("host: 192.168.100.192\r\n")ssl_socket.write("connection: close\r\n")ssl_socket.write("content-length: " + QUERY_STRING.length.to_s + "\r\n")# Insert carriage return/line feed between last header and query contentssl_socket.write("\r\n")ssl_socket.write(QUERY_STRING)








<container name="0x00000001"><atom name="NOID" type="UI32" value="2170093" /><atom name="IADR" type="IPAD" value="192.168.100.193" /><atom name="DTYP" type="FC32" value="BLDR" /><atom name="LINK" type="UI64" value="10" /><atom name="RANK" type="FP64" value="0.7939283" />


<atom name="NOID" type="UI32" value="2170092" /><atom name="IADR" type="IPAD" value="192.168.100.192" /><atom name="DTYP" type="FC32" value="BLDR" /><atom name="LINK" type="UI64" value="10" /><atom name="RANK" type="FP64" value="0.7226283" />




Examples

Retrieve Object (GET)

In this example, the client application retrieves the object and associ-ated metadata (”XAID”). The GET request specifies the UUID of the object identified in the results of the object query on page 165. The object is retrieved from the LDR that had the highest rank in the previous topology query, that is, LDR with IP address 192.168.100.193.

#!/usr/bin/env ruby ###################################################################### GET transaction in UUID namespace to retrieve an object using its UUID# Example provided for illustration purposes only#####################################################################require 'socket'require 'openssl'

# The UUID of the object to be retrieveduuid = "2FAC1234-31F8-11B4-A222-08002B34C003"

print "Retrieving object from grid...\n"# Establish HTTP session with LDR best suited to handle retrieve request# Port 18080 is LDR Query/Retrieve portsocket = TCPSocket.new('192.168.100.193', 18080)



# Submit GET request in UUID namespace# Include mandatory header hostssl_socket.write("GET /UUID/" + uuid + " HTTP/1.1\r\n")ssl_socket.write("host: 192.168.100.193\r\n")ssl_socket.write("connection: close\r\n")# Include header for predefined metadata XAID to be returned with objectssl_socket.write("X-BYC-XAID: \r\n")# Include header for number of locations to be returned with objectssl_socket.write("X-SYS-NLOC: \r\n")# Insert carriage return/line feed after last headerssl_socket.write("\r\n")





This is a sample response:

Delete Object (DELETE)

In this example, the client application deletes the object that has just been retrieved. The DELETE request specifies the UUID of the object identified in the results of the object query on page 165.

HTTP/1.1 200 OKDate: Mon, 07 Jan 2008 08:49:37 GMTConnection: CLOSEContent-Length: 801284Last-modified: Mon, 07 Jan 2008 08:18:29 GMTContent-Type: text/plainX-HASH: "SHA2,A948904F2F0F479B8F8197694B30184B0D2ED1C1CD2A1EC0FB85D299A192A447"X-CBID:"A489B9EF96237023"X-BYC-XAID: "ABCD"X-SYS-NLOC: 2

<801,284 bytes of binary data; the object text file>


Examples

This is a sample response for this DELETE request (202 Accepted).

#!/usr/bin/env ruby ###################################################################### DELETE transaction in UUID namespace to delete an object using its UUID# Example provided for illustration purposes only#####################################################################require 'socket'require 'openssl'

# The UUID of the object to be deleteduuid="2FAC1234-31F8-11B4-A222-08002B34C003"

print "Deleting object from grid...\n"# Establish HTTP session with LDR that was chosen to retrieve the object# Port 18080 is LDR Query/Retrieve portsocket = TCPSocket.new('192.168.100.193', 18080)



# Submit DELETE request in UUID namespace# Include mandatory header hostssl_socket.write("DELETE /UUID/" + uuid + " HTTP/1.1\r\n")ssl_socket.write("host: 192.168.100.193\r\n")ssl_socket.write("connection: close\r\n")ssl_socket.write("\r\n")



HTTP/1.1 202 Accepted Date: Mon, 07 Jan 2008 08:49:37 GMTConnection: CLOSEContent-Length: 0



Confirm Object Deletion (HEAD)

This example shows a HEAD request used to determine if the object has in fact been deleted. If the object is no longer accessible by the client, the response will include the 404 Not Found status code. Whether the object is purged from the grid depends on how the ILM policy is configured.

#!/usr/bin/env ruby ###################################################################### HEAD transaction in UUID namespace to determine whether object was deleted# Example provided for illustration purposes only#####################################################################require 'socket'require 'openssl'

# The UUID of the object that was deleteduuid = "2FAC1234-31F8-11B4-A222-08002B34C003"

print "Looking for object in grid...\n"# Establish HTTP session with the LDR that was chosen to retrieve the object# Port 18080 is LDR Query/Retrieve portsocket = TCPSocket.new('192.168.100.193', 18080)



# Submit HEAD request in UUID namespace# Include mandatory header hostssl_socket.write("HEAD /UUID/" +uuid + " HTTP/1.1\r\n")ssl_socket.write("host: 192.168.100.193\r\n")ssl_socket.write("connection: close\r\n")ssl_socket.write("\r\n")




Examples

This is a sample response if the object is no longer accessible by the client (404 Not Found).

Submit Audit Message (POST)

In this example, the client application submits a custom audit message. The atom EVNT is user-defined.

HTTP/1.1 404 Not FoundDate: Mon, 07 Jan 2009 08:49:37 GMTConnection: CLOSE

#!/usr/bin/env ruby ###################################################################### POST transaction in AUDIT namespace to submit custom audit message# Example provided for illustration purposes only.#####################################################################require 'socket'require 'openssl'

#XML that encodes the audit message#Include the result of the action, the application identifier, the type of audit #message, the version of the audit message, and the name of the audit messageQUERY_STRING =<<"END"<?xml version="1.0" encoding="UTF-8"?><containerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">

<container name="AUDS"><container name="AUDT">

<atom name="RSLT" type="FC32" value="SUCS" /><atom name="XAID" type="FC32" value="ABCD" /><atom name="XTYP" type="FC32" value="TEST" /><atom name="XVER" type="UI32" value="1" /><atom name="EVNT" type="CSTR" value="Test Audit Message" />


</containerxml>END



This is a sample response:

print "Submitting custom audit message...\n"# Establish HTTP session with grid server. Use IP address of any LDR on the grid.# Port 18080 is LDR Query/Retrieve portsocket = TCPSocket.new('192.168.100.192', 18080)



# Submit POST request in AUDIT namespace# Include mandatory headers host and content-lengthssl_socket.write("POST /AUDIT/ HTTP/1.1\r\n")ssl_socket.write("host: 192.168.100.192\r\n")ssl_socket.write("connection: close\r\n")ssl_socket.write("content-length: " + QUERY_STRING.length.to_s + "\r\n")# Insert carriage return/line feed between last header and query contentssl_socket.write("\r\n")ssl_socket.write(QUERY_STRING)



HTTP/1.1 200 OKContent-Length: 54Date: Thu, 22 Feb 2007 22:43:22 GMTConnection: CLOSE

<HTML><HEAD><TITLE></TITLE></HEAD><BODY></BODY></HTML>


Examples

Retrieve an Audit Message (GET)

This example retrieves an audit message from the HTTP audit feed queue.

#!/usr/bin/env ruby###################################################################### GET transaction in AUDIT namespace to retrieve from event feed.# Example provided for illustration purposes only.#####################################################################require 'socket'require 'openssl'

print "Retrieving next audit message from event feed...\n"

# Establish HTTP session with grid server. Use IP address of any LDR on the grid.# Port 18080 is LDR Query/Retrieve portsocket = TCPSocket.new('192.168.100.192', 18080)



# Submit GET request in AUDIT namespace# Include mandatory header hostssl_socket.write("GET /AUDIT/FEED?values:1 HTTP/1.1\r\n")ssl_socket.write("host: 192.168.100.193\r\n")ssl_socket.write("connection: close\r\n")ssl_socket.write("\r\n")

print "--------------------------------------------------------------------------\n"while line = ssl_socket.gets print lineendprint "--------------------------------------------------------------------------\n"



HTTDatConConCon

<?x<co<co </c

This is a sample response to this GET command that returns an audit message:

P/1.1 200 OKe: Mon, 07 Jan 2009 08:49:37 GMTnection: CLOSEtent-Length: 822tent-Type: text/xml

ml version="1.0" encoding="UTF-8"?>ntainerxml version="1" xmlns="http://www.bycast.com/schemas/XML-container-1.0.0">ntainer name="AUDS"> <container name="AUDT"> <atom name="ATYP" type="FC32" value="FDEL" /> <atom name="ANID" type="UI32" value="20591902" /> <atom name="AVER" type="UI32" value="9" /> <atom name="ATIM" type="UI64" value="1265422036709332" /> <atom name="ATID" type="UI64" value="2145065030581231444" /> <atom name="AMID" type="FC32" value="FSGC" /> <atom name="ASQN" type="UI64" value="10" /> <atom name="ASES" type="UI64" value="1265308233627009" /> <atom name="FPTH" type="CSTR" value="/fsg/documents/name.txt" /> <atom name="UUID" type="CSTR" value="D1323D85-C1DE-491E-837B-35A8F9C5278B" /> <atom name="FGRP" type="UI32" value="1" /> </container></container>ontainerxml>


Examples

Delete an Audit Message (DELETE)

This example acknowledges the successful retrieval of an audit message from the HTTP audit feed queue by deleting the retrieved message from the queue.

This is a sample response for this DELETE command:

#!/usr/bin/env ruby###################################################################### DELETE transaction in AUDIT namespace to acknowledge from HTTP audit feed.# Example provided for illustration purposes only.#####################################################################require 'socket'require 'openssl'

print "Acknowledging next audit message from HTTP audit feed...\n"

# Establish HTTP session with grid server. Use IP address of any LDR on the grid.# Port 18080 is LDR Query/Retrieve portsocket = TCPSocket.new('192.168.100.192', 18080)



# Submit DELETE request in AUDIT namespace# Include mandatory header hostssl_socket.write("DELETE /AUDIT/FEED?values:1 HTTP/1.1\r\n")ssl_socket.write("host: 192.168.100.193\r\n")ssl_socket.write("connection: close\r\n")ssl_socket.write("\r\n")

print "--------------------------------------------------------------------------\n"while line = ssl_socket.gets print lineendprint "--------------------------------------------------------------------------\n"

HTTP/1.1 204 No ContentDate: Mon, 07 Jan 2009 08:49:37 GMTConnection: KEEP-ALIVEContent-Length: 0




Date post:	25-May-2020
Category:	Documents
Upload:	others
View:	32 times
Download:	0 times

StorageGRID API Reference Guide -...

Documents