Deploy NXLog Agent with Puppet Bolt

Puppet Bolt is an agentless orchestration 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 Bolt plans, and automate tasks for a streamlined NXLog Agent deployment. It also covers prerequisites, folder structure, and uninstallation to ensure a complete and efficient process. For further details, see the Puppet Bolt documentation.

Prerequisites and assumptions

Before proceeding, ensure you have the following:

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 system with Puppet Bolt installed. See Installing Bolt in the Bolt documentation.
Credentials — A domain account or administrative credentials are needed to install NXLog Agent on target computers for both Linux (Debian-based) and Windows nodes. Bolt will use these credentials to access the target nodes.
Windows Remote Management (WinRM) — The WinRM protocol must be enabled and configured on the Windows target computers.
SSH — SSH must be enabled on the Linux target computers.
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 Debian-based Linux and Windows.

Create the directory structure on the control computer.

$ mkdir nxlog_bolt_project
$ cd nxlog_bolt_project
$ bolt project init
$ touch bolt-project.yaml inventory.yaml
$ mkdir -p modules/nxlog/files
$ mkdir -p modules/nxlog/plans
$ touch modules/nxlog/plans/install_plan.yaml
$ touch modules/nxlog/plans/uninstall_plan.yaml

Copy the NXLog Agent installer files to the nxlog_bolt_project/modules/nxlog/files 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 matches the following:

nxlog_bolt_project/
├── bolt-project.yaml
├── inventory.yaml
├── modules/
│   ├── nxlog/
│   │   ├── files/
│   │   │   ├── nxlog-6.5.9781_windows_x64.msi
│   │   │   ├── nxlog-6.5.9781_ubuntu24_amd64.tar.bz2
│   │   ├── plans/
│   │   │   ├── install_plan.yaml
│   │   │   ├── uninstall_plan.yaml

Edit the inventory.yaml file to define your target nodes. The inventory.yaml file allows you to categorize nodes. This example uses two groups, linux and windows.

inventory.yaml

groups:
  - name: linux
    targets:
      - uri: linux1
    config:
      transport: ssh
      ssh:
        user: bolt
        password: "YourStrongPassword!"
        host-key-check: false
        run-as: root

  - name: windows
    targets:
      - uri: windows1
    config:
      transport: winrm
      winrm:
        user: bolt
        password: "YourStrongPassword!"
        port: 5985
        ssl: false
        basic-auth-only: false

See the Puppet Bolt Inventory file documentation for more details.

Add the following content to the bolt-project.yaml file.

bolt-project.yaml

---
name: nxlog_bolt
modules: []

color: true

plans:
  - nxlog::install_plan
  - nxlog::uninstall.plan

Create a Puppet Bolt plan to define and configure the automated deployment tasks. This plan contains the steps needed to deploy NXLog Agent on Debian-based Linux and Windows, as well as cleaning up the installation files.

install_plan.yaml

---
parameters:
  targets:
    type: TargetSpec

steps:
  - name: upload_nxlog_agent_installer (1)
    upload: nxlog/files/nxlog-6.5.9781_ubuntu24_amd64.deb
    destination: /root/
    targets: linux (2)
    description: "Uploaded NXLog Archive"

  - name: set_permissions (3)
    command: sudo chmod 755 /root/nxlog-6.5.9781_ubuntu24_amd64.deb
    targets: linux
    description: "Set file permissions"

  - name: install_nxlog_main_package (4)
    command: export NXP_ADDRESS="agents.example.com:5515" && export NXP_AGENT_LABEL=Ubuntu24 && apt install -y /root/nxlog-6.5.9781_ubuntu24_amd64.deb
    catch_errors: true
    targets: linux
    description: "Install NXLog on Ubuntu using the .deb package"

  - name: upload_nxlog_agent_installer_windows (5)
    upload: nxlog/files/nxlog-6.5.9781_windows_x64.msi
    destination: C:\nxlog-6.5.9781_windows_x64.msi
    targets: windows (6)
    description: "Uploaded NXLog MSI to Windows"

  - name: install_nxlog_windows (7)
    command: Start-Process -Wait msiexec.exe -ArgumentList '/i C:\nxlog-6.5.9781_windows_x64.msi /quiet NXP_ADDRESS=agents.example.com:5515 NXP_AGENT_LABEL=WindowsServer'
    targets: windows
    description: "Install NXLog on Windows with NXP_ADDRESS and NXP_AGENT_LABEL"

  - name: remove_uploaded_linux_files (8)
    command: rm -f /root/nxlog-6.5.9781_ubuntu24_amd64.deb
    targets: linux
    description: "Remove uploaded NXLog .deb file"

  - name: remove_uploaded_windows_files (9)
    command: Remove-Item -Path C:\nxlog-6.5.9781_windows_x64.msi -Force
    targets: windows
    description: "Remove uploaded NXLog MSI file from Windows"

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

Run the plan.
```
$ bolt plan run nxlog::install_plan -t all
```
Puppet Bolt will install NXLog Agent on each node, and each instance will automatically connect to NXLog Platform.

Uninstall NXLog Agent

There might be scenarios when you need to remove NXLog Agent, for example, when testing. Execute the steps below to uninstall NXLog Agent on Windows and Debian-based Linux, returning them to their original state.

Create a plan to uninstall NXLog Agent.

uninstall_plan.yaml

---
parameters:
  targets:
    type: TargetSpec

steps:
  - name: stop_nxlog_linux (1)
    command: systemctl stop nxlog.service
    targets: linux
    description: "Stop the nxlog service on Linux"

  - name: uninstall_nxlog_linux (2)
    command: apt-get remove -y '^nxlog*' || true && apt-get autoremove -y
    targets: linux
    description: "Uninstall NXLog Agent from Linux"

  - name: cleanup_nxlog_linux (3)
    command: rm -rf /opt/nxlog /var/log/nxlog /root/nxlog /root/nxlog-6.5.9781_ubuntu24_amd64.deb
    targets: linux
    description: "Remove all NXLog Agent related directories and installation files from Linux"

  - name: stop_nxlog_windows (4)
    command: Stop-Service -Name nxlog -Force
    targets: windows
    description: "Stop the nxlog service on Windows"

  - name: uninstall_nxlog_windows (5)
    command: Start-Process -Wait msiexec.exe -ArgumentList '/x C:\nxlog-6.5.9781_windows_x64.msi /quiet /norestart'
    targets: windows
    description: "Uninstall NXLog Agent from Windows"

  - name: remove_nxlog_windows_dir (6)
    command: Remove-Item -Path "C:\Program Files\nxlog" -Recurse -Force
    targets: windows
    description: "Removes the NXLog Agent installation directory from Windows"

  - name: remove_nxlog_windows_installer (7)
    command: Remove-Item -Path C:\nxlog-6.5.9781_windows_x64.msi -Force
    targets: windows
    description: "Remove NXLog Agent MSI installer from Windows"

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

Run the plan.

$ bolt plan run nxlog::uninstall_plan -t all