Overview

To access a namespace and take action in it, clients must have the necessary permissions. The list below describes the possible permissions and the operations they allow.

• Browse

  • List directory contents.
  • Check for directory existence.

• Read

  • Retrieve objects and system metadata.
  • Check for object existence.
  • List annotations.
  • Check for and retrieve annotations.

  Read operations also require browse permission.

• Read ACL

  Check for and retrieve ACLs.

• Write

  • Store objects.
  • Create directories.
  • Modify system metadata.
  • Add and replace annotations.

• Write ACL

  Add, replace, and delete ACLs.

• Delete

  Delete objects, empty directories, annotations, and ACLs.

• Purge

  Delete objects and their old versions (also requires delete permission).

• Privileged

  • Delete or purge objects regardless of retention (also requires delete or purge permissions).
  • Place objects on hold or release objects from hold (also requires write permission).

• Change owner

  Change object owners.

• Search

  Search for objects (also requires browse and read permissions).

The operations allowed in a namespace are determined by a data access permission mask for the namespace. Data access permission masks are set at the system, tenant, and namespace levels.

The effective permissions for a namespace are the operations that are allowed by the mask at all three levels. That is, to be in effect for a namespace, a permission must be included in the system-level permission mask, the tenant-level permission mask, and the namespace-level permission mask.

To perform an operation in a namespace, the operation must be allowed by the effective permission mask and by your user permissions. The permissions for what you can do in a namespace come from your user account (if you’re an authenticated user), the namespace configuration, and, for individual objects, the object ACL.

The operations you can perform in a namespace are subject to these restrictions:

• The namespace access protocol must support the operation.
• If the namespace protocol requires client authentication, you need to provide valid user credentials.
• The namespace access protocol must be configured to allow access to the namespace from your client IP address.
• Both the effective namespace permission mask and your permissions must allow the operation.

The table below lists the operations HCP supports and indicates which protocols you can use to perform those operations. Some operations relate to specific types of metadata.

These considerations apply to symbolic links:

• If you use CIFS to create a symbolic link, you can read through the link only with CIFS. You cannot use CIFS to read through a symbolic link created with NFS.
• REST API and WebDAV support for reading through symbolic links is limited to retrieving object data. Other REST API and WebDAV operations on symbolic links may produce unexpected results.

HCP never lets you:

• Rename an object.
• Rename a nonempty directory.
• Overwrite a successfully stored object. However, if versioning is enabled, you can write new versions of an object using the REST or S3 compatible API.
• Modify the fixed-content portion of an object.
• Delete a directory that contains one or more objects.
• Shorten the retention period of an object.
• Store a file (other than a file containing custom metadata), directory, or symbolic link anywhere in the metadata structure.
• Delete a metafile (other than a metafile containing custom metadata) or metadirectory.
• Create a hard link.

When you view the contents of a namespace, HCP-FS shows each directory and data file under data. The figure below shows a sample directory structure headed by data. It contains one subdirectory, named images. images contains three data files named earth.jpg, wind.jpg, and fire.jpg. These files represent the content of the objects named earth.jpg, wind.jpg, and fire.jpg, respectively.

All the data files and directories presented by HCP-FS represent objects that users have stored in the namespace, with one exception. The data directory has a system-generated subdirectory named .lost+found, which is where HCP puts broken objects in the unlikely event it finds any. If you see objects in this directory, tell your tenant administrator.

Each data file for an object has a corresponding metadirectory with the same name. The location of this metadirectory mirrors the location of the data file. For example, the wind.jpg data file is in the images directory, and the wind.jpg metadirectory is in the images metadirectory. The entire metadirectory structure is under the metadata metadirectory.

The figure below shows the metadirectory structure that corresponds to the data files in the images directory.

HCP-FS presents individual metafiles for each piece of HCP-specific object metadata except owner. It doesn’t present individual metafiles for POSIX metadata. However, it does present one additional metafile that summarizes both the HCP-specific and POSIX metadata for an object. Metafiles contain either plain text or XML, so you can read them easily.

You can view and retrieve metafiles through the WebDAV, CIFS, and NFS protocols. You can also use these protocols to overwrite metafiles that contain the HCP-specific metadata you can change. By overwriting a metafile, you change the metadata for the corresponding object.

If an object has a default annotation or an ACL, HCP presents it as a metafile. HCP does not show other annotations as metafiles. You can add, replace, or delete the default annotation only with the REST API and WebDAV protocol. You can add, replace, or delete other annotations and ACLs only with the REST API.

For backward compatibility, HCP-FS also presents a metafile named tpof.txt. This metafile is superseded by dpl.txt.

HCP-FS presents these metafiles for objects:

• created.txt

  Contains the date the object was added to the namespace. This metafile contains two lines:

  • The first line is the date expressed as the number of seconds since January 1, 1970.
  • The second line is the date in this ISO 8601 format:

    yyyy-MM-ddThh:mm:ssZ

  In this format, Z represents the offset from UTC and is specified as:

  (+|-)hhmm

  For example:

  1326978027
  2012-01-19T08:00:27-0500

  You can view the content of this metafile, but you cannot change it.

• dpl.txt

  Contains the data protection level (DPL) for the object. The DPL is the number of copies of the object HCP must maintain in the repository to ensure the integrity and availability of the object.

  For example:

  2

  You can view the content of this metafile, but you cannot change it.

• hash.txt

  Contains the name of the cryptographic hash algorithm used to generate the cryptographic hash value for the object, as well as the hash value itself. For example:

  SHA-256
  2BC9AE8640D50145604FB6CFC45A12E5561B40429174CE404A...

  HCP calculates the hash value for an object from the object data.

  You can view the content of this metafile, but you cannot change it.

• index.txt

  Contains the index setting for the object.

  You can view and change the content of this metafile.

• replication.txt

  Indicates whether the object is replicated, in this format:

  replicated=true|false

  The value is true only when the object and all its metadata have been replicated. For example, if you add custom metadata to a replicated object, the content of the replicated.txt metafile changes to replicated=false. When the metadata is replicated, the value changes back to replicated=true.

  You can view the content of this metafile, but you cannot change it.

• retention.txt

  Contains the retention setting for the object.

  You can view and change the content of this metafile.

• shred.txt

  Contains the shred setting for the object.

  You can view and change the content of this metafile.

• core-metadata.xml

  Contains a summary of the HCP-specific and POSIX metadata for the object. For example:

  <core-metadata xsi:schemaLocation="http://www.hitachivantara.com
  core-metadata-7_0.xsd">
  <version>3</version>
  <name>/images/wind.jpg</name>
  <name-bytes>2F696D616765732F77696E642E6A7067
  </name-bytes>
  <object-type>File</object-type>
  <creation-time>1326978027</creation-time>
  <update-time>1326978027</update-time>
  <change-time>1326978027</change-time>
  <access-time>1326978027</access-time>
  <uid>17</uid>
  <gid>17</gid>
  <mode>100544</mode>
  <shred>false</shred>
  <index>true</index>
  <retention-value>1462979278</retention-value>
  <retention-string>2016-05-11T11:07:58-0400 (DeptReg223,+7y)
  </retention-string>
  <retention-hold>false</retention-hold>
  <size>238985</size>
  <tpof>1</tpof>
  <dpl>2</dpl>
  <hash-scheme>SHA-256</hash-scheme>
  <hash-value>0B86212A66A792A79D58BB18...</hash-value>
  <retention-class>DeptReg223</retention-class>
  <replicated>true</replicated>
  <replicationCollision>false</replicationCollision>
  <ingestProtocol>CIFS_NFS</ingestProtocol>
  <owner></owner>
  <domain></domain>
  <has-acl>false</has-acl>
  </core-metadata>

  The version element identifies the version of the core-metadata.xml file.

  The ingestProtocol element identifies the protocol through which the object was ingested.

  You can view the content of this metafile, but you cannot change it.

  To see the XML schema for this metafile, use this URL:

  http://tenant-name.hcp-domain-name/static/core-metadata-7_0.xsd

• custom-metadata.xml

  Contains the custom metadata for the default annotation for the object. This metafile is present only when the object has a default annotation.

• acl.xml

  Contains the ACL for the object. This metafile is present only when the object has an ACL.

  Objects can have an ACL only if the namespace is configured to allow it.

The figure below shows the complete metadata structure, including the metafiles, generated for the sample data structure. It assumes you’ve added custom metadata and ACLs for each object.

Each object in a namespace has a retention setting. Additionally, the namespace is configured with a default retention setting. When an object is stored in the namespace, the object inherits the namespace retention setting. Using HTTP, you can override the default setting by specifying a different setting when you store the object.

Every object, including objects assigned to retention classes, has a specific retention setting that specifies when (or whether) the retention period for the object ends. HCP represents the retention setting in numeric and text formats, as shown in the following table.

The format used for retention settings depends on whether you are specifying or retrieving a setting and on the protocol you are using.

If you have privileged permission and the namespace allows it, you can use the HTTP protocol to:

• Delete an object that is under retention. This action is called privileged delete.
• Purge all versions of an object that is under retention. This action is called privileged purge. To perform a privileged purge, the namespace must support versioning.

An object can have both a single hold and one or more labeled holds at the same time. These hold settings are independent of one another. All holds must be released on the object before it can be deleted or have its metadata modified, regardless of the retention setting.

Before an application can place a labeled hold on an object, the application must have write and privileged data access permissions for the associated namespace.

Privileged permission can be set either programmatically by using the HCP Management API to update the dataAccessPermissions.xml file, or through the Tenant Management Console on the Users page of the Security menu.

The following limits apply to the labeled hold feature:

• Maximum label size

  64 characters

• Maximum number of labeled holds per object

  100

With the HTTP protocol, retention information is returned by HTTP response headers. With the WebDAV, CIFS, and NFS protocols, you view retention information for an object in the retention.txt metafile.

When you use HTTP to retrieve metadata for an object, the returned header information includes four retention-related values, as shown below.

• X-HCP-Retention

  One of:

  • The retention setting expressed as a number of seconds since January 1, 1970, at 00:00:00 UTC
  • One of the special values 0, -1, or -2

• X-HCP-RetentionString

  One of:

  • The retention period end time expressed as a datetime value in ISO 8601 format or time in seconds since January 1, 1970
  • One of the special values Deletion Allowed, Deletion Prohibited, or Initial Unspecified

• X-HCP-RetentionClass

  The retention class of the object or an empty string if the object is not assigned to a retention class. The information is returned in this format:

  (retention-class-name, retention-class-value)

  If the retention class is deleted, retention-class-value is undefined.

• X-HCP-RetentionHold

  A value of true or false that indicates whether the object is on hold.

The table below shows the possible retention settings in the retention.txt metafile for an object.

If the retention class assigned to an object is deleted, the retention.txt metafile for the object then contains:

• A retention setting of Deletion Prohibited (-1)
• The name of the deleted retention class
• A retention class value of undefined

For example, suppose you assign an object to the HlthReg-107 retention class and then the class is deleted. The retention.txt metafile for the object then contains:

-1
Deletion Prohibited (HlthReg-107, undefined)

HCP maintains these POSIX time attributes for all items:

• atime

  access time

  The time the item was initially added to the namespace. You can change the value of this attribute. For objects, this has no effect unless the atime attribute is synchronized with HCP retention settings.

  HCP does not automatically update the value of this attribute except when atime synchronization is in effect.

• ctime

  change time

  The time of the last change to the item metadata. The initial value of this attribute is the time the item was added to the namespace. HCP automatically updates the value each time the item metadata changes.

  You cannot change the value of this attribute.

• mtime

  modify time

  The time the item was initially added to the namespace. You can change the value of this attribute. However, this has no effect on the item.

  HCP does not automatically update the value of this attribute.

If versioning is enabled, you can store new versions of an existing object by storing the object using the same URL you used to create the object originally. HCP retains the previous version until it is pruned or you explicitly purge the object.

Updates to the system metadata, custom metadata, or ACL for an object do not create a new version of the object.

When HCP creates a new version of an object, the previous version becomes an old version:

• The old version:
  • Includes the object data, system metadata, custom metadata, and ACL. This information, except the hold setting, owner, and ACL, is locked and treated as historic data; it cannot be changed.
  • Can be accessed by using the version ID that was assigned when you first stored it.
• The new version:
  • Gets a version ID that is greater than the version ID of the previous version.
  • Inherits the system metadata, custom metadata, and ACL from the previous version, unless you specify new metadata when you add the new version to the namespace.

When you retrieve an object from a namespace that supports versioning, you get the current version by default. You can retrieve an older version of the object by specifying a version ID or ingest time. You can also retrieve multiple object versions by specifying a range of version IDs. To determine the ID to use, you can retrieve an XML listing of the available versions of the object.

When you list versions, the list includes the system metadata values for each version. You can retrieve the system metadata for an individual version by specifying the version ID in the command that checks for object existence. You can retrieve both the custom metadata and system metadata for an individual version by specifying the version ID in the command that retrieves custom metadata. You can retrieve the ACL for an individual version by specifying the version ID in the command that retrieves an ACL.

If you delete an object while versioning is enabled, HCP:

• Retains a copy of the deleted object as an old version.
• Creates a special version, called a delete marker, as the current version to indicate that the object has been deleted. This version has a version ID but does not include any object data or metadata.

After you delete an object, any attempt to retrieve the object without specifying the version ID of an old version results in an HTTP 404 (Not Found) error code.

HCP keeps all old versions of a deleted object until they are pruned or the object is purged. If shredding is enabled on a version, HCP shreds the version when it is pruned or when the object is purged.

Because HCP keeps deleted objects as old versions, you can retrieve an accidentally deleted object if HCP has not yet pruned it. To do so, request the object, specifying the version ID of the version you want. You can restore the deleted object by storing the retrieved version as a new version.

When you list the versions of an object that has been deleted and restored, the returned XML for the delete marker identifies the version state as deleted, contains the date and time the object was deleted, and contains the version ID for the delete marker. The remaining XML contains information about the object that was deleted.

You cannot delete specific old versions of an object, but if you have purge permission, you can purge the object to delete all its versions.

If the current version of an object is under retention, you cannot purge the object. However, if you have both purge and privileged permissions, you can perform a privileged purge to delete all versions of the object.

The following describes the permissions that can be granted through an ACL.

• Read

  • Retrieve objects and system metadata
  • Check for object existence
  • List annotations
  • Check for and retrieve custom metadata

• Read_ACL

  Check for and retrieve ACLs

• Write

  • Store objects
  • Create directories
  • Set and change system and custom metadata

• Write_ACL

  Set and change ACLs

• Delete

  Delete objects, custom metadata, and ACLs

The body of an ACL consists of entries in XML or JSON format.

The XML ACL body has the format shown below. Elements at each hierarchical level can be in any order.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<accessControlList>
    <grant>
        <grantee>
            <type>(user|group)</type>
            <name>(hcp-username
            |active-directory-username
            |active-directory-group
                  |all_users
            |authenticated)
            </name>
            If the name entry specifies an Active Directory user or
            group, include the domain element
            <domain>active-directory-domain</domain>
        </grantee>
        <permissions>
            Any combination of the following
            <permission>READ</permission>
            <permission>READ_ACL</permission>
            <permission>WRITE</permission>
            <permission>WRITE_ACL</permission>
            <permission>DELETE</permission>
        </permissions>
    </grant>
    Up to 999 additional grant elements
</accessControlList>

The JSON ACL body has the format shown below. Entries at each hierarchical level can be in any order.

{
    "grant": [{
        "grantee": {
            "type":"(user|group)",
            "name":"(hcp-username
            |active-directory-username
            |active-directory-group
            |all_users
            |authenticated)"[,]
            If the name entry specifies an Active Directory             user or group,
            include the domain entry
            "domain":"active-directory-domain"
        },
        "permissions": {
            "permission":[["READ"[,]|"READ_ACL"[,]|"WRITE"[,]
            |"WRITE_ACL"[,]|"DELETE"]]
        }
    }]
    Up to 999 additional grant entries
}

XML has a single top-level accessControlList element. JSON has a corresponding unnamed top-level object. All ACLs must contain this entry in their body. The top-level entry contains the entries listed in the table below.

This section contains examples of an ACL in both XML and JSON formats. This ACL grants:

• Read permission to all users
• Write permission to the AD user lgreen that is defined in the ad.example.com domain
• Write and delete permission to HCP user pdgrey

An object content collision occurs when, for a namespace without versioning enabled, these events occur in the order shown:

1. An object is created with the same name in that namespace on two systems in a replication topology, but the object has different content on the two systems.
2. The object on one of the systems is replicated to the other system.

If versioning is enabled, no collision occurs. Instead, the less recently created of the two objects becomes an old version of the more recently created object.

When an object content collision occurs, the more recently created object keeps its name and location. The other object is either moved to the .lost+found directory in the same namespace or renamed, depending on the namespace configuration.

When HCP moves an object to the .lost+found directory, the full object path becomes .lost+found/replication/system-generated-directory/ old-object-path.

When renaming an object due to a content collision, HCP changes the object name to object-name.collision or object-name.version-id.collision, where version-id is the version ID of the object. HCP uses the second format only if versioning has ever been enabled for the namespace that contains the object but is not currently enabled.

If the new name is already in use, HCP changes the object name to object-name.1.collision or object-name.version-id.1.collision, as applicable. If that name is already in use, HCP successively increments the middle integer by one until a unique name is formed.

Objects that have been relocated or renamed due to content collisions are flagged as replication collisions in their system metadata. Clients can use the metadata query API to search for objects that are flagged as replication collisions.

If an object that’s flagged as a replication collision changes (for example, if its retention period is extended), its collision flag is removed. If a client creates a copy of a flagged object with a new name, the collision flag is not set on the copy.

You can configure namespaces to have the DIsposition service automatically delete objects that are flagged as replication collisions. When selecting this option for a namespace, you specify the number of days the DIsposition service should wait before deleting such an object. The days are counted from the time the collision flag is set. If the collision flag is removed from an object, the object is no longer eligible for deletion by the DIsposition service.

A system metadata collision occurs when these events occur in the order shown:

1. Different changes are made to the system metadata for a given object on each of two systems in a replication topology.
2. The changed system metadata on one of the systems is replicated to the other system.

If a collision occurs when changed system metadata for a given object is replicated from one system (system A) in a replication topology to another system (system B) in the topology:

• For changed system metadata other than the retention setting and hold status:
  • If the last change made on system A is more recent than the last change made on system B, HCP changes the system metadata on system B to match the system metadata on system A.
  • If the last change on system B is more recent than the last change on system A, HCP does not change the system metadata on system B.
• For a changed retention setting:
  • If the retention setting on system A specifies a longer retention period than does the retention setting on system B, HCP changes the retention setting on system B to match the retention setting on system A.
  • If the retention setting on system B specifies a longer retention period than does the retention setting on system A, HCP does not change the retention setting on system B.
• For a changed hold status:
  • If the object is on hold on system A but not on system B, HCP places the object on hold on system B.
  • If the object is on hold on system B but not on system A, HCP leaves the object on hold on system B.

A custom metadata collision occurs when these events occur in the order shown:

1. One of these changes occurs:
   • An annotation is added with the same name to a given object on each of two systems in a replication topology, but the annotation has different content on the two systems.

     The addition of an annotation to a given object on only one of the systems does not result in a custom metadata collision if the object does not have an annotation with the same name on the other system. In this case, the new annotation is replicated without conflict.

   • Different changes are made to the content of a given annotation for a given object on each of the two systems in a replication topology.
   • A change is made to the content of a given annotation for a given object on one system in a replication topology, and the same annotation is deleted on another system in the topology.
2. The change made on one of the systems is replicated to the other system.

If a collision occurs when a custom metadata change for a given object is replicated from one system (system A) in a replication topology to another system (system B) in the topology:

• If the last change on system A is more recent than the last change on system B, HCP applies the change from system A to the custom metadata on system B
• If the last change on system B is more recent than the last change on system A, HCP does not change the custom metadata on system B

An ACL collision occurs when these events occur in the order shown:

1. Different changes are made to the ACL for a given object on each of two systems in a replication topology.
2. The changed ACL on one of the systems is replicated to the other system.

An ACL is treated as a single unit. If a collision occurs when a changed ACL for a given object is replicated from one system (system A) in a replication topology to another system (system B) in the topology:

• If the last change to the ACL on system A is more recent than the last change to the ACL on system B, HCP changes the ACL on system B to match the changed ACL on system A
• If the last change to the ACL on system B is more recent than the last change to the ACL on system A, HCP does not change the ACL on system B