Manila Shared Filesystem Troubleshooting Prompt
Diagnose Manila share issues — share stuck creating, access rules not applying, mount fails, backend (CephFS / NFS / GlusterFS) errors.
- Target user
- OpenStack engineers running Manila for shared filesystems
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT
The prompt
You are a senior OpenStack engineer who has run Manila with multiple backends — CephFS, generic (LVM-NFS), NetApp. You know that "mount fails" is usually access rules or network path, not the backend.
I will provide:
- The symptom (share stuck creating, mount fails, access rule rejected, share inconsistent across clients)
- `openstack share show <id>` and `openstack share access list`
- Backend type
- Manila logs
- Client-side mount attempt output
Your job:
1. **Verify backend**:
- `openstack share service list` — services up
- Manila API + Manila Share + Manila Scheduler
- Each backend uses a driver (cephfs, generic, etc.)
2. **For share stuck CREATING**:
- Scheduler couldn't pick a backend
- Driver failed during create — check `manila-share` log
- Quota issues
3. **For access rules**:
- **`ip`** rule: client IP / CIDR allowed
- **`user`** rule: e.g., Kerberos principal
- **`cert`** rule: TLS cert CN
- Rule must match what the client presents
- Adding a rule takes time (async); check rule's `state: active`
4. **For mount failures**:
- Network reach from client to share's export location
- Manila returns export location like `IP:/path` (NFS) or specific URL (CephFS)
- Verify with `mount -t nfs ...` manually
- For CephFS: use `mount.ceph` or kernel client
5. **For CephFS backend**:
- Auth: `share_metadata "ceph": {"user_id": "manila", ...}`
- Caps on the cephx user
- MDS active
- For native CephFS: kernel client OR ceph-fuse
6. **For NFS (generic backend)**:
- Manila spawns a service VM with NFS server
- Service VM accessible from client (via service network)
- NFS export visible
7. **For sec types**:
- `manila share-type-list`
- Type metadata controls driver behavior
- `dhss=true` means driver handles share servers (multi-tenant networks)
8. **For share replicas**:
- Replication across sites
- Promote replica to active
Mark DESTRUCTIVE: deleting share with data, removing all access rules (clients can't mount), force-deleting failed share (orphans backend resources).
---
Symptom: [DESCRIBE]
Backend: [cephfs / generic-LVM-NFS / NetApp / etc.]
`openstack share show <id>`:
```
[PASTE]
```
Access rules:
```
[PASTE `openstack share access list <id>`]
```
Manila logs:
```
[PASTE]
```
Client mount output:
```
[PASTE]
```
Why this prompt works
Manila debugging splits between API/scheduler issues, backend issues, and client mount issues. This prompt walks them.
How to use it
- Always include the backend type — drivers debug differently.
- Check access rules state —
creatingrules don’t enforce yet. - Test mount manually outside Manila to isolate.
- For CephFS, check cephx user.
Useful commands
# Shares
openstack share list
openstack share show <id>
openstack share access list <id>
# Create
openstack share create --name myshare nfs 10 --share-network <net-id>
# Access rules
openstack share access create <share-id> ip 10.0.0.0/24
openstack share access delete <share-id> <rule-id>
# Share types
openstack share type list
# Services
openstack share service list
# Manila logs
sudo journalctl -u manila-api -n 100 --no-pager
sudo journalctl -u manila-share -n 100 --no-pager
sudo journalctl -u manila-scheduler -n 100 --no-pager
# Test mount (NFS)
sudo mount -t nfs -o nfsvers=4.1 <export-ip>:/path /mnt/test
# Test CephFS mount
sudo mount -t ceph <mon-ip>:6789:/<path> /mnt/test \
-o name=manila,secret=<key>
# CephFS — check from Ceph side
sudo ceph fs status
sudo ceph auth get client.manila
sudo ceph mds stat
Common findings this catches
- Share creating > 10 min → driver error; check manila-share log.
- Access rule
state: error→ rule conflicts or backend rejection. - Mount succeeds for some clients, not others → access rule by IP/CIDR doesn’t cover all.
- CephFS mount fails “permission denied” → cephx user caps don’t match share’s path.
- NFS mount succeeds but I/O slow → MTU, network path, NFS version mismatch.
- Service VM for generic backend stuck → Nova/Neutron issue.
- Quota errors → manila share quota maxed; expand or release.
When to escalate
- Ceph cluster issues — engage storage team.
- Cross-backend migration at scale — staged plan.
- Vendor backend (NetApp, etc.) bugs — vendor support.
Related prompts
-
Ceph + OpenStack Integration Tuning Prompt
Tune Ceph as storage backend for OpenStack — Glance, Cinder, Nova ephemeral pools; performance tuning, capacity planning, snapshot/clone semantics.
-
Cinder Volume Troubleshooting Prompt
Diagnose stuck volumes, failed attachments, and backend issues (Ceph/LVM/iSCSI/NFS) in OpenStack Cinder using CLI output and service logs.
-
Neutron Networking Debug Prompt
Diagnose Neutron networking failures — unreachable VMs, broken security groups, missing floating IPs, OVS/OVN flow issues — from CLI output and agent logs.