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 uninstall 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.
NXLog Agent version 6.5 or newer installer — From the NXLog Platform Home page, click Download under System setup to download the relevant installer file(s). You may need to log in to your NXLog Platform online account.

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 install-playbook.yml uninstall-playbook.yml inventory

Copy the NXLog Agent installer files to the ansible directory you created in the previous step.
- nxlog-6.5.9781_ubuntu24_amd64.deb for Ubuntu.
- nxlog-6.5.9781_windows_x64.msi for Windows.

Ensure your folder and file structure is correct. When the Ansible playbook runs, it must know where these files are, as it references them by their location.

ansible/
├── inventory
├── nxlog-6.5.9781_windows_x64.msi
├── nxlog-6.5.9781_ubuntu24_amd64.deb
├── install-playbook.yml
└── uninstall-playbook.yml

Edit the inventory file located in the ansible directory and build your node 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.
inventory
```
[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, defining 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, and the steps to clean up the installation files after successful deployment.

install-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.deb
        dest: /root/
        mode: '0755'

    - name: Install the NXLog Agent package with address and label  (3)
      shell: export NXP_ADDRESS="agents.nxlog.example.com:5515" && export NXP_AGENT_LABEL=Ubuntu24 && apt install -y /root/nxlog-6.5.9781_ubuntu24_amd64.deb

    - name: Remove the NXLog Agent installer file from Linux servers  (4)
      file:
        path: /root/nxlog-6.5.9781_ubuntu24_amd64.deb
        state: absent

- hosts: windows (5)
  tasks:
    - name: Upload the NXLog Agent installer to Windows servers  (6)
      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  (7)
      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

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

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 NXLog Agent installer to the target host’s specified directory and sets the required permissions.
3	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.
4	Cleans up the NXLog Agent installer files on Linux systems.
5	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.
6	Copies the NXLog Agent installer MSI file to the specified folder on the target host.
7	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).
8	Deletes the uploaded installer file from the Windows target nodes.

Run the playbook.
```
$ ansible-playbook -i inventory install-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.

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 defining the automated uninstallation tasks.

The playbook below contains all the steps required to uninstall NXLog Agent from Windows and Ubuntu.

uninstall-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

- 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

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.

Run the playbook.

$ ansible-playbook -i inventory uninstall-playbook.yml