Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

WebDAV

This section of the Help contains information on using the WebDAV namespace access protocol.

Using WebDAV

WebDAV is one of the industry-standard protocols HCP supports for namespace access. To access a namespace through WebDAV, you can write applications that use any standard WebDAV client library, or you can use a command-line tool, such as cadaver, which supports WebDAV.

Using the WebDAV protocol, you can store, view, retrieve, and delete objects. You can also add and delete custom metadata, as well as change certain system metadata for existing objects.

NoteUsing WebDAV, you can store and retrieve the default annotation only. It cannot access other annotations.

HCP is compliant with WebDAV level 2, as specified by RFCs 2518 and 4918.

To access a namespace through WebDAV, this protocol must be enabled in the namespace configuration. If you cannot use the WebDAV protocol to access the namespace, contact your tenant administrator.

The WebDAV examples use cadaver open-source software, which you can download from https://pkgs.org/download/cadaver.

An object is equivalent to a WebDAV resource. A directory is equivalent to a WebDAV collection.

WebDAV methods

HCP supports most standard WebDAV methods, as indicated in the list below.

  • PUT

    Use this method to:

    • Store an object in the namespace
    • Add or replace custom metadata in the default annotation for an existing object

    When you store an object in the namespace, HCP uses the ETag response header to return the cryptographic hash value for the object.

  • GET

    Use this method to retrieve an object or metafile from the namespace.

  • HEAD

    Use this method to check whether an object, default annotation, an ACL, or a directory exists in the namespace.

  • MKCOL

    Use this method to create a new directory in the namespace.

  • PROPPATCH

    Use this method to:

    • Change system metadata associated with an object.

      If the request to change system metadata specifies a symbolic link, HCP changes the metadata on the object that’s the target of the link and not on the link itself.

    • Store dead properties as custom metadata in the default annotation (when this capability is enabled in the namespace configuration).
  • PROPFIND

    Use this method to retrieve metadata associated with an object, including both system metadata and dead properties stored as custom metadata. You can use PROPFIND to retrieve dead properties only when the namespace is configured to store dead properties as custom metadata.

  • COPY

    Use this method to copy an object from one location to another.

    When using this method, you need to specify the full URL for the target location.

    A request to copy an object fails if an object with the same name already exists at the target location.

  • MOVE

    Use this method to move an object from one location to another.

    When using this method, you need to specify the full URL for the target location.

    A request to move an object fails if:

    • An object with the same name already exists at the target location.
    • The source object is under retention.
  • DELETE

    Use this method to delete an object, directory, symbolic link, or default annotation from the namespace.

  • LOCK

    Use this method to lock an object on a single node.

  • UNLOCK

    Use this method to unlock an object on a single node.

  • OPTIONS

    Use this method to see which WebDAV methods are supported for the specified object, directory, or symbolic link.

Unsupported methods
  • POST
  • TRACE

URLs for WebDAV access to a namespace

Depending on the method you’re using and what you want to do, the URL you specify can identify any of:

  • The namespace as a whole
  • A directory
  • An object
  • A symbolic link
  • A metadirectory
  • A metafile for an object
NoteTo access a namespace through WebDAV directly from a Windows client, add the namespace as a network share, using any of the URL formats described in URL formats. When you share the namespace in this way, it appears to be part of the local file system in Windows Explorer in the same way it does with CIFS access.

URL formats

The following sections show the URL formats you can use to access a namespace. These formats all use a domain name to identify the HCP system. If the HCP system does not support DNS, you can use the client hosts file to enable access to a namespace by hostname.

Note
  • You need to use the domain name of the HCP system to access an HCP namespace through WebDAV. If you specify the IP address of a node in a URL, you access the default namespace.
  • The URL formats and examples that follow show https. Your tenant administrator can configure the namespace to not allow SSL security for the HTTP protocol. In this case, you need to specify http instead of https in your URLs.
URL for the namespace as a whole

The URL that identifies a namespace as a whole has this format:

https://namespace-name.tenant-name.hcp-domain-name/webdav

For example:

https://finance.europe.hcp.example.com/webdav
URLs for objects, directories, and symbolic links

To access an object, directory, or symbolic link in a namespace, you use a URL that includes the data directory. The format for this is:

https://namespace-name.tenant-name.hcp-domain-name/webdav/data
  [/directory-path[/object-name|symbolic-link-name]]

Here’s a sample URL that identifies a directory:

https://finance.europe.hcp.example.com/webdav/data/Corporate/Employees

Here’s a sample URL that identifies an object:

https://finance.europe.hcp.example.com/webdav/data/Corporate/Employees/2193_John_Doe

You cannot tell from a URL whether it represents an object, directory, or symbolic link.

URLs for metafiles and metadirectories

To access a metafile or metadirectory, you use a URL that includes the metadata directory. The format for this is:

https://namespace-name.tenant-name.hcp-domain-name/webdav/
  metadata/metadirectory-path[/metafile-name]

Here’s a sample URL that identifies a metadirectory:

https://finance.europe.hcp.example.com/webdav/metadata/Corporate/Employees/2193_John_Doe

Here’s a sample URL that identifies a metafile:

https://finance.europe.hcp.example.com/webdav/metadata/Corporate/Employees/2193_John_Doe/shred.txt

URL considerations

The following considerations apply to specifying URLs in WebDAV requests against a namespace.

URL length

The portion of a URL after data or metadata, excluding any appended query parameters, is limited to 4,095 bytes. If a WebDAV request includes a URL that violates that limit, HCP returns an HTTP 414 (Request URI Too Large) error code.

URL character case

All elements of a URL except http[s] and the hostname are case sensitive.

Object names with non-ASCII, nonprintable characters

When you store an object or directory with non-ASCII, nonprintable characters in its name, those characters are percent-encoded in the name displayed back to you. In the core-metadata.xml file for an object, those characters are also percent encoded, but the percent signs (%) are not displayed.

Regardless of how the name is displayed, the object or directory is stored with its original name, and you can access it either by its original name or by the name with the percent-encoded characters.

Percent-encoding for special characters

Some characters have special meaning when used in a URL and may be interpreted incorrectly when used for other purposes. To avoid ambiguity, percent-encode the special characters listed in the table below.

Percent-encoded values are not case sensitive.

CharacterPercent-encoded values
Space%20
Tab%09
New line%0A
Carriage return%0D
+%2B
%%25
#%23
?%3F
&%26
\&5C
Quotation marks with URLs in command lines

When using the HCP management API, you work in a Windows, Unix, or Mac OS X shell. Some characters in the commands you enter may have special meaning to the shell. For example, the ampersand (&) used in URLs to join multiple query parameters may indicate that a process should be put in the background.

To avoid the possibility of the Windows, Unix, or Mac OS X shell misinterpreting special characters in a URL, always enclose the entire URL in double quotation marks.

WebDAV properties

WebDAV properties are name/value pairs that provide information about items in a namespace. To store and retrieve property values, you use the PROPPATCH and PROPFIND methods, respectively.

Properties exist in XML namespaces. To fully identify a property, you need to specify the namespace it’s in as well as the property name.

All the properties defined in the WebDAV specification are in the DAV: namespace. So, for example, the standard WebDAV property named creationdate is in the DAV: namespace.

For information about the standard WebDAV properties, see RFC 2518 or 4918.

Live and dead properties

Properties can be live or dead. Live properties are properties that are known to the WebDAV server (in this case, HCP). The server can respond to changes you make to these properties and can also dynamically modify their values.

Dead properties are properties that are not known to the WebDAV server. The server stores and retrieves these properties but does not do anything else with them. Dead properties can be in any XML namespace.

A PROPFIND request for all properties returns both live and dead properties. However, when responding to such a request, the server may omit live properties whose values are expensive to calculate.

In response to a PROPFIND request for all properties, HCP may omit some standard WebDAV properties but always includes all properties defined in the HCP XML namespace.

HCP-specific metadata properties for WebDAV

HCP recognizes all the live properties defined in the DAV: namespace. Additionally, it provides its own XML namespace with live properties that allow you to store and retrieve HCP system metadata. This namespace is specified as:

http://www.hitachivantara.com/hcap/webdav/
NoteIn a WebDAV PROPPATCH or PROPFIND request, the HCP XML namespace must be specified exactly as shown above. The URL must specify hcap, not hcp.

As with the standard WebDAV properties, you use the PROPPATCH and PROPFIND methods to change and retrieve the values of the HCP-specific properties.

The list below describes the metadata properties HCP provides for objects.

  • access-time

    The value of the POSIX atime attribute for the object.

    You can retrieve, but not change, the value of this property.

  • change-time

    The value of the POSIX ctime attribute for the object.

    You can retrieve, but not change, the value of this property.

  • creation-time

    The date and time the object was stored in the namespace.

    You can retrieve, but not change, the value of this property.

  • domain

    If the object is owned by an Active Directory user, the domain in which the user account of the object owner is defined.

    You can retrieve, but not change, the value of this property.

  • dpl

    The object data protection level.

    You can retrieve, but not change, the value of this property.

  • gid

    The POSIX group ID for the object.

    You can retrieve, but not change, the value of this property.

  • has-acl

    An indication of whether the object has an ACL, either true (has an ACL) or false (does not have an ACL).

    You can retrieve, but not change, the value of this property.

  • hash-scheme

    The name of the cryptographic hash algorithm used to calculate the cryptographic hash value for the object.

    You can retrieve, but not change, the value of this property.

  • hash-value

    The cryptographic hash value for the object.

    You can retrieve, but not change, the value of this property.

  • index

    The index setting for the object, either true (index) or false (don’t index).

    To change this value, specify true or false.

  • mode

    The POSIX permissions for the object as an octal value.

    You can retrieve, but not change, the value of this property.

  • owner

    The user that owns the object.

    If this property specifies an Active Directory user, the domain property is also returned.

    You can retrieve, but not change, the value of this property.

  • replication

    An indication of whether the object has been replicated, either true (replicated) or false (not replicated).

    You can retrieve, but not change, the value of this property.

  • replication-collision

    An indication of whether the object is flagged as a replication collision, either true (flagged) or false (not flagged).

  • retention-class

    The name of the retention class for the object (such as HlthReg-107).

    To change this value, specify a valid retention class name.

  • retention-hold

    The hold status for the object, either true (on hold) or false (not on hold).

    You can retrieve, but not change, the value of this property.

  • retention-string

    Deletion Allowed, Deletion Prohibited, Initial Unspecified, or a date and time in this format:

    yyyy-MM-ddThh:mm:ssZ

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

    (+|-)hhmm

    To change this value, specify any of these values, any of the valid values for the retention-value property, or an offset.

  • retention-value

    0, -1, -2, or seconds since January 1, 1970 at 00:00:00.

    To change this value, you can specify any of these values, any of the valid values for the retention-string property, or an offset.

  • shred

    The shred setting for the object, either true (shred) or false (don’t shred).

  • uid

    The POSIX user ID for the object.

    You can retrieve, but not change, the value of this property.

  • update-time

    The value of the POSIX mtime attribute for the object.

    You can retrieve, but not change, the value of this property.

Storing dead properties as custom metadata

HCP can be configured to store WebDAV dead properties as custom metadata for an object. When HCP is configured this way, you use the PROPPATCH and PROPFIND methods to store and retrieve dead properties just as you do for live properties.

This is the only way HCP can store dead properties. If a namespace is not configured to store dead properties as custom metadata and you try to store dead properties, HCP returns an HTTP 404 (Not Found) error code.

To have a namespace configured to store dead properties as custom metadata file, contact your tenant administrator.

As with custom metadata accessed using WebDAV, dead properties are stored in the default annotation. This annotation is represented by the custom-metadata.xml file

Using the PROPPATCH method, you can change individual dead properties in the default annotation. You do not need to replace the entire annotation as you do when you use it for custom metadata.

You can use the default annotation to store either custom metadata or dead properties, but not both:

  • If, after using the annotation for custom metadata, you try to store dead properties, HCP returns an HTTP 409 (Conflict) error code. In this case, you need to delete the existing annotation before you can store dead properties for the object.
  • If, after storing dead properties, you replace the annotation content with new custom metadata, the dead properties you stored are lost.

WebDAV status codes

The table below describes the possible status codes for WebDAV requests against namespaces.

CodeMeaningDescription
200OKGET, HEAD, PROPPATCH, or LOCK: HCP successfully completed the request.
201CreatedPUT, MKCOL, COPY, or MOVE: HCP successfully completed the request. (For COPY or MOVE, no object existed at the target location.)
204No Content

COPY, MOVE, or DELETE: HCP successfully completed the request. (For COPY or MOVE, a deletable object existed at the target location.)

GET, HEAD, or DELETE of custom metadata: The specified object exists but does not have a default annotation.

206Partial ContentGET: HCP successfully retrieved the data in the byte range specified in the request.
207Multi-statusPROPPATCH, PROPFIND, or DELETE for a directory: The operation generated multiple status codes. The response body contains an XML document that shows the status codes and the names of the objects to which they apply.
400Bad Request

All methods: The request is not well-formed. Correct the request and try again.

PROPPATCH or PROPFIND: The request XML is invalid.

PUT: For a request to add or replace custom metadata, the namespace is configured with custom metadata XML checking enabled, and the request includes custom metadata that is not well-formed XML.

COPY or MOVE: The request does not specify the full URL for the target location.

403Forbidden

For all methods, one of:

  • The namespace does not exist.
  • The WebDAV protocol is not enabled for the namespace.
  • The URL specifies https and the namespace configuration does not support SSL.
  • You don’t have permission to perform the requested operation.

MKDIR: You cannot create a directory in the specified location.

PROPPATCH: The requested change is not allowed.

COPY or MOVE: The specified source and destination locations are the same.

DELETE: The specified object is under retention.

404Not FoundGET, HEAD, PROPPATCH, PROPFIND, COPY, MOVE, DELETE, LOCK, or UNLOCK: HCP could not find the object, metafile, or directory specified in the request.
405Method Not Allowed

MKCOL: HCP could not create the directory because it already exists.

DELETE: HCP could not delete the specified object or custom metadata because it is currently being written to the namespace.

409Conflict

PUT: HCP could not store the object because it already exists.

PUT, MKCOL, COPY, or MOVE: One or more directories in the target path do not exist.

PROPPATCH: HCP could not store dead properties as custom metadata because the default annotation contains custom metadata.

412Precondition Failed

COPY or MOVE: The operation failed because either:

  • HCP could not correctly copy or move the object metadata
  • The target object already exists and could not be deleted

LOCK: HCP could not lock the specified object.

414Request URI Too LongAll methods: The portion of the URL following data or metadata is longer than 4,095 bytes.
416Requested Range Not Satisfiable

GET: For a byte-range request, either:

  • The specified start position is greater than the size of the requested data.
  • The size of the specified range is zero.
423LockedPUT, PROPPATCH, COPY, MOVE, DELETE, or LOCK: HCP could not perform the requested operation because the target object is locked.
500Internal Server Error

All methods: An internal error occurred. Try the request again, gradually increasing the delay between each successive attempt.

If this happens repeatedly, please contact your tenant administrator.

503Service Unavailable

One of:

  • HCP is temporarily unable to handle the request, probably to due to system overload, maintenance, or upgrade.
  • HCP tried to read the object from another system in the replication topology but could not.

In either case, try the request again, gradually increasing the delay between each successive attempt.

507Insufficient Storage

PUT: Not enough space is available to store the object. Try the request again after objects are deleted from the namespace or the namespace capacity is increased.

PROPPATCH, MKCOL, or COPY: Not enough space is available to complete the request. Try the request again after objects are deleted from the namespace or the namespace capacity is increased.

WebDAV examples

The following sections show examples of using WebDAV to access the data directory in a namespace named finance in a tenant named europe. These examples use cadaver.

Example: Storing an object

Here’s a sample WebDAV PUT request that stores a new object named Q1_2012.ppt in the presentations directory.

Request with cadaver command line
put Q1_2012.ppt presentations/Q1_2012.ppt
Request headers
PUT /webdav/data/presentations/Q1_2012.ppt HTTP/1.1
Host: finance.europe.hcp.example.com
Content-Length: 238592
Response headers
HTTP/1.1 201 Created
Content-Length: 0

Example: Retrieving the index setting for an object

Here’s a sample WebDAV PROPFIND request that returns the index setting for the object named wind.jpg in the presentations/images directory.

Request with cadaver command line
propget presentations/images/wind.jpg index
Request XML body
<?xml version="1.0" encoding="utf-8" ?>
<ns0:propfind xmlns:ns0="DAV:">
    <ns0:prop>
         <ns1:index xmlns:ns1="http://www.hitachivantara.com/hcap/webdav/" />
    </ns0:prop>
</ns0:propfind>
Response XML body
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:"
xmlns:HCAP="http://www.hitachivantara.com/hcap/webdav/">
    <D:response>
         <D:href>https://finance.europe.hcp.example.com/webdav/data/
             presentations/images/wind.jpg
        </D:href>
       <D:propstat>
             <D:prop>
                 <HCAP:index>true</HCAP:index>
             </D:prop>
             <D:status>HTTP/1.1 200 OK</D:status>
         </D:propstat>
    </D:response>
</D:multistatus>

Example: Changing the retention setting for an object

Here’s a sample WebDAV PROPPATCH request that changes the retention setting for the object named wind.jpg in the presentations/images directory.

Request with cadaver command line
propset presentations/images/wind.jpg retention-string 2015-09-30T17:00:00-0400
Request XML body
<?xml version="1.0" encoding="utf-8" ?>
<ns0:propertyupdate xmlns:ns0="DAV:">
    <ns0:set>
        <ns0:prop>
              <ns1:retention-string xmlns:ns1="http://www.hitachivantara.com/hcap/webdav/">
                  2015-09-30T17:00:00-0400
              </ns1:retention-string>
          </ns0:prop>
     </ns0:set>
</ns0:propertyupdate>
Response XML body
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:"
xmlns:HCAP="http://www.hitachivantara.com/hcap/webdav/"
xmlns="http://www.hitachivantara.com/hcap/webdav/">
    <D:response>
         <D:href>http://finance.europe.hcp.example.com/webdav/data/
             presentations/images/wind.jpg
         </D:href>
        <D:propstat>
             <D:prop>
                 <ns1:retention-string
                xmlns:ns1="http://www.hitachivantara.com/hcap/webdav/"/>
            </D:prop>
            <D:status>HTTP/1.1 200 OK</D:status>
        </D:propstat>
    </D:response>
</D:multistatus>

Example: Storing a dead property as custom metadata

Here’s a sample WebDAV PROPPATCH request that sets the presentedBy property for the object named Q1_2012.ppt in the presentations directory.

Request with cadaver command line
propset presentations/Q1_2012.ppt presentedBy Lee.Green
Request XML body
<?xml version="1.0" encoding="utf-8" ?>
<D:propertyupdate xmlns:D="DAV:">
    <D:set>
         <D:prop>
             <presentedBy xmlns="http://webdav.org/cadaver/custom-properties/">
                Lee.Green
            </presentedBy>
        </D:prop>
    </D:set>
</D:propertyupdate>
Response XML body
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:HCAP="http://www.hitachivantara.com/hcap/webdav/">
    <D:response>
         <D:href>https://finance.europe.hcp.example.com/webdav/data/
             presentations/Q1_2012.ppt
         </D:href>
         <D:propstat>
             <D:prop>
                 <presentedBy
                xmlns="http://webdav.org/cadaver/custom-properties/"/>
            </D:prop>
            <D:status>HTTP/1.1 200 OK</D:status>
        </D:propstat>
    </D:response>
</D:multistatus>

WebDAV usage considerations

Basic authentication with WebDAV

A namespace can be configured to require basic authentication for WebDAV access. If basic authentication is enabled, you’re prompted for a username and password when you access the namespace through WebDAV. For the username and password to use, contact your tenant administrator.

Even when basic authentication is enabled for a namespace, WebDAV users always access the namespace anonymously.

WebDAV object locking

To accommodate WebDAV clients that require locking functionality, HCP supports the LOCK and UNLOCK methods. However, a LOCK request locks the specified object only on the target node. As a result, locking an object does not prevent other nodes from modifying it.

Failed WebDAV write operations

A WebDAV write operation is considered to have failed if either of these is true:

  • The target node failed while the object was open for write.
  • The TCP connection broke (for example, due to a front-end network failure or the abnormal termination of the client application) while the object was open for write.

Also, in some circumstances, a write operation is considered to have failed if another node or other hardware failed while the object was open for write.

If a write fails, HCP does not create a new object.

TipIf a write operations fails, retry the request.

Storing zero-sized files with WebDAV

When you store a zero-sized file with WebDAV, the resulting object has no data. Because WebDAV causes a flush and a close even when no data is present, this object is WORM and is treated like any other object in the namespace.

WebDAV client timeouts with long-running requests

Some WebDAV operations, such as a GET request on a very large directory, can take a long time to complete.

During such an operation, HCP does not communicate back to the client. As a result, the connection may time out on the client.

If an operation may take a long time, you should adjust the connection timeout setting on the client before making the request.

Persistent connections with WebDAV

HCP supports persistent connections with WebDAV. Following a request for an operation, HCP keeps the connection open for 60 seconds, so a subsequent request can use the same connection.

Persistent connections enhance performance because they avoid the overhead of opening and closing multiple connections. In conjunction with persistent connections, using multiple threads so that operations can run concurrently provides still better performance.

If the persistent connection timeout period is too short, ask your tenant administrator about having it changed.

NoteWith persistent connections, if a single node has more than 254 concurrent open connections, those above the first 254 may have to wait as long as ten minutes to be serviced. This includes connections where the HCP domain name resolved to the target node.

To avoid this issue, either don’t use persistent connections or ensure that no more than 254 threads are working against a single node at any given time.

Multithreading with WebDAV

HCP lets multiple threads access a namespace simultaneously. Using multiple threads can enhance performance, especially when accessing many small objects across multiple directories.

HCP has a limit of 255 concurrent WebDAV connections per node, with another 20 queued.

NoteREST, S3 compatible and WebDAV APIs share the same connection pool.

 

  • Was this article helpful?