Skip to content

README.md

Latest commit

 

History

History
464 lines (365 loc) · 9.82 KB

README.md

File metadata and controls

464 lines (365 loc) · 9.82 KB

devil Ansible Collection

Ansible collection for managing devil shared hosting servers via a local UNIX domain socket.

Overview

This collection provides Ansible modules to manage various aspects of devil-type shared hosting servers including:

  • DNS management - domains, records, templates
  • Database management - MySQL, MongoDB, and PostgreSQL databases and users
  • Web hosting - websites, applications, SSL certificates
  • Email services - mailboxes, forwarders, aliases
  • File services - FTP accounts, repositories
  • System information - account details, limits, ports

All modules communicate with the devil daemon through a Unix domain socket, located at /var/run/devil2.sock.

Installation

Since this collection is only available on GitHub (not on Ansible Galaxy), install it directly from the repository:

# Clone and install from the current directory
git clone https://github.com/devil-imps/devil-ansible.git
cd devil-ansible
ansible-galaxy collection install . --force

# Or install directly from GitHub
ansible-galaxy collection install git+https://github.com/devil-imps/devil-ansible.git --force

Requirements

  • The devil socket must be accessible at the specified path (default: /var/run/devil2.sock)
  • SSH access to the target devil host

Quick Start

---
- name: Basic devil server management
  hosts: devil_servers
  tasks:
    - name: Get account information
      devil_imps.devil.info:
        query: account
      register: account_info

    - name: Create a MySQL database with user
      devil_imps.devil.mysql:
        name: myapp_db
        user: myapp_user
        password: "SecurePassword123!"

    - name: Create a PHP website
      devil_imps.devil.www:
        name: example.com
        type: php

    - name: Add DNS A record
      devil_imps.devil.dns:
        domain: example.com
        record: www
        record_type: A
        target: 192.0.2.10

Modules

Information and System

devil_imps.devil.info

Retrieve account information and limits.

- name: Get account information
  devil_imps.devil.info:
    query: account

- name: Get account limits
  devil_imps.devil.info:
    query: limits

devil_imps.devil.vhost

List available IP addresses (private/public).

- name: List all IP addresses
  devil_imps.devil.vhost:

- name: List only public IPs
  devil_imps.devil.vhost:
    type: public

devil_imps.devil.port

Manage port reservations.

- name: Reserve a port
  devil_imps.devil.port:
    port: 8080
    state: present

- name: List reserved ports
  devil_imps.devil.port:
    manage: list

DNS Management

devil_imps.devil.dns

Comprehensive DNS domain and record management.

# Domain management
- name: Create DNS domain with template
  devil_imps.devil.dns:
    domain: example.com
    template: mail

- name: List all domains
  devil_imps.devil.dns:
    manage: list

- name: List available templates
  devil_imps.devil.dns:
    manage: templates

# Record management
- name: Add A record
  devil_imps.devil.dns:
    domain: example.com
    record: www
    record_type: A
    target: 192.0.2.10
    ttl: 3600

- name: Add MX record
  devil_imps.devil.dns:
    domain: example.com
    record: "@"
    record_type: MX
    target: mail.example.com
    priority: 10

- name: Add CNAME record
  devil_imps.devil.dns:
    domain: example.com
    record: blog
    record_type: CNAME
    target: example.com

- name: Remove specific record by ID
  devil_imps.devil.dns:
    domain: example.com
    record_id: "12345"
    state: absent

Database Management

devil_imps.devil.mysql

MySQL database and user management with advanced features.

# Database operations
- name: Create database with user and privileges
  devil_imps.devil.mysql:
    name: myapp_db
    user: myapp_user
    password: "SecurePassword123!"
    collate: utf8mb4_unicode_ci

- name: Create database only
  devil_imps.devil.mysql:
    name: analytics_db

# User management
- name: Create user with random password
  devil_imps.devil.mysql:
    manage: user
    user: readonly_user

- name: Change user password
  devil_imps.devil.mysql:
    manage: password
    user: myapp_user
    password: "NewPassword456!"

# Access and privileges
- name: Add host access for user
  devil_imps.devil.mysql:
    manage: access
    user: myapp_user
    host: "192.168.1.%"
    state: present

- name: Grant specific privileges
  devil_imps.devil.mysql:
    manage: privileges
    user: readonly_user
    name: myapp_db
    privileges: "+SELECT +SHOW +VIEW"

- name: Grant all privileges
  devil_imps.devil.mysql:
    manage: privileges
    user: admin_user
    name: myapp_db
    privileges: "+ALL"

- name: List databases and users
  devil_imps.devil.mysql:
    manage: list

devil_imps.devil.pgsql

PostgreSQL database and user management.

- name: Create PostgreSQL database
  devil_imps.devil.pgsql:
    name: myapp_db

- name: Create PostgreSQL user
  devil_imps.devil.pgsql:
    manage: user
    user: myapp_user
    password: "SecurePassword123!"

- name: List PostgreSQL resources
  devil_imps.devil.pgsql:
    manage: list

devil_imps.devil.mongo

MongoDB database management.

- name: Create MongoDB database
  devil_imps.devil.mongo:
    name: myapp_db

- name: List MongoDB databases
  devil_imps.devil.mongo:
    manage: list

Web Hosting

devil_imps.devil.www

Comprehensive website and web application management.

# Basic websites
- name: Create PHP website
  devil_imps.devil.www:
    name: example.com
    type: php

- name: Create pointer (redirect)
  devil_imps.devil.www:
    name: www.example.com
    type: pointer
    pointer_target: example.com

# Application hosting
- name: Create Python web application
  devil_imps.devil.www:
    name: app.example.com
    type: python
    passenger_binary: "/home/user/venv/bin/python"
    environment: production

- name: Create Node.js application
  devil_imps.devil.www:
    name: api.example.com
    type: nodejs
    passenger_binary: "/home/user/.nvm/versions/node/v18.0.0/bin/node"
    environment: development

- name: Create Ruby application
  devil_imps.devil.www:
    name: rails.example.com
    type: ruby
    passenger_binary: "/home/user/.rbenv/versions/3.0.0/bin/ruby"
    environment: production

# Proxy configuration
- name: Create proxy to local service
  devil_imps.devil.www:
    name: proxy.example.com
    type: proxy
    proxy_target: localhost
    proxy_port: 3000

# Domain options and management
- name: Set domain options
  devil_imps.devil.www:
    name: example.com
    manage: options
    option_name: gzip
    option_value: "on"

- name: Restart passenger application
  devil_imps.devil.www:
    name: app.example.com
    manage: restart

# Statistics (Matomo) management
- name: Create statistics user
  devil_imps.devil.www:
    manage: stats
    stats_operation: account
    stats_user: analytics_user
    stats_password: "StatsPassword123!"

- name: Add domain to statistics
  devil_imps.devil.www:
    name: example.com
    manage: stats
    stats_operation: domain
    state: present

- name: Grant user access to domain stats
  devil_imps.devil.www:
    name: example.com
    manage: stats
    stats_operation: access
    stats_user: analytics_user
    state: present

- name: List all websites
  devil_imps.devil.www:
    manage: list

devil_imps.devil.ssl

SSL certificate management.

- name: Create LE SSL certificate
  devil_imps.devil.ssl:
    ip: "192.168.1.100"
    domain: "example.com"
    letsencrypt: true

- name: List SSL certificates
  devil_imps.devil.ssl:
    manage: list

- name: Remove SSL certificate
  devil_imps.devil.ssl:
    domain: example.com
    state: absent

Email Services

devil_imps.devil.mail

Email account and forwarding management.

# Mailbox management
- name: Create email account
  devil_imps.devil.mail:
    email: user@example.com
    password: "EmailPassword123!"

- name: Change email password
  devil_imps.devil.mail:
    manage: password
    email: user@example.com
    password: "NewEmailPassword456!"

# Forwarding and aliases
- name: Create email forwarder
  devil_imps.devil.mail:
    manage: forward
    email: info@example.com
    target: admin@example.com

- name: Create catch-all forwarder
  devil_imps.devil.mail:
    manage: forward
    email: "*@example.com"
    target: admin@example.com

- name: List email accounts
  devil_imps.devil.mail:
    manage: list

File Services

devil_imps.devil.ftp

FTP account management.

- name: Create FTP account
  devil_imps.devil.ftp:
    user: ftpuser
    password: "FtpPassword123!"
    path: "/home/user/public_html"

- name: List FTP accounts
  devil_imps.devil.ftp:
    manage: list

- name: Remove FTP account
  devil_imps.devil.ftp:
    user: ftpuser
    state: absent

devil_imps.devil.repo

Repository management (Git, SVN, HG).

- name: Create Git repository
  devil_imps.devil.repo:
    name: myproject
    type: git

- name: List repositories
  devil_imps.devil.repo:
    manage: list

Common Parameters

All modules support these common parameters:

  • socket_path (str): Path to devil socket (default: /var/run/devil2.sock)

Most modules also support:

  • state (str): present or absent (default: present)

Error Handling

The collection includes comprehensive error handling:

- name: Handle potential errors
  devil_imps.devil.mysql:
    name: test_db
  register: result
  failed_when: false

- name: Check if operation succeeded
  debug:
    msg: "Database creation {{ 'succeeded' if result.changed else 'failed or already exists' }}"

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page or submit a pull request.

License

This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE License. See the LICENSE file for details.