Topology installation failure
search cancel

Topology installation failure

book

Article ID: 416666

calendar_today

Updated On:

Products

Network Observability

Issue/Introduction

During the installation of DX NetOps Topology, an Ansible task related to Neo4j (e.g., "Accept Neo4J Commercial License Agreement") fails with an error similar to the following:

fatal: [Neo4J1]: FAILED! => { "cmd": "/opt/netops-topology/neo4j/bin/neo4j-admin server license --accept-commercial", "stderr": "java.lang.RuntimeException: java.lang.UnsatisfiedLinkError: /home/neo4j/.cache/JNA/temp/jna...tmp: ... failed to map segment from shared object\n\tat org.neo4j.internal.unsafe.UnsafeUtil.allocateByteBuffer(UnsafeUtil.java:638)\n...Caused by: java.lang.UnsatisfiedLinkError: /home/neo4j/.cache/JNA/temp/jna...tmp: /home/neo4j/.cache/JNA/temp/jna...tmp: failed to map segment from shared object" }

This java.lang.UnsatisfiedLinkError (specifically "failed to map segment from shared object") indicates that the Java Virtual Machine (JVM) running Neo4j, via its Java Native Access (JNA) library, cannot properly load or execute necessary temporary native libraries.

Environment

DX NetOps Topology 24.3.13 release

Cause

This error is due to one or a combination of the following issues on the Linux server where Neo4j is being installed:

  1. Restrictive ulimit settings: The operating system's ulimit configuration for the user running Neo4j (typically neo4j) is too low for virtual memory (-v / -as) or max locked memory (-l / -memlock). Neo4j is a high-performance database that heavily utilizes memory-mapped files and direct memory access, requiring generous resource limits.
  2. Insufficient Execute Permissions on JNA Cache Directory: The user running Neo4j lacks execute permissions for the directory where JNA extracts its temporary native libraries. By default, JNA often uses ~/.cache/JNA/temp/ (e.g., /home/neo4j/.cache/JNA/temp/). If /home/neo4j or its subdirectories lack execute permissions, JNA cannot properly load and execute the native library, leading to the UnsatisfiedLinkError.
  3. noexec Mount Option on Temporary Filesystems: Less common for the user's home directory, but if /tmp or other default temporary locations were used and mounted with the noexec option, it could prevent JNA from executing its temporary native libraries from those locations.

Resolution

To successfully install and run Neo4j with DX NetOps Topology, ensure the following configurations are in place for the user running the Neo4j process (e.g., neo4j user):

Step 1: Configure System-Level ulimit Settings

  1. Log in as root or a user with sudo privileges to the server where Neo4j is being installed (Neo4J1 in the error).

  2. Edit the /etc/security/limits.conf file.

  3. Add or modify the following lines for the neo4j user (replace neo4j with your actual Neo4j OS user if different):

    # Neo4j user limits for optimal performance and stability
    neo4j soft nofile 65536
    neo4j hard nofile 65536
    neo4j soft nproc 65536
    neo4j hard nproc 65536
    neo4j soft memlock unlimited
    neo4j hard memlock unlimited
    neo4j soft as unlimited
    neo4j hard as unlimited
     

    • nofile: Maximum number of open files. Neo4j can open many files.
    • nproc: Maximum number of processes.
    • memlock: Allows Neo4j to lock memory in RAM, crucial for performance and preventing swap.
    • as (address space/virtual memory): Allows the process to use an unlimited amount of virtual memory, directly addressing "failed to map segment" errors.

  4. Save the file.

  5. Apply ulimit changes: For these changes to take effect, the neo4j user needs to log out and log back in, or the server can be rebooted. Ensure that the Ansible execution environment for the Neo4j tasks correctly inherits these new limits.

Step 2: Ensure Execute Permissions on the Neo4j User's Home Directory

The JNA library often extracts temporary native code into a cache within the user's home directory (e.g., /home/neo4j/.cache/JNA/temp/). For these native libraries to be loaded and executed, the containing directory path must have execute permissions.

  1. Log in as root or a user with sudo privileges.
  2. Verify permissions for the neo4j user's home directory:
    bash ls -ld /home/neo4j
    Ensure the user and group have x (execute) permission.
  3. If necessary, grant execute permissions:
    bash sudo chmod u+x,g+x,o+x /home/neo4j # Or, if more granular control is desired and the problem is deeper: sudo chmod -R +x /home/neo4j/.cache/JNA/temp/ # The key is that the path where JNA extracts and tries to run files must be executable.
    Note: While granting broad execute permissions (chmod +x) on /home/neo4j resolved the customer's specific issue, best practice dictates applying the minimum necessary permissions. However, for Ansible-driven installations where JNA's exact internal temporary path might be dynamic, ensuring /home/neo4j is executable for the user is often the most direct fix.

Step 3: Restart the Installation Process

After implementing the above changes, re-run the DX NetOps Topology installation process (or the specific Ansible playbook task) that previously failed. The Neo4j license acceptance should now complete successfully.

Powered by Wolken Software