Deploy NXLog Agent with Chef

Chef is a configuration management 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 Chef repository, create a cookbook, and automate tasks for a streamlined NXLog Agent deployment. For further details, see Chef Infra Overview in the Chef 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.
Chef server — A Linux-based computer with Chef Infra Server installed and configured. The Chef server manages cookbooks, nodes, and the policies that apply to them. See Install the Chef Infra Server for more information.
Chef workstation — Where you will create cookbooks and manage your Chef configuratiions. See Install Chef Workstation for more information.
Chef clients — Windows or Debian-based Linux machines connected to Chef Server. See the knife-bootstrap command for more information.
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.

Create the NXLog Agent cookbook

You need to run a series of commands to create the correct file structure. These commands will generate a Chef repository, the cookbooks, and the recipes. Cookbooks are a collection of recipes, and there can be many recipes within a cookbook as well as many cookbooks.

Execute the following commands on your Chef workstation.

If you don’t already have a Chef repository, initiate one:
```
$ chef generate repo chef-repo
```
Switch to the cookbooks directory:
```
$ cd chef-repo/cookbooks
```

Generate the NXLog Agent cookbook:

$ chef generate cookbook nxlog-agent

Upon completion, you should have the following directory and file structure.

├── chefignore
├── cookbooks
│   ├── example
│   │   ├── attributes
│   │   │   └── default.rb
│   │   ├── metadata.rb
│   │   ├── README.md
│   │   └── recipes
│   │       └── default.rb
│   ├── nxlog-agent
│   │   ├── CHANGELOG.md
│   │   ├── chefignore
│   │   ├── kitchen.yml
│   │   ├── LICENSE
│   │   ├── metadata.rb
│   │   ├── Policyfile.rb
│   │   ├── README.md
│   │   ├── recipes
│   │   │   └── default.rb
│   │   ├── spec
│   │   │   ├── spec_helper.rb
│   │   │   └── unit
│   │   │       └── recipes
│   │   │           └── default_spec.rb
│   │   └── test
│   │       └── integration
│   │           └── default
│   │               └── default_test.rb
│   └── README.md
├── data_bags
│   ├── example
│   │   └── example_item.json
│   └── README.md
├── LICENSE
├── policyfiles
│   └── README.md
└── README.md

Create the files directory and copy the NXLog Agent installer files to it. This directory in Chef stores the files used in your recipes—for example, with the cookbook_file resource.
```
$ mkdir -p nxlog-agent/files
```
Sync the cookbook with your Chef server. Replace /root/chef-repo with the path to your Chef repository.
```
$ knife upload --chef-repo-path /root/chef-repo cookbook nxlog-agent
```

Install NXLog Agent

Execute the steps below on your Chef workstation to create the recipes to install NXLog Agent on Windows and Debian-based Linux.

Windows

Create the recipe file for installing NXLog Agent on Windows. Replace /root/chef-repo with the path to your Chef repository.
```
$ cd /root/chef-repo/cookbooks/nxlog-agent
$ chef generate recipe nxlog_windows_install
```

Open nxlog-agent/recipes/nxlog_windows_install.rb with a text editor and copy the contents below.

nxlog_windows_install.rb

#
# Cookbook:: nxlog-agent
# Recipe:: nxlog_windows_install
#
# Copyright:: 2025, The Authors, All Rights Reserved.

directory "C:\\chef\\files" do (1)
  rights    :write, 'myusername', :applies_to_children => true 
  action    :create
  recursive true
end
  
cookbook_file "Copy NXLog Agent MSI" do
  source "nxlog-6.5.9781_windows_x64.msi" (2)
  path   "C:\\chef\\files\\nxlog-6.5.9781_windows_x64.msi"
end
  
windows_package "nxlog" do (3)
  action  :install
  source  "C:\\chef\\files\\nxlog-6.5.9781_windows_x64.msi"
  options '/q NXP_ADDRESS="agents.nxlog.example.com:5515" NXP_AGENT_LABEL="Windows"'
end
  
file "Delete NXLog Agent MSI" do (4)
  path   "C:\\chef\\files\\nxlog-6.5.9781_windows_x64.msi"
  action :delete
end

1	Creates the folder where the MSI file will be copied on the node. Replace `myusername` with your username.
2	The source file must be located in the cookbook’s `files` folder.
3	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.
4	Deletes the MSI file after installation.

Debian GNU/Linux

Create the recipe file for installing NXLog Agent on Debian-based Linux. Replace /root/chef-repo with the path to your Chef repository.
```
$ cd /root/chef-repo/cookbooks/nxlog-agent
$ chef generate recipe nxlog_linux_install
```

Open nxlog-agent/recipes/nxlog_linux_install.rb with a text editor and copy the contents below.

nxlog_linux_install.rb

#
# Cookbook:: nxlog-agent
# Recipe:: nxlog_linux_install
#
# Copyright:: 2025, The Authors, All Rights Reserved.

directory "/srv/chef" do (1)
  owner     "root"
  group     "root"
  mode      "0755"
  action    :create
  recursive true
end

cookbook_file "Copy NXLog Agent archive" do
  source "nxlog-6.5.9781_ubuntu22_amd64.tar.bz2" (2)
  path   "/srv/chef/nxlog-6.5.9781_ubuntu22_amd64.tar.bz2"
  owner  "root"
  group  "root"
  mode   "0755"
end

archive_file "Extract NXLog Agent archive" do
   path        "/srv/chef/nxlog-6.5.9781_ubuntu22_amd64.tar.bz2"
   destination "/srv/chef/nxlog/"
   owner       "root"
   group       "root"
   mode        "755"
   action      :extract
end
 
execute "Install NXLog Agent" do (3)
  command "export NXP_ADDRESS=agents.nxlog.example.com:5515 && export NXP_AGENT_LABEL=Linux && dpkg -i /srv/chef/nxlog/nxlog-6.5.9781_ubuntu22_amd64.deb || apt-get install -f -y"
end

file "Delete NXLog Agent package" do (4)
  path   "/srv/chef/nxlog-6.6.9843_ubuntu22_amd64.tar.bz2"
  action :delete
end

directory "/srv/chef/nxlog" do
  action    :delete
  recursive true
end

1	Creates the folder where the package will be copied on the node.
2	The source file must be located in the cookbook’s `files` folder.
3	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.
4	Deletes the NXLog Agent packages after installation.

The next step is to sync your changes with the server and associate your nodes with the relevant recipe. Execute the following steps on your Chef workstation.

Upload the recipes to the Chef server. Replace /root/chef-repo with the path to your Chef repository.
```
$ knife upload --chef-repo-path /root/chef-repo cookbook nxlog-agent
```

Associate your node with the relevant recipe:

$ knife node run_list add <NODE_NAME> recipe[nxlog-agent::<RECIPE_NAME>]

Replace <NODE_NAME> with your node’s hostname and <RECIPE_NAME> with the relevant recipe. For example:

$ knife node run_list add win-srv recipe[nxlog-agent::nxlog_windows_install]

Finally, switch to your node and execute the following command to apply the recipe:
Windows
> cd C:\opscode\chef\bin > chef-client
Debian GNU/Linux
$ sudo chef-client

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.

Windows

Create the recipe file for uninstalling NXLog Agent on Windows. Replace /root/chef-repo with the path to your Chef repository.
```
$ cd /root/chef-repo/cookbooks/nxlog-agent
$ chef generate recipe nxlog_windows_uninstall
```

Open nxlog-agent/recipes/nxlog_windows_uninstall.rb with a text editor and copy the contents below.

nxlog_windows_uninstall.rb

#
# Cookbook:: nxlog-agent
# Recipe:: nxlog_windows_uninstall
#
# Copyright:: 2025, The Authors, All Rights Reserved.

windows_package "Uninstall NXLog Agent" do
  package_name "NXLog"
  action       :remove
end
  
directory "Purge files" do
  path      "C:\\Program Files\\nxlog"
  action    :delete
  recursive true
end

Debian GNU/Linux

Create the recipe file for uninstalling NXLog Agent on Debian-based Linux. Replace /root/chef-repo with the path to your Chef repository.
```
$ cd /root/chef-repo/cookbooks/nxlog-agent
$ chef generate recipe nxlog_linux_uninstall
```

Open nxlog-agent/recipes/nxlog_linux_uninstall.rb with a text editor and copy the contents below.

nxlog_linux_uninstall.rb

#
# Cookbook:: nxlog-agent
# Recipe:: nxlog_linux_uninstall
#
# Copyright:: 2025, The Authors, All Rights Reserved.

dpkg_package "Uninstall NXLog Agent" do
  package_name "nxlog"
  action       :purge (1)
end

1	Uninstalls NXLog Agent and deletes the installation directory.

Next, sync your changes with the server and associate your nodes with the new recipe. Execute the following steps on your Chef workstation.

Upload the new recipes to the Chef server. Replace /root/chef-repo with the path to your Chef repository.
```
$ knife upload --chef-repo-path /root/chef-repo cookbook nxlog-agent
```
Remove the NXLog Agent installation recipe from your node:
```
$ knife node run_list remove <NODE_NAME> recipe[nxlog-agent::<RECIPE_NAME>]
```
Replace <NODE_NAME> with your node’s hostname and <RECIPE_NAME> with the relevant recipe. For example:
```
$ knife node run_list remove win-srv recipe[nxlog-agent::nxlog_windows_install]
```
Associate your node with the recipe to uninstall NXLog Agent:
```
$ knife node run_list add <NODE_NAME> recipe[nxlog-agent::<RECIPE_NAME>]
```
Replace <NODE_NAME> with your node’s hostname and <RECIPE_NAME> with the relevant recipe. For example:
```
$ knife node run_list add win-srv recipe[nxlog-agent::nxlog_windows_uninstall]
```
Finally, switch to your node and execute the following command to apply the recipe:
Windows
> cd C:\opscode\chef\bin > chef-client
Debian GNU/Linux
$ sudo chef-client