nas
8.7 KB•MD
README.md
8.7 KB • 340 lines • markdown
1# NAS (Network Attached Storage) Ansible Role
2
3A comprehensive Ansible role for configuring and managing Network Attached Storage (NAS) servers with NFS exports, RAID monitoring, network bonding, and performance optimization.
4
5## Features
6
7- **NFS Server Configuration**: Complete NFS server setup with selective directory exports
8- **RAID Management**: mdadm RAID array creation, monitoring, and alerting
9- **Network Bonding**: Support for bonded network interfaces (LACP/802.3ad)
10- **Storage Management**: Automated mounting and filesystem management
11- **Performance Optimization**: Network and storage performance tuning
12- **Health Monitoring**: Comprehensive system health checks and alerting
13- **Security**: Secure NFS settings
14- **Backup Integration**: Automated configuration backups
15- **SMART Monitoring**: Disk health monitoring with smartmontools
16
17## Supported Platforms
18
19- **Debian**: 11 (Bullseye), 12 (Bookworm)
20- **Ubuntu**: 20.04 (Focal), 22.04 (Jammy), 24.04 (Noble)
21- **Red Hat Enterprise Linux**: 8, 9
22- **CentOS**: 8, 9, Stream
23
24## Requirements
25
26- Ansible 2.9 or higher
27- Root access (via sudo) on target hosts
28- Network connectivity between Ansible controller and target hosts
29
30## Role Variables
31
32### Basic NFS Configuration
33
34```yaml
35# Enable/disable NFS server
36nas_nfs_enabled: true
37
38# NFS exports configuration
39nas_nfs_exports:
40 - path: "/mnt/storage/shared"
41 clients: "192.168.1.0/24"
42 options: "rw,sync,no_subtree_check,no_root_squash"
43 - path: "/mnt/storage/media"
44 clients: "192.168.1.100(rw,sync) 192.168.1.101(ro,sync)"
45 options: "no_subtree_check"
46
47# Security settings
48nas_nfs_secure_ports: true
49nas_allowed_networks:
50 - "192.168.1.0/24"
51```
52
53### RAID Configuration
54
55```yaml
56# Enable RAID support
57nas_raid_enabled: true
58nas_raid_monitoring: true
59
60# RAID device configuration
61nas_raid_devices:
62 - device: "/dev/md0"
63 level: "raid5"
64 members:
65 - "/dev/sdb1"
66 - "/dev/sdc1"
67 - "/dev/sdd1"
68 mount_point: "/mnt/storage"
69 filesystem: "ext4"
70```
71
72### Network Bonding
73
74```yaml
75# Enable network bonding
76nas_network_bonding_enabled: true
77
78# Bond configuration
79nas_bond_interfaces:
80 - bond_name: "bond0"
81 mode: "802.3ad" # LACP
82 slaves:
83 - "eth0"
84 - "eth1"
85 ip: "192.168.1.100"
86 netmask: "255.255.255.0"
87 gateway: "192.168.1.1"
88```
89
90### Storage Mounts
91
92```yaml
93# Storage mount points
94nas_storage_mounts:
95 - device: "/dev/md0"
96 mount_point: "/mnt/storage"
97 filesystem: "ext4"
98 options: "defaults,noatime"
99 dump: 0
100 pass: 2
101 mode: "0755"
102 owner: "root"
103 group: "root"
104```
105
106### Performance Tuning
107
108```yaml
109# Enable performance optimizations
110nas_performance_tuning_enabled: true
111
112# Network performance settings
113nas_tcp_window_scaling: true
114nas_tcp_congestion_control: "bbr"
115
116# Custom sysctl settings
117nas_sysctl_settings:
118 net.core.rmem_max: 16777216
119 net.core.wmem_max: 16777216
120 vm.dirty_background_ratio: 5
121 vm.dirty_ratio: 10
122```
123
124### Monitoring and Alerting
125
126```yaml
127# Enable monitoring
128nas_monitoring_enabled: true
129nas_smartmontools_enabled: true
130
131# Email notifications for alerts
132nas_email_notifications: "[email protected]"
133
134```
135
136### Backup Integration
137
138```yaml
139# Enable backup of NAS configurations
140nas_backup_integration: true
141
142# Paths to include in backups
143nas_backup_paths:
144 - "/mnt/storage/critical"
145 - "/etc/exports"
146 - "/etc/mdadm/mdadm.conf"
147```
148
149## Example Playbooks
150
151### Basic NAS Server
152
153```yaml
154---
155- hosts: nas_servers
156 become: true
157 roles:
158 - role: nas
159 vars:
160 nas_nfs_enabled: true
161 nas_nfs_exports:
162 - path: "/srv/nfs/shared"
163 clients: "192.168.1.0/24"
164 options: "rw,sync,no_subtree_check"
165 nas_storage_mounts:
166 - device: "/dev/sdb1"
167 mount_point: "/srv/nfs/shared"
168 filesystem: "ext4"
169 options: "defaults,noatime"
170```
171
172### Advanced NAS with RAID5 and Bonding
173
174```yaml
175---
176- hosts: advanced_nas
177 become: true
178 roles:
179 - role: nas
180 vars:
181 # NFS Configuration
182 nas_nfs_enabled: true
183 nas_nfs_exports:
184 - path: "/mnt/raid/shared"
185 clients: "192.168.1.0/24"
186 options: "rw,sync,no_subtree_check,no_root_squash"
187 - path: "/mnt/raid/media"
188 clients: "192.168.1.0/24"
189 options: "ro,sync,no_subtree_check"
190
191 # RAID Configuration
192 nas_raid_enabled: true
193 nas_raid_monitoring: true
194 nas_raid_devices:
195 - device: "/dev/md0"
196 level: "raid5"
197 members:
198 - "/dev/sdb"
199 - "/dev/sdc"
200 - "/dev/sdd"
201 mount_point: "/mnt/raid"
202 filesystem: "ext4"
203
204 # Network Bonding
205 nas_network_bonding_enabled: true
206 nas_bond_interfaces:
207 - bond_name: "bond0"
208 mode: "802.3ad"
209 slaves:
210 - "enp1s0"
211 - "enp2s0"
212 ip: "192.168.1.100"
213 netmask: "255.255.255.0"
214 gateway: "192.168.1.1"
215
216 # Monitoring
217 nas_monitoring_enabled: true
218 nas_email_notifications: "[email protected]"
219 nas_performance_tuning_enabled: true
220
221 # Security
222 nas_allowed_networks:
223 - "192.168.1.0/24"
224 - "10.0.0.0/8"
225```
226
227## Directory Structure
228
229```
230roles/nas/
231âââ README.md
232âââ defaults/
233â âââ main.yml # Default variables
234âââ handlers/
235â âââ main.yml # Service handlers
236âââ meta/
237â âââ main.yml # Role metadata
238âââ tasks/
239â âââ main.yml # Main task orchestration
240â âââ backup.yml # Backup configuration
241â âââ bonding.yml # Network bonding setup
242â âââ monitoring.yml # Health monitoring setup
243â âââ mounts.yml # Storage mounting
244â âââ nfs.yml # NFS server configuration
245â âââ performance.yml # Performance tuning
246â âââ raid.yml # RAID management
247âââ templates/
248â âââ bond-interface.j2 # Bond interface config
249â âââ bond-network.j2 # Bond network config
250â âââ bond-slave.j2 # Bond slave config
251â âââ collect-nas-info.sh.j2 # System info script
252â âââ exports.j2 # NFS exports file
253â âââ mdadm-monitor.j2 # RAID monitoring config
254â âââ nas-backup.sh.j2 # Backup script
255â âââ nas-logrotate.j2 # Log rotation config
256â âââ nas-monitor.sh.j2 # Health monitoring script
257â âââ nas-performance-monitor.sh.j2 # Performance monitoring
258â âââ smartd.conf.j2 # SMART monitoring config
259âââ vars/
260 âââ main.yml # Internal variables
261```
262
263## Monitoring and Maintenance
264
265The role sets up several monitoring mechanisms:
266
267### Health Monitoring
268- **Script**: `/usr/local/bin/nas-monitor.sh`
269- **Frequency**: Every 10 minutes (configurable)
270- **Monitors**: RAID status, NFS services, disk space, network bonds
271
272### Performance Monitoring
273- **Script**: `/usr/local/bin/nas-performance-monitor.sh`
274- **Frequency**: Every 5 minutes (configurable)
275- **Monitors**: Network throughput, disk I/O, NFS statistics, memory usage
276
277### Configuration Backups
278- **Script**: `/usr/local/bin/nas-backup.sh`
279- **Frequency**: Daily at 2 AM
280- **Backs up**: NFS exports, RAID config, fstab, network configuration
281
282### Log Files
283- **Main log**: `/var/log/nas-role.log`
284- **System info**: `/var/log/nas-system-info.txt`
285- **Rotation**: Configured via logrotate
286
287## Troubleshooting
288
289### Common Issues
290
2911. **NFS exports not accessible**
292 - Verify exports: `exportfs -v`
293 - Test connectivity: `showmount -e <nas_ip>`
294
2952. **RAID array degraded**
296 - Check status: `cat /proc/mdstat`
297 - View details: `mdadm --detail /dev/md0`
298 - Monitor logs: `tail -f /var/log/nas-role.log`
299
3003. **Network bond issues**
301 - Check bond status: `cat /proc/net/bonding/bond0`
302 - Verify interface states: `ip link show`
303 - Review network config: `networkctl status`
304
305### Log Analysis
306
307```bash
308# Monitor NAS health in real-time
309tail -f /var/log/nas-role.log
310
311# Check RAID events
312journalctl -u mdmonitor -f
313
314# Monitor NFS activity
315journalctl -u nfs-kernel-server -f
316
317# Check network interface status
318journalctl -u systemd-networkd -f
319```
320
321## Dependencies
322
323This role has no external role dependencies but requires the following system packages (automatically installed):
324
325- `nfs-kernel-server` / `nfs-utils`
326- `nfs-common`
327- `mdadm`
328- `smartmontools`
329- `hdparm`
330- `ifenslave` (for bonding on Debian/Ubuntu)
331
332## License
333
334MIT
335
336## Author Information
337
338Created for personal homelab automation. Contributions and feedback welcome.
339
340For issues or feature requests, please check the project documentation or contact the homelab administrator.