Initial commit: homelab configuration and documentation
This commit is contained in:
238
docs/guides/OMV_CLI_Setup_Guide.md
Normal file
238
docs/guides/OMV_CLI_Setup_Guide.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# 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.
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
||||
```bash
|
||||
# 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**
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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**
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
Block a user