From 6ad192fa9cda6d16174773100133a57e4f6173f8 Mon Sep 17 00:00:00 2001 From: Chris Lu Date: Sun, 6 Jul 2025 22:33:17 -0700 Subject: [PATCH] Created Admin UI (markdown) --- Admin-UI.md | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 Admin-UI.md diff --git a/Admin-UI.md b/Admin-UI.md new file mode 100644 index 0000000..3d468e2 --- /dev/null +++ b/Admin-UI.md @@ -0,0 +1,202 @@ +# Weed Admin + +The `weed admin` command starts a modern web-based administration interface for SeaweedFS cluster management. + +## Overview + +The admin interface provides a comprehensive web UI for managing SeaweedFS clusters, including: +- **Cluster topology visualization and monitoring** +- **Volume management and operations** +- **File browser and management** +- **System metrics and performance monitoring** +- **Configuration management** +- **Maintenance operations** + +The admin interface automatically discovers filers from the master servers and runs a gRPC server for worker connections on HTTP port + 10000. + +## Usage + +```bash +weed admin [options] +``` + +## Options + +| Option | Default | Description | +|--------|---------|-------------| +| `-port` | 23646 | Admin server port | +| `-masters` | localhost:9333 | Comma-separated master servers | +| `-dataDir` | "" | Directory to store admin configuration and data files | +| `-adminUser` | admin | Admin interface username | +| `-adminPassword` | "" | Admin interface password (if empty, auth is disabled) | + +## Examples + +### Basic Usage + +```bash +# Start admin interface on default port (23646) +weed admin -masters=localhost:9333 + +# Start with custom port and multiple masters +weed admin -port=8080 -masters="master1:9333,master2:9333" + +# Start with specific data directory +weed admin -port=23646 -masters="localhost:9333" -dataDir="/var/lib/seaweedfs-admin" + +# Start with home directory expansion +weed admin -port=23646 -masters="localhost:9333" -dataDir="~/seaweedfs-admin" +``` + +### With Authentication + +```bash +# Enable authentication +weed admin -adminUser=admin -adminPassword=secret123 -masters="localhost:9333" +``` + +### Production Deployment + +```bash +# Production setup with data persistence and authentication +weed admin \ + -port=23646 \ + -masters="master1:9333,master2:9333,master3:9333" \ + -dataDir="/var/lib/seaweedfs-admin" \ + -adminUser=admin \ + -adminPassword=strongpassword123 +``` + +## Data Directory + +The data directory (`-dataDir`) is used to persist admin configuration and maintenance data: + +- **If specified**: Configuration and data are persisted to disk +- **If not specified**: All configuration is kept in memory only +- **Path expansion**: Supports tilde (`~`) expansion for home directory +- **Auto-creation**: Directory is automatically created if it doesn't exist +- **Format**: Configuration files are stored in JSON format for easy editing + +## Security and Authentication + +### Authentication + +- **Disabled by default**: If `-adminPassword` is not set, no authentication is required +- **Session-based**: When enabled, uses secure session management with auto-generated session keys +- **User credentials**: Login with `-adminUser` and `-adminPassword` + +### TLS/HTTPS Configuration + +The admin server reads TLS configuration from `security.toml`: + +```toml +[https.admin] +cert = "/etc/ssl/admin.crt" +key = "/etc/ssl/admin.key" +ca = "/etc/ssl/ca.crt" # optional, for mutual TLS +``` + +- **HTTPS**: Automatically enabled if `https.admin.key` is configured +- **Mutual TLS**: Enabled if `https.admin.ca` is configured +- **Certificate loading**: Certificates are loaded from the security configuration + +### Security Best Practices + +1. **Set strong passwords**: Use strong `-adminPassword` for production +2. **Configure TLS**: Use HTTPS for production deployments +3. **Firewall rules**: Restrict admin interface access to authorized networks +4. **Regular updates**: Keep SeaweedFS updated for security patches + +## Worker Communication + +The admin server also runs a gRPC server for worker connections: + +- **Port**: HTTP port + 10000 (e.g., if admin runs on 23646, gRPC runs on 33646) +- **Purpose**: Handles maintenance worker connections and task distribution +- **TLS**: Uses `[grpc.admin]` configuration from `security.toml` +- **Fallback**: Workers fall back to insecure connections if TLS is unavailable + +## Configuration File + +The admin server reads configuration from `security.toml` in the following order: +1. Current directory (`.`) +2. `$HOME/.seaweedfs/` +3. `/usr/local/etc/seaweedfs/` +4. `/etc/seaweedfs/` + +### Generate Example Configuration + +```bash +# Generate example security.toml +weed scaffold -config=security +``` + +## Features + +### Automatic Service Discovery + +- **Master discovery**: Connects to specified master servers +- **Filer discovery**: Automatically discovers filers from masters +- **Health monitoring**: Monitors cluster health and status + +### Web Interface + +- **Modern UI**: Bootstrap-based responsive design +- **Real-time updates**: Live cluster status and metrics +- **File management**: Browse and manage files through web interface +- **Maintenance operations**: Execute maintenance tasks from the UI + +### API Endpoints + +The admin interface provides RESTful API endpoints for: +- Cluster status and topology +- Volume management +- File operations +- System metrics +- Configuration management + +## Troubleshooting + +### Common Issues + +1. **No filers discovered**: + - Check master server connectivity + - Verify master addresses are correct + - Ensure masters are running and accessible + +2. **Authentication not working**: + - Verify `-adminPassword` is set correctly + - Check session cookie settings + - Clear browser cache and cookies + +3. **TLS/HTTPS issues**: + - Verify certificate paths in `security.toml` + - Check certificate validity and permissions + - Ensure certificates are in PEM format + +4. **Worker connections failing**: + - Check if gRPC port (HTTP port + 10000) is accessible + - Verify TLS configuration for worker connections + - Check firewall rules for gRPC port + +### Debug Information + +Enable debug logging for detailed troubleshooting: + +```bash +# Run with verbose logging +weed admin -v=4 -masters="localhost:9333" +``` + +## Related Commands + +- [`weed worker`](Weed-Worker.md): Start maintenance workers that connect to admin +- [`weed master`](https://github.com/seaweedfs/seaweedfs/wiki/Master-Server): Start master servers +- [`weed filer`](https://github.com/seaweedfs/seaweedfs/wiki/Filer-Server): Start filer servers +- [`weed scaffold`](https://github.com/seaweedfs/seaweedfs/wiki/Scaffold): Generate configuration files + +## See Also + +- [SeaweedFS Architecture](https://github.com/seaweedfs/seaweedfs/wiki/SeaweedFS-Architecture) +- [Security Configuration](https://github.com/seaweedfs/seaweedfs/wiki/Security-Configuration) +- [Maintenance Operations](https://github.com/seaweedfs/seaweedfs/wiki/Maintenance) \ No newline at end of file