MCP SSH Orchestrator

# 6.1 servers.yml **Purpose:** Define your SSH host inventory, network settings, and host metadata for mcp-ssh-orchestrator. ## Overview The `servers.yml` file defines the **host inventory** that mcp-ssh-orchestrator can manage. It specifies SSH connection details, host metadata, and network configuration for each target host. ## File Structure ```yaml # servers.yml hosts: - alias: "web1" host: "10.0.0.11" port: 22 credentials: "prod_admin" tags: - "production" - "web" - "linux" - alias: "db1" host: "10.0.0.21" port: 22 credentials: "prod_admin" tags: - "production" - "database" - "linux" ``` ## Configuration Fields ### Required Fields | Field | Type | Description | Example | |-------|------|-------------|---------| | `alias` | string | Unique identifier for the host | `"web1"` | | `host` | string | IP address or hostname | `"10.0.0.11"` | | `credentials` | string | Reference to credentials.yml entry | `"prod_admin"` | ### Optional Fields | Field | Type | Default | Description | Example | |-------|------|---------|-------------|---------| | `port` | integer | `22` | SSH port number | `2222` | | `tags` | array | `[]` | Host categorization tags | `["prod", "web"]` | | `description` | string | `""` | Human-readable description | `"Production web server"` | ## Host Aliases ### Alias Naming Conventions **Recommended patterns:** - **Environment-Purpose-Number**: `prod-web-1`, `staging-db-2` - **Purpose-Environment-Number**: `web-prod-1`, `db-staging-2` - **Location-Purpose-Number**: `us-east-web-1`, `eu-west-db-1` **Examples:** ```yaml hosts: - alias: "prod-web-1" # Production web server 1 - alias: "staging-db-1" # Staging database 1 - alias: "dev-monitor-1" # Development monitoring 1 - alias: "us-east-api-1" # US East API server 1 ``` ### Alias Usage in Policies Aliases are used in policy rules for host targeting: ```yaml # policy.yml rules: - action: "allow" aliases: ["prod-*"] # All production hosts commands: ["uptime*"] - action: "allow" aliases: ["*web*"] # All web servers commands: ["systemctl status nginx*"] ``` ## Host Configuration ### Basic Host Definition ```yaml hosts: - alias: "web1" host: "10.0.0.11" port: 22 credentials: "prod_admin" tags: ["production", "web"] description: "Primary web server" ``` ### Multiple Hosts ```yaml hosts: - alias: "web1" host: "10.0.0.11" credentials: "prod_admin" tags: ["production", "web"] - alias: "web2" host: "10.0.0.12" credentials: "prod_admin" tags: ["production", "web"] - alias: "db1" host: "10.0.0.21" credentials: "prod_admin" tags: ["production", "database"] ``` ### Non-Standard SSH Ports ```yaml hosts: - alias: "bastion" host: "10.0.0.1" port: 2222 credentials: "bastion_admin" tags: ["bastion", "security"] - alias: "legacy-server" host: "10.0.0.100" port: 2200 credentials: "legacy_admin" tags: ["legacy", "maintenance"] ``` ## Host Tags ### Tag Categories **Environment Tags:** - `production` - Production environment - `staging` - Staging environment - `development` - Development environment - `testing` - Testing environment **Service Tags:** - `web` - Web servers - `database` - Database servers - `cache` - Cache servers - `monitoring` - Monitoring servers - `bastion` - Bastion/jump hosts **Infrastructure Tags:** - `linux` - Linux operating system - `windows` - Windows operating system - `docker` - Docker-enabled hosts - `kubernetes` - Kubernetes nodes **Security Tags:** - `pci` - Tags hosts requiring PCI-DSS security controls - `hipaa` - Tags hosts requiring HIPAA security controls - `soc2` - Tags hosts requiring SOC 2 security controls - `critical` - Critical infrastructure requiring enhanced monitoring ### Tag Usage Examples ```yaml hosts: # Production web servers - alias: "prod-web-1" host: "10.0.0.11" credentials: "prod_admin" tags: ["production", "web", "linux", "critical"] # Staging database - alias: "staging-db-1" host: "10.0.1.21" credentials: "staging_admin" tags: ["staging", "database", "linux"] # Development monitoring - alias: "dev-monitor-1" host: "192.168.1.100" credentials: "dev_admin" tags: ["development", "monitoring", "linux"] ``` ### Tag-Based Policy Rules ```yaml # policy.yml rules: # Production hosts - strict policies - action: "allow" tags: ["production"] commands: ["uptime*", "df -h*", "systemctl status *"] # Web servers - web-specific commands - action: "allow" tags: ["web"] commands: ["nginx -t*", "apache2ctl status*"] # Development hosts - permissive policies - action: "allow" tags: ["development"] commands: ["*"] # Allow all commands ``` ## Network Configuration ### IP Address Formats **IPv4 Addresses:** ```yaml hosts: - alias: "web1" host: "10.0.0.11" # IPv4 address credentials: "prod_admin" ``` **Hostnames:** ```yaml hosts: - alias: "web1" host: "web1.example.com" # Hostname (resolved via DNS) credentials: "prod_admin" ``` **IPv6 Addresses:** ```yaml hosts: - alias: "web1" host: "2001:db8::1" # IPv6 address credentials: "prod_admin" ``` ### Network Security Considerations **Private Networks (Recommended):** ```yaml hosts: - alias: "web1" host: "10.0.0.11" # RFC 1918 private credentials: "prod_admin" - alias: "web2" host: "192.168.1.11" # RFC 1918 private credentials: "prod_admin" - alias: "web3" host: "172.16.0.11" # RFC 1918 private credentials: "prod_admin" ``` **Public Networks (Use with caution):** ```yaml hosts: - alias: "bastion" host: "203.0.113.1" # Public IP (bastion host) credentials: "bastion_admin" tags: ["bastion", "public"] ``` ## Credential References ### Referencing Credentials Each host must reference a credential entry from `credentials.yml`: ```yaml # servers.yml hosts: - alias: "web1" host: "10.0.0.11" credentials: "prod_admin" # References credentials.yml # credentials.yml entries: - name: "prod_admin" # Must match servers.yml reference username: "ubuntu" key_path: "id_ed25519" ``` ### Multiple Credential Types ```yaml hosts: # Key-based authentication - alias: "web1" host: "10.0.0.11" credentials: "prod_admin" # Password-based authentication - alias: "legacy-server" host: "10.0.0.100" credentials: "legacy_password" # Different users per host - alias: "db1" host: "10.0.0.21" credentials: "db_admin" ``` ## Environment-Specific Configurations ### Development Environment ```yaml # servers.yml - Development hosts: - alias: "dev-web-1" host: "192.168.1.10" port: 22 credentials: "dev_admin" tags: ["development", "web", "linux"] description: "Development web server" - alias: "dev-db-1" host: "192.168.1.20" port: 22 credentials: "dev_admin" tags: ["development", "database", "linux"] description: "Development database" ``` ### Staging Environment ```yaml # servers.yml - Staging hosts: - alias: "staging-web-1" host: "10.0.1.10" port: 22 credentials: "staging_admin" tags: ["staging", "web", "linux"] description: "Staging web server" - alias: "staging-db-1" host: "10.0.1.20" port: 22 credentials: "staging_admin" tags: ["staging", "database", "linux"] description: "Staging database" ``` ### Production Environment ```yaml # servers.yml - Production hosts: - alias: "prod-web-1" host: "10.0.0.10" port: 22 credentials: "prod_admin" tags: ["production", "web", "linux", "critical"] description: "Primary production web server" - alias: "prod-web-2" host: "10.0.0.11" port: 22 credentials: "prod_admin" tags: ["production", "web", "linux", "critical"] description: "Secondary production web server" - alias: "prod-db-1" host: "10.0.0.20" port: 22 credentials: "prod_admin" tags: ["production", "database", "linux", "critical"] description: "Primary production database" ``` ## Validation and Testing ### Configuration Validation ```bash # Validate servers.yml syntax python -c "import yaml; yaml.safe_load(open('config/servers.yml'))" # Validate credential references python -c " from mcp_ssh.config import Config config = Config('config/') for host in config.list_hosts(): print(f'{host}: {config.get_host(host).credentials}') " ``` ### Host Connectivity Testing ```bash # Test SSH connectivity ssh -i keys/id_ed25519 ubuntu@10.0.0.11 "echo 'Connection successful'" # Test via mcp-ssh-orchestrator ssh_ping # Health check ssh_list_hosts # List configured hosts ssh_describe_host --alias "web1" # Get host details ``` ### Policy Testing ```bash # Test policy rules for specific hosts ssh_plan --alias "web1" --command "uptime" ssh_plan --alias "prod-web-1" --command "systemctl status nginx" ``` ## Best Practices ### Host Organization 1. **Use consistent naming conventions** 2. **Group related hosts with tags** 3. **Separate environments clearly** 4. **Document host purposes** ### Security Practices 1. **Use private IP addresses when possible** 2. **Reference credentials by name, not inline** 3. **Use descriptive tags for policy targeting** 4. **Keep host descriptions up to date** ### Operational Practices 1. **Validate configuration before deployment** 2. **Test connectivity after changes** 3. **Use version control for configuration** 4. **Document network topology** ## Troubleshooting ### Common Issues 1. **Invalid YAML syntax** ```bash # Check syntax python -c "import yaml; yaml.safe_load(open('config/servers.yml'))" ``` 2. **Missing credential references** ```bash # Check references python -c " from mcp_ssh.config import Config config = Config('config/') print('Missing credentials:', config.validate_credentials()) " ``` 3. **Duplicate aliases** ```bash # Check for duplicates grep -o 'alias: "[^"]*"' config/servers.yml | sort | uniq -d ``` ### Network Issues 1. **Host unreachable** ```bash # Test connectivity ping 10.0.0.11 telnet 10.0.0.11 22 ``` 2. **SSH connection refused** ```bash # Check SSH service ssh -v ubuntu@10.0.0.11 ``` ## Next Steps - **[credentials.yml](06.2-credentials.yml)** - SSH authentication configuration - **[policy.yml](06.3-policy.yml)** - Security policy configuration - **[Usage Cookbook](08-Usage-Cookbook)** - Practical configuration examples - **[Troubleshooting](12-Troubleshooting)** - Common configuration issues