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

# 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:

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:

# 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

hosts:
  - alias: "web1"
    host: "10.0.0.11"
    port: 22
    credentials: "prod_admin"
    tags: ["production", "web"]
    description: "Primary web server"

Multiple Hosts

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

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:

• critical - Critical infrastructure requiring enhanced monitoring
• restricted - Hosts that require limited access and additional review
• audit - Systems with elevated logging requirements
• sandbox - Isolated environments for testing untrusted commands

Tag Usage Examples

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

# 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:

hosts:
  - alias: "web1"
    host: "10.0.0.11"        # IPv4 address
    credentials: "prod_admin"

Hostnames:

hosts:
  - alias: "web1"
    host: "web1.example.com" # Hostname (resolved via DNS)
    credentials: "prod_admin"

IPv6 Addresses:

hosts:
  - alias: "web1"
    host: "2001:db8::1"      # IPv6 address
    credentials: "prod_admin"

Network Security Considerations

Private Networks (Recommended):

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):

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:

# 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

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

# 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

# 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

# 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

# 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

# Test SSH connectivity
ssh -i keys/id_ed25519 [email protected] "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

# 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

   # Check syntax
   python -c "import yaml; yaml.safe_load(open('config/servers.yml'))"
   

2. Missing credential references

   # Check references
   python -c "
   from mcp_ssh.config import Config
   config = Config('config/')
   print('Missing credentials:', config.validate_credentials())
   "
   

3. Duplicate aliases

   # Check for duplicates
   grep -o 'alias: "[^"]*"' config/servers.yml | sort | uniq -d
   

Network Issues

1. Host unreachable

   # Test connectivity
   ping 10.0.0.11
   telnet 10.0.0.11 22
   

2. SSH connection refused

   # Check SSH service
   ssh -v [email protected]
   

Next Steps

• credentials.yml - SSH authentication configuration
• policy.yml - Security policy configuration
• Usage Cookbook - Practical configuration examples
• Troubleshooting - Common configuration issues