Skip to main content

Command line interface

While most tasks in Unraid can be performed through the WebGUI, certain operations - especially those related to diagnostics, drive management, or scripting - require using the system console or SSH terminal. This page offers Unraid-specific command-line tools and examples that can be used without needing extensive Linux knowledge.

Device paths

Many disk-level Unraid operations depend on Linux device names, like /dev/sdX. You can find the device identifier for any drive in the Main tab of the WebGUI. Look for the three-letter label sdX or nvmeX next to each disk. Use the appropriate identifier in all commands, replacing sdX with your specific disk.

Accessing the terminal​

Unraid includes a built-in web terminal that you can access directly from the WebGUI. Simply use the top-right dropdown menu and select ">_". This opens a command-line session as the root user, giving you full administrative access to your system.

You can also connect to your Unraid server externally using SSH (secure shell) with a client like PuTTY.

When should I use the terminal?

Terminal access is useful for:

  • Running diagnostics and command-line tools like smartctl, xfs_repair, tail, or top
  • Executing plugin scripts or tools that don't require a user interface
  • Troubleshooting issues related to connectivity, system services, or user shares

Using PuTTY (Windows only)​

If you're using Windows, you might prefer PuTTY for SSH access instead of the built-in terminal. It's lightweight, free, and allows you to save sessions for easy access later.

How to install and use PuTTY - Click to expand/collapse
  1. Download PuTTY from the official site.
  2. Launch the PuTTY application.
  3. Enter your Unraid server’s IP address or hostname (e.g., tower.local).
  4. Set the connection type to %%SSH|ssh%%.
  5. (Optional) Save the session name for future use.
  6. Click Open to start the session.
  7. When prompted, log in as root and then enter your password.

Once you've logged in, you're in the Unraid shell environment. Type exit when you're finished to close the session.

note

Unraid automatically configures the SSH server on the first boot. Ensure your networking is working properly and that your root password is set before attempting a remote connection.

Drive testing and monitoring​

These tools assist with evaluating performance, checking drive health, and troubleshooting array slowness. All commands should be executed from the terminal or via SSH.

hdparm​

Use this command to test read speed and display drive characteristics.

View hdparm options - Click to expand/collapse

Test drive read speed:

hdparm -tT /dev/sdX

The -t flag tests buffered disk reads, while -T tests cache reads. This primarily measures sequential read performance and helps identify unusually slow drives.

Run multiple tests for accuracy:

for ((i=0;i<5;i++)); do hdparm -tT /dev/sdX; done

View drive information:

hdparm -I /dev/sdX

This displays the model, firmware, cache size, and supported features, which helps verify disk type and controller behavior.

smartctl​

This command runs SMART diagnostics and monitors drive health.

View smartctl options - Click to expand/collapse

Basic SMART report:

smartctl -a /dev/sdX

If this command returns an error, try specifying the device type: smartctl -a -d ata /dev/sdX (use -d nvme for NVMe drives).

Start SMART self-tests:

Short test (takes a few minutes)

smartctl -t short /dev/sdX

Extended test (may take hours)

smartctl -t long /dev/sdX

Save SMART report to a file:

smartctl -a /dev/sdX > /boot/smart_report.txt

This saves the report to your Unraid flash drive for later review or sharing on the forums.

diskspeed.sh​

This script allows for comprehensive surface-level performance testing with visual reports.

View diskspeed.sh usage - Click to expand/collapse

This used to be a script you would download from the Unraid forums. DiskSpeed is available now in a more refined package:

Install DiskSpeed from Community Applications (Apps tab) by searching for "DiskSpeed", or visit the GitHub repository for manual installation instructions.

System monitoring​

Use these commands to monitor memory, processes, and system performance when the WebGUI is unavailable or for more detailed diagnostics.

top​

This command provides a real-time process and resource monitor.

View top usage - Click to expand/collapse
top
  • Displays CPU and memory usage for each process in real-time.
  • Press q to exit.
  • Use arrow keys to scroll, and k to terminate processes.
tip

Consider using htop for a more user-friendly interface with enhanced controls.

free​

This command shows memory usage statistics.

View free usage - Click to expand/collapse
free -h

This displays RAM usage in a human-readable format. The -h flag means sizes will show in KB, MB, or GB instead of bytes.

Understand the output

A low "available" memory reading doesn’t necessarily indicate a problem—Linux aggressively caches data for performance.

ps​

Use this command to display running processes with detailed information.

View ps options - Click to expand/collapse

List all processes with full details:

ps aux

Sort by memory usage:

ps aux --sort=-%mem | head -20

Sort by CPU usage:

ps aux --sort=-%cpu | head -20

Storage utilities​

These commands help check disk usage, partition info, and identify storage devices.

df​

This command displays filesystem disk space usage.

View df usage - Click to expand/collapse
df -h

This command displays the used and available space on all mounted file systems. It’s convenient for checking /var/log (which utilizes RAM-based logging) in Unraid. For more information on system logging.

fdisk​

View disk partition tables and geometry.

View fdisk usage - Click to expand/collapse
fdisk -l /dev/sdX

This command displays the partition layout, sizes, and disk geometry. It helps troubleshoot mismatched disk sizes, especially when replacing disks.

lsblk​

List all block devices in tree format.

View lsblk usage - Click to expand/collapse
lsblk

This command displays all storage devices, along with their mount points, in a straightforward tree structure. It’s great for getting an overview of your storage layout.

blockdev -getsz​

Helps determine if a replacement drive has enough space before rebuild.

View blockdev usage - Click to expand/collapse

Syntax:

blockdev --getsz /dev/sdX

Returns the raw number of 512-byte sectors on a device - handy for confirming that a replacement drive is large enough before rebuilding.

blkid​

Identify filesystem labels.

View blkid usage - Click to expand/collapse

Syntax:

blkid /dev/sdX1

Outputs the filesystem type and label. Use this instead of the deprecated vol_id command when verifying that the Unraid flash is labeled UNRAID.

Network diagnostics​

Tools for troubleshooting network connectivity and interface configuration.

ss​

Display socket statistics and network connections. This is the modern replacement for netstat.

View ss options - Click to expand/collapse

Show all listening ports:

ss -tuln
  • -t: TCP sockets
  • -u: UDP sockets
  • -l: Only show listening sockets
  • -n: Show port numbers instead of service names

Show established connections:

ss -tup

This command shows active connections along with process information.

ip​

Configure and display network interface information. This is the modern replacement for ifconfig.

View ip options - Click to expand/collapse

Show all network interfaces:

ip addr show

Show network interfaces with colors:

ip -c addr show

Show routing table:

ip route show

ping​

Test network connectivity.

View ping usage - Click to expand/collapse

Test connectivity by sending a limited number of packets:

ping -c 4 google.com

This command sends four packets to the destination and stops, making it suitable for basic connectivity testing without continuous output.

ethtool​

Handy tool for querying and adjusting network interface card (NIC) parameters, such as link speed, offload features, and statistics.

View ethtool usage - Click to expand/collapse

Basic driver and firmware info:

Use this command to get information about the driver and firmware for your network interface:

ethtool -i eth0

Show current link speed and settings:

To check the current link speed and settings of your interface, run:

ethtool eth0

Display extended interface statistics:

For extended statistics related to the interface, use the following command:

ethtool -S eth0

These commands can help you confirm the negotiation speeds for gigabit, 2.5 GbE, or 10 GbE connections, diagnose issues with cables, or identify dropped packets that might arise from offload mismatches.

System information​

Get detailed information about hardware, kernel, and overall system configuration.

CPU architecture summary:

lscpu

This command displays information about cores, threads, virtualization support, and cache details.

Feature detection:

grep -E 'lm|vmx|svm' /proc/cpuinfo
  • lm: Indicates 64-bit support
  • vmx: Intel VT-x virtualization
  • svm: AMD-V virtualization

System maintenance​

Commands for system shutdown, log monitoring, and service management.

tail​

Monitor log files in real-time.

View tail usage - Click to expand/collapse
tail -f /var/log/syslog

This command shows live updates from the system log. To exit, use Ctrl+C.

Show a specific number of lines:

tail -n 50 /var/log/syslog

powerdown​

Safely shut down the system.

View powerdown usage - Click to expand/collapse
powerdown

This command utilizes Unraid's built-in shutdown process to stop the array and power down the system safely. It's preferred over manual shutdown methods.