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.
Implicit directories: associated calls
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
dir action using this API,
it will be labeled as “implicit”.
[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 “
..//” would be a
subdirectory name, and “
newLink/” could be a symlink
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.
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.