The Content Management Shell (CMShell) allows you to log in to a shell-like interface to manage content in NetStorage, using a secure environment.

CMShell configuration requirements

CMShell requires a client that supports SSH protocol 2 (DSA/RSA). Use any client that provides secure, persistent sessions to securely connect to a storage group. CMShell supports both interactive login and single command execution. This includes applications such as “PuTTY” and “WinSCP.” You can use CMShell after you add an SSH key to your upload account.

Configure “PuTTY” for CMShell

To configure an SSH client, you'll need various items and information:

• The “private” instance of your SSH key. This key resolves with the “public” key that you applied to the upload account. This file must be locally accessible.
• The storage group "domain name prefix". This is the storage group you will be accessing.
• The secure login username. This is always “sshacs” for secure NetStorage access.
• The client must support “remote commands”. Your client needs to append cms as a remote command to the connection call.
• The password assigned to the private SSH key. If you assigned a password during key generation, you will need to know it.

Apply an SSH key to the PuTTY application

1. Launch PuTTY
2. Ensure the Category is set to Session, and input the following in the Host Name (or IP address) field: <Domain Name Prefix>.ssh.upload.akamai.com
3. Set the Connection Type to SSH.
4. Select the Connection > Data sub-category, and set the Auto-login username to “sshacs” (minus the quotes). This value must be used.
5. Select the Connection > SSH sub-category and set the following:
   1. Remote command - Input “cms” (minus the quotes).
   2. Preferred SSH protocol version - Ensure that “2” is selected.
6. Open the Connection > SSH sub-category and select its Auth sub-category to set following:
   1. Private key file for authentication - Click the Browse button to navigate to the associated Private key.
7. Recommended: Return to the Session category, input a desired name in Saved Sessions (“CMShell Access,” for example) and click the Save button. This allows you to quickly load the session for connection in the future.
8. Click Open to launch the session in a separate session window.
9. If you have established a Key Passphrase for the SSH Key pair, input it in the session window.
   With the connection open and resolved, you can now issue CMShell commands.

Access CMShell with an SSH client

Here is an example of an interactive login

In this example shows how to access the CMShell by including specific login information. After the login is resolved, you will be able to issue multiple commands.

    ssh -t -i <Private-key> <Username>@<Domain Name Prefix>.ssh.upload.akamai.com cms

These variable values apply:

• <Private-key>: This is the full path to your private key.
• <Username>: You must use sshacs as the username. This is the case for all secure access methods in NetStorage.
• <Domain Name>: This value followed by .ssh.upload.akamai.com represents your full Upload Domain Name. You set up your domain name during creation of the target storage group.

Once this login is accepted, you will be free to launch multiple CMShell commands, as desired.

Here is an example of single command execution

In this example, we show you how to access the CMShell by including specific login information within an individual command. (This allows you to login and issue a single command.)

ssh <Username>@<Domain Name Prefix>.ssh.upload.akamai.com <command line>

The following variable values apply:

• <Username>: When providing the Username, the value sshacs must be used. (This is the case for all Secure Access Methods in NetStorage.)
• <Domain Name Prefix>: This value followed by .ssh.upload.akamai.com represents your full Upload Domain Name. You set up your Domain Name during creation of the target storage group.
• <command line>: The single command you wish to execute.

CMShell command syntax

Syntax basics

Command responses

Once a CMShell command is issued, one of three responses will be returned after processing:

CMShell commands

The az2z command

This command creates a Serve from Zip compatible zip archive.

Use this command to rewrite a ZIP archive file to Serve from Zip file format (which will verify the file’s integrity and create a hash table for it). The “<FILE>” variable should be set to the complete path and filename for the target file.

 az2z <OPTION> <FILE>

The “cat” command

Use this command to concatenate a file or files and display the result; or concatenate multiple files into a single output file.

cat <OPTION> <FILE>...

Example: Concatenate one or more files

Include one or more instances of the <FILE> parameter, setting each to the complete path and file name to the desired file for concatenation. Resulting concatenated files will be housed in the current active directory.

cat <FILE> <FILE>...

cat /123456/file01 /123456/file02

Example: Concatenate multiple files into a single output file

If you need to process several files as one and save the results of such processing to a single output file, this command can be applied. Include one or more instances of the <FILE> variable, setting each to the complete path and filename for the desired file, and set the <OUTPUTFILE> variable to a desired path and filename for the resulting concatenated output file.

cat <OPTION> <FILE1> <FILE2> <FILE3>... > <OUTPUTFILE>

cat /123456/file01 /123456/file02 /123456/file03 > /123456/completed/output_file

🚧

With this instance of the command, you must use the right angle bracket (>) within the syntax. The final path/file to be concatenated must be followed by a single whitespace, the >, a second whitespace, and finally the filename of the concatenated file. All other instances of < > in the example that follows indicate a variable value.

The “cd” command

Use this command to change to a different remote directory.
Specify the full path to the desired directory as the “<DIRECTORY>” variable.

    cd <DIRECTORY>

While not specifically “options,” these features are also available:

• Include cd standalone to return to your established root directory.
• Include a whitespace followed by two periods to jump up a level in the directory tree (For example, cd ..)

cd <DIRECTORY>

cd /123456/secondary

The “cp” command

Use this command to copy one or more files or directories.

To copy a file, include any “<OPTION” variables along with the “<SOURCE>” path and filename of the file to copy. You can include multiple “<SOURCE>” file entries with a whitespace. Include the "<DIRECTORY>” for the file destination.

    cp <OPTION> <SOURCE> <DIRECTORY>

📘

You can use absolute or relative paths, so long as they resolve within the same top-level directory.

Example: Copy two files from a test directory into a release directory while preserving their attributes

cp <OPTION> <SOURCE> <DIRECTORY>

cp -p /123456/test/movie1.mp4 /123456/test/movie2.mp4 /123456/release/

🚧

Operations are restricted to existing directory trees

Your destination <DIRECTORY> must use a pre-existing path, as this command doesn't create a non-existent directory. For example, because the “non-existent” directory doesn't exist, this command will fail: cp /123456/movie.mp4 /123456/non-existent/

The “debug” command

While shown as available via the command interface, this command is currently not supported for use.

The “du” command

Use this command to estimate how much disk space each specified file or subdirectory uses.

Specify one or more individual files or sub-directories by including the complete path to the desired item as a “<FILE or SUBDIRECTORY>” variable. Separate each entry with a whitespace. Output will summarize each “<FILE or SUBDIRECTORY>” variable entry as disk usage in bytes.

    du <OPTION>... <FILE or SUBDIRECTORY>...

Example: Target a subdirectory and file

The --max-depth=<#> option is incorporated to set the maximum sub-directory depth to four.

du <OPTION>... <FILE or SUBDIRECTORY>...

du --max-depth=4 /123456/test/movie1.mp4 /123456/test/primary

📘

NetStorage supports a limited set of options for this command. NetStorage doesn’t support command options not listed here.

The “exit” command

Use this command to terminate the CMShell session.

exit

There are no options available with this command.

The “help” command

Use this command to display CMShell help.

Issued standalone (help), a list of available CMShell commands will be displayed. Include the name of a specific CMShell command as the “<COMMAND>” variable (for example, help unzip), and any available help for the specified command will be revealed.

    help <COMMAND>

There are no additional options available for use with this command.

The “hostname” command

Use this command to display the IP address of the remote machine.

hostname

There are no additional options available for use with this command.

Example: Display the IP of the remote machine

hostname

[writingteam /]$ hostname

72.246.17.108

The “ln” command

Use this command to create a symbolic link to a file or a directory.

NetStorage doesn't support the creation of hard links. When using the ln command in CMShell, creation of a symlink is implied. (The -s option is applied by default.) A symbolic link is a file that points to another file, much like a shortcut. You can point a symlink to a file, directory, or both.

    ln <OPTION> <TARGET> <LINKNAME>

Example: Target a single file and directory for symlink creation

ln <OPTION> <TARGET> <LINKNAME>

ln -v /123456/videos/movie.mp4 /123456/videos/subtitles /123456/symlinks

Example: Create a symlink to a single file

Include a single “<TARGET>” variable, defining it as the complete path to a desired file. The system will create a symbolic link using the value defined as the "<LINKNAME>" variable.

To create a symlink in your current directory for a file located at /123456/videos/movie.mp4 called symlink.mp4, view the Example CMShell command tab.

The targeted /123456/videos/movie.mp4 file is accessible by using the new symlink located at /123456/symlink.mp4. Performing a list (ls -l) shows the symlink relationship to the target as shown in the Example list output tab.

ln <OPTION> <TARGET> <LINKNAME>

ln -v /123456/videos/movie.mp4 symlink.mp4

[123456]$ ln -v /123456/videos /123456/symlinks
create symbolic link /123456/symlinks to /123456/videos

[123456]$ ls -l
    lrwxrwxrwx storageGroup  storage           24 Mar 26 20:43 symlink.mp4 -> /123456/videos/movie.mp4
    drwxrwxr-x storageGroup  storage            0 Mar 26 20:21 videos

Example: Create a symlink to a single directory

Include a single “<TARGET>” variable, defining it as the complete path to a desired directory. The system will create a symbolic link using the value defined as the "<LINKNAME>" variable.

When you create a symlink to a directory, it will display all content of the target directory. To create a symlink in your current directory for a directory located at /123456/videos, view the Example CMShell command tab.

You can access all files in the targeted directory by using the new symlink directory.

ln <OPTION> <TARGET> <LINKNAME>

ln -v /123456/videos /123456/symlinks

[123456]$ ln -v /123456/videos /123456/symlinks
    create symbolic link /123456/symlinks to /123456/videos

[123456]$ ls -l
    lrwxrwxrwx storageGroup  storage           14 Mar 26 21:07 symlinks -> /123456/videos
    drwxrwxr-x storageGroup  storage            0 Mar 26 20:21 videos

[symlinks]$ ls -l
    -rw-rw-r-- storageGroup  storage        78612 Mar 26 20:08 movie.mp4

Example: Create a symlink to multiple targets

Include multiple “<TARGET>” variables — defining each as the complete path to a desired file or directory, for which individual symbolic links will be created, and placed in the path named for the “<DIRECTORY>” variable.

ln <OPTION> <TARGET> <TARGET> <DIRECTORY>

ln -v /123456/videos/movie.mp4 /123456/videos/subtitles /123456/symlinks

123456]$ ln -v /123456/videos/movie.mp4 /123456/videos/subtitles /123456/symlinks
create symbolic link /123456/symlinks/movie.mp4 to /123456/videos/movie.mp4
create symbolic link /123456/symlinks/subtitles to /123456/videos/subtitles

/123456/symlinks$ ls -l
lrwxrwxrwx storageGroup  storage           24 Mar 26 21:41 movie.mp4 -> /123456/videos/movie.mp4
lrwxrwxrwx storageGroup  storage           24 Mar 26 21:41 subtitles -> /123456/videos/subtitles

The “ls” command

Display the contents of a directory.

This command is used to display the contents of a directory, where the“`” variable should be populated with the complete path to the desired directory.

    ls <OPTION>... <PATH>...

ls <OPTION>... <PATH>...

ls --list -S /123456/test /123456/new

The “md5sum” command

The md5sum command performs a raw byte analysis to display the MD5 digest for one or more files.

The “ <FILE>” variable should include the complete path and filename for the target file. This command doesn't provide a hash digest for symlink directories.

    md5sum <OPTION> <FILE>...

Example: Display the MD5 digest for a single file

md5sum <OPTION> <FILE>...

[123456 /]$ md5sum /videos/movie.mp4

[123456 /]$ md5sum /videos/movie.mp4
d81f21f9d0ac51621cad3de05ff734c6  /videos/movie.mp4

📘

If you run this command after [The “az2z” Command] (This command creates a Serve from Zip compatible zip archive."), its hash will differ from that of your local version.

The "mkdir" command

Use this command to create one or more new directories.

Include one or more instances of the <DIRECTORY> variable (separating each with a whitespace), and set each to the complete path to the new directory to create.

mkdir <OPTION> <DIRECTORY>...

📘

The -p and -v options can't be used together.

Your CMShell directory structure

Your upload account name and default upload directory CP code determine your root directory. When you connect to CMShell, your base directory will appear as [uploadAccountName], displaying the upload account that's connected. On the back-end, it translates to the associated upload directory code.

If directories within a named path don't exist, an error will be generated. To have CMShell automatically create non-existent directories in a path, be sure to include the -p or --parents option.

Example: Create a directory

In this example, the verbose -v option is included, and [writingteam /] is the root folder for the upload account named writingteam.

mkdir <OPTION> <DIRECTORY>...

[writingteam /]$ mkdir -v films

mkdir: created directory `films'

Example: Create a nested directory

Example creation of nested directory structure. The -p option will create any folders that don't already exist. This example combines mkdir with the -p option.

[writingteam /]$ mkdir -p /tv/shows/

The "mv" command

Use this command to rename a single file, or move a single/multiple files.

With this command these points apply:

• Any directory named within a path for a rename or move must preexist. CMShell will not automatically create non-existent directories. If applicable, see The "mkdir" command for details on creating a directory.
• Only files can be targeted as a <SOURCE> for a Rename/Move. Directories and sub-directories cann't be renamed or moved.

mv <OPTION>... <SOURCE> <DESTINATION>

Example: Rename a file

To rename a file, set the complete path and filename of the target file as the <SOURCE> variable, and include the desired path and new filename as the <DESTINATION> variable. The path set within the <DESTINATION> variable can either be the existing path, to keep the file in the same directory; or a new path, in order to also move the renamed file.

In this example the file movie.mp4 is renamed to movie_old.mp4 with the mv command.

mv <OPTION>... <SOURCE> <DESTINATION>

mv -i /123456/test/movie.mp4 /123456/test/movie_old.mp4

Example: Move a file

To move a file, set the <SOURCE> variable to the complete path and filename of the file to be moved, and set the <DIRECTORY> variable to the path to which the file is to be moved. Multiple <SOURCE> file entries can be included to move multiple files (separating each with a whitespace), with the final path in the syntax existing as the <DIRECTORY> to which the files will be moved.

In this example, two files, movie.mp4 and movie1.mp4 are moved to a new directory, preserving their filenames.

mv <OPTION>... <SOURCE>... <DIRECTORY>

mv -v /123456/test/movie.mp4 /123456/test/movie1.mp4 /123456/new/

The “pwd” command

Use this command to display the path of the current remote directory.

pwd

Example: Show the present working directory

This example displays the present working directory, when the current directory is movies.

pwd

[writingteam movies]$ pwd
/movies

The "rm" command

Use this command to delete one or more files or directories.

Include one or more instances of the <FILE> variable, separating each with a whitespace, and set it to the complete path to be deleted. Each <FILE> variable can be either of these:

• End with a directory. This will delete it, as well as all of its associated contents. This includes all sub-directories and file contents.
• End with a specific filename. This will delete an individual file.

    rm <OPTION>... <FILE>...

Example: Delete a single file and directory

This example targets a single file and an empty directory for deletion.

rm <OPTION>... <FILE>...

rm --interactive /123456/test/movie_old.mp4 /123456/old/

The “rmdir” command

Use this command to delete empty directories.

Include one or more instances of the <DIRECTORY> variable (separating each with a whitespace), and set each to the complete path to the directory to be removed.

📘

Targeted directories must be empty to use this command

The default rmdir command requires the directory to be empty.

    rmdir <OPTION> <DIRECTORY>...

🚧

Remove a directory and all of its contents

To permanently remove a directory and all of its contents, you must enable quick-delete and use the --quick_delete=imreallyreallysure <path> option.

Example: Remove two empty directories

This example removes the movies and tv directories.

rmdir <OPTION> <DIRECTORY>...

rmdir /123456/movies 123456/tv

rmdir --quick_delete=imreallyreallysure /123456/movies

[writingteam /]$ rmdir --quick_delete=imreallyreallysure movies
quick_delete for "movies" Error: Permission denied

The “stat” command

Use this command to display information on one or more files, or a file system.

stat <OPTION> <FILENAME> [<FILENAMES>...]

Example: Stat of a single file

This example performs a stat of the movie.mp4 file.

stat <OPTION> <FILENAME>

[writingteam movies]$ stat movie.mp4

File: movie.mp4
Size: 41392
Filetype: File
Mode: (0664/-rw-rw-r--)
Uid: writingteam
Gid: storage
Modify: Tue Jun  9 23:28:59 2020
Md5sum: d81f21f9d0ac51621cad3de05ff734c6

Example: Stat of a directory

This example performs a stat for the films directory.

stat <OPTION> <DIRECTORY>

[writingteam]$ stat films

File: films
Size: 0
Filetype: Directory
Mode: (0775/drwxrwxr-x)
Uid: writingteam
Gid: storage
Modify: Fri Dec 11 17:36:28 2020
Md5sum: -

The “wget” command

Use this command to download files from remote servers.

This command allows you to perform an immediate download of content from one or more specified <URL> entries, to the currently active directory. Prior to initiating this call, use either the cd command to navigate to an existing directory; or use the mkdir command to create a new directory and then use the cd command to access it.

wget <OPTION>... <URL>...

Available options

The <OPTION> variable displayed in the above example can be populated with one or more of the following options:

The “unzip” command

Use this command to perform various operations on a ZIP archive file’s contents.

The “<ZIPFILE>” variable is the complete path and filename of the Zip file to be targeted, while the “ <FILE-or-DIRECTORY>” variable should be the file or directory that will be the target of the operation. This is all based on the selected “ <OPTIONS>” and “ <MODIFIERS>” set.

unzip <OPTIONS> [MODIFIER] <ZIPFILE> [<OPTIONS>] <FILE_or_DIRECTORY>

📘

Only a single hyphen (-) is required when calling out more than one option (e.g., -fldv would be set to include the -f, -l, -d and -v options in a single command.

Available modifiers

The <MODIFIER> variable displayed in the above example can be populated with one of the following modifiers:

Considerations when using "unzip"

• The unzip will take some time proportional to the number of files created.
• The original zip archive will remain uploaded to NetStorage.
• The standard zip32 archives supported are limited to 4,294,967,295 (2^32^-1) bytes and 65,535 (2^16^-1) files.
• Capabilities beyond the basic UNIX "unzip" are not supported.

For example, zip archives with encryption, bzip compression, and zip64 format are not supported.

You should try Serve from Zip

You might be able to serve your files from within an uploaded zip archive on NetStorage without unzipping it, by using Serve from Zip. Serve from Zip supports much larger files and the zip64 file format. If you can use it, you won't need to use this unzip command. See if the Serve from Zip considerations are compatible with your workflow.

Perform a "quick-delete"

A quick-delete allows you to target a specific directory in a storage group to swiftly and recursively delete all of its contents.

Before you use quick-delete

• Quick-delete needs to be activated before it's used.
• You use quick-delete with CMShell and the NetStorage Usage API

To perform a quick-delete you can use either the rmdir command or therm command with these options:

• rmdir: rmdir --quick_delete=imreallyreallysure <path>
• rm: rm -r

🚧

Once used, these operations will perform a recursive deletion of all content in the target directory. Review your target content before use.

Activate “quick-delete” for your storage group

The quick-delete setting is disabled by default to protect against inadvertent deletions of potentially unknown content. This setting is enabled in ​Control Center​ Control Center, on a per-storage group basis. It can be enabled during creation of a group or by editing an existing one.

The Quick Delete switch is available in the upload directories settings for a storage group

📘

Accessing "quick-delete" via CMShell and the NetStorage Usage API are both configured here.

Considerations when using quick-delete

Review these points before enabling and using quick-delete:

• Newly uploaded content will not be deleted. If you have targeted a file with a quick-delete that hasn’t been deleted yet, and you upload a new version of the file that overwrites it, this new version will not be deleted.
• This feature is designed for large deletes. While it can be used to perform a recursive delete of any number of files, it is actually meant to be used when you have millions of objects to delete. You will see the best performance in this case.
• The rmdir and rm -r options are the same with ObjectStore: Both methods can be used to perform a quick-delete in ObjectStore.
• Quick delete must be activated.
• The actual deletion may take some time: The actual deletion occurs in the background with ObjectStore storage groups. If a large number of files have been targeted, the deletions may take a significant amount of time to complete.
• Objects targeted for quick delete may still be accessible. Taking the previous point into consideration, a targeted file or directory will exist until the deletion of that object can fully complete. Until the actual delete, it will still be accessible, and served if requested.
• Currently, there is no alert that a quick-delete has completed. Quick deletes take time, and this may be an issue. You can use the “du” command or the “ls” command to view directories to check status.
• “undeletion” is not supported. When performing a quick-delete from an ObjectStore storage group, targeted content cannot be recovered. Once issued, content will be permanently removed.