Unraid

https://docs.unraid.net
Admin
Unraid is an embedded operating system that transforms hardware into a network-attached storage...
Tokens:81,653
Snippets:1,372
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install QEMU Guest Agent

Source: https://docs.unraid.net/unraid-os/using-unraid-to/create-virtual-machines/vm-conversion-and-migration

After installing VirtIO drivers, install the QEMU guest agent from the VirtIO drivers ISO to enable better integration and management of the VM.

```batch
D:\guest-agent\qemu-ga-x64.msi
```

--------------------------------

### Enable and Start QEMU Guest Agent Service

Source: https://docs.unraid.net/unraid-os/troubleshooting/common-issues/unclean-shutdowns

Commands to enable and start the QEMU Guest Agent service on Linux systems. This ensures the agent runs automatically on boot and is active.

```bash
sudo systemctl enable qemu-guest-agent
sudo systemctl start qemu-guest-agent
```

--------------------------------

### Install QEMU Guest Agent on Ubuntu/Debian

Source: https://docs.unraid.net/unraid-os/troubleshooting/common-issues/unclean-shutdowns

Use this command to install the QEMU Guest Agent on Ubuntu or Debian-based systems. This is a prerequisite for VM hibernation.

```bash
sudo apt install qemu-guest-agent
```

--------------------------------

### Service Management: Start

Source: https://docs.unraid.net/API/cli

Starts the Unraid API service. Allows setting the log level via an option or environment variable.

```APIDOC
## unraid-api start

### Description
Starts the Unraid API service.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Options
- **--log-level** (string) - Optional - Set logging level (trace|debug|info|warn|error|fatal)

### Request Example
```bash
unraid-api start --log-level debug
LOG_LEVEL=trace unraid-api start
```

### Response
N/A
```

--------------------------------

### Install QEMU Guest Agent on CentOS/RHEL/Fedora

Source: https://docs.unraid.net/unraid-os/troubleshooting/common-issues/unclean-shutdowns

Use these commands to install the QEMU Guest Agent on CentOS, RHEL, or Fedora systems. This is a prerequisite for VM hibernation.

```bash
sudo yum install qemu-guest-agent
```

```bash
sudo dnf install qemu-guest-agent
```

--------------------------------

### Example Shutdown Timeout Calculation

Source: https://docs.unraid.net/unraid-os/troubleshooting/common-issues/unclean-shutdowns

An example calculation demonstrating how to apply the general shutdown timeout formula with specific values.

```text
(300 × 3) + 30 + 10 + 30 = 970 seconds (over 16 minutes)
```

--------------------------------

### Complete Workflow Example: Temporary Access Provisioning

Source: https://docs.unraid.net/API/programmatic-api-key-management

A bash script demonstrating the creation of a temporary API key, its use in a `curl` request, and automatic cleanup via `trap`.

```bash
#!/bin/bash
set -e

# 1. Create temporary API key
echo "Creating temporary API key..."
KEY_DATA=$(unraid-api apikey --create \
  --name "temp deployment key" \
  --roles ADMIN \
  --description "Temporary key for deployment $(date)" \
  --json)

# 2. Extract the API key
API_KEY=$(echo "$KEY_DATA" | jq -r '.key')
echo "API key created successfully"

# 3. Use the key for operations
echo "Configuring services..."
curl -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "azure", "clientId": "your-client-id"}' \
  http://localhost:3001/graphql

# 4. Clean up (always runs, even on error)
trap 'echo "Cleaning up..."; unraid-api apikey --delete --name "temp deployment key"' EXIT

echo "Deployment completed successfully"

```

--------------------------------

### Start a Docker Container

Source: https://docs.unraid.net/unraid-os/using-unraid-to/run-docker-containers/managing-and-customizing-containers

Use this command to start a stopped Docker container. Replace 'container-name' with the actual name of your container.

```bash
docker start "container-name"
```

--------------------------------

### Install and Use Wakeonlan on macOS

Source: https://docs.unraid.net/unraid-os/system-administration/advanced-tools/wake-on-lan

Installs the wakeonlan utility via Homebrew and sends a magic packet.

```bash
brew install wakeonlan
```

```bash
wakeonlan MAC_ADDRESS
```

--------------------------------

### Issuer URL Examples

Source: https://docs.unraid.net/API/oidc-provider-setup

Examples of correct base URLs for common OIDC providers. The base URL format is strongly recommended for security.

```text
https://accounts.google.com
```

```text
https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
```

```text
https://keycloak.example.com/realms/YOUR_REALM
```

```text
https://auth.yourdomain.com
```

--------------------------------

### Start Unraid API Service

Source: https://docs.unraid.net/API/cli

Starts the Unraid API service. The log level can be set using the --log-level option or the LOG_LEVEL environment variable.

```bash
unraid-api start [--log-level <level>]
```

```bash
LOG_LEVEL=trace unraid-api start
```

--------------------------------

### Start SMART Self-Tests

Source: https://docs.unraid.net/unraid-os/system-administration/advanced-tools/command-line-interface

Initiate SMART self-tests on a drive to perform diagnostic checks. Use `short` for a quick test or `long` for a more thorough, time-consuming examination.

```bash
smartctl -t short /dev/sdX
```

```bash
smartctl -t long /dev/sdX
```

--------------------------------

### Get Ethtool Driver and Firmware Info

Source: https://docs.unraid.net/unraid-os/system-administration/advanced-tools/command-line-interface

Retrieves basic driver and firmware information for a specified network interface.

```bash
ethtool -i eth0
```

--------------------------------

### Initiate API Key Request

Source: https://docs.unraid.net/API/api-key-app-developer-authorization-flow

Application redirects the user to this URL to start the API key authorization process. Ensure all parameters are correctly encoded.

```url
https://[unraid-server]/ApiKeyAuthorize?name=MyApp&scopes=docker:read,vm:*&redirect_uri=https://myapp.com/callback&state=abc123
```

--------------------------------

### JavaScript Example: Unraid API Key Authorization Flow

Source: https://docs.unraid.net/API/api-key-app-developer-authorization-flow

This JavaScript code demonstrates how to redirect a user to the Unraid authorization page and handle the callback with the generated API key. It includes storing the state for verification and securely saving the received API key.

```javascript
// JavaScript example  

const unraidServer = 'tower.local';  

const appName = 'My Docker Manager';  

const scopes = 'docker:*,system:read';  

const redirectUri = 'https://myapp.com/unraid/callback';  

const state = generateRandomState();  

  

// Store state for verification  
sessionStorage.setItem('oauth_state', state);  

  

// Redirect user to authorization page  
window.location.href =  
    `https://${unraidServer}/ApiKeyAuthorize?` +  
    `name=${encodeURIComponent(appName)}&` +  
    `scopes=${encodeURIComponent(scopes)}&` +  
    `redirect_uri=${encodeURIComponent(redirectUri)}&` +  
    `state=${encodeURIComponent(state)}`;  

  

// Handle callback  
const urlParams = new URLSearchParams(window.location.search);  
const apiKey = urlParams.get('api_key');  
const returnedState = urlParams.get('state');  

if (returnedState === sessionStorage.getItem('oauth_state')) {  
    // Save API key securely  
    saveApiKey(apiKey);  
}  

```

--------------------------------

### Unraid VM startup.nsh Configuration

Source: https://docs.unraid.net/unraid-os/using-unraid-to/create-virtual-machines/unraid-as-a-vm

Create a startup.nsh file on the VM's flash drive to initiate the EFI boot process. This file points to the EFI bootloader.

```shell
\EFI\boot\bootx64.efi  

```

--------------------------------

### Display API Help

Source: https://docs.unraid.net/API/how-to-use-the-api

View all available commands and configuration options for the Unraid API CLI.

```bash
unraid-api --help
```

--------------------------------

### Run Real-time Process Monitor with top

Source: https://docs.unraid.net/unraid-os/system-administration/advanced-tools/command-line-interface

Use the `top` command to view a real-time overview of system processes, CPU usage, and memory consumption. Press 'q' to exit the monitor.

```bash
top
```

--------------------------------

### Run Sysprep for Generalization

Source: https://docs.unraid.net/unraid-os/using-unraid-to/create-virtual-machines/vm-conversion-and-migration

Execute sysprep with generalization, shutdown, and out-of-box experience options. This prepares Windows for new hardware.

```bash
sysprep.exe /generalize /shutdown /oobe
```

--------------------------------

### Launch Midnight Commander

Source: https://docs.unraid.net/unraid-os/system-administration/advanced-tools/command-line-interface

Starts the Midnight Commander file manager in the Unraid web terminal.

```bash
mc
```

--------------------------------

### Prepare Windows for GPLPV Driver Removal

Source: https://docs.unraid.net/unraid-os/using-unraid-to/create-virtual-machines/vm-conversion-and-migration

Use this command in an administrator command prompt to set load options for preparing Windows to remove Xen GPLPV drivers.

```bash
bcdedit -set loadoptions nogplpv
```

--------------------------------

### Markdown Link Example

Source: https://docs.unraid.net/contribute/style-guide

Demonstrates how to create an inline Markdown link to another document within the Unraid documentation.

```markdown
You can also check our [getting started guide](../unraid-os/getting-started/quick-start-guide.mdx).
```

--------------------------------

### List All ZFS Pools via Command Line

Source: https://docs.unraid.net/unraid-os/using-unraid-to/manage-storage/file-systems

Display a list of all available ZFS pools on the system.

```bash
zpool list
```

--------------------------------

### Booting OVMF-based VMs from EFI Shell

Source: https://docs.unraid.net/unraid-os/updating-unraid

Use these commands to boot a VM from the EFI shell if it presents after an upgrade. Try 'fs1:' if 'fs0:' fails.

```bash
fs0:
cd efi/boot
bootx64.efi
```

--------------------------------

### Update Apache Tika Repository

Source: https://docs.unraid.net/guides/paperless-ngx

Replace the default private repository with the official Apache Tika image from Docker Hub to resolve installation issues.

```bash
apache/tika:latest
```

--------------------------------

### Unraid VM syslinux.cfg Configuration

Source: https://docs.unraid.net/unraid-os/using-unraid-to/create-virtual-machines/unraid-as-a-vm

Modify the syslinux.cfg file on the VM's flash drive to specify the unique label for the VM's boot drive. This ensures the VM boots correctly with its own configuration.

```text
label Unraid OS  

  menu default  
  kernel /bzimage  
  append unraidlabel=UNRAID-VM initrd=/bzroot  

```

--------------------------------

### Create API Key via CLI

Source: https://docs.unraid.net/API/how-to-use-the-api

Create a new API key using the Unraid API CLI. Follow the prompts to define its name, description, roles, and permissions.

```bash
unraid-api apikey --create
```

--------------------------------

### Get Block Device Size

Source: https://docs.unraid.net/unraid-os/system-administration/advanced-tools/command-line-interface

Returns the raw number of 512-byte sectors on a device, useful for confirming a replacement drive's size before rebuilding.

```bash
blockdev --getsz /dev/sdX
```

--------------------------------

### Create an API Key with Admin Role

Source: https://docs.unraid.net/API/programmatic-api-key-management

Use this command to create a new API key with administrative privileges. Ensure you have the necessary permissions.

```bash
LOG_LEVEL=debug unraid-api apikey --create --name "debug key" --roles ADMIN
```

--------------------------------

### Show All Network Interfaces

Source: https://docs.unraid.net/unraid-os/system-administration/advanced-tools/command-line-interface

Displays all network interfaces and their configurations. This is a modern replacement for ifconfig.

```bash
ip addr show
```

--------------------------------

### Check BTRFS File System (Read-Only) via Command Line

Source: https://docs.unraid.net/unraid-os/using-unraid-to/manage-storage/file-systems

Perform a read-only check on a BTRFS file system. Start the array in Maintenance Mode for this operation.

```bash
btrfs check --readonly /dev/mdXp1
```

```bash
btrfs check --readonly /dev/sdX1
```

--------------------------------

### Create Mount Point

Source: https://docs.unraid.net/unraid-os/system-administration/advanced-tools/command-line-interface

Creates a temporary directory to serve as a mount point for network shares.

```bash
# Create a temporary mount point
mkdir /work
```

--------------------------------

### Paperless NGX Database Configuration Variables

Source: https://docs.unraid.net/guides/paperless-ngx

Add these variables to configure Paperless NGX to use a PostgreSQL database. Ensure the database name, user, and password match your PostgreSQL setup.

```text
Variable| PAPERLESS_DBHOST| 192.168.1.50| IP address of your Unraid server
```

```text
Variable| PAPERLESS_DBPORT| 5432| Postgres port (only change if you have another Postgres instance)
```

```text
Variable| PAPERLESS_DBNAME| paperless| Database name you set in Postgres
```

```text
Variable| PAPERLESS_DBUSER| paperless| Database user you set in Postgres
```

```text
Variable| PAPERLESS_DBPASS| your-secure-password| Database password you set in Postgres
```

--------------------------------

### Scrub BTRFS File System via Command Line

Source: https://docs.unraid.net/unraid-os/using-unraid-to/manage-storage/file-systems

Perform a scrub operation on a BTRFS file system to automatically check and repair errors. Start the array in Normal mode for this operation.

```bash
btrfs scrub start /mnt/diskX
```

--------------------------------

### Display CPU Architecture Summary

Source: https://docs.unraid.net/unraid-os/system-administration/advanced-tools/command-line-interface

Shows detailed information about CPU architecture, including cores, threads, virtualization support, and cache details.

```bash
lscpu
```

--------------------------------

### Repair XFS Filesystem

Source: https://docs.unraid.net/unraid-os/troubleshooting/common-issues/data-recovery

Use this command to check and repair an XFS filesystem on an Unraid disk. The -v flag provides verbose output. Ensure the array is started in Maintenance Mode before running.

```bash
xfs_repair -v /dev/mdXp1
```
Tokens:
Raw