Introduction To Command Line Tools

An Introduction to Command Line Tools

This page will go through how to use command line tools for those that are new to them!

While the command line can seem intimidating, openSeaChest tries to keep it simple whenever possible.

This will not be able to capture all aspects of the command line, but we hope this will be a good introduction for you to follow and get more comforatble with it!

Quick Definitions

Some terms you may see are:

• CLI - Command Line Interface
• TUI - Text User Interface
• GUI - Graphical User Interface

openSeaChest tools are CLI tools.

An example of a TUI is older system BIOS's that require changing things with arrow keys, tab, enter key, + or - keys, and the function keys on your keyboard with no option for a mouse.

An example of a GUI is SeaTools, many UEFI configurations have a GUI today, or even using Windows to navigate with a mouse and click virtual buttons to navigate windows that your applications run within.

Permissions

For openSeaChest tools you will need Administrator permissions in Windows or sudo/root permissions in other operating systems like Linux.

The reason for these permissions comes from the OS (Operating System) itself. When openSeaChest accesses your storage device it needs to be able to issue raw commands to the device. The OS may not be able to know and understand the effects of all of these commands, even if they are benign, so the OS requires additional permissions for this interface. This is designed to protect your data from possible deletion or other errors in case a bad actor or someone who is less sure about what they are doing cannot cause data-loss.

While it may seem like it is a risk for you to use openSeaChest if you don't know all the details about these raw commands, Seagate has done it's best to provide you the options you want to control your storage and protect your data from mishaps and bad inputs.

Lets Begin!

The first step is to download the openSeaChest tools. Place these in a directory of your choice! It is recommended that they are moved out of the Downloads folder to another location for security so a choice like the Documents folder is a good one.

Next you will need a command window to interact with the CLI.

In Windows you can use Command Prompt (cmd.exe) or Powershell. These are built-in to modern Windows systems, but there are other command windows or shells you can also use if you wish. Be sure to right-click and execute this as Administrator! This is required for Windows!

In Linux you open up your terminal. It can be named Terminal, XTerminal, QTerminal, Konsole, or it may have another name. These are most common to find on your system, so if you aren't sure or cannot find these installed then do a web search for your distribution.

Now you will run your first CLI command: cd in order to change directory to the location of openSeaChest tools.

If you placed the tools in Documents/openSeaChest you will type something like this to change the directory on the command line:

• Linux: cd ~/Documents/openSeaChest
• Windows: cd C:\Users\Username\Documents\openSeaChest

As you are typing out the directory, you can hit the Tab key in many shells[^1] to perform Tab Completion so you do not need to type the full name of a directory manually. Be aware that you must give a starting point, even relative directory, for tab completion to work (ex: ./ or .\). This can be helpful to save time as you get used to the command line, but feel free to try it out! Note that in Windows cmd.exe requires use of \ in the path for tab completion to work correctly.

If you get stuck trying to cd to your directory you can also list the contents of it. If you are using cmd.exe you can use dir and for other shells (powershell, linux, etc) you can use ls. This will list the contents of your current directory to help you figure out where to navigate to next. You can navigate one or more folders at a time, but if you get stuck just go as far as you can, then list what is in that directory! If you are in Windows, continuing to press tab once in a new directory will cycle through each option in that directory (files and folders). In linux if you keep pressing tab it will list the contents of your directory that match what you have typed so far or if in a fresh directory it will have output similar to ls.

If you are unsure of your current directory, you can use another command to tell you where you are. In cmd.exe use cd and no other arguments. In powershell, linux, etc you can use pwd and this will tell you the current directory you have cd'd to.

NOTE: Spaces in your path will need to be "escaped" for the cd command to handle them properly. In a Linux terminal, add a \ (backslash) before each space. In Windows powershell, use ` (back tick) and in cmd.exe quote the full path to cd.

• cmd.exe example: cd "C:\Users\Me\Documents\I put my executables here"
• powershell example: cd C:\Users\Me\Documents\I` put` my` executables` here
• Linux terminal example: cd ~/Documents/I\ put\ my \executables\ here

If you have a folder open to openSeaChest you can also try copy-pasting the address from the address bar into the command line after the cd command to save typing as well.

Note: If you have spaces in the name, you may see the system automatically escape them on copy-paste.

[^1]: Bash, cmd.exe, and powershell support tab completion. Other shells may be installed which may or may not have this support.

Running openSeaChest

Now that you have successfully gotten to the directory where the openSeaChest tools are located, lets run them!

Before you run your first openSeaChest command in Linux, you will need to make sure it is set with the execute or x permission. To add it to the openSeaChest tools you can run chmod +x ./openSeaChest_* and this will set execute permissions for all matching openSeaChest tools in the current directory. You can also run the chmod command on one executable at a time as well typing out the full name.

The first thing you will want to do is scan the system to see what devices are detected. You can do this with the -s option. If you are in Windows, you will need to make sure .exe is at the end of these lines, but otherwise it should work the same!

Scanning the system: ./openSeaChest_Basics -s

NOTE: All openSeaChest tools support the scan option.

This will print out a list of devices that openSeaChest detected in the system with the data separated into columns. Some of the output is informational for you to find your device, but the most important part you will need for all further options is the Handle.

If you do not see any devices output from the scan or you see a warning about running as root/sudo you will need to check your permissions. In Windows the most common scenario is that you see another command window popup then immediately disappear. Check that you have an admin window open and try again. In Linux you may have access to the command sudo which stands for super user do followed by a command. In some shells you can simply type sudo !! to retry your last command with sudo. In others you may need to type out the full command again: sudo ./openSeaChest_Basics -s. Another option you may have is to login as the root user. How you do this varies a little bit between systems, but if you are using Ubuntu or a derivative you can try sudo su and others you can run su to enter super user (root). You will need either access to sudo or you will need the root user's password in all of these cases.

A Handle is how the operating system expects accessing your device and openSeaChest needs this to interact with your intended device. Throughout the remaining instructions it will be shown as <handle> which is meant to tell you to fill in your handle here.

In Windows your handle will typically be PD443. 443 was an example but it will be PD followed by a number. This is short for the longer name (which openSeaChest also accepts) \\.\PhysicalDrive443

In Linux your handle will be /dev/sg443 or /dev/sg followed by a number. In Linux you may be familiar with a handle like /dev/sda which can also be provided to openSeaChest to access your device. The sg handle is preferred as it is a raw character device handle whereas the sd handle is a block device and there are some differences in how they are handled for raw-IO. openSeaChest will attempt to automatically map a sd handle to sg for you when you provide sd. If the mapping fails, it uses the handle you provided exactly as you provided it.

Now lets run the device information option (-i) to get more information about the drive.

openSeaChest_Basics -d <handle> -i

This will dump out a lot more information about the device you specified with a handle. You will see capacity, features supported, and much more from this output.

One last important option for you to know about: --help

All of the openSeaChest tools include the option --help or -h for short. This will dump all of the options a given tool supports and some example usage for the tool as well.

At this point you are ready to start digging into the tools in more detail and learning more about your storage device!

Working with Multiple Drives in openSeaChest

If you want to work with more than one drive at a time there are a few options.

You can write a script to interact with each device which gives you much more control over parallelizing options, or you can let openSeaChest interact sequentially with each device.

You can provide a list of devices by using -d <handle> multiple times:

openSeaChest -d /dev/sg443 -d /dev/sg342 -d /dev/sg95 -i

Another option you have is -d all. This will use every handle shown in -s and go through them sequentially performing all other operations you have defined on the command line.

Another option is to specify only specific models with the --modelMatch <modelNumberNoSpaces>:

openSeaChest -d all --modelMatch ST100000NM0001 -i

If you need parallelization, you will need to use a script. (Seagate will put up a page showing examples as soon as we get to writing it to this wiki!)

The openSeaChest Tools

Now that you have the basics to run a CLI tool, you are probably thinking "What tool do I need". Let's go through a brief introduction to each of the tools.

• openSeaChest_Basics: This tool is more or less a CLI version of SeaTools. It has the common basic options you most likely need for your everyday needs.
• openSeaChest_Configure: This tool has lots of configuration options to change device behavior. This is the "generic" configuration tool. Some options, such as power options will be found in other tools.
• openSeaChest_Defect: This tool has options related to the defect management system in a modern storage device. You can view defect lists (if supported by the device) and you can create test defects to test a device's handling of defects.
• openSeaChest_Erase: This tool contains every method to sanitize your storage with a clear or purge so you can securely remove your data from your drive.
• openSeaChest_Firmware: This tool is all about upgrading your device firmware to a new revision.
• openSeaChest_Format: This tool is NOT about erasure, but about changing the formatting of the medium. Changing sector sizes, adding protection information, depopulating a storage element, and more. This affects the medium and the way the drive finds sectors on the medium. Use it with caution!
• openSeaChest_GenericTests: This tool has some basic testing of a device's Read/Write capabilities.
• openSeaChest_Info: This tool has option to dump drive information beyond -i. Example: --partitionInfo reads the MBR or GPT partition table for you and displays what it detects on the drive.
• openSeaChest_NVMe: This tool is for NVMe specific options that don't really fit in with the other tools. While there may be some overlap in other tools, this is intended to handle NVMe unique capabilities. NVMe drives are supported by all openSeaChest tools!
• openSeaChest_PassthroughTest: This tool is meant to automatically check SATL/SNTL devices (USB, HBAs, Drivers) for known workarounds to get as much support as possible out of them with the openSeaChest tools. You can run the automated test on your device and share it on an openSeaChest issue to improve overall support for your device in future releases.
• openSeaChest_PowerControl: This tool has options to control all the different features that govern your device's power consumption. Use this to adjust idle and standby timers, configure APM, and more.
• openSeaChest_Raw: Issue a RAW device command from the command line. Unless you are comfortable with the device standards or vendor unique commands a drive supports, you probably do not want this. If you find yourself using raw commands often for a feature, please request it be added as its own openSeaChest option!
• openSeaChest_Reservations: This tool handles SCSI/NVMe device reservations. This exposes these commands in easy to use options rather than using a low-level raw command. Unless you are working with special enterprise configurations where multiple systems access a single drive, this won't mean much to you.
• openSeaChest_Security: This tool holds options related to ATA security and other security features.
• openSeaChest_SMART: This tool holds the options needed to explore device health and statistics about how it is performing.
• openSeaChest_ZBD: This tool is all about working with Zoned Block Devices (ZBDs) and offers easy to use options to work with them so a raw command is not necessary. Unless you are working with Host-Managed devices, this tool is probably not something you need.