Open Source RDBMS - Seamless, Scalable, Stable and Free

English | Login |Register

Installation Guide


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 and Tomcat 6.X or later.
    • We don't support OpenJDK yet.
    • We don't support IP6
  • To install nGrinder agent, all you need is Oracle JDK 1.6
    • We don't support OpenJDK yet.
    • 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. 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.
  2. 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
  3. Please check if you configured the correct host name and ip mapping.

     $ hostname
    $ ping dev-ngrinder-abnormal.ncl
    PING ( 56(84) bytes of data
    # In above, the host name is dev-ngrinder-abnormal.ncl and is mapped to
    # If you see the loopback address like (, you should modify /etc/hosts 
    # to make it map into real ip.

  4. Then run tomcat using or, startup.bat(windows).
  5. 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 Advanced Controller Configuration


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
  6. The agent will then execute and create the .ngrinder_agent folder in your account home.
  7. Then, go to the ${user.home}/.ngrinder_agent folder.
    • Window : C:Users{username}.ngrinder_agent or 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. (linux) or stop_agent.bat (windows)
  12. To enable agents, you should approve the connected agents. Please refer to the Administration Guide
  • Sometimes, java fails to detect the current IP on some Linux distribution package. So the controller might not connect the agent.
    • Easiest way to fix this is to delete localhost entry in your /etc/hosts and put real_ip and your_hostname pair 


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
문서 정보
viewed 9420 times
번역 ko en
posted 2년 전
마지막 수정시간 2달 전
변경 내역 보기
Share this article