Open Source RDBMS - Seamless, Scalable, Stable and Free

한국어 | Login |Register

Installation Guide - version 3.2


nGrinder is a combination of a web application(Controller) and a Java application(Agent).

  • To install nGrinder controller, you need to first have Oracle JDK 1.6 or above (OpenJDK 1.7 is also OK) and Tomcat 6.X or later.
    • We don't support OpenJDK 6.X.
    • We don't support IP6
  • To install nGrinder agent, all you need is Oracle JDK 1.6 or above ((OpenJDK 1.7 is also OK) 
    • We don't support OpenJDK 6.X..
    • We don't support IP6

If you installed 32bit JVM on your 64bit OS. nGrinder won't work.

If you don’t know what a controller and agent are, please refer to Architecture.

If you like to install nGrinder in Windows XP, please refer link.

Please check your PATH environment variable if your java path is located at the head of PATH so that appropriate java can be run.

  • (Youtube video for Windows XP)



Install Controller

  1. Please be sure that you configured PATH and JAVA_HOME in advance.
    • There are a lot of questions which comes from wrong PATH configuration. You should put java path in the head of PATH env var.
    • For example, in windows it should be set as C:\Program Files\Java\Your java Version\bin;BlarBlar...
  2. Installing Controller can be done easily, simply by dropping nGrinder's controller war file in the ${TOMCAT_HOME}/webapps folder.
    • If you're not familiar with Tomcat, just download the nGrinder 3.1package bundled with Tomcat.
  3. After dropping it into the folder, please add following option in tomcat's  ${TOMCAT_HOME}/ or catalina.bat(windows) file. nGrinder controller has heavy library requirements so you need to have sufficient PermGem memory.
    JAVA_OPTS="-Xms600m -Xmx1024m -XX:MaxPermSize=200m"    # for
    set JAVA_OPTS=-Xms600m -Xmx1024m -XX:MaxPermSize=200m   # for catalina.bat
  4. If you have multiple IPs in the machine. nGrinder will automatically select one of the IPs which will listen the agent connection. if you want to specify the special IP, please set ngrinder.controller.ipaddress=IP Address property in system.conf file in advance.
  5. Then run tomcat using or, startup.bat(windows).
  6. Now, access nGrinder using web browser. http://hostname:8080/ngrinder-controller  That’s it! You’re ready to use nGrinder.
  • If you want to access ngrinder without any path other than hostname(e.g :http://yourdnsname/), you need to change the name of the war file to ROOT.war.
  • If you want to access ngrinder with port 80, you should configure ${TOMCAT_HOME}/conf/server.xml

※ For more detailed nGrinder controller configuration options, please refer to Controller Configuration Guide - version 3.2


Install Agent

  • From the perspective of nGrinder, Agent is the java application that does the following:
    • When installed on the target server, it can act as a performance monitoring server.
    • When installed on the agent server, it can act as a stress injection server.
  • To configure agents to work as you intend, you need to change some configuration files.
  1. Please make sure that you have installed JDK in your agent machine and provide the JAVA_HOME env variable.
  2. Installing Agents is really simple.  Just download the agent file and decompress it.
    • Windows:  ngrinder-core-{VersionNumber}
    • Linux:  ngrinder-core-{VersionNumber}-agent-package.tar.gz
  3. You will find ngrinder-core-{VersionNumber}.jar and several folders.
  4. Navigate to the decompressed folder and run the following command. Please note that you should run this in the folder where the nGrinder agent is installed.
  5. or run_agent.bat (for background running)
  6. The agent will then execute and create the .ngrinder_agent folder in your account home.
    • If you want to point the other path as a ngrinder agent home, please set NGRINDER_AGENT_HOME env var in advance.
  7. Then, go to the ${user.home}/.ngrinder_agent folder.
    • Window : C:\Users\{username}\.ngrinder_agent
    • Linux : /home/{username}/.ngrinder_agent
  8. Change the following agent.conf file.
    agent.console.ip=please specify your controller IP
    #If you set up the controller region. please provide the region you use here. #agent.region=
  9. Then run the agent again.
    run_agent.bat (windows) or & (linux)
  10. Now the agent will try to connect to the server. 
  11. When you shutdown the agent you can run the following commands. (windows) or stop_agent.bat (linux)
  12. To enable agents, you should approve the connected agents. Please refer to the Administration Guide
  13. If you run an agent in Linux, you may need to configure ulimit to run many threads. Please check followings.
    > ulimit -a                                                                                                                                         
    core file size          (blocks, -c) 0
    data seg size           (kbytes, -d) unlimited
    scheduling priority             (-e) 0
    file size               (blocks, -f) unlimited
    pending signals                 (-i) 30676
    max locked memory       (kbytes, -l) 64
    max memory size         (kbytes, -m) unlimited
    open files                      (-n) 16000
    pipe size            (512 bytes, -p) 8
    POSIX message queues     (bytes, -q) 819200
    real-time priority              (-r) 0
    stack size              (kbytes, -s) 10240
    cpu time               (seconds, -t) unlimited
    max user processes              (-u) 32768
    virtual memory          (kbytes, -v) unlimited
    file locks                      (-x) unlimited
    • If your machine has small "max user processes" and "open files" entry when you run "ulimit -a", please make it at least over 10000.
    • Open /etc/security/limits.conf file in the root account and add followings.
      your_account soft    nproc           32768
      your_account hard    nproc           32768
      root         soft    nproc           32768
      root         hard    nproc           32768
      your_account soft    nofile          16000
      your_account hard    nofile          16000
      root         soft    nofile          16000
      root         hard    nofile          16000

Install Monitor

    1. All you need to do to run monitor is simply run the following command with the same binary as the agent. Nothing else is necessary. or run_monitor.bat &

nGrinder Port

    nGrinder uses many ports to communicate with agent and agent. If some ports are blocked by your firewall, you should have the network admin to open the following ports in the firewall.
    • Agent : Any ==> Controller : 16001
    • Agent : Any ==> Controller : 12000 ~ 12000+(the number of concurrent tests allowed)
      • This can be configured.
    • Controller : Any ==> Monitor : 13243
    • Controller ==> Public user : This is dependent on your tomcat configuration. By default, it is set as 8080.

comments powered by Disqus
Page info
viewed 13153 times
translations ko en
posted 5 years ago by
updated 3 years ago by
View revisions
Share this article