Module and Adhoc Command

Ad Hoc Commands

• Ad hoc commands are simple, one line operations that are run without writing a playbook.

• They are useful for quick tests and changes.

• For example, to start a service or ensure a line exists in a file.

• Ad hoc commands have limitations.

Ansible Modules

• Ansible provides modules, code that can be used to automate particular tasks

• Some uses of modules:

  • Ensure users exist with certain settings

  • Make sure the latest version of a software package is installed

  • Deploy a configuration file to a server

  • Enable a network service and make sure that it is running

• Most modules are idempotent, which means they only make changes if a change is needed. Idempotent modules can be run safely multiple times.

• An ad hoc command runs one module on the specified managed hosts.

Commands

• ansible $Host-Pattern -m module [-a 'module argument'] [-i inventory]

• ansible-doc -l: list all installed modules: https://docs.ansible.com/ansible/latest/modules/modules_by_category.html

• ansible-doc ping: view information about module ping

Examples

Use ping module to check if Ansible module (Python) can be run on managed host

• This is not ping module to send network echo request

ansible -i ansible/inventory.ini -m ping --private-key ~/.ssh/id_rsa host.domain.com

• Use shell command to ping another address

ansible -i ansible/inventory.ini -m shell -a "ping google.com -c 2" --private-key ~/.ssh/id_rsa host.domain.com

Overriding default settings

• These options override the configuration in the ansible.cfg configuration file.

  • -k or --ask-pass will prompt for the connection password.

  • -u REMOTE_USER overrides the remote_user setting in ansible.cfg.

  • -b option enables privilege escalation, running operations with become: yes.

  • --become_user: speicify become user

  • -K or --ask-become-pass will prompt for the privilege escalation password.

  • --become-method will override the default privilege escalation method. The default is sudo. Find valid choices using ansible-doc -t become -l.

Ansible Module Usage

• File Modules:

  • copy: Copy a local file to the manages host

  • file: Set permissions and other properties of files

  • lineinfile: Ensure a particular line is or is not in a file

  • synchronize: Synchronize content using rsync

• Software package modules:

  • yum: Manage packages using YUM

  • dnf: Manage packages using DNF

  • gem: Manage Ruby gems

• System Modules:

• firewalld: Manage arbitrary ports and services using firewalld

• reboot: Reboot a machine

• service: Manage services

• user: Add, remove, and manage user accounts

• group: Add, remove, and manage group

• Net Tools modules:

  • get_url: Download files over HTTP, HTTPS, or FTP

  • nmcli: Manage networking

  • uri: Interact with web services and communicate with APIs

Some Examples

• ansible -m user -a 'name=user uid=4000 state=present' server.domain.com: make sure user user is present and has uid number 4000

• ansible all -m group -a 'name=developers gid=2000 state=present': make sure group developers with UDI 2000 exists on all managed hosts

• ansible all -m user -a 'name=newbie groups=developers,wheel append=yes state=present': add user newbie to group developers and wheel without chaing primary group ore remove newbee from other groups

• ansible all -m package -a 'name=httpd state=present': ensure httpd package is installed on all hosts

• ansible -m ios_command -a "commands='show ip int br'" rtr3: run cli command on cisco ios device

• ansible -m ios_command -a "commands='show ip int brief,show ver'" switch

Some modules that are not Idempotent

• make sure they are safe to run twice

• command: runs a single command on the remote system, requires Python on managed host

• shell: runs a command on the remote system's shell (redirection and other features work), requires Python on managed host

• raw: simply runs a command with no processing (can be dangerous), This run commands direclty using the remote shell -> useful when managing system that cannot have Python installed

Debug module

- name: Print several lines of text
  vars:
    msg: |
         This is the first line.
         This is the second line with a variable like {{ inventory_hostname }}.
         And here could be more...
  debug:
    msg: "{{ msg.split('\n') }}"
    # without split('\n'), the variable will be printed in single line with \n in it

• Besiding using | (Literal Block Scalar) to break string over multiple lines, > (Folded Block Scalar) can be used to break multiple line, but when printed, new line will be represented as a space

• https://www.ansiblepilot.com/articles/break-a-string-over-multiple-lines-ansible-literal-and-folded-block-scalar-operators/

Copy Module - Save content to file

Save output from all host to one file:

• Using special var: ansible_play_hosts_all

- hosts: sw1,sw2
  gather_facts: false
  tasks:
    - command: Gather information
      cisco.ios.ios_command:
        commands:
          - "show cdp neighbors"
          - "show authentication session"
      register: output
    - name: Copy output to file
      copy:
        dest: output.txt
        content: |-
          <div data-gb-custom-block data-tag="for">

          {{''}}
          {{ '###' }}{{ host }}{{ '###' }}
          {{ hostvars[host]['output']['stdout'][0] }}
          {{ hostvars[host]['output']['stdout'][1] }}
          

</div>

      delegate_to: localhost
      run_once: true

Building custom ansible module

• Modules can be written in python or powershell language

• Python or powershell scripts are saved in library folder

• Other common code that are used by scripts in library folder can be saved in module_utils folder

• In the following example, ansible playbook is using backup_check module (backup_check.py) in library folder

---
- name: Check Backup
  hosts: localhost
  gather_facts: no

  vars:
    recipient: [email protected]
    smtpserver: smtp.domain.com
    nagioshost: nagios.domain.com
    nagiosapi: ""
    stashurl: ""
    stashapi: ""
    exclusion: []
  tasks:
    - name: Backup Check
      backup_check:
        nagioshost: "{{nagioshost}}"
        nagiosapi: "{{nagiosapi}}"
        stashurl: "{{stashurl}}"
        stashapi: "{{stashapi}}"
        exclusion: "{{exclusion}}"
      register: backupresult
      notify:
        - Send Final Report

    - name: print result
      debug:
        msg: "{{ backupresult }}"
  handlers:
    - name: Send Final Report
      community.general.mail:
        host: "{{smtpserver}}"
        port: 25
        subject: "Backup Check Report - There is a backup issue"
        body: >-
          Hosts in Nagios but do not have backup configured:
          

<div data-gb-custom-block data-tag="for" data-0='message' data-1='message' data-2='message'>

          {{ m }}
          

</div> 
        from: [email protected]
        to:
        - "{{recipient}}"
      delegate_to: localhost 

• The content of backup_check.py

#!/usr/bin/python

from __future__ import (absolute_import, division, print_function)
__metaclass__ = type

import re
from ansible.module_utils.basic import AnsibleModule
# get_devices.py is in module_utils folder
from ansible.module_utils.get_devices import *


Exclusion=['localhost','server']

def run_module():
    # define available arguments/parameters a user can pass to the module
    module_args = dict(
        nagioshost=dict(type='str', required=True),
        nagiosapi=dict(type='str', required=True),
        stashurl=dict(type='str', required=True),
        stashapi=dict(type='str', required=True),
        exclusion=dict(type='list', required=False, default=[])
    )

    # seed the result dict in the object
    # we primarily care about changed and state
    # changed is if this module effectively modified the target
    # state will include any data that you want your module to pass back
    # for consumption, for example, in a subsequent task
    result = dict(
        changed=False,
        message=''
    )

    # the AnsibleModule object will be our abstraction working with Ansible
    # this includes instantiation, a couple of common attr would be the
    # args/params passed to the execution, as well as if the module
    # supports check mode
    module = AnsibleModule(
        argument_spec=module_args,
        supports_check_mode=True
    )

    # if the user is working with this module in only check mode we do not
    # want to make any changes to the environment, just return the current
    # state with no modifications
    if module.check_mode:
        module.exit_json(**result)

    try:
        nagios=GetDeviceListFromNagios(module.params['nagioshost'],module.params['nagiosapi'])
        stash=GetDeviceListFromStash(module.params['stashurl'],module.params['stashapi'])
        nagiosnotstash=set(nagios)-set(stash)
        exclude=Exclusion+list(module.params['exclusion'])
        devicesnagiosnotstash=[]
        for nnr in nagiosnotstash:
            selected=True
            for e in exclude:
                if re.search(e,nnr,re.IGNORECASE):
                    selected=False
            if selected:
                devicesnagiosnotstash.append(nnr)
        if len(devicesnagiosnotstash) != 0:
            result['changed']=True
            result['message']=list(devicesnagiosnotstash)
        else:
            result['message']="All active devices in Nagios have backup configured"
        module.exit_json(**result)
    except Exception as e:
        exc_type, exc_obj, exc_tb = sys.exc_info()
        fname = os.path.split(exc_tb.tb_frame.f_code.co_filename)[1]
        # print(exc_type, fname, exc_tb.tb_lineno)
        error=f"Error - {exc_type}, {fname}, {exc_tb.tb_lineno}"
        module.fail_json(msg=f"Exception occurred",errors=error)
   

def main():
    run_module()

if __name__ == '__main__':
    main()