The basic unit within a NetStorage instance is referred to as a “storage group.” Put simply, a storage group is where you house your content for distribution.

A storage group consists of:

• A name you've given to the storage group during creation.
• At least one ​Akamai​ Content Provider (CP) code for tracking usage for reporting and billing.
• The contractual amount of storage space allotted for use.
• Geographic locations or "zones" for use in replication of your content (where you'll set up your "replicas").
• A domain name that serves as the origin for the group and is used in requests to access it. You provide a unique prefix for this value.
• At least one upload account used to access the storage group.
• At least one upload directory to which you upload content. This is associated with the CP code discussed above.

Each storage group needs a CP code

The default root directory in any NetStorage storage group is “/<######>. " The variable value "<######>" represents a unique, numeric Content Provider (CP) code assigned to you by contract. You need to provision at least one CP code for a storage group. Billing for services, reporting information, and statistical data are referenced via these individual CP codes. For example, if the CP code associated with a specific storage group is “123456,” your root directory in that group would be “/123456,” and all of the previously mentioned data would be tracked and referenced via this code.

How to get a CP code

There are a few ways you can get a CP code:

• Create a CP code when adding a new storage group. The wizard used to create a new storage group offers options you can use to define a new CP code, while configuring an upload directory for the group.
• Use the API. Use the NetStorage Configuration API to create a CP code.
• Work with your account representative. During initial provisioning of your NetStorage instance, your account representative can work with you to provision at least one CP code for NetStorage use. You can also contact your representative in the future to provision additional CP codes. After provisioning, these CP codes will be available for use when creating a new storage group.

There's a limit on the total number of CP codes that you can apply to a single instance of NetStorage. View the technical limits with NetStorage that may apply to your workflow.

📘

More than one CP code can be associated with a single storage group. For example, if you need to monitor billing based on specific content (entertainment vs. educational), you can establish two CP codes for a single storage group, and maintain the entertainment content in one CP code root and educational content in the second.

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.

📘

Once all files associated with an implicit directory are deleted, the directory "disappears" (it no longer exists) because it is effectively empty.

Implicit directories and associated calls

NetStorage approaches non-existent directories in a different manner than a typical filesystem. A complete path name is 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

🚧

Avoid breaking your workflow

If you use Usage API to manage your content, subsequently using other access methods is not supported. You must continue using the Usage API exclusively.

Files and directories can use the same name

By design, NetStorage does not operate like a traditional “file system” in regard 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 a 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 SSH File Transfer Protocol (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.

📘

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

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 a 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.