DOCSEARCHbyAlgolia
Submit Docs

Unraid webGUI

repository·master·Indexed 42 days ago

https://github.com/unraid/webgui

Source code and documentation for the Unraid web interface, including the Dynamix System Management Utility. Covers the theme system architecture using CSS variables, repository structure, local development environment setup, and system administration guides for array device assignment, pool configuration, encryption, and SMB share security.

Tokens
8.2K
Snippets
4
Records
38
Agent score
54%

What's inside Unraid

  2. Configure User Share Split Levels

    master

    The Split level determines if a directory can expand across multiple disks:

    • Automatically split any directory as required: Creates parent directories on the chosen disk if they don't exist. New files/subdirectories can be placed on any disk.
    • Automatically split only the top level directory as required: If the first-level subdirectory doesn't exist on the target disk, it is created there. For deeper subdirectories, they are kept on the same disk as their parent.
    • Automatically split only the top "N" level directories as required: Similar to top-level, but applies to the first $N$ levels. Beyond level $N$, files stay with their parent directory.
    • Manual: do not automatically split directories: Only considers disks where the parent directory already exists.

  3. Configure User Share Allocation Methods

    master

    The Allocation method determines how Unraid chooses a disk when creating new files/directories within a share:

    • High-water: Writes to the lowest-numbered disk with free space above a calculated 'high water mark' (initially half the size of the largest Data disk). This balances data distribution and minimizes disk spin-ups.
    • Fill-up: Writes to the lowest-numbered disk that has free space above the configured Minimum free space.
    • Most-free: Writes to the disk that currently has the most available free space.

  4. Configure Exclusive Shares for improved I/O performance

    master

    If set to Yes, share directories under /mnt/user act as symlinks to the share directory on a storage volume. This bypasses the FUSE layer, which can significantly increase I/O performance.

    Conditions for Exclusive Shares:

    • The Primary storage for the share must be set to a pool.
    • The Secondary storage for the share must be set to none.
    • The share must exist on a single volume.

  5. Avoid theme variant files by using CSS nesting and variables

    master

    Anti-Pattern Alert: Do not create separate CSS files for different themes (e.g., Eth0-azure.css and Eth0-black.css). This causes code duplication and maintenance issues.

    Recommended Pattern: Use a single component file that defines variables in :root and uses theme classes (.Theme--{name}) to override those variables or specific properties via nesting.

    Benefits

    • Single Source of Truth: All styles for a component live in one file.
    • Maintainability: Changes to component logic only happen in one place.
    • Reduced File Count: Fewer files to manage in the sheets/ directory.
    /* ✅ Do this instead - single file with theme variables and nesting */
/* Eth0.css */
:root {
    /* file specific variables */
    --eth0-narrow-input-width: 188px;
    --eth0-narrow-input-padding: 5px 6px;
    --eth0-narrow-input-border-color: var(--border-color);
    --eth0-narrow-input-text-color: var(--text-color);
}

/* theme file specific variables */
.Theme--black, 
.Theme--white {
    --eth0-narrow-input-width: 166px;
    --eth0-narrow-input-padding: 4px 0;
}

.Theme--black {
    --eth0-narrow-input-border-color: var(--gray-100);
    --eth0-narrow-input-text-color: var(--gray-100);
}

.Theme--white {
    --eth0-narrow-input-border-color: var(--gray-900);
    --eth0-narrow-input-text-color: var(--gray-900);
}

input[type="text"].narrow {
    width: var(--eth0-narrow-input-width);
    padding: var(--eth0-narrow-input-padding);
    border: var(--eth0-narrow-input-border-color);
    color: var(--eth0-narrow-input-text-color);
}

/* Use nesting to override specific properties for groups of themes */
.Theme--black, 
.Theme--white {
    input[type="text"].narrow {
        border: none;
        border-bottom: 1px solid var(--eth0-narrow-input-border-color);
    }
}

  6. Interpret Array and Pool Device Status Indicators

    master

    Unraid uses colored status indicators to represent the state of devices in the Array or Pools. Use these to quickly identify device health and availability:

    Array Devices:

    • green-orb: Normal operation, device is active.
    • grey-orb: Device is in standby mode (spun-down).
    • yellow-orb: Device contents emulated.
    • red-orb: Device is disabled, contents emulated.
    • blue-orb: New device.
    • grey-orb (square): No device present, position is empty.

    Pool Devices:

    • green-orb: Normal operation, device is active.
    • grey-orb: Device is in standby mode (spun-down).
    • blue-orb: New device.
    • grey-orb (square): No device present, position is empty.

    Array Status (Overall):

    • green-orb: Array is Started and Parity is valid.
    • grey-orb: Array is Stopped, Parity is valid.
    • yellow-orb: Array is Started, but Parity is invalid.

  7. Understand the Dynamix Theme System architecture

    master

    The Dynamix theme system uses a layered approach with CSS variables (custom properties) to provide consistent styling across the Unraid webGUI. The system is composed of four core layers:

    1. Base Color Palette (default-color-palette.css): Defines fundamental color scales (e.g., --gray-100 to --gray-900) and opacity variants. This layer should be used as a source but not overridden.
    2. Base Styles (default-base.css): Provides foundational layout, typography, form elements, and responsive patterns. It also includes theme-specific modifiers like .Theme--sidebar.
    3. Theme Files (themes/*.css): Located in emhttp/plugins/dynamix/styles/themes/, these files (e.g., azure, black, gray, white) define specific color schemes by mapping theme-specific variables to the base color palette.
    4. Component Sheets (sheets/*.css): Located in emhttp/plugins/dynamix/styles/sheets/, these files define styles for specific features or utilities using the variables established in the previous layers.

  8. Use Docker Templates for container setup

    master

    Unraid uses two types of Docker templates:

    • Default templates: When valid repositories are added, they appear in a dropdown. Selecting one populates the page with instructions and configuration details. Use this for the first time you configure an application.
    • User-defined templates: Once a container is configured, settings are saved to the boot device. To rebuild a container (e.g., after an upgrade failure), select the application from the User-defined list to restore all previous settings. Clicking Create will redownload files and restore the working state.

  9. Understand the Unraid webgui repository structure

    master

    The Unraid webgui repository contains several key directories that are extracted to the /usr/local/ directory on an Unraid server during the build process. When working with the codebase, keep in mind that the following directories map to that location:

    • emhttp
    • etc
    • sbin
    • src

  10. Configure PCI Pass-through and System Devices

    master

    Unraid allows assigning hardware directly to Virtual Machines via IOMMU groups and driver binding.

    IOMMU Groups and PCI Pass-through

    • IOMMU Groups: Displays devices grouped by the hardware's IOMMU.
      • Warning: Selecting a device binds all devices in that same IOMMU group to the vfio-pci driver.
      • Symbols:
        • Green orb: Device is currently bound to vfio-pci.
        • Grey orb with arrows: Device supports FLR (Function Level Reset).
        • Greyed out checkbox: Device is in use by Unraid OS and cannot be passed through.
    • PCI Devices: You can view current/max speeds and widths. Orange text indicates downgraded speeds/widths.

    Other Hardware Assignment

    • USB Devices: View and configure via lsusb output.
    • SCSI Devices: View and configure via lsscsi output (includes ATA, SATA, and SAS).

  11. Configure WebGUI SSL/TLS and Access URLs

    master

    The Use SSL/TLS setting determines how the webGUI responds to HTTP and HTTPS requests.

    SettingBehavior
    NoUses HTTP only. Access via http://<server-name>.<localTLD> or http://<server-ip-address>.
    YesEnables an automatically-generated self-signed SSL certificate. Access via https://<server-name>.<localTLD>. Note: Browsers will show a warning.
    StrictEnables exclusive use of a myunraid.net SSL certificate. Access via https://<lan-ip>.<hash>.myunraid.net.

    DNS Rebinding Protection

    If using Strict mode, your router or ISP might block access due to DNS rebinding protection.

    • DD-WRT: Add rebind-domain-ok=/myunraid.net/ to the configuration.
    • pfSense: Add a custom option: server: private-domain: "myunraid.net".
    • Ubiquiti USG: Run set service dns forwarding options rebind-domain-ok=/myunraid.net/.
    • OpenDNS: Remove the checkbox for "Suspicious Responses - Block internal IP addresses".

  12. Set up Array Encryption

    master

    Encryption can be configured while the array is Stopped.

    Methods:

    • Passphrase: Enter a passphrase up to 512 characters. It is recommended to use only the 95 printable characters from the first 128 characters of the ASCII table to avoid encoding issues.
    • Keyfile: Upload a local keyfile or binary file (maximum size 8MB).

    CRITICAL WARNING: If you lose your passphrase or keyfile, the encrypted content cannot be recovered. Changing an encryption key requires reformatting the device, which results in permanent data loss.