DEV Community

Harsh Mishra
Harsh Mishra

Posted on

Ansible Ad-Hoc Commands: Complete Guide for Beginners

#ansible #tooling #linux

Ad-Hoc Commands in Ansible: Complete Guide

Ansible ad-hoc commands are one-liner commands that allow you to perform quick tasks on managed hosts without the need to create a playbook. They are especially useful for simple or repetitive tasks, such as installing packages, copying files, or managing services, making them an excellent entry point for learning Ansible.

This guide covers everything you need to know about ad-hoc commands, including their structure, usage, options, and practical examples.

1. What Are Ad-Hoc Commands?

Ad-hoc commands are a quick way to perform tasks without writing a playbook. They leverage Ansible's modules to perform tasks directly on the command line.

Key Characteristics:

  • Simple: Used for quick, one-off tasks.
  • Direct: Executes tasks immediately.
  • Ephemeral: Changes made are not stored or reusable.

2. Structure of an Ad-Hoc Command

The basic syntax for an ad-hoc command is:

ansible <host-pattern> -m <module-name> -a "<module-options>" [options]
Enter fullscreen mode Exit fullscreen mode
  • <host-pattern>: Specifies the target hosts (defined in the inventory).
  • -m <module-name>: Specifies the Ansible module to use.
  • -a "<module-options>": Passes arguments to the module.
  • [options]: Additional command-line options (e.g., -u, --become).

3. Using Ad-Hoc Commands

3.1 Targeting Hosts

Ad-hoc commands work on the hosts defined in your inventory file. Use the hosts parameter to specify the target.

Examples:

  • Run on all hosts: 
  ansible all -m ping
Enter fullscreen mode Exit fullscreen mode
  • Run on a specific host: 
  ansible webserver1 -m ping
Enter fullscreen mode Exit fullscreen mode
  • Run on a group of hosts: 
  ansible webservers -m ping
Enter fullscreen mode Exit fullscreen mode
  • Use patterns: 
  ansible webservers:!dbservers -m ping
Enter fullscreen mode Exit fullscreen mode

3.2 Common Modules Used in Ad-Hoc Commands

Ping Module

The ping module checks the connectivity to the hosts.

ansible all -m ping
Enter fullscreen mode Exit fullscreen mode

This module accepts the parameters:

  1. None. It simply checks if a host is reachable.

Command Module

The command module runs commands on the target host(s).

ansible all -m command -a "ls /etc"
Enter fullscreen mode Exit fullscreen mode

This module accepts the parameters:

  1. cmd – The command to run (in this case, "ls /etc").

Shell Module

The shell module runs shell commands, including pipes and redirects.

ansible all -m shell -a "echo 'Hello, World!' > /tmp/hello.txt"
Enter fullscreen mode Exit fullscreen mode

This module accepts the parameters:

  1. cmd – The shell command to run (in this case, "echo 'Hello, World!' > /tmp/hello.txt").

Copy Module

The copy module copies files from the control node to the target hosts.

ansible all -m copy -a "src=/path/to/local/file dest=/path/to/remote/location"
Enter fullscreen mode Exit fullscreen mode

This module accepts the parameters:

  1. src – The source file on the control node.
  2. dest – The destination path on the target host.
  3. mode (optional) – The permissions to set for the file.

File Module

The file module manages files and directories.

ansible all -m file -a "path=/tmp/testfile state=touch"
Enter fullscreen mode Exit fullscreen mode

This module accepts the parameters:

  1. path – The file or directory path.
  2. state – The state of the file (e.g., "touch" creates an empty file, "absent" removes it).

User Module

The user module manages user accounts.

ansible all -m user -a "name=johndoe state=present"
Enter fullscreen mode Exit fullscreen mode

This module accepts the parameters:

  1. name – The name of the user to manage.
  2. state – The state of the user ("present" to create, "absent" to remove).
  3. password (optional) – The password to set for the user.

Apt Module (for Debian-based systems)

The apt module installs or manages packages.

ansible all -m apt -a "name=nginx state=present"
Enter fullscreen mode Exit fullscreen mode

This module accepts the parameters:

  1. name – The name of the package to manage.
  2. state – The desired state of the package ("present" to install, "absent" to remove).
  3. update_cache (optional) – Whether to update the APT cache before installing.

Yum Module (for RHEL-based systems)

The yum module manages packages using Yum.

ansible all -m yum -a "name=httpd state=present"
Enter fullscreen mode Exit fullscreen mode

This module accepts the parameters:

  1. name – The name of the package to manage.
  2. state – The desired state of the package ("present" to install, "absent" to remove).
  3. enablerepo (optional) – Enable specific repositories.

Service Module

The service module manages system services.

ansible all -m service -a "name=nginx state=started"
Enter fullscreen mode Exit fullscreen mode

This module accepts the parameters:

  1. name – The name of the service.
  2. state – The desired state of the service ("started", "stopped", "restarted").

3.3 Using Privilege Escalation

Many tasks require root privileges. Use the --become flag to elevate permissions.

ansible all -m apt -a "name=nginx state=present" --become
Enter fullscreen mode Exit fullscreen mode

3.4 Running Commands on Specific Users

Use the -u flag to specify the remote user.

ansible all -m shell -a "whoami" -u ubuntu
Enter fullscreen mode Exit fullscreen mode

4. Common Options for Ad-Hoc Commands

4.1 Inventory Options

  • -i <path>: Specify a custom inventory file. 
  ansible all -m ping -i /path/to/inventory
Enter fullscreen mode Exit fullscreen mode
  • Use inline inventory: 
  ansible "192.168.1.1" -m ping
Enter fullscreen mode Exit fullscreen mode

4.2 Debugging Options

  • -v: Enable verbose output (add more v for higher verbosity). 
  ansible all -m ping -v
Enter fullscreen mode Exit fullscreen mode
  • --check: Perform a dry run (simulate the changes without applying them). 
  ansible all -m apt -a "name=nginx state=present" --check
Enter fullscreen mode Exit fullscreen mode

5. Examples of Ad-Hoc Commands

5.1 Connectivity Check

Ping all hosts in the inventory:

ansible all -m ping
Enter fullscreen mode Exit fullscreen mode

5.2 Install a Package

Install the nginx package on all web servers:

ansible webservers -m apt -a "name=nginx state=present" --become
Enter fullscreen mode Exit fullscreen mode

5.3 Restart a Service

Restart the nginx service on all hosts:

ansible all -m service -a "name=nginx state=restarted" --become
Enter fullscreen mode Exit fullscreen mode

5.4 Copy a File

Copy a local file to all managed hosts:

ansible all -m copy -a "src=/path/to/local/file dest=/path/to/remote/location"
Enter fullscreen mode Exit fullscreen mode

5.5 Create a Directory

Create a directory on all managed hosts:

ansible all -m file -a "path=/tmp/testdir state=directory"
Enter fullscreen mode Exit fullscreen mode

5.6 Add a User

Create a user account johndoe on all managed hosts:

ansible all -m user -a "name=johndoe state=present" --become
Enter fullscreen mode Exit fullscreen mode

5.7 Fetch a File

Retrieve a file from the remote hosts:

ansible all -m fetch -a "src=/remote/file/path dest=/local/file/path"
Enter fullscreen mode Exit fullscreen mode

6. Differences Between Ad-Hoc Commands and Playbooks

Feature Ad-Hoc Commands Playbooks
Purpose Quick, one-time tasks Complex, reusable automation
Complexity Simple Structured and advanced
Reusability Not reusable Fully reusable
Execution Immediate Step-by-step as defined
File Required No Yes

7. Best Practices for Ad-Hoc Commands

  1. Use for Simple Tasks: Reserve ad-hoc commands for tasks that don’t require reusability.
  2. Verbose Mode: Use -v to understand what the command is doing.
  3. Use Modules: Prefer using modules over raw shell commands for better idempotency and clarity.
  4. Check Before Applying: Use the --check option for safe execution.

8. Conclusion

Ad-hoc commands are a quick and effective way to manage systems without needing to create a playbook. They are an excellent tool for troubleshooting, testing, and performing one-off tasks. Mastering their syntax and options ensures you can leverage Ansible's power effectively in real-time scenarios.

By understanding and using ad-hoc commands efficiently, you gain a strong foundation in Ansible that complements the more structured approach of playbooks.

Top comments (0)

Read next

codingashish_dev profile image

Step-by-Step Guide to Installing PostgreSQL on Arch Linux

Ashish Prajapati -

nolunchbreaks_22 profile image

Getting Started with Ansible: A Complete Guide to IT Automation

Osagie Anolu -

apilover profile image

Top 8 Swagger Codegen Alternatives

Wanda -

jitanshuraut profile image

Algo-Trading Engine

Jitanshu Raut -