dlx-ansible/USAGE.md

Ansible Project Usage

Quick Start

1. Setup SSH Access

# 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

# 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

# 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

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

# 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

# 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