# Ansible Project Usage

## Quick Start

### 1. Setup SSH Access

```bash
# For existing user
./scripts/setup-ssh.sh <ip_address> <username>

# Create new user via admin account
./scripts/setup-ssh.sh <ip_address> <username> <admin_user>

# Examples
./scripts/setup-ssh.sh 192.168.200.103 ansible
./scripts/setup-ssh.sh 192.168.200.103 ansible root
```

### 2. Test Connectivity

```bash
# Test all hosts
ansible-playbook playbooks/ping.yml

# Test specific group
ansible-playbook playbooks/ping.yml -l dbservers

# Test single host
ansible-playbook playbooks/ping.yml -l postgres

# Quick ping (no playbook)
ansible all -m ping
```

### 3. Run Playbooks

```bash
# Apply common configuration to all hosts
ansible-playbook playbooks/site.yml

# Limit to specific group
ansible-playbook playbooks/site.yml -l dbservers

# Limit to specific host
ansible-playbook playbooks/site.yml -l postgres

# Dry run (check mode)
ansible-playbook playbooks/site.yml --check

# Run specific tags only
ansible-playbook playbooks/site.yml --tags packages
ansible-playbook playbooks/site.yml --tags security
ansible-playbook playbooks/site.yml --tags ssh
```

## Inventory

Hosts are defined in `inventory/hosts.yml`:

| Group          | Host         | IP              |
|----------------|--------------|-----------------|
| control        | ansible-node | 192.168.200.106 |
| dbservers      | postgres     | 192.168.200.103 |
| dbservers      | mysql        | 192.168.200.110 |
| dbservers      | mongo        | 192.168.200.111 |
| webservers     | nginx        | 192.168.200.65  |
| webservers     | npm          | 192.168.200.101 |
| infrastructure | docker       | 192.168.200.200 |
| infrastructure | pihole       | 192.168.200.100 |

### Target Hosts

```bash
# All hosts
ansible-playbook playbooks/site.yml

# By group
ansible-playbook playbooks/site.yml -l dbservers
ansible-playbook playbooks/site.yml -l webservers
ansible-playbook playbooks/site.yml -l infrastructure

# Multiple groups
ansible-playbook playbooks/site.yml -l "dbservers:webservers"

# Single host
ansible-playbook playbooks/site.yml -l postgres
```

## Common Role

The `common` role applies baseline configuration to all hosts.

### Features

- **Packages**: curl, wget, vim, htop, git, unzip, net-tools, tree, jq
- **Timezone**: Configurable (default: UTC)
- **SSH Hardening**: Disable root login, password auth, limit auth tries
- **Firewall**: UFW with configurable allowed ports
- **Auto Updates**: Unattended security upgrades
- **User Management**: Create users with SSH keys and sudo access

### Configuration

Override defaults in `group_vars/` or `host_vars/`:

```yaml
# group_vars/dbservers.yml
common_timezone: "America/New_York"
common_extra_packages:
  - postgresql-client

common_firewall_allowed_ports:
  - "22/tcp"
  - "5432/tcp"

common_users:
  - name: deploy
    groups: ['sudo']
    passwordless_sudo: true
    ssh_keys:
      - "ssh-ed25519 AAAA..."
```

### Available Tags

| Tag       | Description                    |
|-----------|--------------------------------|
| packages  | Install common packages        |
| timezone  | Set timezone and locale        |
| users     | Create users and SSH keys      |
| ssh       | SSH daemon hardening           |
| security  | Firewall, sysctl, auto-updates |

## Ad-hoc Commands

```bash
# Run command on all hosts
ansible all -a "uptime"

# Run command on group
ansible dbservers -a "df -h"

# Run with sudo
ansible all -b -a "apt update"

# Copy file
ansible all -m copy -a "src=/local/file dest=/remote/file"

# Install package
ansible dbservers -b -m apt -a "name=htop state=present"

# Restart service
ansible webservers -b -m service -a "name=nginx state=restarted"
```

## Directory Structure

```
dlx-ansible/
├── ansible.cfg              # Ansible configuration
├── inventory/
│   └── hosts.yml            # Host inventory
├── playbooks/
│   ├── site.yml             # Main playbook
│   └── ping.yml             # Connectivity test
├── roles/
│   └── common/              # Common baseline role
├── group_vars/
│   └── all.yml              # Variables for all hosts
├── host_vars/               # Per-host variables
├── files/                   # Static files
├── templates/               # Jinja2 templates
└── scripts/
    └── setup-ssh.sh         # SSH setup script
```