sterl/Homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f0c525d0df741e0b5c3b42fd9afe92628be21c47
Homelab/docs/guides/OMV_CLI_Setup_Guide.md

9.1 KiB
Raw Blame History

OMV Command-Line (CLI) Setup Guide for Docker Swarm

This guide provides the necessary commands to configure OpenMediaVault (OMV) from the CLI for user management and to apply service configurations. For creating shared folders and configuring NFS/SMB shares, the OpenMediaVault Web UI is the recommended and most robust approach to ensure proper integration with OMV's internal database.

Disclaimer: While these commands are effective, making configuration changes via the CLI can be less intuitive than the Web UI. Always ensure you have backups. It's recommended to have a basic understanding of the OMV configuration database.

Phase 1: Initial Setup (User and Filesystem Identification)

Step 1: Create the Swarm User

First, create a dedicated user for your Swarm mounts.

# Create the user 'swarm-user'
sudo useradd -m swarm-user

# Set a password for the new user (you will be prompted)
sudo passwd swarm-user

# Get the UID and GID for later use
id swarm-user
# Example output: uid=1001(swarm-user) gid=1001(swarm-user)

Step 2: Identify Your Storage Drive

You need the filesystem path for your storage drive. This is where the shared folders will be created.

# List mounted filesystems managed by OMV
sudo omv-show-fs

Look for your 512GB SSD and note its mount path (e.g., /srv/dev-disk-by-uuid-fd2daa6f-bd75-4ac1-9c4c-9e4d4b84d845). We will refer to this as YOUR_MOUNT_PATH for the rest of the guide.

Phase 2: Shared Folder and Service Configuration

For creating shared folders and configuring services, you have two primary methods: the OMV Web UI (recommended for most users) and the omv-rpc command-line tool (for advanced users or scripting).

Method 1: OMV Web UI (Recommended)

The safest and most straightforward way to configure OMV is through its web interface.

  1. Create Shared Folders: Navigate to Storage → Shared Folders and create the new folders required for the Swarm integration:

    • ImmichUploads
    • TraefikLetsEncrypt
    • ImmichDB
    • NextcloudDB
    • NextcloudApps
    • NextcloudConfig
    • NextcloudData
    • Media

  2. Configure Permissions: For each folder, set appropriate permissions:

    • Navigate to Storage → Shared Folders, select a folder, click Permissions
    • Add swarm-user with appropriate read/write permissions
    • For database folders, ensure proper ownership (typically root or specific service user)

  3. Configure Services:

    • For SMB: Navigate to Services → SMB/CIFS → Shares and create shares for folders that need SMB access
    • For NFS: Navigate to Services → NFS → Shares and create shares with appropriate client and privilege settings

Method 2: Advanced CLI Method (omv-rpc)

This is the correct and verified method for creating shared folders from the command line in OMV 6 and 7.

Step 3.1: Get the Storage UUID

First, you must get the internal UUID that OMV uses for your storage drive.

# List all filesystems and their properties known to OMV
sudo omv-rpc "FileSystemMgmt" "enumerateFilesystems" '{}'

From the JSON output, find the object where the devicefile or label matches your drive. Copy the uuid value from that object. It will be a long string like 7f450873-134a-429c-9198-097a5293209f.

Step 3.2: Create the Shared Folders (CLI)

IMPORTANT: The correct method for OMV 6+ uses the ShareMgmt service, not direct config manipulation.

# Set your storage UUID (replace with actual UUID from Step 3.1)
OMV_STORAGE_UUID="7f450873-134a-429c-9198-097a5293209f"

# Create shared folders using ShareMgmt service
sudo omv-rpc ShareMgmt setSharedFolder "{\"uuid\":\"$(uuidgen)\",\"name\":\"ImmichUploads\",\"mntentref\":\"${OMV_STORAGE_UUID}\",\"reldirpath\":\"ImmichUploads/\",\"comment\":\"Immich Uploads Storage\",\"permissions\":\"755\"}"

sudo omv-rpc ShareMgmt setSharedFolder "{\"uuid\":\"$(uuidgen)\",\"name\":\"TraefikLetsEncrypt\",\"mntentref\":\"${OMV_STORAGE_UUID}\",\"reldirpath\":\"TraefikLetsEncrypt/\",\"comment\":\"Traefik SSL Certificates\",\"permissions\":\"755\"}"

sudo omv-rpc ShareMgmt setSharedFolder "{\"uuid\":\"$(uuidgen)\",\"name\":\"ImmichDB\",\"mntentref\":\"${OMV_STORAGE_UUID}\",\"reldirpath\":\"ImmichDB/\",\"comment\":\"Immich Database Storage\",\"permissions\":\"700\"}"

sudo omv-rpc ShareMgmt setSharedFolder "{\"uuid\":\"$(uuidgen)\",\"name\":\"NextcloudDB\",\"mntentref\":\"${OMV_STORAGE_UUID}\",\"reldirpath\":\"NextcloudDB/\",\"comment\":\"Nextcloud Database Storage\",\"permissions\":\"700\"}"

sudo omv-rpc ShareMgmt setSharedFolder "{\"uuid\":\"$(uuidgen)\",\"name\":\"NextcloudApps\",\"mntentref\":\"${OMV_STORAGE_UUID}\",\"reldirpath\":\"NextcloudApps/\",\"comment\":\"Nextcloud Apps\",\"permissions\":\"755\"}"

sudo omv-rpc ShareMgmt setSharedFolder "{\"uuid\":\"$(uuidgen)\",\"name\":\"NextcloudConfig\",\"mntentref\":\"${OMV_STORAGE_UUID}\",\"reldirpath\":\"NextcloudConfig/\",\"comment\":\"Nextcloud Config\",\"permissions\":\"755\"}"

sudo omv-rpc ShareMgmt setSharedFolder "{\"uuid\":\"$(uuidgen)\",\"name\":\"NextcloudData\",\"mntentref\":\"${OMV_STORAGE_UUID}\",\"reldirpath\":\"NextcloudData/\",\"comment\":\"Nextcloud User Data\",\"permissions\":\"755\"}"

sudo omv-rpc ShareMgmt setSharedFolder "{\"uuid\":\"$(uuidgen)\",\"name\":\"Media\",\"mntentref\":\"${OMV_STORAGE_UUID}\",\"reldirpath\":\"Media/\",\"comment\":\"Media Files for Jellyfin\",\"permissions\":\"755\"}"

Step 3.3: Verify Shared Folders Were Created

# List all shared folders
sudo omv-rpc ShareMgmt getSharedFoldersList '{"start":0,"limit":25}'

# Or use the simpler command
omv-showkey conf.system.sharedfolder

Step 3.4: Set Folder Permissions (CLI)

After creating folders, set proper ownership and permissions on the actual directories:

# Replace with your actual mount path
MOUNT_PATH="/srv/dev-disk-by-uuid-fd2daa6f-bd75-4ac1-9c4c-9e4d4b84d845"

# Get swarm-user UID and GID (noted from Step 1)
SWARM_UID=1001  # Replace with actual UID
SWARM_GID=1001  # Replace with actual GID

# Set ownership for media folders
sudo chown -R ${SWARM_UID}:${SWARM_GID} "${MOUNT_PATH}/Media"
sudo chown -R ${SWARM_UID}:${SWARM_GID} "${MOUNT_PATH}/ImmichUploads"

# Database folders should be owned by root with restricted permissions
sudo chown -R root:root "${MOUNT_PATH}/ImmichDB"
sudo chown -R root:root "${MOUNT_PATH}/NextcloudDB"
sudo chmod 700 "${MOUNT_PATH}/ImmichDB"
sudo chmod 700 "${MOUNT_PATH}/NextcloudDB"

# Nextcloud folders should use www-data (UID 33, GID 33)
sudo chown -R 33:33 "${MOUNT_PATH}/NextcloudApps"
sudo chown -R 33:33 "${MOUNT_PATH}/NextcloudConfig"
sudo chown -R 33:33 "${MOUNT_PATH}/NextcloudData"

# Traefik folder
sudo chown -R root:root "${MOUNT_PATH}/TraefikLetsEncrypt"
sudo chmod 700 "${MOUNT_PATH}/TraefikLetsEncrypt"

Step 3.5: Configure NFS Shares (CLI)

Note: Configuring NFS shares via CLI is complex. The Web UI is strongly recommended. However, if needed:

# Get the shared folder UUIDs first
sudo omv-rpc ShareMgmt getSharedFoldersList '{"start":0,"limit":25}' | grep -A5 "ImmichDB"

# Example NFS share creation (requires the shared folder UUID)
# Replace SHAREDFOLDER_UUID with the actual UUID from above
sudo omv-rpc Nfs setShare "{\"uuid\":\"$(uuidgen)\",\"sharedfolderref\":\"SHAREDFOLDER_UUID\",\"client\":\"192.168.1.0/24\",\"options\":\"rw,sync,no_subtree_check,no_root_squash\",\"comment\":\"\"}"

This is error-prone. Use the Web UI for NFS/SMB configuration.

Phase 3: Apply Configuration Changes

Step 4: Apply All OMV Configuration Changes

After making all shared folder and service configurations, apply the changes:

# Apply shared folder configuration
sudo omv-salt deploy run sharedfolder

# Apply the SMB configuration (if SMB shares were configured)
sudo omv-salt deploy run samba

# Apply the NFS configuration (if NFS shares were configured)
sudo omv-salt deploy run nfs

# Apply general OMV configuration changes
sudo omv-salt deploy run phpfpm nginx

# Restart services to ensure all changes take effect
sudo systemctl restart nfs-kernel-server
sudo systemctl restart smbd

Step 5: Verify Services are Running

# Check NFS status
sudo systemctl status nfs-kernel-server

# Check SMB status
sudo systemctl status smbd

# List active NFS exports
sudo exportfs -v

# List SMB shares
sudo smbstatus --shares

Troubleshooting

Check OMV Logs

# General OMV logs
sudo journalctl -u openmediavault-engined -f

# NFS logs
sudo journalctl -u nfs-kernel-server -f

# SMB logs
sudo journalctl -u smbd -f

Verify Mount Points on Docker Nodes

After setting up OMV, verify that Docker nodes can access the shares:

# Test NFS mount
sudo mount -t nfs 192.168.1.70:/ImmichDB /mnt/test

# Test SMB mount
sudo mount -t cifs //192.168.1.70/Media /mnt/test -o credentials=/root/.smbcredentials

# Unmount test
sudo umount /mnt/test

Your OMV server is now fully configured to provide the necessary shares for your Docker Swarm cluster. You can now proceed with configuring the mounts on your Swarm nodes as outlined in the main OMV.md guide.

Reference in New Issue View Git Blame Copy Permalink