# 14: Webmin - System Administration Platform

Webmin provides a web-based system administration interface for Linux servers. It offers user management, service control, file system access, package management, network configuration, and system monitoring through a unified web UI. For module documentation, API details, and advanced configuration, see the [official Webmin documentation](https://webmin.com/documentation.html).

## Prerequisites

- ✅ **Docker installed** (Chapter 3)
- ✅ **Docker Compose** (Chapter 3)
- ✅ **Optional: Traefik installed** (Chapter 4) for HTTPS with Let's Encrypt
- ✅ **Optional: Domain configured** (Chapter 4.5), e.g., `webmin.example.com`

## Installation via Infinity Tools

### Menu Installation

```
📱 APPLICATIONS → Webmin → Install
```

### CLI Installation

```
sudo bash /opt/InfinityTools/Solutions/setup-webmin.sh --install

# With domain (Traefik mode)
export WEBMIN_USE_TRAEFIK=true
export WEBMIN_DOMAIN="webmin.example.com"
sudo -E bash /opt/InfinityTools/Solutions/setup-webmin.sh --install

# With host filesystem access (read-only)
export WEBMIN_HOST_ACCESS=readonly
sudo -E bash /opt/InfinityTools/Solutions/setup-webmin.sh --install

# With host filesystem access (read-write)
export WEBMIN_HOST_ACCESS=readwrite
sudo -E bash /opt/InfinityTools/Solutions/setup-webmin.sh --install

# Custom port (standalone mode)
sudo bash /opt/InfinityTools/Solutions/setup-webmin.sh --install 9443
```

## Deployment Modes

### Traefik Mode

Uses Traefik for SSL termination and domain routing:

- Automatic Let's Encrypt certificate provisioning
- Domain-based access: `https://webmin.example.com`
- Direct web access (no SSH tunnel required)
- Requires: Traefik running, DNS A record configured

### Standalone Mode (Recommended)

Direct HTTPS access with self-signed certificate, accessed via SSH tunnel:

- Access via: `https://localhost:8443` (after SSH tunnel)
- SSH tunnel command: `ssh -L 8443:localhost:10000 user@server`
- Self-signed SSL (browser warning on first access)
- More secure (not directly exposed to internet)
- Default port: 8443 (configurable)

## Host Filesystem Access Configuration

During installation, you'll be prompted for host filesystem access level:

- **None (default)** - Container filesystem only, no host access
- **Read-Only** - Host filesystem mounted at `/host/` (read-only)
- **Read-Write** - Host filesystem mounted at `/host/` (full access)

**Volume Mount:**

- Read-Only: `- /:/host:ro`
- Read-Write: `- /:/host`

## Installation Process

### Configuration Steps

1. **SSL Mode Selection:** Choose Traefik or Standalone
2. **If Traefik:** Provide domain name
3. **If Standalone:** Specify HTTPS port (default: 8443)
4. **Host Access:** Choose filesystem access level
5. **User Creation:** System user `webminadmin` created with random password

### What Gets Created

- **Directory:** `/opt/speedbits/webmin`
- **Container:** `webmin` (johanp/webmin:latest)
- **Volumes:** `webmin-config`, `webmin-logs`
- **Docker Compose:** `/opt/speedbits/webmin/docker-compose.yml`
- **System User:** `webminadmin` with sudo privileges
- **Network:** Joins Traefik network (Traefik mode) or creates internal network (Standalone)

## Access Methods

### Traefik Mode

```
https://webmin.example.com
```

Direct web access after DNS propagation and SSL certificate generation (30-60 seconds).

### Standalone Mode (SSH Tunnel)

**On local machine:**

```
ssh -L 8443:localhost:10000 user@server-ip
```

**Then in browser:**

```
https://localhost:8443
```

Accept self-signed certificate warning (Advanced → Proceed).

### Alternative: Direct Container IP

```
# Get container IP
CONTAINER_IP=$(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' webmin)

# SSH tunnel to container IP
ssh -L 8443:$CONTAINER_IP:10000 user@server-ip
```

## Authentication

### Default Credentials

- **Username:** `webminadmin`
- **Password:** Randomly generated (shown once during installation)

**⚠️ CRITICAL:** Password is displayed only once. Save it immediately!

### System Authentication

- Any user in `sudo` or `wheel` group can login
- Uses system `/etc/passwd`, `/etc/shadow`, `/etc/group`
- Container runs as root with privileged access
- PAM authentication configured (can be disabled for internal password file)

## File Manager: Container vs Host Filesystem

**⭐ CRITICAL:** Webmin's File Manager initially shows the container's filesystem, not the host system.

### Accessing Host Files

1. Navigate to **Other** → **File Manager**
2. You'll see container filesystem (minimal, typically empty)
3. **To access host:** Type `/host/` in the path bar
4. Press Enter or click "Go"
5. Host filesystem is now accessible

### Path Mapping

- **Container root:** `/` (Webmin container filesystem)
- **Host root:** `/host/` (mounted host filesystem)

### Common Host Paths

- `/host/etc/` - Host system configuration
- `/host/home/` - Host user home directories
- `/host/opt/` - Host application data (Infinity Tools, Speedbits)
- `/host/var/log/` - Host system logs
- `/host/var/www/` - Host web directories

### Access Level Behavior

- **Read-Only:** Can browse `/host/` but cannot modify files
- **Read-Write:** Full access to `/host/` (create, edit, delete)
- **None:** `/host/` directory doesn't exist

## Key Features

### System Administration

- User and group management
- Service management (systemd units)
- Package management (apt/yum)
- System information and monitoring
- Log file viewing

### File Management

- Web-based file browser
- Text editor for configuration files
- File upload/download
- Permission management
- **Note:** Use `/host/` path for host filesystem access

### Network Configuration

- Network interface configuration
- Firewall rules (iptables/ufw)
- DNS configuration
- Port forwarding

## Security Configuration

### Access Security

- ✅ SSH tunnel recommended for standalone mode (not directly exposed)
- ✅ Traefik mode uses Let's Encrypt SSL (production-ready)
- ✅ Self-signed certificate in standalone mode (acceptable for tunneled access)
- ✅ System authentication via PAM or internal password file

### Filesystem Security

- **Read-Only:** Safe for viewing host files without modification risk
- **Read-Write:** Full access - use with caution, audit changes
- **None:** Most secure - container filesystem only

### Container Security

- Container runs as root (required for system management)
- Privileged mode enabled (required for system access)
- Mounts host user databases (passwd, shadow, group)
- Optional host filesystem mount

## Configuration Persistence

- **Config Volume:** `webmin-config` persists Webmin settings
- **Logs Volume:** `webmin-logs` persists log files
- **Data Directory:** `/opt/speedbits/webmin` contains docker-compose.yml
- All settings survive container restarts

## Troubleshooting

### Container Not Starting

```
docker logs webmin
docker ps -a | grep webmin
```

### Authentication Issues

- Verify user exists: `docker exec webmin grep webminadmin /etc/passwd`
- Check sudo group: `groups webminadmin`
- Verify password file: `docker exec webmin cat /etc/webmin/miniserv.users`
- Restart container: `docker restart webmin`

### File Manager Issues

- **Can't see host files:** Navigate to `/host/` in path bar
- **/host/ doesn't exist:** Host access was set to "None" during installation
- **Read-only errors:** Host access was set to "Read-Only"
- **To change access:** Reinstall with different `WEBMIN_HOST_ACCESS` setting

### SSH Tunnel Issues

- Verify SSH access: `ssh user@server-ip`
- Check port matches installation: Default is 8443
- Try container IP: `ssh -L 8443:CONTAINER_IP:10000 user@server`
- Verify Webmin is running: `docker ps | grep webmin`

### Traefik Routing Issues

- Verify Traefik is running: `docker ps | grep traefik`
- Check DNS resolution: `dig webmin.example.com`
- Verify SSL certificate: Check Traefik logs
- Wait 30-60 seconds after installation for certificate generation

## Production Considerations

- **Access Method:** SSH tunnel (standalone) is more secure than direct web access
- **Filesystem Access:** Use "Read-Only" unless file editing is required
- **Password Management:** Store credentials in password manager (Vaultwarden)
- **User Management:** Create separate Webmin users for team members
- **Audit Logging:** Monitor Webmin access logs for security
- **Backup:** Backup Webmin configuration volume regularly

## Integration with Infinity Tools

Webmin complements Infinity Tools by providing:

- Visual system administration alongside containerized applications
- File management for host system (via `/host/` mount)
- User management for system users
- Service monitoring and management

**Note:** Infinity Tools applications run in Docker containers. Webmin provides host system management. Use Portainer (Chapter 13) for Docker container management.

## Next Steps

Webmin is now operational. Use it to:

- Manage system users and permissions
- Browse and edit host filesystem (remember `/host/` path!)
- Monitor system resources
- Configure system services
- View system logs

For advanced Webmin features, module development, and enterprise capabilities, refer to the [official Webmin documentation](https://webmin.com/documentation.html).