Deploy NXLog Agent with Salt

Salt is an automation tool that you can use to deploy NXLog Agent instances on Linux, Windows, and macOS. This guide provides step-by-step instructions to set up the required environment, create state files, and automate tasks for a streamlined NXLog Agent deployment. For further details, see the Salt 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.
Salt master — A Linux-based computer with salt-master installed and configured. See the Salt install guide for more information.
Salt minions — Windows or Debian-based Linux machines with salt-minion installed and configured.
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 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.

Configure the Salt master

A basic Salt setup consists of a Salt master managing one or more Salt minions. The master provides the orchestration and automation environment between managed nodes. A minion can either run the salt-minion service or use salt-ssh or salt-proxy. In our example, we manage nodes that have the salt-minion service installed.

If you have already configured your Salt master’s file roots for custom and state files, replace /srv/salt in the examples below with your path. If not, follow these steps to configure file roots:

Create a configuration file in /etc/salt/master.d/ with the following content:
file_roots.conf
```
file_roots:
  base:
    - /srv/salt/states
    - /srv/salt/files
```
Restart the salt-master service to apply the new configuration:
```
$ sudo systemctl restart salt-master
```

It’s also a good idea to test the connection to the Salt minions at this stage.

$ sudo salt '<hostname>' test.ping

Replace <hostname> with your node’s hostname. The command should return output similar to the following:

win-srv:
    True

Install NXLog Agent

Execute the steps below to install NXLog Agent on Windows and Debian-based Linux.

Create the state files and save them in /srv/salt/states with the .sls extension.

Windows

nxlog-windows.sls

copy_nxlog_agent_msi:
  file.managed:
    - name: C:\salt\nxlog-6.5.9781_windows_x64.msi (1)
    - source: salt://nxlog-6.5.9781_windows_x64.msi (2)
    - makedirs: true (3)

install_nxlog_agent:
  cmd.run: (4)
    - name: msiexec /q /i C:\salt\nxlog-6.5.9781_windows_x64.msi NXP_ADDRESS="agents.nxlog.example.com:5515" NXP_AGENT_LABEL="Windows"

delete_agent_msi:
  file.absent: (5)
    - name: C:\salt\nxlog-6.5.9781_windows_x64.msi

1	The path where the MSI file will be copied on the minion.
2	The MSI file path on the master.
3	Creates the directory structure on the minion if it doesn’t exist.
4	The command to execute the NXLog Agent MSI installer. It includes the `NXP_ADDRESS` (for connecting to NXLog Platform) and `NXP_AGENT_LABEL` (to assign a label to the agent) arguments.
5	Deletes the MSI file after installation.

Debian GNU/Linux

nxlog-linux.sls

copy_nxlog_agent_package:
  file.managed:
    - name: /srv/salt/files/nxlog-6.5.9781_ubuntu20_amd64.tar.bz2 (1)
    - source: salt://nxlog-6.5.9781_ubuntu20_amd64.tar.bz2 (2)
    - makedirs: true (3)

extract_package:
  archive.extracted:
    - name: /srv/salt/files/nxlog
    - source: salt://nxlog-6.5.9781_ubuntu20_amd64.tar.bz2
    - enforce_toplevel: False
      
install_nxlog_agent:
  cmd.run:
    - names: (4)
      - export NXP_ADDRESS=agents.nxlog.example.com:5515 && export NXP_AGENT_LABEL=Linux 
      - dpkg -i /srv/salt/files/nxlog/nxlog-6.5.9781_ubuntu20_amd64.deb || apt-get install -f -y

delete_install_packages:
  file.absent: (5)
    - names:
      - /srv/salt/files/nxlog-6.5.9781.tar.bz2
      - /srv/salt/files/nxlog

1	The path where the package will be copied on the minion.
2	The package’s path on the master.
3	Creates the directory structure on the minion if it doesn’t exist.
4	The commands to install NXLog Agent. It includes setting the `NXP_ADDRESS` (for connecting to NXLog Platform) and `NXP_AGENT_LABEL` (to assign a label to the agent) environment variables.
5	Deletes the NXLog Agent packages after installation.

Execute the following command to apply the state and run the tasks on the Salt minions:
```
$ sudo salt '<hostname>' state.apply <state name>
```
Replace <hostname> with your node’s hostname and <state name> with your state file’s name, excluding the extension. For example:
```
$ sudo salt 'win-srv' state.apply nxlog-windows
```

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 Windows and Debian-based Linux, returning them to their original state.

Create the state files and save them in /srv/salt/states with the .sls extension.

Windows

nxlog-windows-uninstall.sls

copy_nxlog_agent_msi:
  file.managed:
    - name: C:\salt\nxlog-6.5.9781_windows_x64.msi (1)
    - source: salt://nxlog-6.5.9781_windows_x64.msi (2)
    - makedirs: true (3)

install_nxlog_agent:
  cmd.run: (4)
    - name: msiexec /qb /x C:\salt\nxlog-6.5.9781_windows_x64.msi
    
purge_files:
  file.absent: (5)
    - names: 
      - C:\salt\nxlog-6.5.9781_windows_x64.msi
      - "C:\\Program Files\\nxlog"

1	The path where the MSI file will be copied on the minion.
2	The MSI file path on the master.
3	Creates the directory structure on the minion if it doesn’t exist.
4	The command to uninstall NXLog Agent.
5	Deletes the MSI file and NXLog Agent installation directory.

Debian GNU/Linux

nxlog-linux-uninstall.sls

uninstall_nxlog_agent:
  cmd.run: (1)
    - name: apt-get purge --auto-remove -y nxlog

1	The command to uninstall NXLog Agent and delete the installation directory.

Execute the following command to apply the state and run the tasks on the Salt minions:
```
$ sudo salt '<hostname>' state.apply <state name>
```
Replace <hostname> with your node’s hostname and <state name> with your state file’s name, excluding the extension. For example:
```
$ sudo salt 'win-srv' state.apply nxlog-windows-uninstall
```