NXLog search
Let's talk Start free
Let's talk Start free
1.03

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

    Inbound

    443/TCP

    HTTPS endpoint for the NXLog Platform user interface.

    5515/TCP

    Agent management.

    5514/TCP

    Ingestion of logs sent by agents.

    Outbound

    {53|custom}/TCP
    {53|custom}/UDP

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

    {25|465|587|custom}/TCP

    SMTP port for sending NXLog Platform email notifications, such as new user invitations. Depending on your SMTP server, allow either port 25, 465, 587, or a custom port.

    *.nxlog.co:443/TCP

    NXLog cloud backend.

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

    Microsoft Azure Container Registry and Microsoft Azure Blob Storage.
    Used for pulling the NXLog Platform container images from the NXLog container registry.

    *.digitaloceanspaces.com:443/TCP

    DigitalOcean Spaces CDN.
    Used for dynamically fetching the most recent versions of NXLog Platform solution packs.

    {*.ubuntu.com|custom}:80/TCP
    {*.ubuntu.com|custom}:443/TCP

    Ubuntu only.

    Official Ubuntu APT system repositories. Depending on your configuration, for example when using custom repository mirrors, you may need to allow access to different hostnames.
    Used for downloading host OS software dependencies

    {*.redhat.com|custom}:80/TCP
    {*.redhat.com|custom}:443/TCP

    RHEL only.

    Official Red Hat Enterprise Linux software repositories. Depending on your configuration, for example when using custom repository mirrors, you may need to allow access to different hostnames.
    Used for downloading host OS software dependencies

    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:

  1. Log in to your NXLog Platform account, or sign up for NXLog Platform if you don’t have an account yet.

  2. 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.

      NXLog Platform on-premises download and API key

  3. Copy the downloaded file to the NXLog Platform host machine.

  4. 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.

  5. 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

    Domain name for accessing your NXLog Platform instance, in the format subdomain.domain.tld.

    To avoid DNS conflicts with other services on your network, we highly recommend choosing a dedicated subdomain for NXLog Platform (such as nxlog.example.com if your organization’s domain name is example.com).

    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 Platform listens for incoming NXLog Agent connections. If you change this variable, you must follow these additional steps after finishing the NXLog Platform installation process.

    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.

  6. 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.

Create DNS A records for the following domain names and point them all to the IP address of the deployment machine, replacing nxlog.example.com with the actual domain you configured on /etc/nxp.conf while installing NXLog Platform.

  • platform.nxlog.example.com

  • auth.nxlog.example.com

  • agents.nxlog.example.com

  • relay.nxlog.example.com

  • grafana.nxlog.example.com

For testing purposes, you can add the following entries to the hosts file on your workstation and on any machine running NXLog Agent. Replace 192.168.1.123 with the IP address of your NXLog Platform host machine and nxlog.example.com with the domain you configured on /etc/nxp.conf while installing 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.

  1. Run the following command to start the certificate import wizard:

    $ sudo nxp_manage.sh import-cert

  2. 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/

  3. 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.

Log in to NXLog Platform using the default administrator user created during the installation:

Username: admin@localhost.local
Password: NXLogPlatform_1

NXLog Platform portal login

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.

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

  1. 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.

  2. Log in to NXLog Platform and navigate to Administration > Tenant operations > Platform configuration.

  3. In the Mail server section, set the fields as described in Mail server.

  4. (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.

  5. 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.

Update the NXLog Agent listening port (optional)

If you changed NXP_MINDER_AGENT_PORT in /etc/nxp.conf when installing NXLog Platform, you must follow these additional steps:

  1. Open https://agents.nxlog.example.com/settings/agent-manager, replacing nxlog.example.com with your domain.

  2. Update the port of the default enrollment address and click Save.

    This ensures that NXLog Platform sends the correct port when enrolling new agents.

  3. Navigate to Agents > Configurations Overview, and delete all built-in templates by clicking the Actions menu and choosing Delete.

    NXLog Platform automatically recreates the built-in templates using the updated NXLog Agent listening port.

    Deleting the built-in agent configuration templates

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

  1. 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

  2. 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

  1. 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)

  2. 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

  1. 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

  2. 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.

  3. 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

  1. 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

  2. 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

  3. 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.

See also

Now that you have NXLog Platform up and running, continue to the next steps:

© Copyright 2024 NXLog Ltd.

PRIVACY POLICY GENERAL TERMS OF BUSINESS