Understand the NetStorage file structure

Prior to using NetStorage to manage content in a storage group, we recommended that you review the information here to get a better understanding of the logic behind directories and files within NetStorage.

Implicit vs. explicit directories

In NetStorage, directories can exist in one of two forms:

  • Explicit Directory: This is an actual, physical directory that you have created in a storage group.
  • Implicit Directory: This refers to a directory within a path that has not been physically created. For example, during upload of a file, non-existent subdirectories can be specified in the target path. NetStorage creates these as “implicit.” While the directories do not physically exist, the noted path will be connected with the uploaded file.
Note: Once all files associated with an implicit directory are deleted, the directory "disappears," (it no longer exists) because it is effectively empty.

Implicit directories: associated calls

NetStorage approaches non-existent directories in a different manner than a typical filesystem. A complete path name will be created for specified non-existent directories, without actually creating physical directories. When one of these directories is revealed within the response for the stat or dir action using this API, it will be labeled as “implicit”.

Put simply, the generated directory, symlink or uploaded file will still exist along the specified [path], but implicit representations of non-existent subdirectories will be generated and associated with it. These calls generate an implicit directory if they don't already exist in the path:
  • mkdir: Used to create a new explicit directory
  • symlink: Used to create a new symlink
  • upload: Used to upload an object

Files and directories can use the same name

By design, NetStorage does not operate like a traditional “file system” in regards to directory structure and file naming. Rather than standard directories and subdirectories comprised of file contents, a database storage model is incorporated, in which the following apply.

  • Forward slashes (“/”) can exist as both a path separator and an object-naming character. For example, your directory and file names can end in one or more trailing slashes.
  • Single or double “dot-files” can be used as a path element. For example, “/.” or “/..” can be included as file names or sub-directories in a path)

With this in mind, it is important to note the following formula:

object name = directory + "/" + filename

Everything before the last “/” is considered the directory name; everything after the last “/” is considered a file name or subsequent directory.

For example, along a path of “/<CP Code>/..///newLink/”, “..//” would be a subdirectory name, and “newLink/” could be a symlink contained therein.

All path names within an NetStorage storage group are treated completely independently. This means that a file and directory that exist in the same parent can use the same name.

Internally with NetStorage all directories end with a trailing slash (“/”). It is added automatically when creating a directory, and removed in command results. (For example, this would occur if you view directory contents via the “lls” command in SFTP.) A particular object name that does not end with a trailing “/” may be a file or a symlink, but not a directory. An object name that ends with a trailing “/” may be either an explicit directory, a file, or a symlink, and in addition to being a file or symlink, this same object name may also represent an implicit directory.

Note: Certain protocols do not support the inclusion of same-name files and sub-directories in the same parent directory, when targeting an NetStorage storage group. If this exception applies, it is discussed in the relevant protocol's section of the NetStorage - User Guide.

Caveats and recommendations

  • You can only use a dot character (".") in a path when using the NetStorage Usage API to manage your content. You cannot use a dot character in a path when using any of the standard protocols supported for use with NetStorage (SSH, FTP, etc.).
  • We recommend against using these characters for uploads. While they are supported for use in an NetStorage path, it's best that you don't upload files using repeated slashes, trailing slashes, and path components comprised of only a single dot (".") or two dots (".."). Browsers are known to have trouble accessing these paths. This has also been known to create issues when incorporating protocols such as FTP and SFTP.