Storage Sources

Storage sources connect Grail to your SMB file shares so the agent can discover and index media assets.

Adding a Storage Source

Open storage sources

In the Grail web app, navigate to Storage Sources and click Add Storage Source.
Select an agent

Choose which agent will scan this share. The agent must have network access to the SMB server.
Name the source

Give it a descriptive name like “Main NAS” or “Archive SAN”.
Configure the SMB connection
- SMB Host — The hostname or IP address of your file server (e.g., nas.church.local or 192.168.1.100)
- SMB Share — The share name (e.g., media)
- Base Path (optional) — A subfolder within the share to index (e.g., /Videos/2024). Leave empty to index the entire share. Grail normalizes leading and trailing slashes when saving the source.
- Username and Password — SMB credentials for the share (see SMB permissions below)
The full path is previewed below the fields (e.g., smb://nas.church.local/media/Videos/2024).

Click Test Connection to verify that the selected agent can reach the SMB share before saving. If the test fails, Grail shows recommendations and may offer suggested settings you can apply.
Choose a change detection mode
- Watch + Poll (recommended) — Real-time SMB change notifications for the configured share or base path, with scheduled polling as a backup. If real-time watching is unavailable, polling continues on schedule. Works with most NAS devices (Synology, QNAP).
- Poll Only — Scheduled polling without real-time notifications. Use this if your NAS doesn’t support SMB change notifications.
Set a scan schedule

Choose how often the agent performs a full scan of the share. Presets include every 6 hours, daily, or weekly. You can also enter a custom cron expression or disable scheduled scans entirely.

The default is daily at 2 AM.
Configure proxy generation and thumbnails
- On-Demand (NAS) (default, recommended) — Generate and cache proxies on the NAS with automatic eviction. Requires a proxy path pattern to define where proxies are stored (default: grail-proxies). The SMB credentials must have write access to this folder.
- On-Demand (Agent) — Generate and cache proxies locally on the agent
- Pregenerate — Generate preview proxies for all assets on discovery
For on-demand modes, set the max cache size (default 100 GB).

Pre-generate thumbnails is enabled by default. The agent generates thumbnail images for all discovered assets, providing visual previews in the asset browser. Disable this if you want to minimize agent processing.
Auto-transcribe

Auto-transcribe is enabled by default for new storage sources. It automatically queues transcription for video and audio files after they are discovered and hashed. This uses Whisper AI to generate searchable transcripts without manual intervention.

If enabled, you can add exclude patterns (regex) to skip specific files from auto-transcription. For example, use \.mp3$ to skip MP3 files or ^Music/ to skip a folder. Quick-add buttons are provided for common patterns.
Save

Click Create Storage Source. The source will appear in the grid but won’t start scanning until you trigger it.

Starting a Scan

After creating a storage source, an Admin can click Start Scan on the storage source card to begin indexing. The agent will discover files, generate thumbnails, and create preview proxies based on your configuration.

Subsequent scans run automatically based on your scan schedule.

If the agent cannot reach the configured share or base path, the scan will fail and the storage source card will show the latest mount error. Fix the path, credentials, or network access, then start another scan.

Storage Source Health

Storage source cards show separate health for the share mount and change detection:

Mount — Whether the agent can reach the configured SMB share and base path.
Detection — Whether real-time watching is active, or whether the source is using scheduled polling or polling fallback.

An Active source has a reachable mount and healthy detection. A Degraded source can still be partially usable, such as a reachable share with watcher issues. An Offline source cannot currently be reached by the assigned agent.

SMB Permissions

We recommend giving Grail read-only access to your media shares and read/write access to the proxy folder.

When using the On-Demand (NAS) proxy mode (recommended), the agent writes generated proxies to a folder on the NAS (default: grail-proxies). This is the only folder that requires read/write access. All other operations — scanning, indexing, thumbnail generation, and streaming — only need read access.

If your organization uses local people discovery, Grail also keeps face crops in this customer-controlled proxy storage instead of requiring a separate cloud image store.

Exclude Patterns

You can add regex patterns to exclude files from indexing. Common patterns include:

Pattern	Excludes
`^\.`	Hidden files (dotfiles)
`\.tmp$`	Temporary files
`\.DS_Store$`	macOS metadata
`Thumbs\.db$`	Windows thumbnails
`\._`	macOS resource forks

Add patterns in the Exclude Patterns section of the form using the quick-add buttons or by entering custom regex.

The built-in ignore list also applies during ongoing change detection and scheduled polling, so NAS recycle bins and vendor metadata folders should not keep re-triggering scans after the initial setup.

Editing a Storage Source

Admins can click a storage source card and select Edit to modify its configuration. When editing, credentials are preserved unless you check Update credentials and enter new ones.

Use Test Connection after changing the host, share, base path, agent, or credentials. When editing an existing source, you can test with the saved credentials unless you choose to update them.

When you toggle Pre-generate thumbnails or Auto-transcribe on an existing storage source, a confirmation dialog will ask how to handle existing assets:

Enabling — Choose to process all existing assets (backfill) or only apply to newly discovered assets going forward.
Disabling — Choose to cancel any pending jobs for that feature or let them finish.

Quantum StorNext Tiered Storage

Grail supports Quantum StorNext environments where files may move between resident disk storage and archive media. When enabled, Grail uses StorNext Web Services to check whether a file is currently resident before indexing or processing it.

Enabling StorNext Detection

Before enabling this in Grail, turn on StorNext Web Services V2 and HTTPS in the StorNext GUI, then create a Web Services user. Grail requires an https:// Web Services URL because StorNext sends the Web Services username and password as request query parameters. File, Read-Only permission is enough for detection. File, Read-Write is only needed if you later enable restore or archive actions.

Toggle Quantum StorNext Tiered Storage on the storage source form. When enabled:

Cold files are skipped — The agent detects archived/offline files and skips content-reading work. No thumbnails, proxies, or transcriptions are generated, and no tape recalls are triggered.
Resident files are processed normally — Files reported as DISK or DISK AND ARCHIVE are indexed and processed as available files.
Cold-to-hot transitions are detected — When a file is recalled from tape, the next scan detects the change and creates jobs for it automatically.

Configure a clean Web Services base URL such as https://stornext.example.com, the authentication mode, and one StorNext path prefix. Do not include credentials, query parameters, or fragments in this URL; Grail adds StorNext’s required credential query parameters only when it makes the request. Use User authentication when StorNext Web Services requires a username and password, or None when the endpoint is already trusted on your internal network.

TLS certificate verification is enabled by default. Enable the per-source self-signed certificate option only when the StorNext endpoint uses an internal certificate that the agent cannot otherwise verify.

For example, a StorNext path prefix of /stornext/example-volume/media checks source-relative files through that StorNext filesystem path. The agent detects the SMB source root; you do not need to configure a local SMB mount path.

StorNext path prefix: /stornext/example-volume/media

With that mapping, the source-relative scan path 2026/... is checked through Web Services as /stornext/example-volume/media/2026/....

How Archived Assets Appear

Assets that exist only on cold storage are marked with an archive indicator:

Asset browser — An archive icon is shown in place of the thumbnail
Asset detail page — An “Archived Asset” banner is displayed with a Restore from Archive button
Transcription — Disabled for cold-only assets

If StorNext reports that a file is resident on disk, Grail treats it as available even when the file also has archive copies. Grail does not show a separate archived-but-resident state.

Restoring Archived Assets

Restore and archive actions are separate opt-in settings and default off. When restore actions are enabled, Restore from Archive requests a StorNext Web Services restore for the selected file. Grail does not restore or archive files automatically.

Pausing StorNext for an Agent

StorNext connection behavior is managed on the agent that scans the source. From the agent’s settings, an Admin can pause StorNext requests for that agent — for example, if the StorNext appliance needs a break. While paused, Grail makes no StorNext Web Services calls for that agent’s sources: archived files stay protected (they are treated as unavailable rather than read from tape), while Grail-generated proxies and thumbnails keep serving normally. Turn the pause off to resume detection.