This section of the Help contains information on using the CIFS namespace access protocol.
CIFS is one of the industry-standard protocols HCP supports for namespace access. To access a namespace through CIFS, you can write applications that use any standard CIFS client library, or you can use the Windows GUI or a Command Prompt window to access the namespace directly.
Using the CIFS protocol, you can store, view, retrieve, and delete objects. You can also change certain system metadata for existing objects.
For you to access a namespace through CIFS, this protocol must be enabled in the namespace configuration, and the namespace configuration must have the Browse, Read, and Write Minimum Data Access Permissions enabled. If you cannot use the CIFS protocol to access the namespace, contact your namespace administrator.
This chapter explains how to use CIFS for namespace access.
Namespace access with CIFS
You access a namespace through CIFS by mapping the namespace to a network drive or by adding the namespace as a network place on a CIFS client. You can map or add the namespace as a whole, either root directory (data or metadata), or any specific data directory or metadirectory. Additionally, you can have multiple directories mapped or added at the same time.
Once mapped or added, the namespace appears to be part of the local file system, and you can perform any of the operations HCP supports for CIFS. On a Windows client, this includes dragging and dropping files and directories to the namespace and, likewise, objects and directories from the namespace.
When mapping or adding the namespace, you can use either the domain name of the HCP system or the IP address of a node in the system. Here are the supported formats:
\\cifs.hcp-domain-name\tenant-name_namespace-name[\data|metadata] \\namespace-name.tenant-name.hcp-domain-name \tenant-name_namespace-name[\data|metadata] \\node-ip-address\tenant-name_namespace-name[\data|metadata]
\\cifs.hcp.example.com\europe_finance \\cifs.hcp.example.com\europe_finance\data\presentations \\cifs.hcp.example.com\europe_finance\metadata \\finance.europe.hcp.example.com\europe_finance\data \\192.168.210.16\europe_finance\data\presentations\images
CIFS return codes
The list below describes the possible return codes for CIFS requests against a namespace.
The requested operation is not allowed. Reasons for this return code include attempts to:
- Rename an object
- Rename a directory that contains one or more objects
- Overwrite an object
- Modify the content of an object
- Delete an object that’s under retention
- Delete a directory that contains one or more objects
- Add a file (other than a file containing custom metadata), directory, or symbolic link anywhere in the metadata structure
- Delete a metafile or metadirectory
- Create a hard link
The requested operation would shorten the retention period of the specified object, which is not allowed.
HCP tried to read the requested object from another system in the replication topology, and the data either could not be read or was not yet available.
The following sections show examples of using CIFS to access a namespace. Each example shows both a Windows command and Python code that implements the same command.
These examples assume that the data directory is mapped to the X: drive and the metadata metadirectory is mapped to the Y: drive.
Example: Storing an object
This example stores an object named wind.jpg in the existing images directory by copying a file of the same name from the local file system.
copy wind.jpg x:\images
import shutil shutil.copy("wind.jpg", "x:\\images\\wind.jpg")
Example: Changing a retention setting
This example extends the retention period for the wind.jpg object by one year. If this object is still open due to lazy close, changing the retention setting closes it.
echo +1y > y:\images\wind.jpg\retention.txt
retention_value = "+1y" retention_fh = file("y:\\images\\wind.jpg\\retention.txt") try: retention_fh.write(retention_value) finally: retention_fh.close()
Example: Retrieving an object
This example retrieves the object named wind.jpg from the namespace and stores the resulting file with the same name in the existing RetrievedFiles directory.
copy x:\images\wind.jpg RetrievedFiles
import shutil shutil.copy("x:\\images\\wind.jpg", "RetrievedFiles\\wind.jpg")
CIFS usage considerations
This chapter presents considerations that affect the use of the CIFS protocol for namespace access.
CIFS case sensitivity
The Windows operating system is case preserving but not case sensitive. The HCP CIFS implementation, by default, is both case preserving and case sensitive. One result of this discrepancy is that Windows applications that don’t observe differences in case may not be able to access objects by name.
For example, suppose a Windows application adds a file named File.txt to the namespace by using the CIFS protocol. CIFS preserves case, so the namespace then contains an object named File.txt. Now suppose the application tries to retrieve that object using the name file.txt. CIFS is case sensitive, so it passes the request to HCP with only the name file.txt. It doesn’t include any case variations on the name, such as File.TXT or FILE.txt. As a result, HCP cannot find the object.
You can ask your tenant administrator to make the CIFS implementation case insensitive. However, this change has two consequences that affect object reads:
- It slows performance.
- If the namespace contains multiple objects with names that differ only in case, HCP may return the wrong object.
CIFS permission translations
When you view an object on a Windows client, CIFS translates the POSIX permission settings used in the namespace into settings Windows understands. The list below shows how CIFS maps POSIX permissions to Windows permissions.
Read and Execute
Creating an empty directory with atime synchronization in effect
When you use Windows Explorer to create a new directory, Windows automatically names it New Folder. This is also true for directories you create in a namespace.
Normally, you can rename an empty directory in a namespace. However, if
atime synchronization is in effect, you cannot do this. As a result, the name of the new directory remains New Folder.
CIFS lazy close
When writing a file to a namespace, CIFS can cause a flush at any time. After each flush or write, HCP waits a short amount of time for the next one. If no write occurs within that time, HCP considers the resulting object to be complete and closes it. This event is called lazy close.
If you set retention on an object during the lazy close period, HCP closes the object immediately. The object becomes WORM, and retention applies, even if the object contains no data. However, if the directory that contains the object and its corresponding metadirectory are shared on two different nodes in the HCP system, setting retention during the lazy close period does not close the object.
Using CIFS with objects open for write
These considerations apply to objects that are open for write through any protocol:
- While an object is open for write through one IP address, you cannot open it for write through any other IP address.
- You can read an object that is open for write from any IP address, even though the object data may be incomplete. A read against the node hosting the write may return more data than a read against any other node.
- While an object is open for write, you cannot delete it.NoteDepending on the timing, the delete request may result in a busy error. In that case, wait one or two seconds and then try the request again.
- While an object that’s open for write has no data:
- It is not WORM
- It may or may not have a cryptographic hash value
- It is not subject to retention
- It cannot have custom metadata
- It is not indexed
Failed CIFS write operations
A CIFS write operation is considered to have failed if the target node failed 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.
A CIFS write operation is not considered to have failed if the TCP connection broke. This is because HCP doesn’t see the failure. In this case, lazy close applies, and the object is considered complete.
Objects left by failed CIFS write operations:
- May have none, some, or all of their data
- If partially written, may or may not have a cryptographic hash value
- If the failure was on the HCP side, remain open and:
- Are not WORM
- Cannot have annotations
- Are not indexed
- Are not replicated
- If the failure was on the client side, are WORM after the lazy close
If a write operation fails, delete the object and try the write operation again.
Storing zero-sized files with CIFS
When you store a zero-sized file with CIFS, the resulting object has no data. After lazy close occurs, the object becomes WORM and is treated like any other object in the namespace.
Out-of-order writes with CIFS
CIFS can write the data for an object out of order. If HCP receives an out-of-order write for a large file (200,000 bytes or larger), it discards the cryptographic hash value it already calculated. The object then has no hash value until one of these occurs:
- HCP returns to the object at a later time and calculates the hash value for it.
- A user or application opens or downloads the hash.txt metafile for the object, which causes HCP to calculate the hash value. However, because HCP calculates this value asynchronously, the value may not be immediately available. This is particularly true for large objects.
Temporary files created by Windows clients
During certain operations, Windows clients may create temporary files. In a namespace, these files correspond to successfully created objects.
As with any other new object stored through the CIFS protocol, the retention period for such an object is determined by the namespace configuration. If the object ends up being under retention, it remains in the namespace after the operation completes and cannot be deleted until its retention period expires.
Multithreading with CIFS
HCP lets multiple threads access a namespace simultaneously. Using multiple threads can enhance performance, especially when accessing many small objects across multiple directories.
With CIFS, multiple concurrent threads can write to the same object, but only if they are working against the same node. Multiple concurrent threads can read the same object on the same or different nodes.
With a single share of the namespace, concurrent threads are always working against the same node.
HCP doesn’t limit the number of concurrent CIFS threads per node but does limit the total number of outstanding requests using all protocols to 500 per node.