Deploy NXLog Agent with Ansible

Ansible is an automation tool that you can use to deploy and manage NXLog Agent instances on Linux and Windows systems. This guide provides step-by-step instructions to set up the required environment, create playbooks, and automate tasks for a streamlined NXLog Agent deployment. It also covers prerequisites, folder structure, and cleanup or undeployment scenarios to ensure a complete and efficient process. For further details, see the Ansible community documentation.

Prerequisites and assumptions

Before proceeding, ensure the following conditions are met.

Name resolution — We assume you are working in an environment where DNS is set up and working correctly. Host names translate to IP addresses.
Control computer — A Linux-based computer with Ansible installed. See the Installing Ansible section in the Ansible documentation.
Credentials — A domain account or administrative credentials are needed to install NXLog Agent on target computers for both Linux and Windows nodes. Ansible will use these credentials to access the target nodes.
Windows Remote Management (WinRM) — The Windows Remote Management protocol must be enabled and configured on the Windows target computers.
Python — Python must be installed on the control node and the target Linux computers, too. It is installed by default on most Linux distributions.
NXLog Platform — Installed and configured. See Install NXLog Platform on-premises in the NXLog Platform User Guide.
NXP_ADDRESS and NXP_AGENT_LABEL — You must have these values to pass to the NXLog Agent installation.
- NXP_ADDRESS is the NXLog Platform Agent Management URL and port. You must replace agents.nxlog.example.com:5515 with agents.<YOURDOMAIN>:5515 in the instructions below.
  
  For more details, see Connecting to NXLog Platform in the NXLog Agent Reference Manual.
- NXP_AGENT_LABEL is a label that identifies the agent. You can use this label when creating auto-enroll rules so that your NXLog Agent instances automatically download and apply preset configurations to start collecting logs immediately.
  
  See Set up automatic agent enrollment for more information.

Install NXLog Agent

Execute the steps below to install and configure NXLog Agent on Ubuntu and Windows.

Create the directory structure on the control computer.

$ mkdir ansible
$ cd ansible
$ touch deploy-playbook.yml inventory

Log in to NXLog Platform, and from the Home page, click Download under System setup. You may need to log in to your NXLog Platform online account.
Download the Ubuntu and Windows installers. Then, copy both files to the ansible directory you created in the previous step.
- nxlog-6.5.9781_ubuntu24_amd64.tar.bz2 for Ubuntu.
- nxlog-6.5.9781_windows_x64.msi for Windows.
Ensure your folder and file structure are correctly arranged.
Example 1. Folder and file structure
It is very important to organize the files correctly. When the Ansible playbook runs, it has to know where these files are, as it references them by their location.
ansible/ ├── inventory.yml ├── nxlog-6.5.9781_windows_x64.msi ├── nxlog-6.5.9781_ubuntu24_amd64.tar.bz2 └── deploy-playbook.yml
Edit the inventory file located in the ansible directory and build your node inventory.
Example 2. Inventory
The inventory file allows you to define categories or groups of servers. This example uses two categories linux and windows for the two different OS binaries.
[linux] linux_host ansible_host=Ubuntu24 ansible_user=ansible ansible_ssh_password=YourStrongPassword! ansible_connection=ssh [windows] windows_host ansible_host=Windows1 ansible_user=ansible ansible_password=YourStrongPassword! ansible_connection=winrm ansible_winrm_transport=basic ansible_port=5985
Ansible provides various approaches to build your inventory file. See the How to build your inventory section in the Ansible documentation.

Create the content of your Ansible playbook, which defines and configures the automated deployment tasks. Ensure that you set NXP_ADDRESS and NXP_AGENT_LABEL with your own settings.

This playbook contains all the steps needed to deploy NXLog Agent on Ubuntu and Windows. These steps include elevating privileges and installing prerequisites.

deploy-playbook.yaml

---
- hosts: linux (1)
  become: true
  tasks:
    - name: Upload the NXLog Agent installer to Linux servers (2)
      copy:
        src: nxlog-6.5.9781_ubuntu24_amd64.tar.bz2
        dest: /root/
        mode: '0755'

    - name: Install bzip2 (3)
      ansible.builtin.apt:
        name: bzip2
        state: present
      when: ansible_distribution in ["Debian", "Ubuntu"]

    - name: Extract the NXLog Agent installer on the Linux servers (4)
      shell: |
        mkdir -p /root/nxlog
        tar -xvf /root/nxlog-6.5.9781_ubuntu24_amd64.tar.bz2 -C /root/nxlog
      args:
        chdir: /root

    - name: Install the main NXLog Agent package with address and label (5)
      shell: |
        export NXP_ADDRESS=agents.nxlog.example.com:5515
        export NXP_AGENT_LABEL=Ubuntu24
        dpkg -i /root/nxlog/nxlog-*.deb || apt-get install -f -y
      args:
        chdir: /root/nxlog

    - name: Install the additional NXLog Agent packages (6)
      shell: |
        for pkg in /root/nxlog/*.deb; do
          if [[ $pkg != "/root/nxlog/nxlog-*.deb" ]]; then
            dpkg -i $pkg || apt-get install -f -y
          fi
        done
      args:
        chdir: /root/nxlog

- hosts: windows (7)
  tasks:
    - name: Upload the NXLog Agent installer to Windows servers (8)
      ansible.windows.win_copy:
        src: nxlog-6.5.9781_windows_x64.msi
        dest: C:\nxlog-6.5.9781_windows_x64.msi

    - name: Install NXLog Agent on Windows with address and label (9)
      ansible.windows.win_package:
        path: C:\nxlog-6.5.9781_windows_x64.msi
        state: present
        arguments: >
          /quiet
          NXP_ADDRESS=agents.nxlog.example.com:5515
          NXP_AGENT_LABEL=WindowsServer

1	Specifies the host group (in this case, a Linux computer group) from the inventory file. The tasks execute on all hosts under the `linux` group.
2	Copies the compressed NXLog Agent installer to the target host’s specified directory and sets the required permissions.
3	Installs the `bzip2` software on the target host to enable decompression of the uploaded installer file.
4	Creates the `/root/nxlog/` directory, decompresses the NXLog Agent installer, and places the extracted files in the directory.
5	Installs NXLog Agent on the target host. The process includes passing the `NXP_ADDRESS` (for connecting to NXLog Platform) and `NXP_AGENT_LABEL` (to assign a label for the connected agent) arguments. Dependencies are also resolved as needed.
6	Installs additional NXLog Agent packages while handling any required dependencies.
7	Specifies the host group (in this case, a Windows computer group) from the inventory file. The tasks execute on all hosts under the `windows` group.
8	Copies the NXLog Agent installer MSI file to the specified folder on the target host.
9	Installs NXLog Agent on the target host, while defining the environment variables `NXP_ADDRESS` (to connect to NXLog Platform) and `NXP_AGENT_LABEL` (to assign a label for the connected agent).

Run the playbook.
```
$ ansible-playbook -i inventory -u ansible --ask-pass --ask-become-pass deploy-playbook.yml
```
By running the script Ansible will take care of installing NXLog Agent on each node, and each NXLog Agent instance will automatically connect to NXLog Platform and the user can then proceed to enroll them.

Cleaning up after installation

If your deployment is successful, you may want to do some housekeeping. Execute the steps below to clean up the installation files on Ubuntu and Windows.

Create the content of your Ansible playbook which defines and configures the automated cleanup tasks.

The playbook below contains all the steps to clean up the installation files after a successful deployment.

cleanup-playbook.yaml

---
- hosts: linux
  become: true
  tasks:
    - name: Remove NXLog Agent tarball from Linux servers (1)
      file:
        path: /root/nxlog-6.5.9781_ubuntu24_amd64.tar.bz2
        state: absent

    - name: Remove extracted NXLog Agent installer files from Linux servers (2)
      file:
        path: /root/nxlog
        state: absent

- hosts: windows
  tasks:
    - name: Remove NXLog Agent installer file from Windows servers (3)
      ansible.windows.win_file:
        path: C:\nxlog-6.5.9781_windows_x64.msi
        state: absent

1	Removes the compressed tarball from the Linux target nodes.
2	Cleans up decompressed installer files on Linux systems.
3	Deletes the uploaded installer file from the Windows target nodes.

Run the playbook.

$ ansible-playbook -i inventory -u ansible --ask-pass --ask-become-pass cleanup-playbook.yml

Uninstall NXLog Agent

There might be scenarios when you need to reverse the deployment of NXLog Agent, for example, when testing. Execute the steps below to uninstall NXLog Agent on Ubuntu and Windows, returning them to their original state.

Create the content of your Ansible playbook which defines and configures the automated undemployment tasks.

The playbook below contains all the steps that are needed to undeploy NXLog Agent from Windows and Ubuntu.

undeploy-playbook.yaml

---
- hosts: linux
  become: true
  become_user: root
  tasks:
    - name: Uninstall NXLog Agent packages on Linux (1)
      shell: |
        apt-get remove -y '^nxlog*' || true
        apt-get autoremove -y
      ignore_errors: true

    - name: Remove NXLog Agent directories on Linux (2)
      file:
        path: "{{ item }}"
        state: absent
      loop:
        - /opt/nxlog
        - /var/log/nxlog
        - /root/nxlog
        - /root/nxlog-6.5.9781_ubuntu24_amd64.tar.bz2

- hosts: windows
  tasks:
    - name: Stop NXLog Agent service on Windows (3)
      win_service:
        name: nxlog
        state: stopped
      ignore_errors: yes

    - name: Uninstall NXLog Agent via MSI installer (4)
      win_package:
        path: "C:\\nxlog-6.5.9781_windows_x64.msi"
        state: absent
      ignore_errors: yes

    - name: Remove NXLog Agent installation directory (5)
      win_file:
        path: "C:\\Program Files\\nxlog"
        state: absent
        recurse: yes

    - name: Remove NXLog Agent MSI installer (6)
      win_file:
        path: "C:\\nxlog-6.5.9781_windows_x64.msi"
        state: absent
        recurse: no

1	Uninstalls NXLog Agent from the Linux target nodes.
2	Cleans up directories and files created during the installation process.
3	Stops the `nxlog` service on Windows nodes to ensure a smooth uninstallation process.
4	Uninstalls NXLog Agent from the Windows nodes using the MSI installer.
5	Cleans up the NXLog Agent installation directory and its contents.
6	Deletes the uploaded installer file from the Windows target nodes.

Run the playbook.

$ ansible-playbook -i inventory -u ansible --ask-pass --ask-become-pass undeploy-playbook.yml