Install NXLog Platform on-premises

The steps below guide you to install your on-premises NXLog Platform instance on a physical or virtual machine, which you can fully manage and administer.

System requirements

The system requirements of NXLog Platform depend on the number of log-collecting agents that you plan to connect and your log storage needs.

The following sections provide initial resource provisioning guidelines for the different deployment sizes supported by NXLog. After completing the deployment, we recommend monitoring resource usage and increasing resources as necessary to ensure the smooth running of NXLog Platform.

Supported operating systems

You can deploy NXLog Platform on the following operating systems:

Red Hat Enterprise Linux (RHEL) 8
Red Hat Enterprise Linux (RHEL) 9
Ubuntu 22.04.x
Ubuntu 24.04.x

CPU and RAM requirements

NXLog Platform provides several deployment sizes depending on the number of agents that you run or plan to run in your environment. The following table lists the minimum CPU and operating memory requirements for each deployment size.

The Managed agents column represents the maximum number of agents supported by the agent management capability of NXLog Platform. Note that the number of agents sending logs to NXLog Platform can be lower or higher than that number depending on your log collection architecture.

CPUs must have an x86_64 architecture and support Advanced Vector Extensions 2 (AVX2) instructions.

To verify that AVX2 instructions are present, run the following command on the machine where you are deploying NXLog Platform:

$ grep -io -m1 avx2 /proc/cpuinfo
avx2

If you use virtualization, ensure that your hypervisor’s BIOS has AVX2 enabled and that the hypervisor allows AVX2 pass-through to the guest OS.

Table 1. NXLog Platform deployment sizes
Deployment size	Managed agents	CPU cores	RAM
small	up to 1,000	2	6 GB
medium	1,001 to 10,000	3	8 GB
large	10,001 to 50,000	4	16 GB
xlarge	50,001 to 100,000	8	32 GB

Storage requirements

Ensure that the following storage is available on the machine before you start deploying NXLog Platform:

For installation files and system logs:

30 GB of free disk space in /var/lib/containers/storage/.
At least 10 GB of free disk space in /var/log/.

NXLog Platform can exhaust this space more slowly or more quickly depending on the number of agents. If you expect a lot of activity, consider allocating more space and implementing rotation of the systemd journal and syslog logs.
1 GB of free disk space in /var/ outside the aforementioned directories.
1 GB of free disk space in /usr/ for dependency OS packages.

For NXLog Platform data, including agent-collected logs:

At least 10 GB of free disk space.

By default, NXLog Platform stores data in the directory /srv/nxp/data, but you can change this directory during the installation process. We recommend mounting this directory on a dedicated physical disk or disk partition.

Network requirements

Ensure that the deployment machine and your network are set up as follows:

The machine has a static IP address.
The local network 10.89.0.0/24 is free to use and reserved for the container services of NXLog Platform.

Both your organization firewall and the host machine firewall allow the URLs and ports described in the table below.

We do not recommend turning off the firewall on production systems.

Direction Service Description

Direction	Service	Description
Inbound	`443/TCP`	HTTPS endpoint for the NXLog Platform user interface.
Inbound	`5515/TCP`	Agent management.
Inbound	`5514/TCP`	Ingestion of logs sent by agents.
Outbound	`53/TCP 53/UDP`	DNS services. Change the port number if you are running your organization’s DNS server on another port.
Outbound	`.nxlog.co:443/TCP .nxlog.company:443/TCP`	NXLog cloud backend.
Outbound	`dl-cdn.alpinelinux.org`	Alpine Linux CDN.
Outbound	`azure.microsoft.com:443/TCP`	General access to Microsoft Azure services.
Outbound	`gcr.io:443/TCP`	Google Cloud Container registry.
Outbound	`nxlogacr.azurecr.io:443/TCP`	NXLog container registry on Microsoft Azure.
Outbound	`*.blob.core.windows.net:443/TCP`	Microsoft Azure Blob Storage.
Outbound	`.docker.io:443/TCP .docker.com:443/TCP`	Docker Hub container image library.
Outbound	`*.github.com:443/TCP objects.githubusercontent.com:443/TCP`	Docker Compose GitHub repository and Git Large File Storage.
Outbound	`{25\|465\|587\|custom}/TCP`	SMTP port for email notifications. Depending on your SMTP server, allow either port 25, 465, 587, or a custom port.

Inbound

443/TCP

HTTPS endpoint for the NXLog Platform user interface.

Inbound

5515/TCP

Agent management.

Inbound

5514/TCP

Ingestion of logs sent by agents.

Outbound

53/TCP 53/UDP

DNS services. Change the port number if you are running your organization’s DNS server on another port.

Outbound

*.nxlog.co:443/TCP *.nxlog.company:443/TCP

NXLog cloud backend.

Outbound

dl-cdn.alpinelinux.org

Alpine Linux CDN.

Outbound

azure.microsoft.com:443/TCP

General access to Microsoft Azure services.

Outbound

gcr.io:443/TCP

Google Cloud Container registry.

Outbound

nxlogacr.azurecr.io:443/TCP

NXLog container registry on Microsoft Azure.

Outbound

*.blob.core.windows.net:443/TCP

Microsoft Azure Blob Storage.

Outbound

*.docker.io:443/TCP *.docker.com:443/TCP

Docker Hub container image library.

Outbound

*.github.com:443/TCP objects.githubusercontent.com:443/TCP

Docker Compose GitHub repository and Git Large File Storage.

Outbound

{25|465|587|custom}/TCP

SMTP port for email notifications. Depending on your SMTP server, allow either port 25, 465, 587, or a custom port.

You can use one of the scripts below to create and enable the inbound traffic firewall rules. Copy the script to a text file and save it with the .sh extension. Ensure the file is executable, then run the script as root on the machine where you will install NXLog Platform.

The script might produce warnings if any of the firewall services that it adds are already allowed, but you can ignore those messages.

RHEL

configure-firewall.sh

#!/bin/bash

# Function to create a firewalld service file
create_service_file() {
    filename=$1
    content=$2
    echo "$content" > "$filename"
}

# HTTPS service
firewall-cmd --permanent --add-service=https --zone=public
firewall-cmd --reload

# Agents service
create_service_file "agents.xml" '<?xml version="1.0" encoding="utf-8"?>
<service>
  <short>nxlog-agents</short>
  <description>NXLog Agent Manager</description>
  <port protocol="tcp" port="5515"/>
</service>'

# NXLog Agent Relay service
create_service_file "relay.xml" '<?xml version="1.0" encoding="utf-8"?>
<service>
  <short>nxlog-relay</short>
  <description>NXLog Agent Relay</description>
  <port protocol="tcp" port="5514"/>
</service>'

# Register and enable Agents and Relay services
firewall-cmd --permanent --new-service-from-file=agents.xml --name=nxlog-agents
firewall-cmd --permanent --new-service-from-file=relay.xml --name=nxlog-relay
firewall-cmd --permanent --add-service=nxlog-agents --zone=public
firewall-cmd --permanent --add-service=nxlog-relay --zone=public
firewall-cmd --reload

Ubuntu

In Ubuntu, the firewall (UFW) is not enabled by default. This means you need to enable it first and then configure the above NXLog Platform services. To simplify the process, save the bash script below to your computer and then run it as root.

configure-firewall.sh

#!/bin/bash

BASEDIR=/etc/ufw/applications.d/

# Create the services
declare -A services
services["https.ufw"]="[https]\ntitle=HTTPS\ndescription=HTTPS\nports=443/tcp"
services["agents.ufw"]="[nxlog-agents]\ntitle=NXLog Agents\ndescription=NXLog Agents\nports=5515/tcp"
services["relay.ufw"]="[nxlog-relay]\ntitle=NXLog Relay\ndescription=NXLog Relay\nports=5514/tcp"

for file in "${!services[@]}"; do
    printf "%b\n" "${services[$file]}" > "$BASEDIR/$file"
done

# Firewall commands
ufw enable
ufw allow openssh
ufw allow https
ufw allow nxlog-agents
ufw allow nxlog-relay
ufw reload

SMTP server requirements

Important NXLog Platform features such as creating user accounts and resetting account passwords rely on email. Ensure that you have the details of your organization’s SMTP server available, including network address, port number, and credentials in case of authenticated SMTP.

NXLog Platform supports both plain-text and STARTTLS SMTP communication. It uses a self-signed certificate for TLS. Ensure that your SMTP server accepts self-signed certificates or install an SMTP relay that does.

Install NXLog Platform

Follow these steps to install NXLog Platform:

Log in to your NXLog Platform account, or sign up for NXLog Platform if you don’t have an account yet.
Download the installer:
1. In the left navigation menu, click Product Download.
2. Select your OS and download the installer.
3. Take note of the API key.
Copy the downloaded file to the NXLog Platform host machine.
Run the following commands, replacing M.m.p with your version:
```
$ tar xvf nxp-M.m.p-onprem-amd64.tar.gz
$ sudo ./nxp-M.m.p-onprem-amd64.sfx.sh
```
This will extract the deployment file and install the nxp_manage.sh command-line interface for managing your NXLog Platform instance, along with any software requirements that are missing on your system.

Edit the configuration file /etc/nxp.conf as root. For example:

$ sudo nano /etc/nxp.conf

Then, define or review the following variables and save the file:

NXP_API_KEY

Your NXLog Platform API key.

NXP_DOMAIN

NXLog Platform domain name that you specified while signing up.

NXP_SIZE

NXLog Platform deployment size. The accepted values are small, medium, large, and xlarge. See the CPU and RAM requirements for each deployment size.

The default is small.

NXP_BACKUP_LOCATION

Directory where NXLog Platform creates backup files.

The default is /srv/nxp/backup.

NXP_DATA_LOCATION

Directory where NXLog Platform writes and stores all data. Ensure that the directory has sufficient disk space, as mentioned in the storage requirements.

The default is /srv/nxp/data.

NXP_MINDER_AGENT_PORT

TCP port where NXLog Agent instances use when connecting to NXLog Platform.

The default is 5515.

http_proxy

https_proxy

If you use a proxy server, you must uncomment the lines and replace PROXY_ADDRESS and PORT with those of your proxy server. If your proxy does not use basic authentication, remove user:password@. Otherwise, replace them with your proxy credentials.

Pay attention to using the correct quotes and escaping characters where necessary. If your proxy uses basic authentication, you must escape characters like $ in the password with three backslashes. See Proxy-related errors and Enable debug logging if you encounter a problem installing NXLog Platform when using a proxy.

no_proxy

If you use a proxy server, you must uncomment the line to exclude the internal NXLog Platform IP address range 10.89.0.0/24 from being routed through the proxy.

Run the following commands to install NXLog Platform:
```
$ sudo nxp_manage.sh wizard
$ sudo nxp_manage.sh install
```
The installation might take some time, depending on the available system resources. If the installation doesn’t complete successfully, check out the troubleshooting section.

You will have NXLog Platform installed and running at this stage, but you still have to configure DNS to be able to log in for the first time.

Post-installation steps

Although NXLog Platform is up and running at this stage, there are additional configuration steps that we advise to perform immediately after installation. Examples include tightening security and initiating important features.

Configure DNS

You need to configure the appropriate DNS records before you can access your NXLog Platform instance. You will likely need to do this on your corporate DNS server.

Provided that nxlog.example.com is the domain name that you supplied when you signed up for NXLog Platform, create DNS A records for the following domain names and point them all to the IP address of the deployment machine:

platform.nxlog.example.com
auth.nxlog.example.com
agents.nxlog.example.com
relay.nxlog.example.com
grafana.nxlog.example.com

Replace nxlog.example.com with your actual domain name.

For testing purposes, you can add the following entries to your hosts file. Replace 192.168.1.123 with the IP address of your NXLog Platform machine and nxlog.example.com with the domain you provided when you signed up for NXLog Platform:

# Your workstation must resolve the names for the services
# hosting the NXLog Platform UI
192.168.1.123 platform.nxlog.example.com auth.nxlog.example.com agents.nxlog.example.com grafana.nxlog.example.com

# The machines running agents must resolve the names for the services
# responsible for the NXLog Platform log collection and management
192.168.1.123 relay.nxlog.example.com agents.nxlog.example.com

Set up a custom TLS certificate

NXLog Platform generates a self-signed certificate and private key pair during the installation and uses it when serving NXLog Platform UI web pages and API requests to simplify the configuration for evaluation purposes. For production environments, we recommend that you use your own TLS certificate and private key generated by a local or public CA.

Run the following command to start the certificate import wizard:
```
$ sudo nxp_manage.sh import-cert
```

Enter the path of the TLS certificate and private key when prompted. If the import is successful, you should see output similar to the following:

[2024-08-26 16:47:08] [SUCCESS] Successfully copied cert.crt to /srv/nxp/data/nginx_certs/
[2024-08-26 16:47:08] [SUCCESS] Successfully copied private.key to /srv/nxp/data/nginx_certs/
[2024-08-26 16:47:08] [SUCCESS] Script execution completed successfully
[2024-08-26 16:47:08] [SUCCESS] Files have been successfully copied to /srv/nxp/data/nginx_certs/

Restart NXLog Platform:

$ sudo nxp_manage.sh stop
$ sudo nxp_manage.sh start

Log in for the first time

Before you can log in to NXLog Platform, you need to configure DNS.

After the DNS records are in place, open a web browser and navigate to your NXLog Platform URL:

https://platform.nxlog.example.com

Replace nxlog.example.com with your NXLog Platform domain.

Username: admin@localhost.local
Password: NXLogPlatform_1

Configure a mail server

NXLog Platform needs to connect to an SMTP server to be able to send emails such as user invites, password reset requests, and system alerts. Without configuring an SMTP server, those features will be unavailable.

Take these steps to configure an SMTP server for outbound emails:

Ensure that your organization has access to an SMTP server either locally or as a cloud service and that you have its connection details at hand.
Log in to NXLog Platform and navigate to Administration > Tenant operations > Platform configuration.
In the Mail server section, set the fields as described in Mail server.
(Optional) Click Send test email to test out your settings.

The test email will not arrive unless you change the default administrator account’s email address to point to a real mailbox.
Click Save changes.

Harden the Administrator account

As the default admin account’s credentials are publicly available, we highly recommend changing them immediately after you log in for the first time. We also recommend enabling two-factor authentication (2FA) for the account.

The email address is also the account’s login name. We recommend changing it to an email address that you monitor regularly, as NXLog Platform sends important email notifications to it.

Ensure that you have configured a mail server before changing the email address.

To change the admin password, follow the steps in Change your password.
To change the admin email address, open the user account menu in the upper right-hand corner, navigate to View Account > General, and click Change email. See Update personal information for details.

After completing the change, use the new email address as a login name for future logins.
To enable 2FA, follow the steps in Enable two-factor authentication.

Troubleshooting the NXLog Platform installation

There might be occasions when you experience issues during or right after the installation of NXLog Platform. In this section, we provide troubleshooting instructions and workarounds for the most common issues.

Services can’t start after the first reboot

Symptom

After the first reboot, NXLog Platform services don’t start up, and logs indicate that Vault is unreachable.

Possible reason

The podman-restart service may not have been enabled.

Investigation

Check if Vault is running by executing the following command:

$ sudo podman ps --filter name=vault
CONTAINER ID  IMAGE                             COMMAND     CREATED             STATUS                           PORTS       NAMES
5d3ff406ba12  nxlogacr.azurecr.io/vault:1.13.3              3 hours ago  Up 3 hours (healthy)              nxlog-1_2_0-c16aa3e2-vault-1

Alternatively, you can execute the following ps command to check the status of the Vault process:

$ sudo ps -fC vault
UID          PID    PPID  C STIME TTY          TIME CMD
root       22110   21693  1 11:04 ?        00:02:48 vault server -config=/init/vault_server_config.hcl

If Vault is not started automatically following a system restart, the podman-restart service may be disabled resulting in a non-functional system. The PostgreSQL and container registry containers must also be started by the podman-restart service.

Check this by running the systemctl status podman-restart command:
```
$ sudo systemctl status podman-restart
○ podman-restart.service - Podman Start All Containers With Restart Policy Set To Always
     Loaded: loaded (/usr/lib/systemd/system/podman-restart.service; disabled; preset: disabled)
     Active: inactive (dead)
       Docs: man:podman-start(1)
```

Solution

If the output confirms that the podman-restart.service is disabled, enable it by executing the following commands:

$ sudo systemctl enable podman-restart
Created symlink /etc/systemd/system/default.target.wants/podman-restart.service → /usr/lib/systemd/system/podman-restart.service.
$ sudo systemctl status podman-restart
○ podman-restart.service - Podman Start All Containers With Restart Policy Set To Always
     Loaded: loaded (/usr/lib/systemd/system/podman-restart.service; enabled; preset: disabled)
     Active: inactive (dead)
       Docs: man:podman-start(1)

Reboot your server.

Error writing blob

Symptom

Deployment fails with the following outcome:

$ sudo nxp_manage.sh install
[...]
Error: writing blob: adding layer with blob "sha256:877cab0f2b20b3216be0b74c2533ce470ac014006d858f363cd33e62660022a4": Error processing tar file(exit status 1): write /usr/lib/libLLVM-15.so: no space left on device

Possible reason

The filesystem under /var/lib/containers does not have enough free space.

Investigation

Check the available space by executing the following command:

$ df -h /var/lib/containers
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1       4.7G  4.7G   23M 100% /

Solution

If the available space is less than 10GB, provision more space and restart the deployment process.

This issue might occur in environments where a proxy is used to access resources on the internet.

Symptom

A wrong or missing proxy configuration could cause 403 forbidden or 404 not found errors when the proxy refuses to serve the request. In some instances, you may also see the following or similar error message during installation:

[ERROR] Please check if your system can reach platform.nxlog.co. If you're using a proxy setup please ensure that proxy environment variables are exported before running make targets.

Possible reason

When the http_proxy or https_proxy environment variables are defined on your machine, HTTP clients will be directed to go through the proxy to access all web services. The proxy may not allow access to the external resources listed in network requirements, and could also interfere with internal communication to the IP range 10.89.0.0/24 in NXLog Platform’s internal Podman network.

Investigation

Check if your proxy is correctly configured on your machine.

If the proxy isn’t configured or working correctly, you will obtain a connection refused, timeout, or different type of error. For example:

$ curl --head https://platform.nxlog.co/registry/tenant
curl: (7) Failed to connect to platform.nxlog.co port 443 after 0 ms: Connection refused

If the proxy is configured and working correctly, you will obtain an HTTP 401 Unauthorized from the NXLog cloud URL. For example:

$ curl --head https://platform.nxlog.co/registry/tenant
HTTP/1.1 200 Connection established
Proxy-agent: tinyproxy/1.11.2

HTTP/1.1 401 Unauthorized
Date: Fri, 23 Aug 2024 09:42:25 GMT
Connection: keep-alive

If the curl test wasn’t successful, define the following environment variables for your current shell and repeat the previous test:

$ export https_proxy="http://user:password@PROXY_ADDRESS:PORT" (1)
$ export http_proxy="http://user:password@PROXY_ADDRESS:PORT"  (1)
$ export no_proxy="localhost,127.0.0.1,10.89.0.0/24"           (2)

1	Replace `PROXY_ADDRESS` and `PORT` with those of your proxy server. If your proxy does not use basic authentication, remove `user:password@`. Otherwise, replace them with your proxy credentials.
2	Exclude the internal NXLog Platform IP address range `10.89.0.0/24` from being routed through the proxy.

Once the curl test is successful, run the following command and take note of the http_proxy, https_proxy, and no_proxy environment variables defined in your current shell:
```
$ env | grep proxy
```

Solution

Edit the file /etc/nxp.conf and ensure the lines that define the http_proxy, https_proxy, and no_proxy environment variables are uncommented and use the same values that you obtained during the investigation steps above:
```
$ sudo nano /etc/nxp.conf
```
Check if your proxy allows ping requests to reach the NXLog container registry:
```
$ ping -c 1 nxlogacr.azurecr.io
```
If not, configure Podman not to ping the registry before pulling containers:
```
$ echo "podman.ping_registries = false" >> /etc/containers/containers.conf
```
Ensure that the proxy allows access to the outbound service FQDNs listed in the network requirements.

Enable debug logging

If you encounter another issue or cannot resolve the problem with the troubleshooting tips above, you can enable Podman debug logging by executing the following commands.

Remember to turn off debug logging when you no longer need it, or it could affect system performance.

$ sudo mkdir -p /etc/systemd/system/podman.service.d/
$ sudo cat << EOF > /etc/systemd/system/podman.service.d/debug.conf
[Service]
Environment=LOGGING="--log-level=debug"
EOF
$ sudo systemctl daemon-reload
$ sudo systemctl restart podman
$ sudo truncate -s 0 /var/log/syslog (1)

1	This command clears the system log file. Replace the path with your system’s logging path, usually `/var/log/syslog` on Ubuntu and `/var/log/messages` on other operating systems.

After enabling debug logging, retry the NXLog Platform installation and check the system log file for relevant errors.

If you need assistance installing NXLog Platform, please open a support ticket and one of our experts will contact you.

Install NXLog Platform on-premises

System requirements

Supported operating systems

CPU and RAM requirements

Storage requirements

Network requirements

SMTP server requirements

Install NXLog Platform

Post-installation steps

Configure DNS

Set up a custom TLS certificate

Log in for the first time

Configure a mail server

Harden the Administrator account

Troubleshooting the NXLog Platform installation

Services can’t start after the first reboot

Error writing blob

Proxy-related errors

Enable debug logging

See also